listbas: make colors customizable (-c), add -U and -C options, add LISTBAS_OPTS environment variable.

1 files changed, 123 insertions, 19 deletions

diff --git a/listbas.rst b/listbas.rst
index 8321ab1..b3e4ca7 100644
--- a/listbas.rst
+++ b/listbas.rst
@@ -32,18 +32,27 @@ Output modes
 The default output mode is Unicode/UTF-8 representations of ATASCII
 characters.
 
+**-U**
+  Output Unicode/UTF-8 representations of ATASCII characters. This is
+  the default output mode; the **-U** option is provided so you can
+  override **-a**, **-d**, **-m**, **-x** in **LISTBAS_OPTS** (see
+  **ENVIRONMENT**, below).
+
 **-a**
   Output raw ATASCII; no translation to the host character set. Must be
   used with redirection; **listbas** will not write ATASCII to the terminal.
 
 **-d**
   Print dots rather than Unicode/UTF-8 characters. Color and inverse
-  video are still supported in this mode. Use this only if your
-  terminal *really* doesn't support Unicode (e.g. **rxvt**\(1)).
+  video are still supported in this mode, but no Unicode/UTF8 characters
+  are printed. Use this only if your terminal *really* doesn't support
+  Unicode (e.g. **rxvt**\(1))... but even then, **-m** is preferred,
+  because you can't tell what the dots are supposed to represent.
 
 **-m**
-  Output "magazine listing". See the **-m** option for **a8cat** for details.
-  Color is supported in this mode,
+  Output "magazine listing". See the **-m** option for **a8cat**\(1) for details.
+  Color is supported in this mode. No Unicode/UTF-8 characters are printed in
+  this mode.
 
 **-x**
   Output Unicode/UTF-8 representations of the XL International Character
@@ -52,21 +61,32 @@ characters.
 Other 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.
 
+**-C**
+  Enable color syntax highlighting. This option is enabled by default;
+  the **-C** option is provided so you can override **-n** in
+  **LISTBAS_OPTS** (see **ENVIRONMENT**, below).
+
 **-n**
   No color. Has no effect if **-a** is in effect, since this
   mode doesn't support color anyway. Disabling color does not
   disable reverse video.
 
+**-b**
+  Use bold for color output. This may make it easier to read on
+  some terminals. Or, it may hurt your eyes...
+
 **-u**
   Use underlining for inverse video, rather than reverse video output.
 
+**-c** *colors*
+  Customize the color scheme. See **COLORS**, below, for the format of the
+  *colors* argument. Once you've found a set of colors you like,
+  you can place this option in the **LISTBAS_OPTS** environment variable
+  to use your colors by default. See **ENVIRONMENT**, below.
+
 .. include:: genopts.rst
 
 COLORS
@@ -76,7 +96,11 @@ 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:
+The color scheme is adjustable via the **-c** option; see
+**Customization**, below. To avoid having to give your custom colors on
+the command line every time, see **ENVIRONMENT**, below.
+
+The default color scheme is:
 
 **yellow**
   Commands. Also "command operators" such as the **GOTO** in **ON/GOTO** and
@@ -96,15 +120,80 @@ The color scheme is:
 **cyan**
   Line numbers at the start of a line, comments (**REM** text) and **DATA** elements.
 
-Quotes around strings, 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).
+**uncolorized**
+  Variable names.
+
+Quotes around strings and commas between **DATA** elements are
+never colorized, 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 blue in the default color scheme. 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.
+
+Customization
+-------------
+You can customize the colors by using the **-c** *colors* option, either
+on the command line, or in the **LISTBAS_OPTS** environment variable.
+*colors* is a string of exactly 6 characters, each of which must be the
+digits *0* through *7* to specify a color, or the letter *n* to specify
+no color.
+
+The colors are the standard ANSI ones, plus *n*:
+
+*0*
+  Black.
+
+*1*
+  Red.
+
+*2*
+  Green.
 
-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.
+*3*
+  Yellow (or brown, on some terminals).
+
+*4*
+  Blue.
+
+*5*
+  Purple (aka violet).
+
+*6*
+  Cyan.
+
+*7*
+  White.
+
+*n*
+  No custom color. Output will be in the terminal's default foreground color.
+
+The order they're used in the *colors* argument is:
+
+**1**
+  Commands.
+
+**2**
+  Operators.
+
+**3**
+  Functions.
+
+**4**
+  Constants.
+
+**5**
+  Line numbers (at the start of a line only; **GOTO** and **GOSUB** line numbers
+  are constants).
+
+**6**
+  Variable names.
+
+So, the default color scheme is equivalent to:
+
+  **-c** *32516n*
 
 NOTES
 =====
@@ -126,8 +215,8 @@ protection.
 - **listbas** doesn't show information about the variables. Use **vxrefbas**\(1)
   for that.
 
-- **listbas** will not write ATASCII data to your terminal. By default, it uses
-  **a8cat**\(1) to convert the output to something human-readable
+- **listbas** will not write ATASCII data to your terminal. By default, it
+  converts ATASCII characters into Unicode/UTF-8 characters
   that won't confuse the terminal. When outputting raw ATASCII (**-a** option),
   it refuses to run if standard output is a terminal.
 
@@ -146,6 +235,21 @@ something like::
 
   listbas PROGRAM.BAS | aha > program.html
 
+ENVIRONMENT
+===========
+
+**LISTBAS_OPTS**
+  If this environment variable is set, **listbas** parses its value as though
+  the contents were placed on the command line as options, preceding any actual
+  option. Example::
+
+    export LISTBAS_OPTS="-c123456 -d"
+
+  If you place the above line in your shell's startup script, **listbas** will
+  use your custom color scheme, and will default to the "dots" output mode. If
+  you then run **listbas** the **-c** and/or **-x**, **-m** options, the options
+  on the command line will override the environment.
+
 EXIT STATUS
 ===========