diff options
Diffstat (limited to 'listbas.1')
| -rw-r--r-- | listbas.1 | 385 |
1 files changed, 345 insertions, 40 deletions
@@ -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 "LISTBAS" 1 "2024-07-05" "0.2.1" "Urchlay's Atari 8-bit Tools" +.TH "LISTBAS" 1 "2024-07-24" "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 .sp -listbas [\fB\-v\fP] [\fB\-i\fP] [\fB\-a\fP | \fB\-m\fP ] \fBinput\-file\fP +listbas [\fB\-a\fP | \fB\-d\fP | \fB\-m\fP | \fB\-x\fP | \fB\-U\fP] [\fB\-B\fP] [\fB\-u\fP] [\fB\-i\fP] [\fB\-l\fP] [\fB\-n\fP | \fB\-C\fP] [\fB\-v\fP] [\fB\-c\fP \fIcolors\fP] [\fB\-r\fP \fIline\-range\fP] \fBinput\-file\fP .SH DESCRIPTION .sp \fBlistbas\fP acts like the \fILIST\fP command in BASIC. It reads a @@ -41,27 +41,120 @@ format. .sp By default, output is Unicode in UTF\-8 encoding, with ANSI/VT220 escape sequences for inverse video and color syntax highlighting. +.sp +\fBlistbas\fP supports several BASIC dialects used on the Atari. By +default, the BASIC dialect is autodetected by running \fBwhichbas\fP(1) +as an external process. To override this, see the \fB\-b\fP option, below. .SH OPTIONS -.SS List options +.SS BASIC options .INDENT 0.0 .TP -.B \fB\-a\fP -Output raw ATASCII; no translation to the host character set. Must be -used with redirection; \fBlistbas\fP will not write ATASCII to the terminal. -.TP .B \fB\-b\fP -Use bold, for color output. This may make it easier to read on -some terminals. Or, it may hurt your eyes... +Set the BASIC dialect the program will be treated as. This disables +autodetection. Supported dialects are: +.INDENT 7.0 +.TP +.B \fB\-ba\fP +Atari BASIC. +.TP +.B \fB\-ba+\fP +OSS BASIC/A+. +.TP +.B \fB\-bt\fP +Turbo BASIC XL. +.TP +.B \fB\-bxl\fP +OSS BASIC XL. +.TP +.B \fB\-bxe\fP +OSS BASIC XE. +.UNINDENT +.sp +See \fBBASIC DIALECTS\fP below 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\-separated pair of starting and ending line numbers (e.g. \fB100,200\fP). +If the start line number is omitted (e.g. \fB,100\fP), it will be treated as +\fB0\fP (meaning, list from the beginning of the program). If the ending line +number is omitted (e.g. \fB100,\fP), it means "list until the end of the program". +\fB\-r,\fP is equivalent to not using the \fB\-r\fP option at all. .TP .B \fB\-i\fP -Include the immediate mode command (line 32768) in the output. +Include the immediate mode command (line 32768) in the output. This option has no +effect if the \fB\-r\fP option is used to stop listing before the end of the program. +.TP +.B \fB\-l\fP +Do not print line numbers at the start of each line. \fBGOTO\fP, \fBGOSUB\fP, +\fBTRAP\fP, and \fBTHEN\fP target line numbers are still printed. +.TP +.B \fB\-t\fP +Do not indent, if the program is Turbo BASIC, BASIC/A+, BASIC XL, or BASIC XE. +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), +for BASIC XL or BASIC XE. Equivalent of \fBSET 5,0\fP\&. +.UNINDENT +.SS Output modes +.sp +The default output mode is Unicode/UTF\-8 representations of ATASCII +characters. +.INDENT 0.0 +.TP +.B \fB\-U\fP +Output Unicode/UTF\-8 representations of ATASCII characters. This is +the default output mode; the \fB\-U\fP option is provided so you can +override \fB\-a\fP, \fB\-d\fP, \fB\-m\fP, \fB\-x\fP in \fBLISTBAS_OPTS\fP (see +\fBENVIRONMENT\fP, below). +.TP +.B \fB\-x\fP +Output Unicode/UTF\-8 representations of the XL International Character +Set, rather than ATASCII. +.TP +.B \fB\-a\fP +Output raw ATASCII; no translation to the host character set. Must be +used with redirection or a pipe; \fBlistbas\fP will not write ATASCII to the terminal. +ATASCII output does not support color (because ATASCII doesn\(aqt). .TP .B \fB\-m\fP -Output "magazine listing". See the \fB\-m\fP option for \fBa8cat\fP for details. +Output "magazine listing". See the \fB\-m\fP option for \fBa8cat\fP(1) for details. +Color is supported in this mode. No Unicode/UTF\-8 characters are printed in +this mode. +.TP +.B \fB\-d\fP +Print dots rather than Unicode/UTF\-8 characters. Color and inverse +video are still supported in this mode, but no Unicode/UTF8 characters +are printed. Use this only if your terminal \fIreally\fP doesn\(aqt support +Unicode (e.g. \fBrxvt\fP(1))... but even then, \fB\-m\fP is preferred, +because you can\(aqt tell what the dots are supposed to represent. +.UNINDENT +.SS Other display options +.INDENT 0.0 +.TP +.B \fB\-C\fP +Enable color syntax highlighting. This option is enabled by default; +the \fB\-C\fP option is provided so you can override \fB\-n\fP in +\fBLISTBAS_OPTS\fP (see \fBENVIRONMENT\fP, below). .TP .B \fB\-n\fP -No color. Has no effect if \fB\-a\fP or \fB\-m\fP are in effect, since these -modes don\(aqt support color anyway. +No color. Has no effect if \fB\-a\fP is in effect, since this +mode doesn\(aqt support color anyway. Disabling color does not +disable reverse video. +.TP +.B \fB\-B\fP +Use bold for color output. This may make it easier to read on +some terminals. Or, it may hurt your eyes... +.TP +.B \fB\-u\fP +Use underlining for inverse video, rather than reverse video output. +.TP +.B \fB\-c\fP \fIcolors\fP +Customize the color scheme. See \fBCOLORS\fP, below, for the format of the +\fIcolors\fP argument. Once you\(aqve found a set of colors you like, +you can place this option in the \fBLISTBAS_OPTS\fP environment variable +to use your colors by default. See \fBENVIRONMENT\fP, below. .UNINDENT .SS General Options .INDENT 0.0 @@ -76,48 +169,184 @@ 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) that support ANSI/VT220 style escape codes. This includes all modern -terminal emulators, and most not\-so\-modern ones in the UNIX world. +terminal emulators, and most not\-so\-modern ones in the UNIX world. See +\fBNOTES\fP for a list of tested terminal emulators. +.sp +You can customize the colors by using the \fB\-c\fP \fIcolors\fP option, either +on the command line, or in the \fBLISTBAS_OPTS\fP environment variable. +\fIcolors\fP is a string of exactly 8 characters, each of which must be the +digits \fI0\fP through \fI7\fP to specify a color, or the letter \fIn\fP to specify +no color. +.sp +The colors are the standard ANSI ones, plus \fIn\fP: +.INDENT 0.0 +.TP +.B \fI0\fP +Black. +.TP +.B \fI1\fP +Red. +.TP +.B \fI2\fP +Green. +.TP +.B \fI3\fP +Yellow (or brown/orange, on some terminals). +.TP +.B \fI4\fP +Blue. +.TP +.B \fI5\fP +Purple (aka violet). +.TP +.B \fI6\fP +Cyan. +.TP +.B \fI7\fP +White. +.TP +.B \fIn\fP +No custom color. Output will be in the terminal\(aqs default foreground color. +.UNINDENT .sp -The color scheme is: +The order they\(aqre used in the \fIcolors\fP argument is: .INDENT 0.0 .TP -.B \fByellow\fP -Commands. Also "command operators" such as the \fBGOTO\fP in \fBON/GOTO\fP and -the \fBSTEP\fP in a \fBFOR\fP command. These are really operators as far as -BASIC is concerned, but it makes more sense to colorize them as commands. +.B \fB1\fP +BASIC keywords. Default: \fI3\fP (yellow). +.TP +.B \fB2\fP +Operators, including quotes around strings and commas between \fBDATA\fP items. Default: \fI2\fP (green). .TP -.B \fBgreen\fP -Operators (except functions and "command operators"). +.B \fB3\fP +Functions. Default: \fI5\fP (purple). .TP -.B \fBpurple\fP -Functions. +.B \fB4\fP +Constants (numeric or string). Default: \fI1\fP (red). .TP -.B \fBred\fP -Numbers (except line numbers at the start of a line) and string -constants. +.B \fB5\fP +Line numbers (at the start of a line only; \fBGOTO\fP and \fBGOSUB\fP line numbers +are constants). Default: \fI6\fP (cyan). .TP -.B \fBcyan\fP -Line numbers at the start of a line, comments (\fBREM\fP text) and \fBDATA\fP elements. +.B \fB6\fP +\fBREM\fP text. Default: \fI4\fP (blue). +.TP +.B \fB7\fP +\fBDATA\fP items (but not the commas between them). Default: \fI6\fP (cyan). +.TP +.B \fB8\fP +Variable names. Default: \fIn\fP (uncolorized). .UNINDENT .sp -Variable names and commas between \fBDATA\fP elements are not highlighted, -so they\(aqll appear in the default foreground color (usually white if the -terminal has a black background, or black if the background is white). +So, the default color scheme is equivalent to: +.INDENT 0.0 +.INDENT 3.5 +\fB\-c\fP \fI3251646n\fP +.UNINDENT +.UNINDENT .sp -Note that nothing is highlighted in blue. This is because it\(aqs -difficult to read on many terminals. Also, black and white are not -used because presumably, one or the other is the background color of -the terminal. +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 +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). +.sp +BASIC XL actually does indentation within a line. If you write: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +10 IF A:IF B:IF C:REM +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\&...BXL lists it as: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +10 If A: If B: If C:Rem +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fBlistbas\fP only indents at the start of a line, so this behaviour is +not emulated. +.sp +One thing \fBlistbas\fP gets right: the \fBLIST\fP command in Turbo, A+, +BXL, and BXE always starts out with 0 indent spaces, if you\(aqre only +listing part of a program. BXE example: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +10 While 1 +20 If Peek(764)<>255 +30 ? "SOMEONE PRESSED A KEY":Poke 764,255 +40 Endif +50 Endwhile +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\&...but if you give a \fBLIST 30\fP in BXE, you\(aqll get line 30 without any +indentation. \fBlistbas\fP does this, too, if you use the \fB\-r\fP option. +.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. +.SS Comparison to chkbas .sp \fBlistbas\fP is similar to Jindroush\(aqs \fBchkbas\fP(1). The main differences are: .INDENT 0.0 @@ -127,13 +356,16 @@ looks very similar to how it would appear on the Atari. .IP \(bu 2 \fBlistbas\fP does color syntax highlighting. .IP \(bu 2 -\fBlistbas\fP only supports Atari BASIC, not Turbo BASIC or BASIC XL/XE. +\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 -\fBlistbas\fP will not write ATASCII data to your terminal. By default, it uses -\fBa8cat\fP(1) to convert the output to something human\-readable +\fBlistbas\fP will not write ATASCII data to your terminal. By default, it +converts ATASCII characters into Unicode/UTF\-8 characters that won\(aqt confuse the terminal. When outputting raw ATASCII (\fB\-a\fP option), it refuses to run if standard output is a terminal. .IP \(bu 2 @@ -143,9 +375,55 @@ specifically asked to do so. \fBlistbas\fP doesn\(aqt print a banner on startup. .IP \(bu 2 \fBlistbas\fP tells you if the program is protected, and refuses to operate -on variable\-protected programs. +on variable\-protected programs. For code\-protected programs, it lists +the program up to the "poisoned" line (normally the last line). +.UNINDENT +.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 +\fBterminfo\fP(5), or even look at \fBTERM\fP in the environment. It just +blindly emits the escape codes. Likewise, Unicode characters are printed +in UTF\-8 encoding, without actually checking whether the terminal or the +current locale supports UTF\-8. +.sp +\fBlistbas\fP has been tested and is known to work in at least these +terminals: +.INDENT 0.0 +.INDENT 3.5 +\fBrxvt\-unicode\fP, aka \fBurxvt\fP\&. This is the terminal the author uses. +.sp +\fBxterm\fP \- tested frequently. Requires the XTerm.locale resource +to be set to \fBUTF\-8\fP (e.g. in \fB~/.Xdefaults\fP), or the \fB\-lc\fP +and/or \fB\-en UTF\-8\fP command line options. +.sp +\fBLinux console\fP \- works fine, but good luck finding a font with +all the Unicode graphics characters. Better use \fB\-m\fP\&. +.sp +\fBkitty\fP \- very fancy terminal emulator that supports both X11 and +Wayland. \fBlistbas\fP was only tested on X11. +.sp +\fBxfce4\-terminal\fP \- version 0.8.10, with XFCE4 4.16.0. +.sp +\fBkonsole\fP \- the KDE terminal, from KDE 5.90. +.sp +\fBgnome\-terminal\fP \- version 3.43.90. +.sp +\fBst\fP \- minimal terminal from suckless.org, version 0.9.2. +.sp +\fBmlterm\fP \- version 3.9.3. +.sp +\fBkmscon\fP \- version 9.0.0. \fI\%https://github.com/Aetf/kmscon\fP +.sp +\fBfbterm\fP \- version 1.8. \fI\%https://github.com/sfzhi/fbterm\fP +.UNINDENT .UNINDENT .sp +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\&. +.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 \fI\%https://github.com/theZiz/aha\fP (or your distro\(aqs package repo) and run @@ -160,6 +438,29 @@ listbas PROGRAM.BAS | aha > program.html .fi .UNINDENT .UNINDENT +.SH ENVIRONMENT +.INDENT 0.0 +.TP +.B \fBLISTBAS_OPTS\fP +If this environment variable is set, \fBlistbas\fP parses its value as though +the contents were placed on the command line as options, preceding any actual +option. Example: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +export LISTBAS_OPTS="\-c123456 \-d" +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +If you place the above line in your shell\(aqs startup script, \fBlistbas\fP will +use your custom color scheme, and will default to the "dots" output mode. If +you then run \fBlistbas\fP the \fB\-c\fP and/or \fB\-x\fP, \fB\-m\fP options, the options +on the command line will override the environment. +.UNINDENT .SH EXIT STATUS .sp 0 for success, 1 if there was an error reading the input (e.g. file @@ -181,11 +482,13 @@ Watson <\fI\%urchlay@slackware.uk\fP>; Urchlay on irc.libera.chat \fI##atari\fP\ \fBatr2xfd\fP(1), \fBatrsize\fP(1), \fBaxe\fP(1), +\fBbas2aplus\fP(1), \fBblob2c\fP(1), \fBblob2xex\fP(1), \fBcart2xex\fP(1), \fBcxrefbas\fP(1), \fBdasm2atasm\fP(1), +\fBdiffbas\fP(1), \fBdumpbas\fP(1), \fBf2toxex\fP(1), \fBfenders\fP(1), @@ -196,13 +499,15 @@ Watson <\fI\%urchlay@slackware.uk\fP>; Urchlay on irc.libera.chat \fI##atari\fP\ \fBunmac65\fP(1), \fBunprotbas\fP(1), \fBvxrefbas\fP(1), +\fBwhichbas\fP(1), \fBxex1to2\fP(1), \fBxexamine\fP(1), \fBxexcat\fP(1), \fBxexsplit\fP(1), \fBxfd2atr\fP(1), \fBxex\fP(5), -\fBatascii\fP(7). +\fBatascii\fP(7), +\fBfauxtari\fP(7). .sp Any good Atari 8\-bit book: \fIDe Re Atari\fP, \fIThe Atari BASIC Reference Manual\fP, the \fIOS Users\(aq Guide\fP, \fIMapping the Atari\fP, etc. |