From afcaf14599cc82deeb321129382600521ec8e869 Mon Sep 17 00:00:00 2001 From: "B. Watson" Date: Fri, 14 Nov 2025 04:52:27 -0500 Subject: Tweak man page. --- src/unalf.1 | 35 ++++++++++++++++++++++++++--------- src/unalf.rst | 37 +++++++++++++++++++++++++++---------- 2 files changed, 53 insertions(+), 19 deletions(-) diff --git a/src/unalf.1 b/src/unalf.1 index 040a94e..7cc8aab 100644 --- a/src/unalf.1 +++ b/src/unalf.1 @@ -36,7 +36,7 @@ unalf \- extract Atari 8-bit ALF archives . .SH SYNOPSIS .sp -unalf [\fB\-aetklLopqv\fP] [\fB\-d\fP \fIdir\fP] [\fB\-x\fP \fIwildcard\fP] \fIalf\-file\fP [\fIwildcard\fP ...] +unalf [\fB\-aetklLopqtv\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. @@ -59,6 +59,9 @@ below for details. 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. +.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). .TP .BI \-a\fB a Convert line endings in all extracted files. This will corrupt any @@ -100,6 +103,10 @@ 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 \-t +Test archive. Same as extraction, except the files are not written +anywhere. +.TP .B \-v Verbose listing of archive contents, with compressed and original sizes, compression ration, date/time stamps, and checksum. The @@ -136,14 +143,14 @@ Unlike the Atari, matching is case\-insensitive. 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 +.B \fBthis 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 +.B \fBnot 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 +.B \fBjunk 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. @@ -153,14 +160,23 @@ 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\fP +.B \fBchecksum error on\fP \fI\fP The archive is corrupt. If \fI\fP is a text file, it may be partially readable. If it\(aqs an executable or other binary file, it\(aqs probably unrecoverable. +.TP +.B \fBstack underrun/overrun\fP +Generally means the archive is corrupt. Valid ALF files should never +cause these errors. +.sp +If you have an ALF file that does this, try it +with the Atari \fBUNALF14.COM\fP and see if it has the same problem. +If it does, you\(aqve found a bug in \fBunalf\fP, please send me the +\&.alf file via email (see \fBAUTHOR\fP, below). .UNINDENT .SH NOTES .sp -This \fBunalf\fP is 100% compatible with the original Atari \fBUNALF.COM\fP +This \fBunalf\fP is 100% compatible with the original Atari \fBUNALF14.COM\fP aka \fBDZ.COM\fP, with the following differences: .INDENT 0.0 .IP \(bu 2 @@ -169,19 +185,20 @@ 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 or testing the contents of an archive -without extracting it. +without extracting it, plus other handy features such as extracting +to standard output and text file EOL conversion. .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 +Neither this \fBunalf\fP nor \fBUNALF14.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 +.SH AUTHOR .INDENT 0.0 .IP B. 3 Watson <\fI\%urchlay@slackware.uk\fP> diff --git a/src/unalf.rst b/src/unalf.rst index 9eaa0ad..a1cfb7e 100644 --- a/src/unalf.rst +++ b/src/unalf.rst @@ -20,7 +20,7 @@ extract Atari 8-bit ALF archives SYNOPSIS ======== -unalf [**-aetklLopqv**] [**-d** *dir*] [**-x** *wildcard*] *alf-file* [*wildcard* ...] +unalf [**-aetklLopqtv**] [**-d** *dir*] [**-x** *wildcard*] *alf-file* [*wildcard* ...] DESCRIPTION =========== @@ -47,6 +47,9 @@ OPTIONS files are detected by name: **\*.txt**, **\*.doc**, **\*.lst** files are considered text. + Note that *only* line-endings are converted. Other ATASCII characters + are left alone. If you need anything more in-depth, use **a8cat**\(1). + -aa Convert line endings in all extracted files. This will corrupt any executables or non-text data files, so use with caution. @@ -87,6 +90,10 @@ OPTIONS and warnings will still be printed. This is the default when **-p** is used. +-t + Test archive. Same as extraction, except the files are not written + anywhere. + -v Verbose listing of archive contents, with compressed and original sizes, compression ration, date/time stamps, and checksum. The @@ -128,14 +135,14 @@ DIAGNOSTICS Besides the standard error messages such as "no such file or directory": -**unalf: this is an ARC file, not ALF** +**this is an ARC file, not ALF** Self-explanatory. Use the **arc**\(1) utility for this file. -**unalf: not an ALF file** +**not an ALF file** Self-explanatory. Either the file is too small (less than 29 bytes) or its first two bytes don't match the *ALF* signature **0x1a** **0x0f**\. -**unalf: junk at EOF (ignored)** +**junk at EOF (ignored)** 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. @@ -145,15 +152,24 @@ Besides the standard error messages such as "no such file or directory": you know that this .alf file can't be appended to by the **ALF.COM** aka **LZ.COM** Atari utility. -**unalf: checksum error on** ** +**checksum error on** ** The archive is corrupt. If ** is a text file, it may be partially readable. If it's an executable or other binary file, it's probably unrecoverable. +**stack underrun/overrun** + Generally means the archive is corrupt. Valid ALF files should never + cause these errors. + + If you have an ALF file that does this, try it + with the Atari **UNALF14.COM** and see if it has the same problem. + If it does, you've found a bug in **unalf**, please send me the + .alf file via email (see **AUTHOR**, below). + NOTES ===== -This **unalf** is 100% compatible with the original Atari **UNALF.COM** +This **unalf** is 100% compatible with the original Atari **UNALF14.COM** aka **DZ.COM**, with the following differences: - There is no interactive mode. The file to extract must be given as @@ -161,12 +177,13 @@ aka **DZ.COM**, with the following differences: with the **-d** option. - This **unalf** is capable of listing or testing the contents of an archive - without extracting it. + without extracting it, plus other handy features such as extracting + to standard output and text file EOL conversion. - Turning the screen off for speed makes no sense on modern operating systems, so there's no option for that. -Neither this **unalf** nor **UNALF.COM** actually use the dates/times +Neither this **unalf** nor **UNALF14.COM** actually use the dates/times stored in the archive. Extracted files will have their timestamps set to the current date/time. @@ -175,8 +192,8 @@ COPYRIGHT **unalf** is released under the WTPFL: Do WTF you want with this. -AUTHORS -======= +AUTHOR +====== B. Watson -- cgit v1.2.3