listamsb: add -k option, reorganize man page.

1 files changed, 58 insertions, 33 deletions

diff --git a/listamsb.rst b/listamsb.rst
index 902319b..dac3c1e 100644
--- a/listamsb.rst
+++ b/listamsb.rst
@@ -11,7 +11,7 @@ List the source of a tokenized Atari Microsoft BASIC program
 SYNOPSIS
 ========
 
-listamsb [**-l**] | [**-C**] | [**-D**] | [[**-a**\] [**-c**] [**-v**\] [**-h**\] [**-i**\] [**-u**\] [**-t**\] [**-m**\] [**-n**\] [**-s**\] ...] [**-r** *line-range*] [**input-file**\] [**output-file**\]
+listamsb [**-U**] | [**-C**] | [**-D**] | [[**-L**] [**-a**] [**-c**] [**-v**] [**-h**] [**-i**] [**-u**] [**-t**] [**-m**] [**-n**] [**-s**] [**-r** *line-range*] ...] [**input-file**] [**output-file**]
 
 DESCRIPTION
 ===========
@@ -33,7 +33,7 @@ input is read from **stdin**.
 
 Programs created with *SAVE "filename" LOCK* are autodetected,
 and will be listed normally. It's also possible to convert a LOCKed
-program to an unencrypted one, with the **-l** option.
+program to an unencrypted one, with the **-U** option.
 
 Programs can be "crunched" and "decrunched" with the **-C** and **-D**
 options.
@@ -43,36 +43,64 @@ If no **output-file** is given, output is to **stdout**.
 OPTIONS
 =======
 
-**-a**
-  Output raw ATASCII. This option must be used with an
-  **output-file**, a pipe, or redirection: **listamsb** will not write
-  ATASCII to a terminal. **a8cat** is not used, with this option.
+Operation Modes
+---------------
 
-**-c**
-  Check only. No output on stdout. Diagnostics are still printed on stderr,
-  and the exit status is unchanged. It's an error to give an **output-file** with
-  this option.
+**-L**
+  LIST program. This is the default, so there's no need to give this option
+  normally. See next section for options that control the listing.
 
 **-C**
   "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't 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.
+
+  If any comment-only lines are the target of GOTO or GOSUB, the
+  program won't RUN correctly because all comment-only lines are
+  removed. If this happens, you can use the **-k** option (see below).
 
   This option must be used with an **output-file**, since seeking is done.
   None of the other options have any effect with **-C**.
 
 **-D**
   "Decrunch" a crunched program. Puts spaces where they're required for
-  AMSB's parser. The result will be editable in AMSB. Of course, any
-  comments that were removed during crunching will not magically be
-  retored (they're gone).
+  AMSB's 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're gone).
 
   This option must be used with an **output-file**, since seeking is done.
   None of the other options have any effect with **-D**.
 
+**-U**
+  UnLOCK or LOCK the the program. Locked programs are created with
+  *SAVE "filename" LOCK*. 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).
+
+  This option must be used with an **output-file**, a pipe, or
+  redirection: **listamsb** will not write tokenized BASIC to a
+  terminal. None of the other options have any effect with **-U**.
+
+Options for **-L** (list) Mode
+------------------------------
+
+None of these options have any effect when used with **-C**, **-D**,
+or **-U**.
+
+**-a**
+  Output raw ATASCII. This option must be used with an
+  **output-file**, a pipe, or redirection: **listamsb** will not write
+  ATASCII to a terminal. **a8cat** is not used, with this option.
+
+**-c**
+  Check only. No output on stdout. Diagnostics are still printed on stderr,
+  and the exit status is unchanged. It's an error to give an **output-file** with
+  this option.
+
+**-i**\, **-u**\, **-t**\, **-m**\, **-s**
+  These options are passed to **a8cat**. See its man page for details.
+
 **-r** *line-range*
   Show only part of the listing. *line-range* can be a single line, or
   a comma- or hyphen-separated pair of starting and ending line numbers (e.g. **100,200**, or
@@ -83,21 +111,22 @@ OPTIONS
   number is omitted (e.g. **100,**), it means "list until the end of the program".
   **-r,** or **-r-** is equivalent to not using the **-r** option at all.
 
-**-l**
-  "Lock" or "unlock" the program. Locked programs are created with
-  *SAVE "filename" LOCK*. 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).
-
-  This option must be used with an **output-file**, a pipe, or
-  redirection: **listamsb** will not write tokenized BASIC to a
-  terminal. **a8cat** is not used, with this option.  None of the
-  other options have any effect with **-l**.
-
 **-n**
   No empty line. By default, **listamsb** prints an empty line at the
   start of the output, to match AMSB's LIST command.
 
+Options for **-C** (crunch) Mode
+--------------------------------
+
+**-k**
+  Keep comment-only lines. Normally these are removed. If the program
+  gives UNDEF'D LINE ERROR, it means the target line was a comment-only
+  line that got removed. With **-k**, these lines will be kept, although
+  the actual comments won't (*10 REM HELLO* will become *10 REM*).
+
+Utility Options
+---------------
+
 **-v**
   Verbose output, on **stderr**. May be given twice for extra verbosity,
   which shows each line number, its offset, length, and end-of-line pointer.
@@ -108,10 +137,6 @@ OPTIONS
 **--version**
   Print version number and exit.
 
-**-i**\, **-u**\, **-t**\, **-m**\, **-s**
-  These options are passed to **a8cat**. See its man page for details. If
-  any of the **-a**, **-c**, or **-l** options are used, these options have no effect.
-
 DIAGNOSTICS
 ===========