path: root/src/alf.1

.\" 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.
.sp
The \fBALF\fP file format only supports uppercase "8.3" filenames
(Atari DOS or MS\-DOS style), and does not support subdirectories. The
filenames you give will be stored in the \fBALF\fP file uppercased
and truncated to fit the 8.3 scheme. This could result in duplicate
filenames in the archive, if you\(aqre not careful.
.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. If \fIalf\-file\fP doesn\(aqt exist, it will be created.
.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
.SS Compatibility
.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.
.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
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.
.SS File Size Limits
.sp
\fBalf\fP (and \fBLZ.COM\fP) have a 16MB file size limit. \fBuanlf\fP
actually can\(aqt handle files above about 15MB, if you compress one with
\fBalf\fP\&. Real Atari 8\-bit files are never this large anyway, so it\(aqs
a pathological case. A real Atari would take hours or even days to
compress/decompress such files, and you\(aqd have to have a hard disk and
a DOS capable of handling multi\-megabyte files...
.sp
It\(aqs also impossible to compress empty (0\-byte) files. \fBalf\fP will
skip them, if any are found.
.SS Performance
.sp
Performance is \fIhorrible\fP\&. This shouldn\(aqt be a real problem on
modern multi\-GHz CPU, especially since most Atari 8\-bit files are
small (usually under 64KB). Interestingly, it\(aqs not O(n^2), it scales
linearly, O(1): Compressing a 1.3MB text file takes 0.7 seconds on the
author\(aqs (rather modest) Intel i7 workstation, and a file 10x as large
takes approximately 10x as long (7 seconds). A 50KB file is almost
instantaneous, 0.05 seconds, which is more typical of the files you\(aqd
actually use this with.
.SS Timestamps
.sp
The date/time stamps stored in the archive are the \fBmtime\fPs of
the files (which is the same time \fBls\fP(1) shows, by default), and
your local timezone is assumed. Only a 2\-digit year is displayed by
\fBunalf\fP, but the year stored in the \fIALF\fP file doesn\(aqt have a Y2K
problem. It does, however, have a Y2108 problem...
.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.
.