Update docs

3 files changed, 162 insertions, 79 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)
diff --git a/slowbaud.1 b/slowbaud.1
index 7fcec1e..c25d8e9 100644
--- a/slowbaud.1
+++ b/slowbaud.1
@@ -38,28 +38,49 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .
 .SH SYNOPSIS
 .sp
-\fBslowbaud\fP \fI<bits\-per\-sec>\fP [\fI<file>\fP ...]
+\fBslowbaud\fP [\fI<bits\-per\-sec>\fP] [\fI<file>\fP ...]
 .sp
-\fBslowbaud\fP \fI<bits\-per\-sec>\fP \fB\-c\fP [\fI<command>\fP [\fI<arg>\fP ...]]
+\fBslowbaud\fP [\fI<bits\-per\-sec>\fP] \fB\-c\fP [\fI<command>\fP [\fI<arg>\fP ...]]
+.sp
+\fBslowbaud\fP [\fI<bits\-per\-sec>\fP] \fB\-e\fP \fI<string>\fP [\fI<string>\fP ...]
 .SH DESCRIPTION
 .sp
 slowbaud by default acts as a filter, or like the \fBcat(1)\fP 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.
+Input and output are unbuffered.
 .sp
-With the \fB\-c\fP option, it creates a pseudo\-tty and runs the given command
-in it (or an interactive shell, if no command is given).
+slowbaud can also act like \fBecho(1)\fP (the \fB\-e\fP option), or run an
+interactive command (the \fB\-c\fP option).
 .sp
-The \fI<bits\-per\-sec>\fP 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%
-accurate.
+The \fI<bits\-per\-sec>\fP argument is optional. If it\(aqs not given, the
+bit rate will be set from \fBSLOWBAUD_BPS\fP in the environment, or a
+built\-in default of 2400 if not set.
+.SH OPTIONS
+.INDENT 0.0
+.TP
+.B \fBbits\-per\-sec\fP
+The bit ("baud") rate to simulate. This must be the first argument.
+slowbaud assumes that if the first argument is a number, it\(aqs the bit rate.
+If you\(aqre trying to pass a filename that consists only of digits, give
+\fB\-\-\fP as the first argument, or use e.g. \fI\&./filename\fP\&.
+.TP
+.B \fB\-e\fP
+Echo mode. Prints all further arguments as strings to stdout, separated
+by a single space, at the given bit rate. Does not support backslash\-escapes, or any of
+the options of the regular \fBecho\fP command.
+.TP
+.B \fB\-c\fP
+Command mode. Next argument (if present) is the command to run, any remaining arguments
+become arguments to the command. With no arguments after \fB\-c\fP, a shell is spawned.
+This creates a pseudo\-tty, so the command can be interactive.
+.UNINDENT
 .SH ENVIRONMENT
 .INDENT 0.0
 .TP
+.B \fBSLOWBAUD_BPS\fP
+Can be used to set the bit rate, when no \fI<bits\-per\-sec>\fP argument is used.
+.TP
 .B \fBSLOWBAUD_DEBUG\fP
 Set this (to any value) in the environment to see verbose debug
 output on stderr, including timing accuracy stats.
@@ -80,6 +101,12 @@ the child process couldn\(aqt be spawned (e.g. command not found).
 Of course, the child process could also exit with status 127...
 .SH NOTES
 .sp
+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" 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 at least 99.7% accurate.
+.sp
 We can\(aqt really insert a delay between the bits of a byte, since
 I/O is done with byte granularity. For calculation purposes,
 \fI<bits\-per\-sec>\fP is divided by 10 to get bytes per second. This
diff --git a/slowbaud.rst b/slowbaud.rst
index 13e9e64..e88f890 100644
--- a/slowbaud.rst
+++ b/slowbaud.rst
@@ -21,9 +21,11 @@ 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>* ...]]
+
+**slowbaud** [*<bits-per-sec>*] **-e** *<string>* [*<string>* ...]
 
 DESCRIPTION
 ===========
@@ -31,21 +33,40 @@ 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.
+Input and output are unbuffered.
+
+slowbaud can also act like **echo(1)** (the **-e** option), or run an
+interactive command (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
+=======
 
-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).
+**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 digits, give
+    **--** as the first argument, or use e.g. *./filename*.
 
-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%
-accurate.
+**-e**
+    Echo mode. Prints all further arguments as strings to stdout, separated
+    by a single space, at the given bit rate. Does not support backslash-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 command 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.
@@ -69,6 +90,12 @@ Of course, the child process could also exit with status 127...
 NOTES
 =====
 
+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" 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 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