Update docs

1 files changed, 86 insertions, 57 deletions

diff --git a/README.txt b/README.txt
index 28132d3..d9e2c32 100644
--- a/README.txt
+++ b/README.txt
@@ -1,79 +1,108 @@
-SLOWBAUD(1)                        Urchlay's Useless Stuff                        SLOWBAUD(1)
+SLOWBAUD(1)                    Urchlay's Useless Stuff                    SLOWBAUD(1)
 
 NAME
        slowbaud - simulate a low bitrate serial connection
 
 SYNOPSIS
-       slowbaud <bits-per-sec> [<file> ...]
+       slowbaud [<bits-per-sec>] [<file> ...]
 
-       slowbaud <bits-per-sec> -c [<command> [<arg> ...]]
+       slowbaud [<bits-per-sec>] -c [<command> [<arg> ...]]
 
-DESCRIPTION
-       slowbaud  by  default  acts as a filter, or like the cat(1) command. It reads files or
-       its standard input, and writes the  contents  unmodified  to  standard  output...  but
-       slowly, at the given bits-per-second rate.  Output is unbuffered.
-
-       With  the  -c  option, it creates a pseudo-tty and runs the given command in it (or an
-       interactive shell, if no command is given).
+       slowbaud [<bits-per-sec>] -e <string> [<string> ...]
 
-       The <bits-per-sec> argument supports a range of 1 to 500000. Timing  accuracy  depends
-       on  your  OS,  kernel  config  (HZ and/or NO_HZ on Linux), and system load. No "fancy"
-       techniques like realtime scheduling or hardware event timers are used. At bitrates  up
-       to  57600, on a typical unloaded Linux system, the timing should be around 99.7% accu‐
-       rate.
+DESCRIPTION
+       slowbaud  by  default  acts  as a filter, or like the cat(1) command. It reads
+       files or its standard input, and writes the contents  unmodified  to  standard
+       output... but slowly, at the given bits-per-second rate.  Input and output are
+       unbuffered.
+
+       slowbaud can also act like echo(1) (the -e option), or run an interactive com‐
+       mand (the -c option).
+
+       The  <bits-per-sec> argument is optional. If it's not given, the bit rate will
+       be set from SLOWBAUD_BPS in the environment, or a built-in default of 2400  if
+       not set.
+
+OPTIONS
+       bits-per-sec
+              The  bit  ("baud")  rate  to simulate. This must be the first argument.
+              slowbaud assumes that if the first argument is a number, it's  the  bit
+              rate.   If  you're trying to pass a filename that consists only of dig‐
+              its, give -- as the first argument, or use e.g. ./filename.
+
+       -e     Echo mode. Prints all further arguments as strings to stdout, separated
+              by  a  single  space,  at  the  given  bit rate. Does not support back‐
+              slash-escapes, or any of the options of the regular echo command.
+
+       -c     Command mode. Next argument (if present) is the  command  to  run,  any
+              remaining  arguments become arguments to the command. With no arguments
+              after -c, a shell is spawned.  This creates a pseudo-tty, so  the  com‐
+              mand can be interactive.
 
 ENVIRONMENT
+       SLOWBAUD_BPS
+              Can  be  used  to  set the bit rate, when no <bits-per-sec> argument is
+              used.
+
        SLOWBAUD_DEBUG
-              Set this (to any value) in the environment  to  see  verbose  debug  output  on
-              stderr, including timing accuracy stats.
+              Set this (to any value) in the environment to see verbose debug  output
+              on stderr, including timing accuracy stats.
 
-       SHELL  Standard *nix environment variable, used to determine what shell to run when -c
-              is given with no <command>. If unset, /bin/sh is used.
+       SHELL  Standard *nix environment variable, used to determine what shell to run
+              when -c is given with no <command>. If unset, /bin/sh is used.
 
 EXIT STATUS
-       Without -c, 0 for success, non-zero on any error such as nonexistent/unreadable files.
-       slowbaud exits immediately on such errors (this is unlike cat(1)).
+       Without -c, 0 for success, non-zero on any error such  as  nonexistent/unread‐
+       able files. slowbaud exits immediately on such errors (this is unlike cat(1)).
 
-       With  -c,  exit  status  is  that  of  the  child process, or 127 if the child process
-       couldn't be spawned (e.g. command not found).  Of course, the child process could also
-       exit with status 127...
+       With -c, exit status is that of the child process, or 127 if the child process
+       couldn't be spawned (e.g. command not found).  Of course,  the  child  process
+       could also exit with status 127...
 
 NOTES
