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

1 files changed, 137 insertions, 19 deletions

diff --git a/listbas.1 b/listbas.1
index 97ebb9c..6aa93ca 100644
--- a/listbas.1
+++ b/listbas.1
@@ -48,18 +48,27 @@ 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\-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\-d\fP
 Print dots rather than Unicode/UTF\-8 characters. Color and inverse
-video are still supported in this mode. Use this only if your
-terminal \fIreally\fP doesn\(aqt support Unicode (e.g. \fBrxvt\fP(1)).
+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.
 .TP
 .B \fB\-m\fP
-Output "magazine listing". See the \fB\-m\fP option for \fBa8cat\fP for details.
-Color is supported in this mode,
+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\-x\fP
 Output Unicode/UTF\-8 representations of the XL International Character
@@ -68,20 +77,31 @@ Set, rather than ATASCII.
 .SS Other options
 .INDENT 0.0
 .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\-i\fP
 Include the immediate mode command (line 32768) in the output.
 .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 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
@@ -102,7 +122,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.
 .sp
-The color scheme is:
+The color scheme is adjustable via the \fB\-c\fP option; see
+\fBCustomization\fP, below. To avoid having to give your custom colors on
+the command line every time, see \fBENVIRONMENT\fP, below.
+.sp
+The default color scheme is:
 .INDENT 0.0
 .TP
 .B \fByellow\fP
@@ -122,17 +146,88 @@ constants (but not the quotes around the string).
 .TP
 .B \fBcyan\fP
 Line numbers at the start of a line, comments (\fBREM\fP text) and \fBDATA\fP elements.
+.TP
+.B \fBuncolorized\fP
+Variable names.
 .UNINDENT
 .sp
-Quotes around strings, 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).
+Quotes around strings and commas between \fBDATA\fP elements are
+never colorized, 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).
+.sp
+Note that nothing is blue in the default color scheme. 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.
+.SS Customization
+.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 6 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, 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
-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.
+The order they\(aqre used in the \fIcolors\fP argument is:
+.INDENT 0.0
+.TP
+.B \fB1\fP
+Commands.
+.TP
+.B \fB2\fP
+Operators.
+.TP
+.B \fB3\fP
+Functions.
+.TP
+.B \fB4\fP
+Constants.
+.TP
+.B \fB5\fP
+Line numbers (at the start of a line only; \fBGOTO\fP and \fBGOSUB\fP line numbers
+are constants).
+.TP
+.B \fB6\fP
+Variable names.
+.UNINDENT
+.sp
+So, the default color scheme is equivalent to:
+.INDENT 0.0
+.INDENT 3.5
+\fB\-c\fP \fI32516n\fP
+.UNINDENT
+.UNINDENT
 .SH NOTES
 .sp
 \fBlistbas\fP will refuse to operate on a LIST\-protected program with
@@ -153,8 +248,8 @@ looks very similar to how it would appear on the Atari.
 \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
@@ -181,6 +276,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