Re: [patch] selected/context colors

[Charles Levert]

* On Monday 2005-11-14 at 21:54:25 -0500, Charles Levert wrote:
> 
> Here is a new version of the patch.

Here are now fragments covering most of the
reworked TeXinfo documentation for this.
An embedded @table for the capabilities was
added within the @table row for the GREP_COLORS
environment variable.

I am not posting a patch, since I am also
reworking the whole TeXinfo documentation.
There is no clear reference version from which
to post one.



========================================================================
@item address@hidden
@itemx address@hidden
@opindex --color
@opindex --colour
@cindex highlight, color, colour
Surround the matching non-empty strings, matching lines, context lines,
file names, line numbers, octet offsets, and separators (for fields and
groups of context lines) with escape sequences to display them in color
on the terminal.
The colors are defined by the environment variable @var{GREP_COLORS}
and default to @samp{ms=01;31:mc=01;31:sl=:cx=:fn=35:ln=32:bn=32:se=36}
for bold red matched text, magenta file names, green line numbers,
green octet offsets, cyan separators, and default terminal colors otherwise.
The deprecated environment variable @var{GREP_COLOR} is still supported,
but its setting does not have priority; it defaults to `01;31' (bold red)
which only covers the color for matched text.
@var{WHEN} is `never', `always', or `auto'.
========================================================================
@item GREP_COLOR
@vindex GREP_COLOR
@cindex highlight markers
This variable is deprecated but still supported;
its setting does not have priority over that of @code{GREP_COLORS}.
It specifies the color used to highlight the matching non-empty text
in any matching line
(a selected or context line, whether the @samp{-v} option is specified).
Its equivalent default is @samp{01;31},
which means bold red foreground text on the terminal's default background.

@item GREP_COLORS
@vindex GREP_COLORS
@cindex highlight markers
This variable specifies the colors and other attributes
used to highlight various parts of the output.
Its value is a colon-separated list of capabilities
which defaults to @samp{ms=01;31:mc=01;31:sl=:cx=:fn=35:ln=32:bn=32:se=36}
with the @samp{rv} and @samp{ne} boolean capabilities omitted (false).
Supported capabilities are as follows.

@table @samp
@item sl=
@vindex sl GREP_COLORS capability
SGR substring for whole selected lines
(matching lines when the @samp{-v} command-line option is not specified,
non-matching lines when the @samp{-v} command-line option is specified);@*
however if the boolean @samp{rv} capability
and the @samp{-v} command-line option are both specified,
applies to context matching lines instead;@*
default is empty (terminal's default color pair)

@item cx=
@vindex cx GREP_COLORS capability
SGR substring for whole context lines
(non-matching lines when the @samp{-v} command-line option is not specified,
matching lines when the @samp{-v} command-line option is specified);@*
however if the boolean @samp{rv} capability
and the @samp{-v} command-line option are both specified,
applies to selected non-matching lines instead;@*
default is empty (terminal's default color pair)

@item rv
@vindex rv GREP_COLORS capability
boolean value that reverses (swaps) the meaning of
the @samp{sl=} and @samp{cx=} capabilities
when the @samp{-v} command-line option is specified;@*
default is omitted (false)

@item mt=01;31
@vindex mt GREP_COLORS capability
SGR substring for matching non-empty text in any matching line
(a selected line when the @samp{-v} command-line option is not specified,
a context line when the @samp{-v} command-line option is specified);@*
equivalent to setting both @samp{ms=} and @samp{mc=}
at once to the same value;@*
default is bright red foreground over current line background

@item ms=01;31
@vindex ms GREP_COLORS capability
SGR substring for matching non-empty text in a selected line
(only used when the @samp{-v} command-line option is not specified);@*
effect of the @samp{sl=} (or @samp{cx=} if @samp{rv}) capability
remains active when this kicks in;@*
default is bright red foreground over current line background

@item mc=01;31
@vindex mc GREP_COLORS capability
SGR substring for matching non-empty text in a context line
(only used when the @samp{-v} command-line option is specified);@*
effect of the @samp{cx=} (or @samp{sl=} if @samp{rv}) capability
remains active when this kicks in;@*
default is bright red foreground over current line background

@item fn=35
@vindex fn GREP_COLORS capability
SGR substring for file names prefixing any content line;@*
default is magenta foreground over terminal's default background

@item ln=32
@vindex ln GREP_COLORS capability
SGR substring for line numbers prefixing any content line;@*
default is green foreground over terminal's default background

@item bn=32
@vindex bn GREP_COLORS capability
SGR substring for octet offsets prefixing any content line;@*
default is green foreground over terminal's default background

@item se=36
@vindex fn GREP_COLORS capability
SGR substring for separators
(@samp{:} between selected line fields,
@samp{-} between context line fields,
@samp{--} between groups of adjacent lines
when nonzero context is specified);@*
default is cyan foreground over terminal's default background

@item ne
@vindex ne GREP_COLORS capability
boolean value that prevents clearing to the end of line
using Erase in Line (EL) to Right (@samp{\33[K})
each time a colorized item ends
(needed on terminals on which EL is not supported;
otherwise useful on terminals
where the @code{back_color_erase} (@code{bce}) boolean terminfo capability
is not specified,
when the chosen highlight colors do not affect the background,
or when EL is too slow to bother doing or causes too much flicker);@*
default is omitted (false)
@end table

Note that boolean capabilities have no @samp{=...} part.
They are false (omitted) by default and become true when specified.

See the Select Graphic Rendition
(SGR, @samp{\33[...m}, for character attributes)
section in the documentation of the text terminal that is used
for permissible substring values (semicolon-separated lists of integers)
and their meaning.
Common values include
@samp{1} for bold,
@samp{4} for underline,
@samp{5} for blink,
@samp{7} for inverse,
@samp{39} for default foreground color,
@samp{30} to @samp{37} for foreground colors,
@samp{90} to @samp{97} for 16-color mode foreground colors,
@samp{38;5;0} to @samp{38;5;255}
for 88-color and 256-color modes foreground colors,
@samp{49} for default background color,
@samp{40} to @samp{47} for background colors,
@samp{100} to @samp{107} for 16-color mode background colors,
and @samp{48;5;0} to @samp{48;5;255}
for 88-color and 256-color modes background colors.
These common values can be combined by inserting a semicolon between them.
========================================================================