grep-2.5.1: documentation deficiency

[Nelson H. F. Beebe]

The color support added at grep-2.5 is lovely, but the documentation
in grep-2.5.1 is deficient:

This is all "man grep" has to say:

>> ...
>>        --colour[=WHEN], --color[=WHEN]
>>               Surround  the  matching string with the marker find
>>               in GREP_COLOR environment  variable.  WHEN  may  be
>>               `never', `always', or `auto'
>>
>>        GREP_COLOR
>>               Specifies the marker for highlighting.
>> ...

The grep manual in the info system says:

>> ...
>>      `--colour[=WHEN]'
>>      `--color[=WHEN]'
>>           The matching string is surrounded by the marker specify in
>>           GREP_COLOR.  WHEN may be `never', `always', or `auto'.
>>
>>      `GREP_COLOR'
>>           This variable specifies the surrounding markers use to highlight
>>           the matching text.  The default is control ascii red.
>> ...

What the dickens is ``control ascii red''?  And what should GREP_COLOR
contain?

I had to examine source code to figure out how to use it.  I've since
made these settings in my shell startup files:

        setenv GREP_OPTIONS     "--color=always"
        setenv GREP_COLOR       "1;46;37"               # bright, white 
foreground, cyan background

What is expected for the GREP_COLOR setting is a semicolon-separated
list of terminal emulator colors.

My dired (directory editor) release at

        http://www.math.utah.edu/pub/dired
        ftp://ftp.math.utah.edu/pub/dired

has the attached section in its manual pages.  You're welcome to
borrow/steal/adapt/rewrite to improve the grep documentation of its
color support:

.\"=====================================================================
.SH "COLOR SUPPORT"
>From version 4.00,
.B dired
supports color coding of files by type and by extension.
.PP
The color support is identical to that provided by the
GNU
.BR ls (1)
command: if the terminal type defined by the
.I TERM
environment variable is known to support color
(i.e., is one of
.IR "con132x25" ,
.IR "con132x30" ,
.IR "con132x43" ,
.IR "con132x60" ,
.IR "con80x25" ,
.IR "con80x28" ,
.IR "con80x30" ,
.IR "con80x43" ,
.IR "con80x50" ,
.IR "con80x60" ,
.IR "console" ,
.IR "linux" ,
.IR "vt100" ,
or
.IR "xterm" ),
then built-in defaults determine file colors.
.PP
Do not be disappointed if your terminal type is one of the above, but
the output is still monochrome: only recent versions of UNIX terminal
emulators, such as
.BR xterm (1),
contain support for text color beyond the normal foreground and
background colors.  However, all should have at least bold, flashing,
underlined, and reverse video capability.
.PP
The defaults can be overridden by settings of the
.I LS_COLORS
(or
.IR LS_COLOURS )
environment variable; that variable augments, but does not eliminate,
the internal defaults.  Thus, for customization, the user need only
supply changed values.
.PP
The value of the
.I LS_COLORS
variable is a
.BR termcap (1)-like
capability list: a colon-separated list of
.I key=value
pairs.  As in computer programming languages, when there are repeated
assignments to the same key name, only the last is effective.
.PP
Keys may be one of these file types or commands:
.RS
.TP
.IR bd
block device,
.TP
.IR cd
character device,
.TP
.IR di
directory,
.TP
.IR ec
end control sequence code (replaces
.IR lc+no+rc ),
.TP
.IR ex
executable file,
.TP
.IR fi
regular file,
.TP
.IR lc
left control sequence code,
.TP
.IR ln
symbolic link,
.TP
.IR mi
missing file (defaults to
.IR fi ),
.TP
.IR no
normal (non-filename) text,
.TP
.IR or
orphaned symbolic link (defaults to
.IR ln ),
.TP
.IR pi
named pipe (FIFO),
.TP
.IR rc
right control sequence code,
.TP
.IR so
socket.
.RE
.PP
Keys may also be of the form
.IR "*.ext"
to select files by dotted extension.
.PP
Values are terminal color control sequences, usually
semicolon-separated lists of numbers, as follows:
.RS
.TP
.I " 0"
restore default color
.TP
.I " 1"
brighter colors
.TP
.I " 4"
underlined text
.TP
.I " 5"
flashing text
.TP
.I " 7"
reverse video
.TP
.I "30"
black foreground
.TP
.I "31"
red foreground
.TP
.I "32"
green foreground
.TP
.I "33"
yellow (or brown) foreground
.TP
.I "34"
blue foreground
.TP
.I "35"
purple foreground
.TP
.I "36"
cyan foreground
.TP
.I "37"
white (or gray) foreground
.TP
.I "40"
black background
.TP
.I "41"
red background
.TP
.I "42"
green background
.TP
.I "43"
yellow (or brown) background
.TP
.I "44"
blue background
.TP
.I "45"
purple background
.TP
.I "46"
cyan background
.TP
.I "47"
white (or gray) background
.RE
.PP
For convenience, here is the same data, sorted by color names instead
of color numbers:
.RS
.TP
.I "40"
black background
.TP
.I "30"
black foreground
.TP
.I "44"
blue background
.TP
.I "34"
blue foreground
.TP
.I "46"
cyan background
.TP
.I "36"
cyan foreground
.TP
.I "42"
green background
.TP
.I "32"
green foreground
.TP
.I "45"
purple background
.TP
.I "35"
purple foreground
.TP
.I "41"
red background
.TP
.I "31"
red foreground
.TP
.I "47"
white (or gray) background
.TP
.I "37"
white (or gray) foreground
.TP
.I "43"
yellow (or brown) background
.TP
.I "33"
yellow (or brown) foreground
.RE
.PP
Any required special characters in capability values can be
represented by backslash or caret escape sequences:
.RS
.TP
.I "\e?"
rubout (ASCII DELete)
.TP
.I "\e_"
space
.TP
.I "\ea"
alert (ASCII BEL)
.TP
.I "\eb"
backspace (ASCII BS)
.TP
.I "\ee"
escape (ASCII ESCape)
.TP
.I "\ef"
formfeed (ASCII FF)
.TP
.I "\en"
newline (ASCII NL)
.TP
.I "\eooo"
3-octal-digit character value
.TP
.I "\er"
carriage return (ASCII CR)
.TP
.I "\et"
horizontal tab (ASCII HT)
.TP
.I "\ev"
vertical tab (ASCII VT)
.TP
.I "\exhh"
2-or-more-hexadecimal-digit character value
.TP
.I "^x"
Control character formed from the five low-order bits of the
character `x'
.RE
.PP
Backslash can also be used to protect other characters, notably,
backslash, colon, and equals, from misinterpretation: `\e\e'
reduces to a single `\e', and `e:' to a non-separating colon.
.PP
The GNU
.BR dircolors (1)
command can be used to display the default setting
of
.I LS_COLORS
used by
.BR dired .
For convenience, the default is displayed here, but for readability,
newlines have been inserted after the colons separating
.I key=value
pairs, and the pairs have been sorted into ascending order:
.RS
.nf
.I *.arj=01;31:
.I *.avi=01;37:
.I *.bmp=01;35:
.I *.deb=01;31:
.I *.dl=01;37:
.I *.gif=01;35:
.I *.gl=01;37:
.I *.gz=01;31:
.I *.jpg=01;35:
.I *.lzh=01;31:
.I *.mpg=01;37:
.I *.ppm=01;35:
.I *.tar=01;31:
.I *.taz=01;31:
.I *.tga=01;35:
.I *.tgz=01;31:
.I *.tif=01;35:
.I *.xbm=01;35:
.I *.xpm=01;35:
.I *.Z=01;31:
.I *.z=01;31:
.I *.zip=01;31:
.I bd=40;33;01:
.I cd=40;33;01:
.I di=01;34:
.I ex=01;32:
.I fi=0:
.I lc=\ee[:
.I ln=01;36:
.I no=0:
.I or=40;31;01:
.I pi=40;33:
.I rc=m:
.I so=01;35:
.fi
.RE
.PP
.B dired
writes each filename to the screen in the form
.IR <lc><color code><rc><filename><ec> .
If the
.I ec
command is undefined, the sequence
.I <lc><no><rc>
is used instead.  For example, the default setting shown above for the
.I di
directory file capability,
.IR "01;34" ,
produces bright blue text on the screen background, and the character
string that is output to the screen is
.IR "\ee[01;34mfilename\ee[0m" .
.PP
If you routinely use colored screen backgrounds, you should define
background, as well as foreground, colors in each color capability
value; otherwise, you may find that the color selected for certain
files is difficult, or impossible, to see against the colored
background.

-------------------------------------------------------------------------------
- Nelson H. F. Beebe                    Tel: +1 801 581 5254                  -
- Center for Scientific Computing       FAX: +1 801 581 4148                  -
- University of Utah                    Internet e-mail: address@hidden  -
- Department of Mathematics, 110 LCB        address@hidden  address@hidden -
- 155 S 1400 E RM 233                       address@hidden                    -
- Salt Lake City, UT 84112-0090, USA    URL: http://www.math.utah.edu/~beebe  -
-------------------------------------------------------------------------------