Generate usage message from comments in the .rst.

1 files changed, 69 insertions, 0 deletions

diff --git a/src/unalf.1 b/src/unalf.1
index 7cc8aab..99ed684 100644
--- a/src/unalf.1
+++ b/src/unalf.1
@@ -62,50 +62,100 @@ are considered text.
 .sp
 Note that \fIonly\fP line\-endings are converted. Other ATASCII characters
 are left alone. If you need anything more in\-depth, use \fBa8cat\fP(1).
+.UNINDENT
+.\" convert EOLs in text files.
+.
+.INDENT 0.0
 .TP
 .BI \-a\fB a
 Convert line endings in all extracted files. This will corrupt any
 executables or non\-text data files, so use with caution.
+.UNINDENT
+.\" convert EOLs in ALL files.
+.
+.INDENT 0.0
 .TP
 .BI \-d \ output\-dir
 Write extracted files to this directory, which will be created if it
 does not exist. The default is the current directory.
+.UNINDENT
+.\" set output directory (created if needed).
+.
+.INDENT 0.0
 .TP
 .B  \-e
 Extract files. This is actually a no\-op, as extraction is the
 default action.
+.UNINDENT
+.\" extract files (redundant; this is the default action).
+.
+.INDENT 0.0
 .TP
 .B  \-k
 Keep trailing periods. In most (all?) ALF files, filenames that have no
 extension are stored with a trailing period, e.g. \(aq\fBFOO\fP\(aq would
 be stored as \(aq\fBFOO.\fP\(aq. By default, \fBunalf\fP removes the trailing
 period; use \fB\-k\fP to keep it.
+.UNINDENT
+.\" keep trailing periods (dots) in filenames.
+.
+.INDENT 0.0
 .TP
 .B  \-l
 List filenames in archive, one per line, but do not extract. Use
 \fB\-v\fP for more information (file size, etc).
+.UNINDENT
+.\" list files in archive (filenames only).
+.
+.INDENT 0.0
 .TP
 .B  \-L
 Lowercase filesnames. Example: \fBFOO.TXT\fP will extract to \fBfoo.txt\fP\&.
+.UNINDENT
+.\" use lowercase filenames.
+.
+.INDENT 0.0
 .TP
 .B  \-o
 Overwrite files, if they already exist. The default is to rename
 existing files, adding a \fB~\fP suffix. Note that renaming \fBfile\fP
 to \fBfile~\fP \fIwill\fP overwrite \fBfile~\fP if it already exists.
+.UNINDENT
+.\" overwrite files (do not create file~ backups).
+.
+.INDENT 0.0
 .TP
 .B  \-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. \fB\-q\fP is automatically enabled by this option.
+.sp
+\fIWarning:\fP 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.
+.UNINDENT
+.\" extract to stdout (enables -q).
+.
+.INDENT 0.0
 .TP
 .B  \-q
 Quiet extraction: do not print "Uncrunching \fIfile\fP" messages. Errors
 and warnings will still be printed. This is the default when \fB\-p\fP
 is used.
+.UNINDENT
+.\" quiet: don't print filenames during extraction.
+.
+.INDENT 0.0
 .TP
 .B  \-t
 Test archive. Same as extraction, except the files are not written
 anywhere.
+.UNINDENT
+.\" test archive.
+.
+.INDENT 0.0
 .TP
 .B  \-v
 Verbose listing of archive contents, with compressed and original
@@ -114,12 +164,18 @@ output format is similar to that of \fBarc \-v\fP, minus the \fIStowage\fP
 column, since \fIALF\fP doesn\(aqt support multiple compression types. The
 date and time are displayed, but in most .alf files these are the
 default values of "8 Jan 82  12:24a".
+.UNINDENT
+.\" verbose listing of archive contents.
+.
+.INDENT 0.0
 .TP
 .BI \-x \ wildcard
 Exclude (do not list or extract) files matching \fIwildcard\fP\&. See
 \fBWILDCARDS\fP below. This option can be given multiple times
 to exclude multiple patterns.
 .UNINDENT
+.\" exclude <wildcard>. may be given multiple times.
+.
 .SH WILDCARDS
 .sp
 Wildcard (aka glob) matching works like it does on the Atari: \fI*.*\fP
@@ -135,6 +191,19 @@ ignored: \fBFOO*BAR.TXT\fP is equivalent to \fBFOO*.TXT\fP, and
 equivalent to \fBFOO*\fP, and \fIwill not\fP match the file \fBFOO.TXT\fP\&.
 .sp
 Unlike the Atari, matching is case\-insensitive.
+.sp
+To avoid your shell trying to expand the wildcards, always quote them!
+Example:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+unalf filename.alf \(aq*.txt\(aq
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
 .SH EXIT STATUS
 .sp
 \fB0\fP for success, \fB1\fP for failure.