initial commit

1 files changed, 136 insertions, 0 deletions

diff --git a/src/unalf.1 b/src/unalf.1
new file mode 100644
index 0000000..3ed769b
--- /dev/null
+++ b/src/unalf.1
@@ -0,0 +1,136 @@
+.\" 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 "UNALF" 1 "2025-11-12" "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:
+.
+.\" rst2man.py unalf.rst > unalf.1
+.
+.SH SYNOPSIS
+.sp
+unalf [\fB\-l\fP] \fBalf\-file\fP
+.SH DESCRIPTION
+.sp
+\fBunalf\fP lists or extracts the contents of an \fIALF\fP archive.
+.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.
+.sp
+Extracted files are written to the current directory. Existing files
+are overwritten without warning.
+.SH OPTIONS
+.sp
+For compatibility with \fBarc\fP(1) usage, the \fB\-\fP in front of
+option letters is optional.
+.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".
+.TP
+.B  \-v
+Same as \fB\-l\fP\&.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \fB\-e\fP, \fB\-x\fP
+Extract files. This is actually a no\-op, as extraction is the
+default action.
+.UNINDENT
+.SH EXIT STATUS
+.sp
+\fB0\fP for success, \fB1\fP for failure.
+.SH DIAGNOSTICS
+.sp
+Besides the standard error messages such as "no such file or directory":
+.INDENT 0.0
+.TP
+.B \fBunalf: this is an ARC file, not ALF\fP
+Self\-explanatory. Use the \fBarc\fP(1) utility for this file.
+.TP
+.B \fBunalf: not an ALF file\fP
+Self\-explanatory. Either the file is too small (less than 29 bytes)
+or its first two bytes don\(aqt match the \fIALF\fP signature \fB0x1a\fP \fB0x0f\fP\&.
+.TP
+.B \fBunalf: junk at EOF (ignored)\fP
+Usually this is caused by the .alf file being stored on a CP/M disk
+at some time, or by a dumb file transfer protocol. Either way, the
+file gets padded to the block size of the filesystem or protocol.
+Usually, the padding characters are \fB0x1a\fP, aka ASCII control\-Z.
+.sp
+If you see this message, you can ignore it. It\(aqs intended to let
+you know that this .alf file can\(aqt be appended to by the \fBALF.COM\fP
+aka \fBLZ.COM\fP Atari utility.
+.TP
+.B \fBunalf: checksum error on\fP \fI<file>\fP
+The archive is corrupt. If \fI<file>\fP is a text file, it may be
+partially readable. If it\(aqs an executable or other binary file, it\(aqs
+probably unrecoverable.
+.UNINDENT
+.SH NOTES
+.sp
+This \fBunalf\fP is 100% compatible with the original Atari \fBUNALF.COM\fP
+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.
+.IP \(bu 2
+This \fBunalf\fP is capable of listing the contents of an archive
+without extracting it.
+.IP \(bu 2
+Turning the screen off for speed makes no sense on modern operating
+systems, so there\(aqs no option for that.
+.UNINDENT
+.sp
+Neither this \fBunalf\fP nor \fBUNALF.COM\fP actually use the dates/times
+stored in the archive. Extracted files will have their timestamps set
+to the current date/time.
+.SH COPYRIGHT
+.sp
+\fBunalf\fP is released under the WTPFL: Do WTF you want with this.
+.SH AUTHORS
+.INDENT 0.0
+.IP B. 3
+Watson <\fI\%urchlay@slackware.uk\fP>
+.UNINDENT
+.SH SEE ALSO
+.sp
+TODO
+.\" Generated by docutils manpage writer.
+.