Add alf man page.

4 files changed, 238 insertions, 2 deletions

diff --git a/src/Makefile b/src/Makefile
index 7a992e9..d09d8dc 100644
--- a/src/Makefile
+++ b/src/Makefile
@@ -45,7 +45,7 @@ ALF_OBJS=alf.o
 
 .PHONY: all clean install crosswin windows windows-upload realclean
 
-all: unalf unalf.1 alfsum alfsum.1 alf
+all: unalf unalf.1 alfsum alfsum.1 alf alf.1
 
 # unalf and alfsum need explicit rules for BSD make compatibility.
 # without them, bmake tries to run "cc -o unalf unalf.c" which ain't
diff --git a/src/alf.1 b/src/alf.1
new file mode 100644
index 0000000..eb5b0b7
--- /dev/null
+++ b/src/alf.1
@@ -0,0 +1,129 @@
+.\" Man page generated from reStructuredText.
+.
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.TH "ALF" 1 "2025-11-26" "0.2.0" "Urchlay's Atari 8-bit Tools"
+.SH NAME
+alf \- create Atari 8-bit ALF archives
+.\" RST source for alf(1) man page. Convert with:
+.
+.\" rst2man.py alf.rst > alf.1
+.
+.SH SYNOPSIS
+.sp
+alf [\fB\-\-help\fP] [\fB\-a\fP | \fB\-o\fP ] \fIalf\-file\fP \fIfile\fP [\fIfile\fP ...]
+.SH DESCRIPTION
+.sp
+\fBalf\fP creates \fIALF\fP archives.
+.sp
+\fIALF\fP is a compressed archive format similar to \fBarc\fP(1), though
+not compatible with it. It was used on the Atari 8\-bit platform
+beginning in the late 1980s. The Atari executables are \fBLZ.COM\fP
+for the compressor and \fBDZ.COM\fP for the decompressor. \fBalf\fP is a
+rewrite of \fBLZ.COM\fP for modern operating systems, with added features.
+.sp
+By default, the \fIalf\-file\fP is created, and the \fIfile\fPs are compressed
+and added to it. If \fIalf\-file\fP already existed, it is backed up by adding
+a \fB~\fP to the filename.
+.SH OPTIONS
+.INDENT 0.0
+.TP
+.B  \-a
+Append to \fIalf\-file\fP\&. The files are added to the end of the archive. Be
+careful not to add a file with the same name as as existing member of
+the archive.
+.TP
+.B  \-o
+Overwrite \fIalf\-file\fP if it exists; do not make a \fB~\fP backup.
+.UNINDENT
+.SH EXIT STATUS
+.INDENT 0.0
+.TP
+.B 0
+Success.
+.TP
+.B 1
+Fatal error (I/O or bad command\-line arguments).
+.UNINDENT
+.SH NOTES
+.sp
+This \fBalf\fP is \fIintended\fP to be 100% compatible with the original
+Atari \fBLZ.COM\fP aka \fBALF.COM\fP, with the following differences:
+.INDENT 0.0
+.IP \(bu 2
+There is no interactive mode. The file to create and the files to add
+must be given as command\-line arguments.
+.IP \(bu 2
+\fBLZ.COM\fP always appends to a file that already exists. This \fBalf\fP
+overwrites (making a backup) by default, and can append with the \fB\-a\fP
+option.
+.UNINDENT
+.sp
+Note that \fBalf\fP is a complete reverse\-engineered rewrite in C, \fInot\fP
+a port of the original 6502 code as \fBunalf\fP is. It\(aqs still being
+tested, and may still contain bugs.
+.sp
+Performance is \fIhorrible\fP, O(n^2) or worse. This shouldn\(aqt be a real
+problem on modern multi\-GHz CPU, especially since most Atari 8\-bit
+files are small (usually under 64KB). Compressing a 1.3MB text file
+takes 5 seconds on the author\(aqs (rather modest) Intel i7 workstation.
+A 50KB file takes 0.2 seconds, which is more typical of the files
+you\(aqd actually use this with.
+.SH COPYRIGHT
+.sp
+The original AlfCrunch (\fBDZ.COM\fP and \fBLZ.COM\fP) for the Atari 8\-bit
+was released into the Public Domain. \fBalf\fP contains no code from
+AlfCrunch.
+.sp
+\fBalf\fP is released under the WTPFL: Do WTF you want with this.
+.SH AUTHOR
+.sp
+The original AlfCrunch for the Atari 8\-bit was written by Alfred, who
+can be reached via the AtariAge.com forums with the username "Alfred".
+.sp
+This \fBalf\fP was written by B. Watson <\fI\%urchlay@slackware.uk\fP>.
+.SH SEE ALSO
+.sp
+\fBunalf\fP(1), \fBalfls\fP(1)
+.sp
+The git repository for \fBunalf\fP:
+.INDENT 0.0
+.INDENT 3.5
+\fI\%https://slackware.uk/~urchlay/repos/unalf\fP
+.UNINDENT
+.UNINDENT
+.sp
+Other Atari\-related projects by the author, including \fBbw\-atari8\-tools\fP
+and \fBunmac65\fP:
+.INDENT 0.0
+.INDENT 3.5
+\fI\%https://slackware.uk/~urchlay/repos/\fP
+.UNINDENT
+.UNINDENT
+.\" Generated by docutils manpage writer.
+.
diff --git a/src/alf.rst b/src/alf.rst
new file mode 100644
index 0000000..fbfd2c6
--- /dev/null
+++ b/src/alf.rst
@@ -0,0 +1,107 @@
+.. RST source for alf(1) man page. Convert with:
+..   rst2man.py alf.rst > alf.1
+
+.. include:: ver.rst
+
+.. |date| date::
+
+===
+alf
+===
+
+-------------------------------
+create Atari 8-bit ALF archives
+-------------------------------
+
+:Manual section: 1
+:Manual group: Urchlay's Atari 8-bit Tools
+:Date: |date|
+:Version: |version|
+
+SYNOPSIS
+========
+
+alf [**--help**] [**-a** | **-o** ] *alf-file* *file* [*file* ...]
+
+DESCRIPTION
+===========
+
+**alf** creates *ALF* archives.
+
+*ALF* is a compressed archive format similar to **arc**\(1), though
+not compatible with it. It was used on the Atari 8-bit platform
+beginning in the late 1980s. The Atari executables are **LZ.COM**
+for the compressor and **DZ.COM** for the decompressor. **alf** is a
+rewrite of **LZ.COM** for modern operating systems, with added features.
+
+By default, the *alf-file* is created, and the *file*\s are compressed
+and added to it. If *alf-file* already existed, it is backed up by adding
+a **~** to the filename.
+
+OPTIONS
+=======
+
+-a
+  Append to *alf-file*. The files are added to the end of the archive. Be
+  careful not to add a file with the same name as as existing member of
+  the archive.
+
+-o
+  Overwrite *alf-file* if it exists; do not make a **~** backup.
+
+EXIT STATUS
+===========
+
+0
+  Success.
+
+1
+  Fatal error (I/O or bad command-line arguments).
+
+NOTES
+=====
+
+This **alf** is *intended* to be 100% compatible with the original
+Atari **LZ.COM** aka **ALF.COM**, with the following differences:
+
+- There is no interactive mode. The file to create and the files to add
+  must be given as command-line arguments.
+
+- **LZ.COM** always appends to a file that already exists. This **alf**
+  overwrites (making a backup) by default, and can append with the **-a**
+  option.
+
+Note that **alf** is a complete reverse-engineered rewrite in C, *not*
+a port of the original 6502 code as **unalf** is. It's still being
+tested, and may still contain bugs.
+
+Performance is *horrible*, O(n^2) or worse. This shouldn't be a real
+problem on modern multi-GHz CPU, especially since most Atari 8-bit
+files are small (usually under 64KB). Compressing a 1.3MB text file
+takes 5 seconds on the author's (rather modest) Intel i7 workstation.
+A 50KB file takes 0.2 seconds, which is more typical of the files
+you'd actually use this with.
+
+COPYRIGHT
+=========
+
+The original AlfCrunch (**DZ.COM** and **LZ.COM**) for the Atari 8-bit
+was released into the Public Domain. **alf** contains no code from
+AlfCrunch.
+
+**alf** is released under the WTPFL: Do WTF you want with this.
+
+AUTHOR
+======
+
+The original AlfCrunch for the Atari 8-bit was written by Alfred, who
+can be reached via the AtariAge.com forums with the username "Alfred".
+
+This **alf** was written by B. Watson <urchlay@slackware.uk>.
+
+SEE ALSO
+========
+
+**unalf**\(1), **alfls**\(1)
+
+.. include:: manftr.rst
diff --git a/src/unalf.1 b/src/unalf.1
index b8a0566..59709ee 100644
--- a/src/unalf.1
+++ b/src/unalf.1
@@ -372,7 +372,7 @@ can be reached via the AtariAge.com forums with the username "Alfred".
 This \fBunalf\fP was written by B. Watson <\fI\%urchlay@slackware.uk\fP>.
 .SH SEE ALSO
 .sp
-\fBalfls\fP(1)
+\fBalf\fP(1), \fBalfls\fP(1)
 .sp
 The git repository for \fBunalf\fP:
 .INDENT 0.0