listamsb: add -k option, reorganize man page.

1 files changed, 58 insertions, 35 deletions

diff --git a/listamsb.1 b/listamsb.1
index f1b34e0..e8d95a6 100644
--- a/listamsb.1
+++ b/listamsb.1
@@ -27,12 +27,12 @@ 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 "LISTAMSB" 1 "2025-03-08" "0.2.1" "Urchlay's Atari 8-bit Tools"
+.TH "LISTAMSB" 1 "2025-03-11" "0.2.1" "Urchlay's Atari 8-bit Tools"
 .SH NAME
 listamsb \- List the source of a tokenized Atari Microsoft BASIC program
 .SH SYNOPSIS
 .sp
-listamsb [\fB\-l\fP] | [\fB\-C\fP] | [\fB\-D\fP] | [[\fB\-a\fP] [\fB\-c\fP] [\fB\-v\fP] [\fB\-h\fP] [\fB\-i\fP] [\fB\-u\fP] [\fB\-t\fP] [\fB\-m\fP] [\fB\-n\fP] [\fB\-s\fP] ...] [\fB\-r\fP \fIline\-range\fP] [\fBinput\-file\fP] [\fBoutput\-file\fP]
+listamsb [\fB\-U\fP] | [\fB\-C\fP] | [\fB\-D\fP] | [[\fB\-L\fP] [\fB\-a\fP] [\fB\-c\fP] [\fB\-v\fP] [\fB\-h\fP] [\fB\-i\fP] [\fB\-u\fP] [\fB\-t\fP] [\fB\-m\fP] [\fB\-n\fP] [\fB\-s\fP] [\fB\-r\fP \fIline\-range\fP] ...] [\fBinput\-file\fP] [\fBoutput\-file\fP]
 .SH DESCRIPTION
 .sp
 \fBlistamsb\fP acts like the \fILIST\fP command in Atari Microsoft BASIC. It reads a
