diff options
Diffstat (limited to 'listbas.1')
| -rw-r--r-- | listbas.1 | 156 |
1 files changed, 137 insertions, 19 deletions
@@ -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 |