Generate usage message from comments in the .rst.

1 files changed, 36 insertions, 0 deletions

diff --git a/src/unalf.rst b/src/unalf.rst
index a1cfb7e..64a0be5 100644
--- a/src/unalf.rst
+++ b/src/unalf.rst
@@ -50,50 +50,78 @@ OPTIONS
   Note that *only* line-endings are converted. Other ATASCII characters
   are left alone. If you need anything more in-depth, use **a8cat**\(1).
 
+.. convert EOLs in text files.
+
 -aa
   Convert line endings in all extracted files. This will corrupt any
   executables or non-text data files, so use with caution.
 
+.. convert EOLs in ALL files.
+
 -d output-dir
   Write extracted files to this directory, which will be created if it
   does not exist. The default is the current directory.
 
+.. set output directory (created if needed).
+
 -e
   Extract files. This is actually a no-op, as extraction is the
   default action.
 
+.. extract files (redundant; this is the default action).
+
 -k
   Keep trailing periods. In most (all?) ALF files, filenames that have no
   extension are stored with a trailing period, e.g. '**FOO**' would
   be stored as '**FOO.**'. By default, **unalf** removes the trailing
   period; use **-k** to keep it.
 
+.. keep trailing periods (dots) in filenames.
+
 -l
   List filenames in archive, one per line, but do not extract. Use
   **-v** for more information (file size, etc).
 
+.. list files in archive (filenames only).
+
 -L
   Lowercase filesnames. Example: **FOO.TXT** will extract to **foo.txt**.
 
+.. use lowercase filenames.
+
 -o
   Overwrite files, if they already exist. The default is to rename
   existing files, adding a **~** suffix. Note that renaming **file**
   to **file~** *will* overwrite **file~** if it already exists.
 
+.. overwrite files (do not create file~ backups).
+
 -p
   Extract to standard output. All the files that get extracted will be
   printed to stdout with no delimiters, so this is most useful when
   only extracting one file. **-q** is automatically enabled by this option.
 
+  *Warning:* No checking is done to see whether stdout is a terminal.
+  Printing binary files to a terminal is a good way to make a mess.
+  Even text files with the EOLs translated can still contain ATASCII
+  formatting/graphics codes that can confuse your terminal. You have
+  been warned.
+
+.. extract to stdout (enables -q).
+
 -q
   Quiet extraction: do not print "Uncrunching *file*" messages. Errors
   and warnings will still be printed. This is the default when **-p**
   is used.
 
+.. quiet: don't print filenames during extraction.
+
 -t
   Test archive. Same as extraction, except the files are not written
   anywhere.
 
+.. test archive.
+
 -v
   Verbose listing of archive contents, with compressed and original
   sizes, compression ration, date/time stamps, and checksum.  The
@@ -102,12 +130,15 @@ OPTIONS
   date and time are displayed, but in most .alf files these are the
   default values of "8 Jan 82  12:24a".
 
+.. verbose listing of archive contents.
 
 -x wildcard
   Exclude (do not list or extract) files matching *wildcard*. See
   **WILDCARDS** below. This option can be given multiple times
   to exclude multiple patterns.
 
+.. exclude <wildcard>. may be given multiple times.
+
 WILDCARDS
 =========
 
@@ -125,6 +156,11 @@ equivalent to **FOO\***, and *will not* match the file **FOO.TXT**.
 
 Unlike the Atari, matching is case-insensitive.
 
+To avoid your shell trying to expand the wildcards, always quote them!
+Example::
+
+  unalf filename.alf '*.txt'
+
 EXIT STATUS
 ===========