aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorB. Watson <urchlay@slackware.uk>2024-07-18 06:53:45 -0400
committerB. Watson <urchlay@slackware.uk>2024-07-18 06:53:45 -0400
commitc5e0c30599a49c15ce85034a96393429bee5c77c (patch)
tree3b7c133548eefc874ac457d811846a8e461fba48
parent53d33d9a44e3609b1abab902f4a45001690df142 (diff)
downloadbw-atari8-tools-c5e0c30599a49c15ce85034a96393429bee5c77c.tar.gz
listbas: tweak doc.
-rw-r--r--listbas.168
-rw-r--r--listbas.rst72
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