Re: [patch #4610] Consolidated documentation patch

[Julian Foad]

Charles Levert wrote:
> Follow-up Comment #3, patch #4610 (project grep):
>
> TeXinfo manual, version 3.  I attached a unidiff output file.
>
> Check out dvi and info.
>
>     _______________________________________________________
>
> Additional Item Attachment:
>
> File name: grep.texi.diff3                Size:74 KB
> TeXinfo manual, unidiff output, version 3
> <http://savannah.gnu.org/patch/download.php?item_id=4610&item_file_id=5490>

This is getting very hard to review.  Could you please:

* Give us a description of the changes (like a ChangeLog entry) so we 
understand what we're looking at.

* Maybe have a look at my patch (attached) and combine the best of your and my 
changes.  (Sorry, I should have sent this earlier rather than trying to 
"finish" it first.)

(I'm tempted also to suggest an alternative: "Just commit it all and then we'll 
move ahead from there."  But that would be defeatist.)

Thanks.

First thing I noticed: in the manual (grep.1), I see you added back-ticks and 
single quotes around some quoted items (as well as them being bold).  This is 
not the normal way of quoting things in the man page: the normal way is to mark 
them as "bold" (and nothing else).  The only back ticks that are there before 
your patch are those introduced recently; I intended to remove those and use 
"bold" instead for consistency with the rest of the page.

For some items, like hyphens, I remember you did this because bold doesn't show 
up on those characters on some output devices.  However, I suggest finding a 
different approach such as writing "a hyphen (-)" where the result would 
otherwise be confusing.  I strongly dislike using back-ticks/grave-accent 
characters at all, and especially if that style is not used consistently 
throughout the document.

- Julian

Index: ChangeLog
===================================================================
RCS file: /cvsroot/grep/grep/ChangeLog,v
retrieving revision 1.284
diff -u -3 -p -d -r1.284 ChangeLog
--- ChangeLog   13 Nov 2005 08:15:16 -0000      1.284
+++ ChangeLog   18 Nov 2005 01:21:02 -0000
@@ -1,3 +1,12 @@
+2005-11-10  Julian Foad  <address@hidden>
+
+       * doc/grep.1, doc/grep.texi: Fix mark-up; add a missing entry for
+         "--exclude-from"; change the mentions of "octet" (which were added
+         recently) to "byte" for consistency; mention and describe wildcard
+         matching for filename patterns; improve some wording and punctuation;
+         don't mention one of the escape sequences used in coloring, since we
+         don't mention the others.
+
 2005-11-13  Charles Levert  <address@hidden>
 
        * tests/yesno.sh: New file.  Test feature interaction
Index: doc/grep.1
===================================================================
RCS file: /cvsroot/grep/grep/doc/grep.1,v
retrieving revision 1.36
diff -u -3 -p -d -r1.36 grep.1
--- doc/grep.1  9 Nov 2005 20:04:41 -0000       1.36
+++ doc/grep.1  18 Nov 2005 01:21:02 -0000
@@ -134,9 +134,9 @@ might output binary garbage,
 which can have nasty side effects if the output is a terminal and if the
 terminal driver interprets some of it as commands.
 .TP
-.BI \-\^\-color[=\fIWHEN\fR] ", " \-\^\-colour[=\fIWHEN\fR]
+.BR \-\^\-color [ =\fIWHEN\fP "], " \-\^\-colour [ =\fIWHEN\fP ]
 Surround the matching non-empty strings, matching lines, context lines,
-file names, line numbers, octet offsets, and separators (for fields and
+file names, line numbers, byte 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
@@ -145,7 +145,7 @@ The deprecated environment variable
 .B GREP_COLOR
 is still supported, but its setting does not have priority.
 .I WHEN
-is `never', `always', or `auto'.
+.RB "is " never ", " always ", or " auto .
 .TP
 .BR \-c ", " \-\^\-count
 Suppress normal output; instead print a count of
@@ -203,7 +203,16 @@ as the pattern; useful to protect patter
 .BR \- .
 .TP
 .BI \-\^\-exclude= FILE_PATTERN
-.RI "Skip files " "and directories" " that match " FILE_PATTERN.
+.RI "Skip files " "and directories" " that match " FILE_PATTERN
+(using wildcard matching as described under
+.BR \-\^\-include ).
+.TP
+.BI \-\^\-exclude-from= FILE
+.RI "Skip files " "and directories"
+that match any of the filename patterns read from
+.I FILE
+(using wildcard matching as described under
+.BR \-\^\-include ).
 .TP
 .BR \-F ", " \-\^\-fixed-strings
 Interpret
@@ -244,9 +253,14 @@ Ignore case distinctions in both the
 and the input files.
 .TP
 .BI \-\^\-include= FILE_PATTERN
-Search only files that match
+Search only files whose names match the filename pattern
 .I FILE_PATTERN
 (using wildcard matching).
+A filename pattern can use
+.BR * ", " ? " and " [ ... ]
+as wildcards, and
+.B \e
+to quote a wildcard or backslash character literally.
 .TP
 .BR \-L ", " \-\^\-files-without-match
 Suppress normal output; instead print the name
@@ -269,7 +283,7 @@ e.g.,
 .B "gzip -cd foo.gz | grep --label=foo something"
 .TP
 .BR \-\^\-line-buffered
-Use line buffering, it can be a performance penalty.
+Use line buffering.  This can be a performance penalty.
 .TP
 .BI \-m " NUM" "\fR,\fP \-\^\-max-count=" NUM
 Stop reading a file after
@@ -324,8 +338,8 @@ Prefix each line of output with the line
 within its input file.
 .TP
 .BR \-o ", " \-\^\-only-matching
-Show only the non-empty parts of a matching line that match
-.IR PATTERN .
+Print only the (non-empty) matched parts of a matching line, with each
+such part on a separate output line.
 .TP
 .BR \-P ", " \-\^\-perl-regexp
 .RI "Interpret " PATTERN " as a Perl regular expression."
@@ -378,19 +392,17 @@ and should redirect standard and error o
 instead.
 .TP
 .BR \-T ", " \-\^\-initial\-tab
-Makes sure that the first character of actual line content lies on a
+Make sure that the first character of actual line content lies on a
 tab stop, so that the alignment of tabs looks normal.
-This is useful when combined with
+This is useful with options that prefix their output to the actual content:
 .B \-H
 (which is implicit when there is more than one file to search),
 .BR \-n ,
 and
-.BR \-b ;
-these options prepend their output at the beginning of the displayed
-line, before the actual content.
-In order to improve the probability that all matched or context lines
+.BR \-b .
+In order to improve the probability that lines
 from a single file will all start at the same column, this also causes
-the line number and octet offset (if present) to be printed in a minimum
+the line number and byte offset (if present) to be printed in a minimum
 size field width.
 .TP
 .BR \-U ", " \-\^\-binary
@@ -734,35 +746,51 @@ A backslash escapes the next character,
 so it can be used to specify an option containing whitespace or a backslash.
 .TP
 .B GREP_COLOR
-Deprecated in favor of
+This variable specifies the color used to highlight matched text.  It is
+deprecated in favor of
 .BR GREP_COLORS ,
-which has priority.
-It can only specify the marker for highlighting matched non-empty text and
-defaults to `01;31' (bold red).
+but still supported.  The
+.B mt
+element of
+.B GREP_COLORS
+has priority over it.  The default is
+.B 01;31
+(bold red).
 .TP
 .B GREP_COLORS
-Specifies the markers for highlighting matched non-empty 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).
+This variable specifies the colors used to highlight
+.RB "matched text (" mt ),
+.RB "matching lines (" ml ),
+.RB "context lines (" cx ),
+.RB "file names (" fn ),
+.RB "line numbers (" ln ),
+.RB "byte offsets (" bn ),
+.RB "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
+The default is
+.B 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.
-Note that the `ml' setting, if any, remains in effect just before the
-`mt' setting kicks in.
+Note that the
+.B ml
+setting, if any, remains in effect just before the
+.B mt
+setting kicks in.
 See the Select Graphic Rendition (SGR, for character attributes)
 section in the documentation of the text terminal that is used
 for permissible values (semicolon-separated lists of integers)
 and their meaning.
 .B GREP_COLORS
-also supports a boolean `ne' capability (with no `=...' part) to not
-clear to the end of line using Erase in Line (EL) to Right (`\\33[K')
-each time a colorized item ends (needed on terminals on which EL is not
-supported; otherwise useful on terminals where the `back_color_erase'
-(`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).
+also supports a boolean
+.B ne
+capability (with no
+.B =...
+part) to not clear to the end of line using Erase in Line to Right (EL) each
+time a colorized item ends; this is needed on terminals on which EL is not
+supported, and useful on terminals where the Back Color Erase (BCE) boolean
+terminfo capability is not specified, when the chosen highlight colors do not
+affect the background, or when EL is too slow or causes too much flicker.
 .TP
 \fBLC_ALL\fP, \fBLC_COLLATE\fP, \fBLANG\fP
 These variables specify the
Index: doc/grep.texi
===================================================================
RCS file: /cvsroot/grep/grep/doc/grep.texi,v
retrieving revision 1.59
diff -u -3 -p -d -r1.59 grep.texi
--- doc/grep.texi       9 Nov 2005 20:04:41 -0000       1.59
+++ doc/grep.texi       18 Nov 2005 01:21:02 -0000
@@ -190,8 +190,8 @@ Prefix each line of output with the line
 @opindex -o
 @opindex --only-matching
 @cindex only matching
-Print only the non-empty parts of matching lines
-that actually match @var{pattern}.
+Print only the (non-empty) matched parts of a matching line, with each
+such part on a separate output line.
 
 @item -q
 @itemx --quiet
@@ -268,18 +268,18 @@ Print @var{num} lines of output context.
 @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
+Surround the matched non-empty strings, matching lines, context lines,
+file names, line numbers, byte 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 `mt=01;31:ml=:cx=:fn=35:ln=32:bn=32:se=36' for bold red
-matched text, magenta file names, green line numbers, green octet offsets,
+and default to @samp{mt=01;31:ml=:cx=:fn=35:ln=32:bn=32:se=36} for bold red
+matched text, magenta file names, green line numbers, green byte 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)
+but its setting does not have priority; it defaults to @samp{01;31} (bold red)
 which only covers the color for matched text.
address@hidden is `never', `always', or `auto'.
address@hidden is @samp{never}, @samp{always}, or @samp{auto}.
 
 @item address@hidden
 @opindex -NUM
@@ -369,7 +369,7 @@ Suppress the prefixing of filenames on o
 @item --line-buffered
 @opindex --line-buffered
 @cindex line buffering
-Set the line buffering policy, this can be a performance penalty.
+Use line buffering.  This can be a performance penalty.
 
 @item address@hidden
 @opindex --label
@@ -428,13 +428,27 @@ files in that directory, recursively.  T
 @opindex --include
 @cindex include files
 @cindex searching directory trees
-Search only files matching @var{file_pattern}.
+Search only files whose names match the filename pattern @var{file_pattern}
+(using wildcard matching).
+A filename pattern can use @samp{*}, @samp{?} and @address@hidden as
+wildcards, and @samp{\} to quote a wildcard or backslash character
+literally.
 
 @item address@hidden
 @opindex --exclude
 @cindex exclude files
 @cindex searching directory trees
-Skip files @emph{and directories} matching @var{file_pattern}.
+Skip files @emph{and directories} whose names match the filename pattern
address@hidden (using wildcard matching as described under
address@hidden).
+
address@hidden address@hidden
address@hidden --exclude
address@hidden exclude files
address@hidden searching directory trees
+Skip files @emph{and directories} whose names match any of the filename
+patterns read from @var{file} (using wildcard matching as described under
address@hidden).
 
 @item -m @var{num}
 @itemx address@hidden
@@ -529,15 +543,13 @@ behavior (including core dumps) if an in
 @opindex -T
 @opindex --initial-tab
 @cindex tab-aligned content lines
-Makes sure that the first character of actual line content lies on a
+Make sure that the first character of actual line content lies on a
 tab stop, so that the alignment of tabs looks normal.
-This is useful when combined with @samp{-H} (which is implicit when
-there is more than one file to search), @samp{-n}, and @samp{-b};
-these options prepend their output at the beginning of the displayed
-line, before the actual content.
-In order to improve the probability that all matched or context lines
+This is useful with options that prefix their output to the actual content: 
@samp{-H} (which is implicit when
+there is more than one file to search), @samp{-n}, and @samp{-b}.
+In order to improve the probability that lines
 from a single file will all start at the same column, this also causes
-the line number and octet offset (if present) to be printed in a minimum
+the line number and byte offset (if present) to be printed in a minimum
 size field width.
 
 @item -Z
@@ -603,36 +615,35 @@ specify an option containing whitespace 
 @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.
-The default is `01;31' which means bold red text on the default
-background.
+This variable specifies the color used to highlight matched text.
+It is deprecated in favor of @code{GREP_COLORS}, but still supported.
+The @samp{mt} element of @code{GREP_COLORS} has priority over it.
+The default is @samp{01;31} (bold red).
 
 @item GREP_COLORS
 @vindex GREP_COLORS
 @cindex highlight markers
 This variable specifies the colors used to highlight
-the matching non-empty 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).
+matched text (@samp{mt}), matching lines (@samp{ml}), context lines 
(@samp{cx}),
+file names (@samp{fn}), line numbers (@samp{ln}), byte offsets (@samp{bn}),
+and separators (@samp{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
+The default is @samp{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.
-Note that the `ml' setting, if any, remains in effect just before the
-`mt' setting kicks in.
+Note that the @samp{ml} setting, if any, remains in effect just before the
address@hidden setting kicks in.
 See the Select Graphic Rendition (SGR, for character attributes)
 section in the documentation of the text terminal that is used
 for permissible values (semicolon-separated lists of integers)
 and their meaning.
address@hidden also supports a boolean `ne' capability (with no
-`=...' part) to not clear to the end of line using Erase in Line (EL)
-to Right (`\33[K') each time a colorized item ends (needed on terminals
-on which EL is not supported; otherwise useful on terminals where the
address@hidden (@code{bce}) boolean terminfo capability is not
address@hidden also supports a boolean @samp{ne} capability (with no
address@hidden part) to not clear to the end of line using Erase in Line
+to Right (EL) each time a colorized item ends; this is needed on terminals
+on which EL is not supported, and useful on terminals where the
+Back Color Erase (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).
+or when EL is too slow or causes too much flicker.
 
 @item LC_ALL
 @itemx LC_COLLATE