Add command-line options.

1 files changed, 80 insertions, 23 deletions

diff --git a/src/unalf.1 b/src/unalf.1
index 3ed769b..040a94e 100644
--- a/src/unalf.1
+++ b/src/unalf.1
@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "UNALF" 1 "2025-11-12" "0.0.0" "Urchlay's Atari 8-bit Tools"
+.TH "UNALF" 1 "2025-11-14" "0.0.0" "Urchlay's Atari 8-bit Tools"
 .SH NAME
 unalf \- extract Atari 8-bit ALF archives
 .\" RST source for unalf(1) man page. Convert with:
@@ -36,7 +36,7 @@ unalf \- extract Atari 8-bit ALF archives
 .
 .SH SYNOPSIS
 .sp
-unalf [\fB\-l\fP] \fBalf\-file\fP
+unalf [\fB\-aetklLopqv\fP] [\fB\-d\fP \fIdir\fP] [\fB\-x\fP \fIwildcard\fP] \fIalf\-file\fP [\fIwildcard\fP ...]
 .SH DESCRIPTION
 .sp
 \fBunalf\fP lists or extracts the contents of an \fIALF\fP archive.
@@ -45,30 +45,89 @@ unalf [\fB\-l\fP] \fBalf\-file\fP
 not compatible with it. It was used on the Atari 8\-bit platform
 beginning in the late 1980s.
 .sp
-Extracted files are written to the current directory. Existing files
-are overwritten without warning.
-.SH OPTIONS
+Extracted files are written to the current directory by
+default. Existing files are backed up by default (by adding a \fB~\fP
+suffix to the filename).
 .sp
-For compatibility with \fBarc\fP(1) usage, the \fB\-\fP in front of
-option letters is optional.
+If one or more \fBwildcard\fP arguments are provided, files will only be
+listed or extracted if they match one of the wildcards. See \fBWILDCARDS\fP
+below for details.
+.SH OPTIONS
 .INDENT 0.0
 .TP
-.B  \-l
-List contents of archive, but do not extract. The 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".
+.B  \-a
+Convert text file line endings from Atari EOL to UNIX newline. Text
+files are detected by name: \fB*.txt\fP, \fB*.doc\fP, \fB*.lst\fP files
+are considered text.
 .TP
-.B  \-v
-Same as \fB\-l\fP\&.
-.UNINDENT
-.INDENT 0.0
+.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.
 .TP
-.B \fB\-e\fP, \fB\-x\fP
+.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.
+.TP
+.B  \-e
 Extract files. This is actually a no\-op, as extraction is the
 default action.
+.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.
+.TP
+.B  \-l
+List filenames in archive, one per line, but do not extract. Use
+\fB\-v\fP for more information (file size, etc).
+.TP
+.B  \-L
+Lowercase filesnames. Example: \fBFOO.TXT\fP will extract to \fBfoo.txt\fP\&.
+.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.
+.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.
+.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.
+.TP
+.B  \-v
+Verbose listing of archive contents, with compressed and original
+sizes, compression ration, date/time stamps, and checksum.  The
+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".
+.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
+.SH WILDCARDS
+.sp
+Wildcard (aka glob) matching works like it does on the Atari: \fI*.*\fP
+matches any filename (whether or not it has an extension), and \fI*\fP
+or \fI*.\fP only match filenames with no extension.
+.sp
+A \fI*\fP matches any number of characters (including zero). A \fI?\fP
+matches a single character.
+.sp
+Like the Atari, anything in the name or extension following a \fI*\fP is
+ignored: \fBFOO*BAR.TXT\fP is equivalent to \fBFOO*.TXT\fP, and
+\fBFOO.T*T\fP is equivalent to \fBFOO.T*\fP\&. \fBFOO*TXT\fP is
+equivalent to \fBFOO*\fP, and \fIwill not\fP match the file \fBFOO.TXT\fP\&.
+.sp
+Unlike the Atari, matching is case\-insensitive.
 .SH EXIT STATUS
 .sp
 \fB0\fP for success, \fB1\fP for failure.
@@ -106,12 +165,10 @@ aka \fBDZ.COM\fP, with the following differences:
 .INDENT 0.0
 .IP \(bu 2
 There is no interactive mode. The file to extract must be given as
-a command\-line argument.
-.IP \(bu 2
-Files are always extracted to the current directory. The original
-\fBUNALF.COM\fP accepted a 2nd argument or prompted for the output directory.
+a command\-line argument, and the output directory must be given
+with the \fB\-d\fP option.
 .IP \(bu 2
-This \fBunalf\fP is capable of listing the contents of an archive
+This \fBunalf\fP is capable of listing or testing the contents of an archive
 without extracting it.
 .IP \(bu 2
 Turning the screen off for speed makes no sense on modern operating