@@ -52,45 +52,71 @@ input is read from \fBstdin\fP\&.
 .sp
 Programs created with \fISAVE "filename" LOCK\fP are autodetected,
 and will be listed normally. It\(aqs also possible to convert a LOCKed
-program to an unencrypted one, with the \fB\-l\fP option.
+program to an unencrypted one, with the \fB\-U\fP option.
 .sp
 Programs can be "crunched" and "decrunched" with the \fB\-C\fP and \fB\-D\fP
 options.
 .sp
 If no \fBoutput\-file\fP is given, output is to \fBstdout\fP\&.
 .SH OPTIONS
+.SS Operation Modes
 .INDENT 0.0
 .TP
-.B \fB\-a\fP
-Output raw ATASCII. This option must be used with an
-\fBoutput\-file\fP, a pipe, or redirection: \fBlistamsb\fP will not write
-ATASCII to a terminal. \fBa8cat\fP is not used, with this option.
-.TP
-.B \fB\-c\fP
-Check only. No output on stdout. Diagnostics are still printed on stderr,
-and the exit status is unchanged. It\(aqs an error to give an \fBoutput\-file\fP with
-this option.
+.B \fB\-L\fP
+LIST program. This is the default, so there\(aqs no need to give this option
+normally. See next section for options that control the listing.
 .TP
 .B \fB\-C\fP
 "Crunch" program: remove comments and spaces that occur outside of a
-string. The resulting program is usually 5 to 10 percent smaller, and
-will RUN correctly, but will be difficult to edit in AMSB because its
-parser requires the spaces. Also, if any comment\-only lines are the
-target of GOTO or GOSUB, the program won\(aqt run because all comment\-only
-lines are removed.
+string. The resulting program is tokenized, and is usually 5 to 10
+percent smaller. It should RUN correctly, but will be difficult to
+edit in AMSB because its parser requires the spaces.
+.sp
+If any comment\-only lines are the target of GOTO or GOSUB, the
+program won\(aqt RUN correctly because all comment\-only lines are
+removed. If this happens, you can use the \fB\-k\fP option (see below).
 .sp
 This option must be used with an \fBoutput\-file\fP, since seeking is done.
 None of the other options have any effect with \fB\-C\fP\&.
 .TP
 .B \fB\-D\fP
 "Decrunch" a crunched program. Puts spaces where they\(aqre required for
-AMSB\(aqs parser. The result will be editable in AMSB. Of course, any
-comments that were removed during crunching will not magically be
-retored (they\(aqre gone).
+AMSB\(aqs parser. The resulting program is tokenized, and will be
+editable in AMSB. Of course, any comments that were removed during
+crunching will not magically be retored (they\(aqre gone).
 .sp
 This option must be used with an \fBoutput\-file\fP, since seeking is done.
 None of the other options have any effect with \fB\-D\fP\&.
 .TP
+.B \fB\-U\fP
+UnLOCK or LOCK the the program. Locked programs are created with
+\fISAVE "filename" LOCK\fP\&. The "encryption" is a reciprocal cipher: locking and
+unlocking are the same operation (similar to ROT13). The output will
+be the locked or unlocked tokenized program (rather than a listing).
+.sp
+This option must be used with an \fBoutput\-file\fP, a pipe, or
+redirection: \fBlistamsb\fP will not write tokenized BASIC to a
+terminal. None of the other options have any effect with \fB\-U\fP\&.
+.UNINDENT
+.SS Options for \fB\-L\fP (list) Mode
+.sp
+None of these options have any effect when used with \fB\-C\fP, \fB\-D\fP,
+or \fB\-U\fP\&.
+.INDENT 0.0
+.TP
+.B \fB\-a\fP
+Output raw ATASCII. This option must be used with an
+\fBoutput\-file\fP, a pipe, or redirection: \fBlistamsb\fP will not write
+ATASCII to a terminal. \fBa8cat\fP is not used, with this option.
+.TP
+.B \fB\-c\fP
+Check only. No output on stdout. Diagnostics are still printed on stderr,
+and the exit status is unchanged. It\(aqs an error to give an \fBoutput\-file\fP with
+this option.
+.TP
+.B \fB\-i\fP, \fB\-u\fP, \fB\-t\fP, \fB\-m\fP, \fB\-s\fP
+These options are passed to \fBa8cat\fP\&. See its man page for details.
+.TP
 .B \fB\-r\fP \fIline\-range\fP
 Show only part of the listing. \fIline\-range\fP can be a single line, or
 a comma\- or hyphen\-separated pair of starting and ending line numbers (e.g. \fB100,200\fP, or
@@ -101,20 +127,21 @@ If the start line number is omitted (e.g. \fB,100\fP), it will be treated as
 number is omitted (e.g. \fB100,\fP), it means "list until the end of the program".
 \fB\-r,\fP or \fB\-r\-\fP is equivalent to not using the \fB\-r\fP option at all.
 .TP
-.B \fB\-l\fP
-"Lock" or "unlock" the program. Locked programs are created with
-\fISAVE "filename" LOCK\fP\&. The "encryption" is a reciprocal cipher: locking and
-unlocking are the same operation (similar to ROT13). The output will
-be the locked or unlocked tokenized program (rather than a listing).
-.sp
-This option must be used with an \fBoutput\-file\fP, a pipe, or
-redirection: \fBlistamsb\fP will not write tokenized BASIC to a
-terminal. \fBa8cat\fP is not used, with this option.  None of the
-other options have any effect with \fB\-l\fP\&.
-.TP
 .B \fB\-n\fP
 No empty line. By default, \fBlistamsb\fP prints an empty line at the
 start of the output, to match AMSB\(aqs LIST command.
+.UNINDENT
+.SS Options for \fB\-C\fP (crunch) Mode
+.INDENT 0.0
+.TP
+.B \fB\-k\fP
+Keep comment\-only lines. Normally these are removed. If the program
+gives UNDEF\(aqD LINE ERROR, it means the target line was a comment\-only
+line that got removed. With \fB\-k\fP, these lines will be kept, although
+the actual comments won\(aqt (\fI10 REM HELLO\fP will become \fI10 REM\fP).
+.UNINDENT
+.SS Utility Options
+.INDENT 0.0
 .TP
 .B \fB\-v\fP
 Verbose output, on \fBstderr\fP\&. May be given twice for extra verbosity,
@@ -125,10 +152,6 @@ Print built\-in help and exit.
 .TP
 .B \fB\-\-version\fP
 Print version number and exit.
-.TP
-.B \fB\-i\fP, \fB\-u\fP, \fB\-t\fP, \fB\-m\fP, \fB\-s\fP
-These options are passed to \fBa8cat\fP\&. See its man page for details. If
-any of the \fB\-a\fP, \fB\-c\fP, or \fB\-l\fP options are used, these options have no effect.
 .UNINDENT
 .SH DIAGNOSTICS
 .sp