From c5e0c30599a49c15ce85034a96393429bee5c77c Mon Sep 17 00:00:00 2001 From: "B. Watson" Date: Thu, 18 Jul 2024 06:53:45 -0400 Subject: listbas: tweak doc. --- listbas.1 | 68 +++++++++++++++++++++++++++++++++++++++++---------------- listbas.rst | 72 +++++++++++++++++++++++++++++++++++++++++++++++++------------ 2 files changed, 108 insertions(+), 32 deletions(-) diff --git a/listbas.1 b/listbas.1 index 126f00c..002ca8d 100644 --- a/listbas.1 +++ b/listbas.1 @@ -27,7 +27,7 @@ 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 "LISTBAS" 1 "2024-07-17" "0.2.1" "Urchlay's Atari 8-bit Tools" +.TH "LISTBAS" 1 "2024-07-18" "0.2.1" "Urchlay's Atari 8-bit Tools" .SH NAME listbas \- List the source of a tokenized Atari 8-bit BASIC program .SH SYNOPSIS @@ -50,7 +50,7 @@ as an external process. To override this, see the \fB\-b\fP option, below. .INDENT 0.0 .TP .B \fB\-b\fP -Set the BASIC dialect the program was written in. This disables +Set the BASIC dialect the program will be treated as. This disables autodetection. Supported dialects are: .INDENT 7.0 .TP @@ -70,10 +70,7 @@ OSS BASIC XL. OSS BASIC XE. .UNINDENT .sp -If you see lots of "bad token XX" messages, or if the code just doesn\(aqt -make any sense, you\(aqre using the wrong BASIC option. \fBwhichbas\fP(1) -can usually detect the BASIC a program was written in, but if the -results are ambiguous, \fBlistbas\fP will assume Turbo BASIC XL. +See \fBBASIC DIALECTS\fP below for details. .TP .B \fB\-i\fP Include the immediate mode command (line 32768) in the output. @@ -84,7 +81,8 @@ Do not print line numbers at the start of each line. \fBGOTO\fP, \fBGOSUB\fP, .TP .B \fB\-t\fP Do not indent, if the program is Turbo BASIC, BASIC/A+, BASIC XL, or BASIC XE. -If you want to indent an Atari BASIC program, use \fB\-bt\fP or \fB\-bxl\fP\&. +By default, indentation is enabled for everything but Atari BASIC. +If you want to indent an Atari BASIC program, use \fB\-bt\fP or \fB\-bxe\fP\&. .TP .B \fB\-k\fP Do not print keywords in mixed case (e.g. \fBPrint\fP, \fBGraphics\fP), @@ -161,6 +159,30 @@ Print version number and exit. Verbose operation. When displaying a number in verbose mode, it will be prefixed with \fI$\fP if it\(aqs in hex, or no prefix for decimal. .UNINDENT +.SH BASIC DIALECTS +.sp +Note that Turbo, BASIC XL, and BASIC XE are all proper supersets of +Atari BASIC, so you can view an Atari BASIC program with any of +\fB\-bt\fP, \fB\-bxl\fP, or \fB\-bxe\fP\&. Also, BASIC XE is a superset of BASIC XL +(provided BASIC XL\(aqs disk\-based toolkit extended commands are not used), +so you can usually use \fB\-bxe\fP on a BASIC XL program. +.sp +BASIC/A+ uses incompatible tokens, so its programs can\(aqt be viewed as +any of the others. Trying to do this results in a very funny\-looking +listing, with commands like \fBPOSITION\fP with no arguments (or with a +string argument, or \fBPOSITION #6;"string"\fP; it so happens A+ uses the +same token number for \fBPOSITION\fP that the other BASICs use for +\fB?\fP). The same thing would happen if you booted BASIC/A+ on an Atari +and tried to \fBLOAD\fP an Atari BASIC program. I can\(aqt help but think +this is a major reason BASIC/A+ didn\(aqt sell that well (fortunately, +OSS realized their mistake and fixed it in BASIC XL). +.sp +If you see lots of "bad token XX" messages, or if the code +just doesn\(aqt make any sense, you\(aqre using the wrong BASIC +option. \fBwhichbas\fP(1) can usually detect the BASIC a program was +written in, but if the results are ambiguous, \fBlistbas\fP will assume +Turbo BASIC XL. If this is wrong, use \fB\-bxl\fP or \fB\-bxe\fP to force +the issue. .SH COLORS .sp Color output only works on terminal emulators (or real terminals) @@ -244,20 +266,29 @@ So, the default color scheme is equivalent to: Black and white are not used by default because presumably, one or the other is the background color of the terminal. .SH NOTES +.SS Indentation .sp -So far, \fBlistbas\fP doesn\(aqt support the indentation that BASIC A+/XL/XE -do by default. It acts like \fBSET 12,0\fP has been executed... though -BASIC A+ doesn\(aqt actually \fIhave\fP this option, and the indentation can\(aqt -be turned off in A+ at all. +The indentation isn\(aqt all that well\-tested yet, but so far it seems work +correctly. The \fB\-t\fP option is the equivalent of \fB*L\-\fP for Turbo, +or \fBSET 12,0\fP for BXL/BXE. The different BASICs have different +indentation rules; try viewing the same Atari BASIC program with +\fB\-bt\fP, \fB\-bxl\fP, and \fB\-bxe\fP to compare them. .sp -\-\- +\fBlistbas \-t\fP is also (as far as I know) the only way to \fBLIST\fP +a BASIC/A+ program without indentation, since BASIC/A+ itself doesn\(aqt +have a way to disable it. +.sp +Turbo BASIC, at least, will "max out" the indentation level at some +point. Once there are 60 or so levels of indent, it stops adding +more. \fBlistbas\fP doesn\(aqt emulate this behaviour (shouldn\(aqt be a +problem, it\(aqs a pathological case). +.SS Protected Programs .sp \fBlistbas\fP will refuse to operate on a LIST\-protected program with scrambled variable names. For code\-protected programs, it will stop at the line with the invalid offset. Use \fBunprotbas\fP(1) to remove the protection. -.sp -\-\- +.SS Comparison to chkbas .sp \fBlistbas\fP is similar to Jindroush\(aqs \fBchkbas\fP(1). The main differences are: .INDENT 0.0 @@ -269,6 +300,9 @@ looks very similar to how it would appear on the Atari. .IP \(bu 2 \fBlistbas\fP supports OSS BASIC/A+ in addition to Turbo and BXL/BXE. .IP \(bu 2 +\fBlistbas\fP indents BASIC/A+, Turbo, BXL, and BXE code, just like the +actual BASICs do. +.IP \(bu 2 \fBlistbas\fP doesn\(aqt show information about the variables. Use \fBvxrefbas\fP(1) for that. .IP \(bu 2 @@ -286,8 +320,7 @@ specifically asked to do so. on variable\-protected programs. For code\-protected programs, it lists the program up to the "poisoned" line (normally the last line). .UNINDENT -.sp -\-\- +.SS Terminal Support .sp The color and inverse/bold/underline support assumes your terminal supports ANSI/VT220 escape codes... but it does \fInot\fP use \fBcurses\fP(3X) or @@ -331,8 +364,7 @@ Wayland. \fBlistbas\fP was only tested on X11. Also, \fBrxvt\fP and \fBaterm\fP don\(aqt support Unicode, but they will otherwise work (display color and inverse) with the \fB\-m\fP or \fB\-d\fP options to \fBlistbas\fP\&. -.sp -\-\- +.SS HTML Output .sp I thought about adding an HTML output option, but there\(aqs no need: if you want a colorful listing of an Atari BASIC program, install \fBaha\fP(1) from diff --git a/listbas.rst b/listbas.rst index a32f5c2..cb905c4 100644 --- a/listbas.rst +++ b/listbas.rst @@ -34,7 +34,7 @@ BASIC options ------------- **-b** - Set the BASIC dialect the program was written in. This disables + Set the BASIC dialect the program will be treated as. This disables autodetection. Supported dialects are: **-ba** @@ -52,10 +52,7 @@ BASIC options **-bxe** OSS BASIC XE. - If you see lots of "bad token XX" messages, or if the code just doesn't - make any sense, you're using the wrong BASIC option. **whichbas**\(1) - can usually detect the BASIC a program was written in, but if the - results are ambiguous, **listbas** will assume Turbo BASIC XL. + See **BASIC DIALECTS** below for details. **-i** Include the immediate mode command (line 32768) in the output. @@ -66,7 +63,8 @@ BASIC options **-t** Do not indent, if the program is Turbo BASIC, BASIC/A+, BASIC XL, or BASIC XE. - If you want to indent an Atari BASIC program, use **-bt** or **-bxl**. + By default, indentation is enabled for everything but Atari BASIC. + If you want to indent an Atari BASIC program, use **-bt** or **-bxe**. **-k** Do not print keywords in mixed case (e.g. **Print**, **Graphics**), @@ -132,6 +130,31 @@ Other display options .. include:: genopts.rst +BASIC DIALECTS +============== +Note that Turbo, BASIC XL, and BASIC XE are all proper supersets of +Atari BASIC, so you can view an Atari BASIC program with any of +**-bt**, **-bxl**, or **-bxe**. Also, BASIC XE is a superset of BASIC XL +(provided BASIC XL's disk-based toolkit extended commands are not used), +so you can usually use **-bxe** on a BASIC XL program. + +BASIC/A+ uses incompatible tokens, so its programs can't be viewed as +any of the others. Trying to do this results in a very funny-looking +listing, with commands like **POSITION** with no arguments (or with a +string argument, or **POSITION #6;"string"**; it so happens A+ uses the +same token number for **POSITION** that the other BASICs use for +**?**). The same thing would happen if you booted BASIC/A+ on an Atari +and tried to **LOAD** an Atari BASIC program. I can't help but think +this is a major reason BASIC/A+ didn't sell that well (fortunately, +OSS realized their mistake and fixed it in BASIC XL). + +If you see lots of "bad token XX" messages, or if the code +just doesn't make any sense, you're using the wrong BASIC +option. **whichbas**\(1) can usually detect the BASIC a program was +written in, but if the results are ambiguous, **listbas** will assume +Turbo BASIC XL. If this is wrong, use **-bxl** or **-bxe** to force +the issue. + COLORS ====== @@ -211,19 +234,35 @@ other is the background color of the terminal. NOTES ===== -So far, **listbas** doesn't support the indentation that BASIC A+/XL/XE -do by default. It acts like **SET 12,0** has been executed... though -BASIC A+ doesn't actually *have* this option, and the indentation can't -be turned off in A+ at all. --- +Indentation +----------- + +The indentation isn't all that well-tested yet, but so far it seems work +correctly. The **-t** option is the equivalent of **\*L\ -** for Turbo, +or **SET 12,0** for BXL/BXE. The different BASICs have different +indentation rules; try viewing the same Atari BASIC program with +**-bt**, **-bxl**, and **-bxe** to compare them. + +**listbas -t** is also (as far as I know) the only way to **LIST** +a BASIC/A+ program without indentation, since BASIC/A+ itself doesn't +have a way to disable it. + +Turbo BASIC, at least, will "max out" the indentation level at some +point. Once there are 60 or so levels of indent, it stops adding +more. **listbas** doesn't emulate this behaviour (shouldn't be a +problem, it's a pathological case). + +Protected Programs +------------------ **listbas** will refuse to operate on a LIST-protected program with scrambled variable names. For code-protected programs, it will stop at the line with the invalid offset. Use **unprotbas**\(1) to remove the protection. --- +Comparison to chkbas +-------------------- **listbas** is similar to Jindroush's **chkbas**\(1). The main differences are: @@ -234,6 +273,9 @@ protection. - **listbas** supports OSS BASIC/A+ in addition to Turbo and BXL/BXE. +- **listbas** indents BASIC/A+, Turbo, BXL, and BXE code, just like the + actual BASICs do. + - **listbas** doesn't show information about the variables. Use **vxrefbas**\(1) for that. @@ -251,7 +293,8 @@ protection. on variable-protected programs. For code-protected programs, it lists the program up to the "poisoned" line (normally the last line). --- +Terminal Support +---------------- The color and inverse/bold/underline support assumes your terminal supports ANSI/VT220 escape codes... but it does *not* use **curses**\(3X) or @@ -293,7 +336,8 @@ Also, **rxvt** and **aterm** don't support Unicode, but they will otherwise work (display color and inverse) with the **-m** or **-d** options to **listbas**. --- +HTML Output +----------- I thought about adding an HTML output option, but there's no need: if you want a colorful listing of an Atari BASIC program, install **aha**\(1) from -- cgit v1.2.3