From 997fb1bf0878cb6a455abec1d9d399cd5fcb0b44 Mon Sep 17 00:00:00 2001 From: "B. Watson" Date: Tue, 11 Mar 2025 05:17:56 -0400 Subject: listamsb: add -k option, reorganize man page. --- listamsb.rst | 91 ++++++++++++++++++++++++++++++++++++++---------------------- 1 file changed, 58 insertions(+), 33 deletions(-) (limited to 'listamsb.rst') 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 =========== -- cgit v1.2.3