listbas: do Unicode/magazine internally (no external a8cat); add color syntax highlighting and options related to it.

1 files changed, 52 insertions, 8 deletions

diff --git a/listbas.rst b/listbas.rst
index d6d17b1..d7f5d26 100644
--- a/listbas.rst
+++ b/listbas.rst
@@ -20,12 +20,8 @@ DESCRIPTION
 tokenized (SAVEd) BASIC program and prints the code in human-readable
 format.
 
-By default, output is piped through **a8cat**\(1), to covert ATASCII
-characters into Unicode equivalents. Raw ATASCII and "magazine listing"
-mode are also available.
-
-**a8cat** is run as an external processe. The executables is 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
 =======
@@ -33,6 +29,10 @@ OPTIONS
 List options
 ------------
 
+**-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.
 
@@ -40,12 +40,51 @@ List options
   Output raw ATASCII; no translation to the host character set. Must be
   used with redirection; **listbas** will not write ATASCII to the terminal.
 
+**-n**
+  No color. Has no effect if **-a** or **-m** are in effect, since these
+  modes don't support color anyway.
+
 **-m**
-  Output "magazine listing". Pipes output through **a8cat -m**; see the man
-  page for **a8cat** for details.
+  Output "magazine listing". See the **-m** option for **a8cat** for details.
 
 .. 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,6 +95,11 @@ 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)