Re: Changes to grep/doc/grep.1

[Julian Foad]

Charles Levert wrote:
> Index: grep/doc/grep.1
> diff -u grep/doc/grep.1:1.31 grep/doc/grep.1:1.32
> --- grep/doc/grep.1:1.31        Tue Jun 21 15:22:58 2005
> +++ grep/doc/grep.1     Tue Jul  5 01:03:33 2005
[...]
>  The colors are defined by the environment variable
> -.B GREP_COLORS
> -and default to `mt=01;31:ml=:cx=:fn=35:ln=32:bn=32:se=36' for bold red
> -matched text, default matching lines, default context lines,
> -magenta file names, green line numbers, green octet offsets,
> -and cyan separators.

While rightly moving the description of the environment variable to its own
section, it would be nice also to state the default colours here, because a
user of "--color" who is not using the variable would not expect to have to
read the documentation of that variable.  Items that have default colour need 
not be mentioned for this purpose, so, maybe:

  The colors are defined by the environment variable
  .B GREP_COLORS
  (and possibly
  .B GREP_COLOR )
  and default to bold red matched text,
  magenta file names, green line numbers, green octet offsets,
  and cyan separators.


[About GREP_COLOR:]
> @@ -743,11 +724,31 @@
>  Deprecated in favor of
>  .BR GREP_COLORS ,
>  which has priority.
> -Specifies the marker for highlighting.
> +It can only specify the marker for highlighting matched text and
> +defaults to `01;31' (bold red).

It doesn't seem right to say that GREP_COLOR has a default: if GREP_COLOR is
missing, the colour will not necessarily be red as it is also controlled by 
GREP_COLORS.  It is not so much that the value of the environment variable 
GREP_COLOR defaults to `01;31' but rather the colour of matched text does.  So, 
maybe:

  Specifies the color for highlighting matched text.
  Deprecated, and overridden by the `mt' field in
  .BR GREP_COLORS .
  The value is a semicolon-separated list of numeric codes, and will be output
  within a Select Graphic Rendition control sequence (ESC `[' codes `m').
  The value `01;31' would give the default color for matched text (bold red).


>  .TP
>  .B GREP_COLORS
> -Specifies the markers for highlighting matched text, file names,
> -line numbers, octet offsets, and separators.
> +Specifies the markers for highlighting matched text (mt), matching lines
> +(ml), context lines (cx), file names (fn), line numbers (ln), octet
> +offsets (bn), and separators (se, for fields and groups of context lines).
> +It is a colon-separated list of color specification assignments.
> +The default is `mt=01;31:ml=:cx=:fn=35:ln=32:bn=32:se=36' which means
> +bold red, default, default, magenta, green, green, and cyan, all text
> +foregrounds on the default background.

Please also specify what happens if a field is absent, as opposed to its value
being empty.  I find by experiment that each missing field takes its value from
the list above, or from GREP_COLOR in the case of "mt", rather than the
terminal's default colour.


This description in the manual page grep.1 is now different from the
description in the info page grep.texi.  Please could you keep them the same
except for any intentional differences?

- Julian