Re: [patch] selected/context colors

[Charles Levert]

* On Tuesday 2005-11-15 at 22:07:18 +0100, Benno Schulenberg wrote:
[...]

Thanks.  I think I've taken every one of your
suggestions into account.  I have switched to
"@table @code" and replaced incomplete sentence
propositions by complete period-terminated
sentences (except for the initial ones that lack
a main verb).  I have removed the @* that forced
line breaks.  In @vindex entries, I have added @r{}.



========================================================================
@item GREP_COLOR
@vindex GREP_COLOR @r{environment variable}
@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 line when the @samp{-v} command-line option is omitted,
or a context line when @samp{-v} is specified).
Its equivalent default is @samp{01;31},
which means a bold red foreground text on the terminal's default background.

@item GREP_COLORS
@vindex GREP_COLORS @r{environment variable}
@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
that 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 (i.e., false).
Supported capabilities are as follows.

@table @code
@item sl=
@vindex sl GREP_COLORS @r{capability}
SGR substring for whole selected lines
(i.e.,
matching lines when the @samp{-v} command-line option is omitted,
or non-matching lines when @samp{-v} is specified).
If however the boolean @samp{rv} capability
and the @samp{-v} command-line option are both specified,
it applies to context matching lines instead.
The default is empty (i.e., the terminal's default color pair).

@item cx=
@vindex cx GREP_COLORS @r{capability}
SGR substring for whole context lines
(i.e.,
non-matching lines when the @samp{-v} command-line option is omitted,
or matching lines when @samp{-v} is specified).
If however the boolean @samp{rv} capability
and the @samp{-v} command-line option are both specified,
it applies to selected non-matching lines instead.
The default is empty (i.e., the terminal's default color pair).

@item rv
@vindex rv GREP_COLORS @r{capability}
Boolean value that reverses (swaps) the meanings of
the @samp{sl=} and @samp{cx=} capabilities
when the @samp{-v} command-line option is specified.
The default is false (i.e., the capability is omitted).

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

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

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

@item fn=35
@vindex fn GREP_COLORS @r{capability}
SGR substring for file names prefixing any content line.
The default is a magenta text foreground over the terminal's default background.

@item ln=32
@vindex ln GREP_COLORS @r{capability}
SGR substring for line numbers prefixing any content line.
The default is a green text foreground over the terminal's default background.

@item bn=32
@vindex bn GREP_COLORS @r{capability}
SGR substring for octet offsets prefixing any content line.
The default is a green text foreground over the terminal's default background.

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

@item ne
@vindex ne GREP_COLORS @r{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.
This is needed on terminals on which EL is not supported.
It is otherwise useful on terminals
for which the @code{back_color_erase} (@code{bce}) boolean terminfo capability
do not apply,
when the chosen highlight colors do not affect the background,
or when EL is too slow to bother doing or causes too much flicker.
The default is false (i.e., the capability is omitted).
@end table

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

See the Select Graphic Rendition (SGR) section
in the documentation of the text terminal that is used
for permitted values and their meaning as character attributes.
These substring values are integers in decimal representation
and can be concatenated with semicolons.
@command{grep} takes care of assembling the result
into a complete SGR sequence (@samp{\33[...m}).
Common values to concatenate 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.
========================================================================