diff options
Diffstat (limited to 'listbas.rst')
| -rw-r--r-- | listbas.rst | 88 |
1 files changed, 71 insertions, 17 deletions
diff --git a/listbas.rst b/listbas.rst index c4a937a..881da5f 100644 --- a/listbas.rst +++ b/listbas.rst @@ -11,7 +11,7 @@ List the source of a tokenized Atari 8-bit BASIC program SYNOPSIS ======== -listbas [**-v**] [**-i**] [**-a** | **-u** ] **input-file** +listbas [**-v**] [**-i**] [**-a** | **-m** ] **input-file** DESCRIPTION =========== @@ -20,13 +20,8 @@ DESCRIPTION tokenized (SAVEd) BASIC program and prints the code in human-readable format. -By default, output is piped through **a8eol**\(1), to convert ATASCII -characters to human-readable sequences. Raw ATASCII and Unicode output -are also available. - -**a8eol**\(1) and **a8utf8**\(1) (for **-u**) are run as external -processes. The executables are searched for first in the current -directory, and then in *PATH*. +By default, output is Unicode in UTF-8 encoding, with ANSI/VT220 +escape sequences for inverse video and color syntax highlighting. OPTIONS ======= @@ -34,18 +29,62 @@ OPTIONS List options ------------ -**-i** - Include the immediate mode command (line 32768) in the output. - **-a** Output raw ATASCII; no translation to the host character set. Must be used with redirection; **listbas** will not write ATASCII to the terminal. -**-u** - Use **a8utf8**\(1) to translate ATASCII to ASCII. +**-b** + Use bold, for color output. This may make it easier to read on + some terminals. Or, it may hurt your eyes... + +**-i** + Include the immediate mode command (line 32768) in the output. + +**-m** + Output "magazine listing". See the **-m** option for **a8cat** for details. + +**-n** + No color. Has no effect if **-a** or **-m** are in effect, since these + modes don't support color anyway. .. include:: genopts.rst +COLORS +====== + +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. + +The color scheme is: + +**yellow** + Commands. Also "command operators" such as the **GOTO** in **ON/GOTO** and + the **STEP** in a **FOR** command. These are really operators as far as + BASIC is concerned, but it makes more sense to colorize them as commands. + +**green** + Operators (except functions and "command operators"). + +**purple** + Functions. + +**red** + Numbers (except line numbers at the start of a line) and string + constants. + +**cyan** + Line numbers at the start of a line, comments (**REM** text) and **DATA** elements. + +Variable names and commas between **DATA** elements are not highlighted, +so they'll appear in the default foreground color (usually white if the +terminal has a black background, or black if the background is white). + +Note that nothing is highlighted in blue. This is because it's +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. + NOTES ===== @@ -56,14 +95,20 @@ protection. **listbas** is similar to Jindroush's **chkbas**\(1). The main differences are: +- **listbas** prints ATASCII graphics as Unicode equivalents, so the listing + looks very similar to how it would appear on the Atari. + +- **listbas** does color syntax highlighting. + - **listbas** only supports Atari BASIC, not Turbo BASIC or BASIC XL/XE. - **listbas** doesn't show information about the variables. Use **vxrefbas**\(1) for that. -- **listbas** will not write ATASCII data to your terminal. Instead, it uses - **a8eol**\(1) or **a8utf8**\(1) to convert the output to something human-readable - that won't confuse the terminal. +- **listbas** will not write ATASCII data to your terminal. By default, it uses + **a8cat**\(1) to convert the output to something human-readable + that won't confuse the terminal. When outputting raw ATASCII (**-a** option), + it refuses to run if standard output is a terminal. - **listbas** only lists line 32768 (the immediate mode command) if specifically asked to do so. @@ -73,9 +118,18 @@ protection. - **listbas** tells you if the program is protected, and refuses to operate on variable-protected programs. +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 +https://github.com/theZiz/aha (or your distro's package repo) and run +something like:: + + listbas PROGRAM.BAS | aha > program.html + EXIT STATUS =========== -0 for success, 1 for failure. +0 for success, 1 if there was an error reading the input (e.g. file +not found), or 2 if the input file has invalid tokens (if this +happens, you will also see a warning about it on stderr). .. include:: manftr.rst |