-       We can't really insert a delay between the bits of a byte, since I/O is done with byte
-       granularity. For calculation purposes, <bits-per-sec> is divided by 10  to  get  bytes
-       per  second. This simulates "8-N-1": one start bit, 8 data bits, no parity, and 1 stop
-       bit (total of 10 bits per byte).
-
-       The timing code works by calculating how  long  to  sleep  after  each  character  (in
-       microseconds),  but actually sleeping slightly less than that, then busy-waiting until
-       the rest of the interval expires.  At slower bitrates, this works well,  and  the  CPU
-       overhead is barely noticeable (at least on reasonably fast modern systems).
-
-       The  timing  error will almost always result in the bitrate being slightly too slow at
-       lower bitrates and slightly too fast at higher ones.
-
-       Timing is more accurate on Linux than OSX. It's done with getitimer()  and  sigwait().
-       This works out to be slightly more accurate than using usleep() on both Linux and OSX.
-       It would be possible to use the realtime timer_create()  and  clock_gettime()  API  on
-       Linux, for possibly even better accuracy, but OSX doesn't have these (and I want to be
-       portable).
-
-       If this were a truly useful application, it would be worth trying to decrease  latency
-       further, with realtime process scheduling. I didn't do this because slowbaud is just a
-       toy, and because the RT stuff tends to be unportable and require  elevated  privileges
-       (root,  or something like setrtlimit or extended filesystem attributes to manage capa‐
-       bilities).
-
-       About the name... I'm aware that "baud" is not  synonymous  with  bps.  I  just  think
-       "slowbaud"  sounds  better than "slowbps", as a name. Anyway the stty command on Linux
-       misuses the term ("speed 38400 baud"), so I'm in good company.
+       The  bitrate  has  a range of 1 to 500000. Timing accuracy depends on your OS,
+       kernel config (HZ and/or NO_HZ on Linux), and system load.  No  "fancy"  tech‐
+       niques like realtime scheduling or hardware event timers are used. At bitrates
+       up to 57600, on a typical unloaded Linux system, the timing should be at least
+       99.7% accurate.
+
+       We  can't  really insert a delay between the bits of a byte, since I/O is done
+       with byte granularity. For calculation purposes, <bits-per-sec> is divided  by
+       10  to  get  bytes  per  second. This simulates "8-N-1": one start bit, 8 data
+       bits, no parity, and 1 stop bit (total of 10 bits per byte).
+
+       The timing code works by calculating how long to sleep  after  each  character
+       (in  microseconds),  but  actually  sleeping  slightly  less  than  that, then
+       busy-waiting until the rest of the interval expires.  At slower bitrates, this
+       works  well, and the CPU overhead is barely noticeable (at least on reasonably
+       fast modern systems).
+
+       The timing error will almost always result in the bitrate being  slightly  too
+       slow at lower bitrates and slightly too fast at higher ones.
+
+       Timing is more accurate on Linux than OSX. It's done with getitimer() and sig‐
+       wait(). This works out to be slightly more accurate  than  using  usleep()  on
+       both  Linux  and  OSX. It would be possible to use the realtime timer_create()
+       and clock_gettime() API on Linux, for possibly even better accuracy,  but  OSX
+       doesn't have these (and I want to be portable).
+
+       If  this were a truly useful application, it would be worth trying to decrease
+       latency further, with realtime process scheduling. I didn't  do  this  because
+       slowbaud  is  just  a toy, and because the RT stuff tends to be unportable and
+       require elevated privileges (root, or something like  setrtlimit  or  extended
+       filesystem attributes to manage capabilities).
+
+       About  the  name...  I'm  aware that "baud" is not synonymous with bps. I just
+       think "slowbaud" sounds better than "slowbps", as a name. Anyway the stty com‐
+       mand on Linux misuses the term ("speed 38400 baud"), so I'm in good company.
 
 BUGS
-       With -c, signals aren't handled gracefully. Window size changes (SIGWINCH)  don't  get
-       propagated to the child process, and pressing ^C doesn't interrupt the process. Yet.
+       With  -c,  signals  aren't  handled gracefully. Window size changes (SIGWINCH)
+       don't get propagated to the child process, and pressing ^C  doesn't  interrupt
+       the process. Yet.
 
 COPYRIGHT
-       slowbaud  is  copyright 2021, B. Watson <yalhcru@gmail.com>. Released under the WTFPL.
-       See http://www.wtfpl.net/txt/copying/ for details.
+       slowbaud  is copyright 2021, B. Watson <yalhcru@gmail.com>. Released under the
+       WTFPL. See http://www.wtfpl.net/txt/copying/ for details.
 
-0.0.1                                     2021-07-21                              SLOWBAUD(1)
+0.0.1                                 2021-07-21                          SLOWBAUD(1)