Index: grep/ChangeLog
===================================================================
RCS file: /cvsroot/grep/grep/ChangeLog,v
retrieving revision 1.283
diff -u -r1.283 ChangeLog
--- grep/ChangeLog	11 Nov 2005 12:17:50 -0000	1.283
+++ grep/ChangeLog	12 Nov 2005 12:15:14 -0000
@@ -1,3 +1,48 @@
+2005-11-12  Charles Levert  <charles_levert@gna.org>
+
+	This set of documentation changes includes contributions by
+	Julian Foad <julianfoad@btopenworld.com>, by Benno Schulenberg
+	<benno@nietvergeten.nl>, and by the committer.
+
+	* doc/grep.1, doc/grep.texi: Use just "grep" instead of
+	  "the grep command", unless an example command really follows.
+	  Use just "command" instead of "shell command".
+	  Make sure that "grep" is always appropriately marked up.
+	  Use "file name" not "filename", "back-reference" not
+	  "backreference", and other similar fixes.
+	  Reserve the terms "bracket expression" and "subexpression"
+	  for specific meanings.  Distinguish "locale" from "locale category".
+	* doc/grep.1, doc/grep.texi: Note that context lines are not available
+	  with --only-matching and that a warning is issued under such uses.
+	* doc/grep.1, doc/grep.texi: Clarify and uniformize the
+	  explanations of the --include and --exclude options.
+	* doc/grep.texi: Use the same title as everywhere else in the
+	  documentation.  Align @direntry according to convention.
+	  Create a new @menu and @nodes for the "Invoking grep" @chapter.
+	  Add a synopsis for grep invocation.  Create a new @menu,
+	  @nodes, and @subsections for "Command-line Options" @section:
+	  "Generic Program Information", "Matching Control",
+	  "General Output Control", "Output Line Prefix Control",
+	  "Context Line Control", "File and Directory Selection", and
+	  "Other Options".  Reorganize existing options accordingly.
+	  Merge synonym options under the main name and explain their status.
+	  Explicitly note which short option names are specified by POSIX.
+	  @xref to the "grep Programs" @chapter earlier in the @section above.
+	  Explain the influence of context lines on ":", "-", and "--"
+	  separators, as well as the notion of groups of output lines.
+	  Explain the systematic order of line prefix fields.
+	  Create a new @node for the "Environment Variables" @section.
+	  Create a new @menu and @nodes for the "Regular Expressions"
+	  @chapter.  Give more complete names to its @sections.
+	  Clarify, update, and reformat some usage examples.
+	  Update copyright notice years according to CVS logs and releases.
+	  Fix various typographical and source code formatting details.
+	* doc/grep.1: Document -NUM.  Sort options.
+	* doc/grep.1, doc/grep.texi: Uniformize the typography of
+	  operating system names and make sure they are always properly
+	  prefixed, as "windows" alone is a common noun than morally belongs
+	  to the public domain, along with its meaning in computing.
+
 2005-11-11  Charles Levert  <charles_levert@gna.org>
 
 	* configure.in (ALL_LINGUAS): Add languages that were missing
Index: grep/doc/grep.1
===================================================================
RCS file: /cvsroot/grep/grep/doc/grep.1,v
retrieving revision 1.36
--- grep/doc/grep.1	9 Nov 2005 20:04:41 -0000	1.36
+++ grep/doc/grep.1	12 Nov 2005 11:43:08 -0000
@@ -32,9 +32,8 @@
 .RI [ FILE .\|.\|.]
 .SH DESCRIPTION
 .PP
-The
 .B grep
-command searches the named input
+searches the named input
 .IR FILE s
 (or standard input if no files are named, or
 the file name
@@ -73,6 +72,11 @@
 Places a line containing
 .B \-\^\-
 between contiguous groups of matches.
+With the
+.B \-o
+or
+.B \-\^\-only-matching
+option, this has no effect and a warning is given.
 .TP
 .BR \-a ", " \-\^\-text
 Process a binary file as if it were text; this is equivalent to the
@@ -86,14 +90,24 @@
 Places a line containing
 .B \-\^\-
 between contiguous groups of matches.
+With the
+.B \-o
+or
+.B \-\^\-only-matching
+option, this has no effect and a warning is given.
 .TP
-.BI \-C " NUM" "\fR,\fP \-\^\-context=" NUM
+.BI \-C " NUM" "\fR,\fP \-" NUM "\fR,\fP \-\^\-context=" NUM
 Print
 .I NUM
 lines of output context.
 Places a line containing
 .B \-\^\-
 between contiguous groups of matches.
+With the
+.B \-o
+or
+.B \-\^\-only-matching
+option, this has no effect and a warning is given.
 .TP
 .BR \-b ", " \-\^\-byte-offset
 Print the byte offset within the input file before
@@ -134,6 +148,15 @@
 which can have nasty side effects if the output is a terminal and if the
 terminal driver interprets some of it as commands.
 .TP
+.BR \-c ", " \-\^\-count
+Suppress normal output; instead print a count of
+matching lines for each input file.
+With the
+.BR \-v ", " \-\^\-invert-match
+option (see below), count non-matching lines.
+.BR "" ( \-c
+is specified by \s-1POSIX\s0.)
+.TP
 .BI \-\^\-color[=\fIWHEN\fR] ", " \-\^\-colour[=\fIWHEN\fR]
 Surround the matching non-empty strings, matching lines, context lines,
 file names, line numbers, octet offsets, and separators (for fields and
@@ -147,13 +170,6 @@
 .I WHEN
 is `never', `always', or `auto'.
 .TP
-.BR \-c ", " \-\^\-count
-Suppress normal output; instead print a count of
-matching lines for each input file.
-With the
-.BR \-v ", " \-\^\-invert-match
-option (see below), count non-matching lines.
-.TP
 .BI \-D " ACTION" "\fR,\fP \-\^\-devices=" ACTION
 If an input file is a device, FIFO or socket, use
 .I ACTION
@@ -195,27 +211,37 @@
 Interpret
 .I PATTERN
 as an extended regular expression (see below).
+.BR "" ( \-E
+is specified by \s-1POSIX\s0.)
 .TP
 .BI \-e " PATTERN" "\fR,\fP \-\^\-regexp=" PATTERN
 Use
 .I PATTERN
 as the pattern; useful to protect patterns beginning with
 .BR \- .
+.BR "" ( \-e
+is specified by \s-1POSIX\s0.)
 .TP
 .BI \-\^\-exclude= FILE_PATTERN
-.RI "Skip files " "and directories" " that match " FILE_PATTERN.
+Skip files with base names that match
+.I FILE_PATTERN
+(using wildcard matching).
 .TP
 .BR \-F ", " \-\^\-fixed-strings
 Interpret
 .I PATTERN
 as a list of fixed strings, separated by newlines,
 any of which is to be matched.
+.BR "" ( \-F
+is specified by \s-1POSIX\s0.)
 .TP
 .BI \-f " FILE" "\fR,\fP \-\^\-file=" FILE
 Obtain patterns from
 .IR FILE ,
 one per line.
 The empty file contains zero patterns, and therefore matches nothing.
+.BR "" ( \-f
+is specified by \s-1POSIX\s0.)
 .TP
 .BR \-G ", " \-\^\-basic-regexp
 Interpret
@@ -223,10 +249,10 @@
 as a basic regular expression (see below).  This is the default.
 .TP
 .BR \-H ", " \-\^\-with-filename
-Print the filename for each match.
+Print the file name for each match.
 .TP
 .BR \-h ", " \-\^\-no-filename
-Suppress the prefixing of filenames on output
+Suppress the prefixing of file names on output
 when multiple files are searched.
 .TP
 .B \-\^\-help
@@ -242,9 +268,11 @@
 Ignore case distinctions in both the
 .I PATTERN
 and the input files.
+.BR "" ( \-i
+is specified by \s-1POSIX\s0.)
 .TP
 .BI \-\^\-include= FILE_PATTERN
-Search only files that match
+Search only files with base names that match
 .I FILE_PATTERN
 (using wildcard matching).
 .TP
@@ -259,6 +287,8 @@
 the name of each input file from which output
 would normally have been printed.  The scanning will
 stop on the first match.
+.BR "" ( \-l
+is specified by \s-1POSIX\s0.)
 .TP
 .BI \-\^\-label= LABEL
 Display input actually coming from standard input as input coming from file
@@ -269,7 +299,8 @@
 .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 cause a performance penalty.
 .TP
 .BI \-m " NUM" "\fR,\fP \-\^\-max-count=" NUM
 Stop reading a file after
@@ -322,6 +353,8 @@
 .BR \-n ", " \-\^\-line-number
 Prefix each line of output with the line number
 within its input file.
+.BR "" ( \-n
+is specified by \s-1POSIX\s0.)
 .TP
 .BR \-o ", " \-\^\-only-matching
 Show only the non-empty parts of a matching line that match
@@ -339,6 +372,8 @@
 or
 .B \-\^\-no-messages
 option.
+.BR "" ( \-q
+is specified by \s-1POSIX\s0.)
 .TP
 .BR \-R ", " \-r ", " \-\^\-recursive
 Read all files under each directory, recursively;
@@ -376,6 +411,8 @@
 and should redirect standard and error output to
 .B /dev/null
 instead.
+.BR "" ( \-s
+is specified by \s-1POSIX\s0.)
 .TP
 .BR \-T ", " \-\^\-initial\-tab
 Makes sure that the first character of actual line content lies on a
@@ -394,7 +431,8 @@
 size field width.
 .TP
 .BR \-U ", " \-\^\-binary
-Treat the file(s) as binary.  By default, under MS-DOS and MS-Windows,
+Treat the file(s) as binary.
+By default, under \s-1MS-DOS\s0 and \s-1MS\s0-Windows,
 .BR grep
 guesses the file type by looking at the contents of the first 32KB
 read from the file.  If
@@ -410,19 +448,22 @@
 matching mechanism verbatim; if the file is a text file with CR/LF
 pairs at the end of each line, this will cause some regular
 expressions to fail.
-This option has no effect on platforms other than MS-DOS and
-MS-Windows.
+This option has no effect on platforms
+other than \s-1MS-DOS\s0 and \s-1MS\s0-Windows.
 .TP
 .BR \-u ", " \-\^\-unix-byte-offsets
-Report Unix-style byte offsets.  This switch causes
+Report Unix-style byte offsets.
+This switch causes
 .B grep
-to report byte offsets as if the file were Unix-style text file, i.e., with
-CR characters stripped off.  This will produce results identical to running
+to report byte offsets as if the file were a Unix-style text file,
+i.e., with CR characters stripped off.
+This will produce results identical to running
 .B grep
-on a Unix machine.  This option has no effect unless
+on a Unix machine.
+This option has no effect unless
 .B \-b
 option is also used;
-it has no effect on platforms other than MS-DOS and MS-Windows.
+it has no effect on platforms other than \s-1MS-DOS\s0 and \s-1MS\s0-Windows.
 .TP
 .BR \-V ", " \-\^\-version
 Print the version number of
@@ -432,6 +473,8 @@
 .TP
 .BR \-v ", " \-\^\-invert-match
 Invert the sense of matching, to select non-matching lines.
+.BR "" ( \-v
+is specified by \s-1POSIX\s0.)
 .TP
 .BR \-w ", " \-\^\-word-regexp
 Select only those lines containing matches that form whole words.
@@ -443,6 +486,8 @@
 .TP
 .BR \-x ", " \-\^\-line-regexp
 Select only those matches that exactly match the whole line.
+.BR "" ( \-x
+is specified by \s-1POSIX\s0.)
 .TP
 .B \-y
 Obsolete synonym for
@@ -471,9 +516,8 @@
 Regular expressions are constructed analogously to arithmetic
 expressions, by using various operators to combine smaller expressions.
 .PP
-The
 .B grep
-command understands two different versions of regular expression syntax:
+understands two different versions of regular expression syntax:
 \*(lqbasic\*(rq and \*(lqextended.\*(rq  In
 .RB "\s-1GNU\s0\ " grep ,
 there is no difference in available functionality using either syntax.
@@ -483,7 +527,7 @@
 .PP
 The fundamental building blocks are the regular expressions that match
 a single character.  Most characters, including all letters and digits,
-are regular expressions that match themselves.  Any metacharacter with
+are regular expressions that match themselves.  Any meta-character with
 special meaning may be quoted by preceding it with a backslash.
 .PP
 A
@@ -549,8 +593,9 @@
 of locale and character set.
 (Note that the brackets in these class names are part of the symbolic
 names, and must be included in addition to the brackets delimiting
-the bracket list.)  Most metacharacters lose their special meaning
-inside lists.  To include a literal
+the bracket expression.)
+Most meta-characters lose their special meaning inside bracket expressions.
+To include a literal
 .B ]
 place it first in the list.  Similarly, to include a literal
 .B ^
@@ -574,7 +619,7 @@
 .B ^
 and the dollar sign
 .B $
-are metacharacters that respectively match the empty string at the
+are meta-characters that respectively match the empty string at the
 beginning and end of a line.
 The symbols
 .B \e<
@@ -623,18 +668,19 @@
 Two regular expressions may be concatenated; the resulting
 regular expression matches any string formed by concatenating
 two substrings that respectively match the concatenated
-subexpressions.
+expressions.
 .PP
 Two regular expressions may be joined by the infix operator
 .BR | ;
 the resulting regular expression matches any string matching
-either subexpression.
+either alternate expression.
 .PP
 Repetition takes precedence over concatenation, which in turn
-takes precedence over alternation.  A whole subexpression may be
-enclosed in parentheses to override these precedence rules.
+takes precedence over alternation.
+A whole expression may be enclosed in parentheses
+to override these precedence rules and form a subexpression.
 .PP
-The backreference
+The back-reference
 .BI \e n\c
 \&, where
 .I n
@@ -643,7 +689,7 @@
 .IR n th
 parenthesized subexpression of the regular expression.
 .PP
-In basic regular expressions the metacharacters
+In basic regular expressions the meta-characters
 .BR ? ,
 .BR + ,
 .BR { ,
@@ -665,7 +711,7 @@
 .B egrep
 did not support the
 .B {
-metacharacter, and some
+meta-character, and some
 .B egrep
 implementations support
 .B \e{
@@ -683,7 +729,8 @@
 attempts to support traditional usage by assuming that
 .B {
 is not special if it would be the start of an invalid interval
-specification.  For example, the shell command
+specification.
+For example, the command
 .B "grep\ \-E\ '{1'"
 searches for the two-character string
 .B {1
@@ -695,7 +742,7 @@
 .B grep
 is affected by the following environment variables.
 .PP
-A locale
+The locale for category
 .BI LC_ foo
 is specified by examining the three environment variables
 .BR LC_ALL ,
@@ -709,11 +756,11 @@
 .B LC_MESSAGES
 is set to
 .BR pt_BR ,
-then Brazilian Portuguese is used for the
+then the Brazilian Portuguese locale is used for the
 .B LC_MESSAGES
-locale.
+category.
 The C locale is used if none of these environment variables are set,
-or if the locale catalog is not installed, or if
+if the locale catalog is not installed, or if
 .B grep
 was not compiled with national language support (\s-1NLS\s0).
 .TP
@@ -765,22 +812,25 @@
 to bother doing or causes too much flicker).
 .TP
 \fBLC_ALL\fP, \fBLC_COLLATE\fP, \fBLANG\fP
-These variables specify the
+These variables specify the locale for the
 .B LC_COLLATE
-locale, which determines the collating sequence used to interpret
-range expressions like
+category,
+which determines the collating sequence
+used to interpret range expressions like
 .BR [a\-z] .
 .TP
 \fBLC_ALL\fP, \fBLC_CTYPE\fP, \fBLANG\fP
-These variables specify the
+These variables specify the locale for the
 .B LC_CTYPE
-locale, which determines the type of characters, e.g., which
-characters are whitespace.
+category,
+which determines the type of characters,
+e.g., which characters are whitespace.
 .TP
 \fBLC_ALL\fP, \fBLC_MESSAGES\fP, \fBLANG\fP
-These variables specify the
+These variables specify the locale for the
 .B LC_MESSAGES
-locale, which determines the language that
+category,
+which determines the language that
 .B grep
 uses for messages.
 The default C locale uses American English messages.
@@ -848,13 +898,15 @@
 .PP
 Large repetition counts in the
 .BI { n , m }
-construct may cause grep to use lots of memory.
+construct may cause
+.B grep
+to use lots of memory.
 In addition,
 certain other obscure regular expressions require exponential time
 and space, and may cause
 .B grep
 to run out of memory.
 .PP
-Backreferences are very slow, and may require exponential time.
+Back-references are very slow, and may require exponential time.
 .\" Work around problems with some troff -man implementations.
 .br
Index: grep/doc/grep.texi
===================================================================
RCS file: /cvsroot/grep/grep/doc/grep.texi,v
retrieving revision 1.59
--- grep/doc/grep.texi	9 Nov 2005 20:04:41 -0000	1.59
+++ grep/doc/grep.texi	12 Nov 2005 11:26:20 -0000
@@ -26,7 +26,7 @@
 
 @ifinfo
 @direntry
-* grep: (grep).                   print lines matching a pattern.
+* grep: (grep).                 print lines matching a pattern.
 @end direntry
 This file documents @command{grep}, a pattern matching engine.
 
@@ -36,7 +36,7 @@
 Boston, MA 02110-1301, USA
 
 @c man begin COPYRIGHT
-Copyright @copyright{} 2000, 2001 Free Software Foundation, Inc.
+Copyright @copyright{} 1999, 2000, 2001, 2002, 2005  Free Software Foundation, Inc.
 
 Permission is granted to make and distribute verbatim copies of
 this manual provided the copyright notice and this permission notice
@@ -62,13 +62,13 @@
 @setchapternewpage off
 
 @titlepage
-@title grep, searching for a pattern
+@title @command{grep}, print lines matching a pattern
 @subtitle version @value{VERSION}, @value{UPDATED}
 @author Alain Magloire et al.
 
 @page
 @vskip 0pt plus 1filll
-Copyright @copyright{} 2000, 2001 Free Software Foundation, Inc.
+Copyright @copyright{} 1999, 2000, 2001, 2002, 2005  Free Software Foundation, Inc.
 
 @sp 2
 Published by the Free Software Foundation, @*
@@ -89,7 +89,7 @@
 @node Top
 @top grep
 
-The @command{grep} command searches for lines matching a pattern.
+@command{grep} searches for lines matching a pattern.
 
 This document was produced for version @value{VERSION} of @sc{gnu}
 @command{grep}.
@@ -115,7 +115,7 @@
 
 @cindex Searching for a pattern.
 
-The @command{grep} command searches the input files
+@command{grep} searches the input files
 for lines containing a match to a given
 pattern list.  When it finds a match in a line, it copies the line to standard
 output (by default), or does whatever other sort of output you have requested
@@ -131,21 +131,79 @@
 
 @node Invoking
 @chapter Invoking @command{grep}
+
+The general synopsis of a @command{grep} command line is
+
+@example
+grep @var{options} @var{pattern} @var{input_file_names}
+@end example
+
+@noindent
+where there can be zero or more @var{options},
+@var{pattern} will only be seen as such
+(and not as an @var{input_file_name})
+if it wasn't already specified within @var{options},
+and there can be zero or more @var{input_file_names}.
+
+@menu
+* Command-line Options::        Short and long names, grouped by category.
+* Environment Variables::       POSIX, GNU generic, and GNU grep specific.
+@end menu
+
+@node Command-line Options
+@section Command-line Options
 
-@command{grep} comes with a rich set of options from @sc{posix.2} and @sc{gnu}
-extensions.
+@command{grep} comes with a rich set of options
+from @sc{posix.2} and @sc{gnu} extensions.
+Long option names are always a @sc{gnu} extension,
+even for options that are from @sc{posix} specifications.
+Options that are specified by @sc{posix},
+under their short names,
+are explicitly marked as such
+to facilitate @sc{posix}-portable programming.
+A few option names are provided
+for compatibility with older or more exotic implementations.
+
+Several additional options control
+which variant of the @command{grep} matching engine is used.
+@xref{grep Programs}.
+
+@menu
+* Generic Program Information::
+* Matching Control::
+* General Output Control::
+* Output Line Prefix Control::
+* Context Line Control::
+* File and Directory Selection::
+* Other Options::
+@end menu
+
+@node Generic Program Information
+@subsection Generic Program Information
+
+@table @samp
+
+@item --help
+@opindex --help
+@cindex Usage summary, printing
+Print a usage message briefly summarizing these command-line options
+and the bug-reporting address, then exit.
+
+@item -V
+@itemx --version
+@opindex -V
+@opindex --version
+@cindex Version, printing
+Print the version number of @command{grep} to the standard output stream.
+This version number should be included in all bug reports.
+
+@end table
+
+@node Matching Control
+@subsection Matching Control
 
 @table @samp
 
-@item -c
-@itemx --count
-@opindex -c
-@opindex --count
-@cindex counting lines
-Suppress normal output; instead print a count of matching
-lines for each input file.  With the @samp{-v}, @samp{--invert-match} option,
-count non-matching lines.
-
 @item -e @var{pattern}
 @itemx --regexp=@var{pattern}
 @opindex -e
@@ -153,6 +211,7 @@
 @cindex pattern list
 Use @var{pattern} as the pattern; useful to protect patterns
 beginning with a @samp{-}.
+(@samp{-e} is specified by @sc{posix}.)
 
 @item -f @var{file}
 @itemx --file=@var{file}
@@ -161,14 +220,93 @@
 @cindex pattern from file
 Obtain patterns from @var{file}, one per line.  The empty
 file contains zero patterns, and therefore matches nothing.
+(@samp{-f} is specified by @sc{posix}.)
 
 @item -i
+@itemx -y
 @itemx --ignore-case
 @opindex -i
+@opindex -y
 @opindex --ignore-case
 @cindex case insensitive search
 Ignore case distinctions in both the pattern and the input files.
+@samp{-y} is an obsolete synonym that is provided for compatibility.
+(@samp{-i} is specified by @sc{posix}.)
+
+@item -v
+@itemx --invert-match
+@opindex -v
+@opindex --invert-match
+@cindex invert matching
+@cindex print non-matching lines
+Invert the sense of matching, to select non-matching lines.
+(@samp{-v} is specified by @sc{posix}.)
+
+@item -w
+@itemx --word-regexp
+@opindex -w
+@opindex --word-regexp
+@cindex matching whole words
+Select only those lines containing matches that form
+whole words.  The test is that the matching substring
+must either be at the beginning of the line, or preceded
+by a non-word constituent character.  Similarly,
+it must be either at the end of the line or followed by
+a non-word constituent character.  Word-constituent
+characters are letters, digits, and the underscore.
+
+@item -x
+@itemx --line-regexp
+@opindex -x
+@opindex --line-regexp
+@cindex match the whole line
+Select only those matches that exactly match the whole line.
+(@samp{-x} is specified by @sc{posix}.)
+
+@end table
 
+@node General Output Control
+@subsection General Output Control
+
+@table @samp
+
+@item -c
+@itemx --count
+@opindex -c
+@opindex --count
+@cindex counting lines
+Suppress normal output; instead print a count of matching
+lines for each input file.  With the @samp{-v}, @samp{--invert-match} option,
+count non-matching lines.
+(@samp{-c} is specified by @sc{posix}.)
+
+@item --color[=@var{WHEN}]
+@itemx --colour[=@var{WHEN}]
+@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 `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,
+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 -L
+@itemx --files-without-match
+@opindex -L
+@opindex --files-without-match
+@cindex files which don't match
+Suppress normal output; instead print the name of each input
+file from which no output would normally have been printed.
+The scanning of every file will stop on the first match.
+
 @item -l
 @itemx --files-with-matches
 @opindex -l
@@ -177,13 +315,49 @@
 Suppress normal output; instead print the name of each input
 file from which output would normally have been printed.
 The scanning of every file will stop on the first match.
+(@samp{-l} is specified by @sc{posix}.)
 
-@item -n
-@itemx --line-number
-@opindex -n
-@opindex --line-number
-@cindex line numbering
-Prefix each line of output with the line number within its input file.
+@item -m @var{num}
+@itemx --max-count=@var{num}
+@opindex -m
+@opindex --max-count
+@cindex max-count
+Stop reading a file after @var{num} matching lines.
+If the input is standard input from a regular file,
+and @var{num} matching lines are output,
+@command{grep} ensures that the standard input is positioned
+just after the last matching line before exiting,
+regardless of the presence of trailing context lines.
+This enables a calling process to resume a search.
+For example, the following shell script makes use of it:
+
+@example
+while grep -m 1 PATTERN
+do
+  echo xxxx
+done < FILE
+@end example
+
+But the following probably will not work because a pipe is not a regular
+file:
+
+@example
+# This probably will not work.
+cat FILE |
+while grep -m 1 PATTERN
+do
+  echo xxxx
+done
+@end example
+
+When @command{grep} stops after @var{num} matching lines,
+it outputs any trailing context lines.
+Since context does not include matching lines,
+@command{grep} will stop when it encounters another matching line.
+When the @samp{-c} or @samp{--count} option is also used,
+@command{grep} does not output a count greater than @var{num}.
+When the @samp{-v} or @samp{--invert-match} option is also used,
+@command{grep} stops after outputting @var{num} non-matching lines.
 
 @item -o
 @itemx --only-matching
@@ -203,6 +377,7 @@
 Quiet; do not write anything to standard output.  Exit immediately with
 zero status if any match is found, even if an error was detected.  Also
 see the @samp{-s} or @samp{--no-messages} option.
+(@samp{-q} is specified by @sc{posix}.)
 
 @item -s
 @itemx --no-messages
@@ -218,25 +393,122 @@
 @sc{gnu} @command{grep}.  Portable shell scripts should avoid both
 @samp{-q} and @samp{-s} and should redirect
 standard and error output to @file{/dev/null} instead.
+(@samp{-s} is specified by @sc{posix}.)
 
-@item -v
-@itemx --invert-match
-@opindex -v
-@opindex --invert-match
-@cindex invert matching
-@cindex print non-matching lines
-Invert the sense of matching, to select non-matching lines.
-
-@item -x
-@itemx --line-regexp
-@opindex -x
-@opindex --line-regexp
-@cindex match the whole line
-Select only those matches that exactly match the whole line.
+@end table
+
+@node Output Line Prefix Control
+@subsection Output Line Prefix Control
+
+When several prefix fields are to be output,
+the order is always file name, line number, and octet offset,
+regardless of the order in which these options were specified.
+
+@table @samp
+
+@item -b
+@itemx --byte-offset
+@opindex -b
+@opindex --byte-offset
+@cindex byte offset
+Print the byte offset within the input file before each line of output.
+When @command{grep} runs on @sc{ms-dos} or @sc{ms}-Windows,
+the printed byte offsets depend on whether
+the @samp{-u} (@samp{--unix-byte-offsets}) option is used;
+see below.
+
+@item -H
+@itemx --with-filename
+@opindex -H
+@opindex --with-filename
+@cindex with filename prefix
+Print the file name for each match.
+
+@item -h
+@itemx --no-filename
+@opindex -h
+@opindex --no-filename
+@cindex no filename prefix
+Suppress the prefixing of file names on output when multiple files are searched.
+
+@item --label=@var{LABEL}
+@opindex --label
+@cindex changing name of standard input
+Display input actually coming from standard input
+as input coming from file @var{LABEL}.
+This is especially useful for tools like @command{zgrep};
+e.g.:
+
+@example
+gzip -cd foo.gz | grep --label=foo something
+@end example
+
+@item -n
+@itemx --line-number
+@opindex -n
+@opindex --line-number
+@cindex line numbering
+Prefix each line of output with the line number within its input file.
+(@samp{-n} is specified by @sc{posix}.)
+
+@item -T
+@itemx --initial-tab
+@opindex -T
+@opindex --initial-tab
+@cindex tab-aligned content lines
+Makes 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
+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 size field width.
+
+@item -u
+@itemx --unix-byte-offsets
+@opindex -u
+@opindex --unix-byte-offsets
+@cindex @sc{ms-dos}/@sc{ms}-Windows byte offsets
+@cindex byte offsets, on @sc{ms-dos}/@sc{ms}-Windows
+Report Unix-style byte offsets.
+This option causes @command{grep} to report byte offsets
+as if the file were a Unix-style text file,
+i.e., the byte offsets ignore the @code{CR} characters that were stripped.
+This will produce results identical
+to running @command{grep} on a Unix machine.
+This option has no effect unless @samp{-b} option is also used;
+it has no effect on platforms other than @sc{ms-dos} and @sc{ms}-Windows.
+
+@item -Z
+@itemx --null
+@opindex -Z
+@opindex --null
+@cindex zero-terminated file names
+Output a zero byte (the @sc{ascii} @code{NUL} character)
+instead of the character that normally follows a file name.
+For example,
+@samp{grep -lZ} outputs a zero byte after each file name
+instead of the usual newline.
+This option makes the output unambiguous,
+even in the presence of file names containing unusual characters like newlines.
+This option can be used with commands like
+@samp{find -print0}, @samp{perl -0}, @samp{sort -z}, and @samp{xargs -0}
+to process arbitrary file names,
+even those that contain newline characters.
 
 @end table
 
-@section @sc{gnu} Extensions
+@node Context Line Control
+@subsection Context Line Control
+
+Regardless of how these options are set,
+@command{grep} will never print any given line more than once.
+If the @samp{-o} or @samp{--only-matching} option is specified,
+these options have no effect and a warning is given upon their use.
 
 @table @samp
 
@@ -257,86 +529,75 @@
 Print @var{num} lines of leading context before matching lines.
 
 @item -C @var{num}
+@itemx -@var{num}
 @itemx --context=@var{num}
 @opindex -C
 @opindex --context
+@opindex -@var{num}
 @cindex context
-Print @var{num} lines of output context.
+Print @var{num} lines of leading and trailing output context.
+
+@end table
+
+Matching lines normally use @samp{:} as a separator
+between prefix fields and actual line content.
+Context (i.e., non-matching) lines use @samp{-} instead.
+When no context is specified,
+matching lines are simply output one right after another.
+When nonzero context is specified,
+lines that are adjacent in the input form a group
+and are output one right after another,
+but disjoint groups of lines are separated by a @samp{--}
+without any prefix and on a line of its own.
+Each group may contain several matching lines
+when they are close enough to each other
+that two otherwise adjacent but divided groups connect
+and can just merge into a single contiguous one.
 
-@item --color[=@var{WHEN}]
-@itemx --colour[=@var{WHEN}]
-@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 `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,
-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 -@var{num}
-@opindex -NUM
-Same as @samp{--context=@var{num}} lines of leading and trailing
-context.  However, grep will never print any given line more than once.
-
-@item -V
-@itemx --version
-@opindex -V
-@opindex --version
-@cindex Version, printing
-Print the version number of @command{grep} to the standard output stream.
-This version number should be included in all bug reports.
-
-@item --help
-@opindex --help
-@cindex Usage summary, printing
-Print a usage message briefly summarizing these command-line options
-and the bug-reporting address, then exit.
+@node File and Directory Selection
+@subsection File and Directory Selection
+
+@table @samp
+
+@item -a
+@itemx --text
+@opindex -a
+@opindex --text
+@cindex suppress binary data
+@cindex binary files
+Process a binary file as if it were text;
+this is equivalent to the @samp{--binary-files=text} option.
 
 @itemx --binary-files=@var{type}
 @opindex --binary-files
 @cindex binary files
-If the first few bytes of a file indicate that the file contains binary
-data, assume that the file is of type @var{type}.  By default,
-@var{type} is @samp{binary}, and @command{grep} normally outputs either
-a one-line message saying that a binary file matches, or no message if
-there is no match.  If @var{type} is @samp{without-match},
+If the first few bytes of a file indicate that the file contains binary data,
+assume that the file is of type @var{type}.
+By default, @var{type} is @samp{binary},
+and @command{grep} normally outputs either
+a one-line message saying that a binary file matches,
+or no message if there is no match.
+If @var{type} is @samp{without-match},
 @command{grep} assumes that a binary file does not match;
-this is equivalent to the @samp{-I} option.  If @var{type}
-is @samp{text}, @command{grep} processes a binary file as if it were
-text; this is equivalent to the @samp{-a} option.
+this is equivalent to the @samp{-I} option.
+If @var{type} is @samp{text},
+@command{grep} processes a binary file as if it were text;
+this is equivalent to the @samp{-a} option.
 @emph{Warning:} @samp{--binary-files=text} 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.
-
-@item -b
-@itemx --byte-offset
-@opindex -b
-@opindex --byte-offset
-@cindex byte offset
-Print the byte offset within the input file before each line of output.
-When @command{grep} runs on @sc{ms-dos} or MS-Windows, the printed
-byte offsets
-depend on whether the @samp{-u} (@samp{--unix-byte-offsets}) option is
-used; see below.
+which can have nasty side effects
+if the output is a terminal and
+if the terminal driver interprets some of it as commands.
 
 @item -D @var{action}
 @itemx --devices=@var{action}
 @opindex -D
 @opindex --devices
 @cindex device search
-If an input file is a device, FIFO or socket, use @var{action} to process it.
-By default, @var{action} is @samp{read}, which means that devices are
-read just as if they were ordinary files.
-If @var{action} is @samp{skip}, devices, FIFOs and sockets are silently
-skipped.
+If an input file is a device, FIFO, or socket, use @var{action} to process it.
+By default, @var{action} is @samp{read},
+which means that devices are read just as if they were ordinary files.
+If @var{action} is @samp{skip},
+devices, FIFOs, and sockets are silently skipped.
 
 @item -d @var{action}
 @itemx --directories=@var{action}
@@ -344,75 +605,34 @@
 @opindex --directories
 @cindex directory search
 If an input file is a directory, use @var{action} to process it.
-By default, @var{action} is @samp{read}, which means that directories are
-read just as if they were ordinary files (some operating systems
-and filesystems disallow this, and will cause @command{grep} to print error
-messages for every directory or silently skip them). If @var{action} is
-@samp{skip}, directories are silently skipped.  If @var{action} is
-@samp{recurse}, @command{grep} reads all files under each directory,
-recursively; this is equivalent to the @samp{-r} option.
-
-@item -H
-@itemx --with-filename
-@opindex -H
-@opindex --With-filename
-@cindex with filename prefix
-Print the filename for each match.
-
-@item -h
-@itemx --no-filename
-@opindex -h
-@opindex --no-filename
-@cindex no filename prefix
-Suppress the prefixing of filenames on output when multiple files are searched.
-
-@item --line-buffered
-@opindex --line-buffered
-@cindex line buffering
-Set the line buffering policy, this can be a performance penalty.
-
-@item --label=@var{LABEL}
-@opindex --label
-@cindex changing name of standard input
-Display input actually coming from standard input as input coming from file
-@var{LABEL}. This is especially useful for tools like @command{zgrep}, e.g.,
-@command{gzip -cd foo.gz | grep --label=foo something}
+By default, @var{action} is @samp{read},
+which means that directories are read just as if they were ordinary files
+(some operating systems and file systems disallow this,
+and will cause @command{grep}
+to print error messages for every directory or silently skip them).
+If @var{action} is @samp{skip}, directories are silently skipped.
+If @var{action} is @samp{recurse},
+@command{grep} reads all files under each directory, recursively;
+this is equivalent to the @samp{-r} option.
 
-@item -L
-@itemx --files-without-match
-@opindex -L
-@opindex --files-without-match
-@cindex files which don't match
-Suppress normal output; instead print the name of each input
-file from which no output would normally have been printed.
-The scanning of every file will stop on the first match.
+@item --exclude=@var{file_pattern}
+@opindex --exclude
+@cindex exclude files
+@cindex searching directory trees
+Skip files with base names that match @var{file_pattern}
+(using wildcard matching).
 
-@item -a
-@itemx --text
-@opindex -a
-@opindex --text
-@cindex suppress binary data
-@cindex binary files
-Process a binary file as if it were text; this is equivalent to the
-@samp{--binary-files=text} option.
+@item --include=@var{file_pattern}
+@opindex --include
+@cindex include files
+@cindex searching directory trees
+Search only files with base names that match @var{file_pattern}
+(using wildcard matching).
 
 @item -I
-Process a binary file as if it did not contain matching data; this is
-equivalent to the @samp{--binary-files=without-match} option.
+Process a binary file as if it did not contain matching data;
+this is equivalent to the @samp{--binary-files=without-match} option.
 
-@item -w
-@itemx --word-regexp
-@opindex -w
-@opindex --word-regexp
-@cindex matching whole words
-Select only those lines containing matches that form
-whole words.  The test is that the matching substring
-must either be at the beginning of the line, or preceded
-by a non-word constituent character.  Similarly,
-it must be either at the end of the line or followed by
-a non-word constituent character.  Word-constituent
-characters are letters, digits, and the underscore.
-
 @item -r
 @itemx -R
 @itemx --recursive
@@ -420,139 +640,52 @@
 @opindex --recursive
 @cindex recursive search
 @cindex searching directory trees
-For each directory mentioned in the command line, read and process all
-files in that directory, recursively.  This is the same as the
-@samp{--directories=recurse} option.
+For each directory mentioned in the command line,
+read and process all files in that directory, recursively.
+This is the same as the @samp{--directories=recurse} option.
+
+@end table
 
-@item --include=@var{file_pattern}
-@opindex --include
-@cindex include files
-@cindex searching directory trees
-Search only files matching @var{file_pattern}.
-
-@item --exclude=@var{file_pattern}
-@opindex --exclude
-@cindex exclude files
-@cindex searching directory trees
-Skip files @emph{and directories} matching @var{file_pattern}.
-
-@item -m @var{num}
-@itemx --max-count=@var{num}
-@opindex -m
-@opindex --max-count
-@cindex max-count
-Stop reading a file after @var{num} matching lines.  If the input is
-standard input from a regular file, and @var{num} matching lines are
-output, @command{grep} ensures that the standard input is positioned to
-just after the last matching line before exiting, regardless of the
-presence of trailing context lines.  This enables a calling process
-to resume a search.  For example, the following shell script makes use
-of it:
-
-@example
-while grep -m 1 PATTERN
-do
-  echo xxxx
-done < FILE
-@end example
-
-But the following probably will not work because a pipe is not a regular
-file:
-
-@example
-# This probably will not work.
-cat FILE |
-while grep -m 1 PATTERN
-do
-  echo xxxx
-done
-@end example
-
-When @command{grep} stops after NUM matching lines, it outputs
-any trailing context lines. Since context does not include matching
-lines, @command{grep} will stop when it encounters another matching line.
-When the @samp{-c} or @samp{--count} option is also used,
-@command{grep} does not output a count greater than @var{num}.
-When the @samp{-v} or @samp{--invert-match} option is
-also used, @command{grep} stops after outputting @var{num}
-non-matching lines.
-
-@item -y
-@opindex -y
-@cindex case insensitive search, obsolete option
-Obsolete synonym for @samp{-i}.
+@node Other Options
+@subsection Other Options
+
+@table @samp
+
+@item --line-buffered
+@opindex --line-buffered
+@cindex line buffering
+Use line buffering.
+This can cause a performance penalty.
+
+@item --mmap
+@opindex --mmap
+@cindex memory mapped input
+If possible, use the @code{mmap} system call to read input,
+instead of the default @code{read} system call.
+In some situations, @samp{--mmap} yields better performance.
+However, @samp{--mmap} can cause undefined behavior (including core dumps)
+if an input file shrinks while @command{grep} is operating,
+or if an I/O error occurs.
 
 @item -U
 @itemx --binary
 @opindex -U
 @opindex --binary
-@cindex DOS/Windows binary files
-@cindex binary files, DOS/Windows
-Treat the file(s) as binary.  By default, under @sc{ms-dos}
-and MS-Windows, @command{grep} guesses the file type by looking
-at the contents of the first 32kB read from the file.
-If @command{grep} decides the file is a text file, it strips the
-@code{CR} characters from the original file contents (to make
-regular expressions with @code{^} and @code{$} work correctly).
-Specifying @samp{-U} overrules this guesswork, causing all
-files to be read and passed to the matching mechanism
-verbatim; if the file is a text file with @code{CR/LF} pairs
-at the end of each line, this will cause some regular
-expressions to fail.  This option has no effect on platforms other than
-@sc{ms-dos} and MS-Windows.
-
-@item -u
-@itemx --unix-byte-offsets
-@opindex -u
-@opindex --unix-byte-offsets
-@cindex DOS byte offsets
-@cindex byte offsets, on DOS/Windows
-Report Unix-style byte offsets.  This switch causes
-@command{grep} to report byte offsets as if the file were Unix style
-text file, i.e., the byte offsets ignore the @code{CR} characters which were
-stripped.  This will produce results identical to running @command{grep} on
-a Unix machine.  This option has no effect unless @samp{-b}
-option is also used; it has no effect on platforms other than @sc{ms-dos} and
-MS-Windows.
-
-@item --mmap
-@opindex --mmap
-@cindex memory mapped input
-If possible, use the @code{mmap} system call to read input, instead of
-the default @code{read} system call.  In some situations, @samp{--mmap}
-yields better performance.  However, @samp{--mmap} can cause undefined
-behavior (including core dumps) if an input file shrinks while
-@command{grep} is operating, or if an I/O error occurs.
-
-@item -T
-@itemx --initial-tab
-@opindex -T
-@opindex --initial-tab
-@cindex tab-aligned content lines
-Makes 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
-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
-size field width.
-
-@item -Z
-@itemx --null
-@opindex -Z
-@opindex --null
-@cindex zero-terminated file names
-Output a zero byte (the @sc{ascii} @code{NUL} character) instead of the
-character that normally follows a file name.  For example, @samp{grep
--lZ} outputs a zero byte after each file name instead of the usual
-newline.  This option makes the output unambiguous, even in the presence
-of file names containing unusual characters like newlines.  This option
-can be used with commands like @samp{find -print0}, @samp{perl -0},
-@samp{sort -z}, and @samp{xargs -0} to process arbitrary file names,
-even those that contain newline characters.
+@cindex @sc{ms-dos}/@sc{ms}-Windows binary files
+@cindex binary files, @sc{ms-dos}/@sc{ms}-Windows
+Treat the file(s) as binary.
+By default, under @sc{ms-dos} and @sc{ms}-Windows,
+@command{grep} guesses the file type
+by looking at the contents of the first 32kB read from the file.
+If @command{grep} decides the file is a text file,
+it strips the @code{CR} characters from the original file contents
+(to make regular expressions with @code{^} and @code{$} work correctly).
+Specifying @samp{-U} overrules this guesswork,
+causing all files to be read and passed to the matching mechanism verbatim;
+if the file is a text file with @code{CR/LF} pairs at the end of each line,
+this will cause some regular expressions to fail.
+This option has no effect
+on platforms other than @sc{ms-dos} and @sc{ms}-Windows.
 
 @item -z
 @itemx --null-data
@@ -565,24 +698,26 @@
 @samp{sort -z} to process arbitrary file names.
 
 @end table
-
-Several additional options control which variant of the @command{grep}
-matching engine is used.  @xref{grep Programs}.
 
+@node Environment Variables
 @section Environment Variables
 
 The behavior of @command{grep} is affected
 by the following environment variables.
 
-A locale @code{LC_@var{foo}} is specified by examining the three
-environment variables @env{LC_ALL}, @env{LC_@var{foo}}, and @env{LANG},
-in that order.  The first of these variables that is set specifies the
-locale.  For example, if @env{LC_ALL} is not set, but @env{LC_MESSAGES}
-is set to @samp{pt_BR}, then Brazilian Portuguese is used for the
-@code{LC_MESSAGES} locale.  The C locale is used if none of these
-environment variables are set, or if the locale catalog is not
-installed, or if @command{grep} was not compiled with national language
-support (@sc{nls}).
+The locale for category @w{@code{LC_@var{foo}}}
+is specified by examining the three environment variables
+@env{LC_ALL}, @w{@env{LC_@var{foo}}}, and @env{LANG},
+in that order.
+The first of these variables that is set specifies the locale.
+For example, if @env{LC_ALL} is not set,
+but @env{LC_MESSAGES} is set to @samp{pt_BR},
+then the Brazilian Portuguese locale is used
+for the @code{LC_MESSAGES} category.
+The C locale is used if none of these environment variables are set,
+if the locale catalog is not installed,
+or if @command{grep} was not compiled
+with national language support (@sc{nls}).
 
 @cindex environment variables
 
@@ -643,9 +778,9 @@
 @cindex character type
 @cindex national language support
 @cindex NLS
-These variables specify the @code{LC_COLLATE} locale, which determines
-the collating sequence used to interpret range expressions like
-@samp{[a-z]}.
+These variables specify the locale for the @code{LC_COLLATE} category,
+which determines the collating sequence
+used to interpret range expressions like @samp{[a-z]}.
 
 @item LC_ALL
 @itemx LC_CTYPE
@@ -656,8 +791,9 @@
 @cindex character type
 @cindex national language support
 @cindex NLS
-These variables specify the @code{LC_CTYPE} locale, which determines the
-type of characters, e.g., which characters are whitespace.
+These variables specify the locale for the @code{LC_CTYPE} category,
+which determines the type of characters,
+e.g., which characters are whitespace.
 
 @item LC_ALL
 @itemx LC_MESSAGES
@@ -670,9 +806,9 @@
 @cindex national language support
 @cindex NLS
 @cindex translation of message language
-These variables specify the @code{LC_MESSAGES} locale, which determines
-the language that @command{grep} uses for messages.  The default C
-locale uses American English messages.
+These variables specify the locale for the @code{LC_MESSAGES} category,
+which determines the language that @command{grep} uses for messages.
+The default C locale uses American English messages.
 
 @item POSIXLY_CORRECT
 @vindex POSIXLY_CORRECT
@@ -717,7 +853,7 @@
 @node grep Programs
 @chapter @command{grep} programs
 
-The @command{grep} command searches the named input files
+@command{grep} searches the named input files
 (or standard input if no files are named,
 or the file name @file{-} is given)
 for lines containing a match to the given pattern.
@@ -740,6 +876,7 @@
 @opindex --extended-regexp
 @cindex matching extended regular expressions
 Interpret the pattern as an extended regular expression.
+(@samp{-E} is specified by @sc{posix}.)
 
 @item -F
 @itemx --fixed-strings
@@ -748,6 +885,7 @@
 @cindex matching fixed strings
 Interpret the pattern as a list of fixed strings, separated
 by newlines, any of which is to be matched.
+(@samp{-F} is specified by @sc{posix}.)
 
 @item -P
 @itemx --perl-regexp
@@ -755,6 +893,8 @@
 @opindex --perl-regexp
 @cindex matching Perl regular expressions
 Interpret the pattern as a Perl regular expression.
+This is highly experimental and
+@samp{grep@ -P} may warn of unimplemented features.
 
 @end table
 
@@ -781,9 +921,21 @@
 The following description applies to extended regular expressions;
 differences for basic regular expressions are summarized afterwards.
 
+@menu
+* Fundamental Structure::
+* Character Classes and Bracket Expressions::
+* The Backslash Character and Special Expressions::
+* Anchoring::
+* Back-references and Subexpressions::
+* Basic vs Extended::
+@end menu
+
+@node Fundamental Structure
+@section Fundamental Structure
+
 The fundamental building blocks are the regular expressions that match
 a single character.  Most characters, including all letters and digits,
-are regular expressions that match themselves.  Any metacharacter
+are regular expressions that match themselves.  Any meta-character
 with special meaning may be quoted by preceding it with a backslash.
 
 A regular expression may be followed by one of several
@@ -836,16 +988,19 @@
 
 Two regular expressions may be concatenated; the resulting regular
 expression matches any string formed by concatenating two substrings
-that respectively match the concatenated subexpressions.
+that respectively match the concatenated expressions.
 
-Two regular expressions may be joined by the infix operator @samp{|}; the
-resulting regular expression matches any string matching either subexpression.
+Two regular expressions may be joined by the infix operator @samp{|};
+the resulting regular expression
+matches any string matching either alternalte expression.
 
 Repetition takes precedence over concatenation, which in turn
-takes precedence over alternation.  A whole subexpression may be
-enclosed in parentheses to override these precedence rules.
+takes precedence over alternation.
+A whole expression may be enclosed in parentheses
+to override these precedence rules and form a subexpression.
 
-@section Character Class
+@node Character Classes and Bracket Expressions
+@section Character Classes and Bracket Expressions
 
 @cindex bracket expression
 @cindex character class
@@ -958,14 +1113,15 @@
 encoding, whereas the former is independent of locale and character set.
 (Note that the brackets in these class names are
 part of the symbolic names, and must be included in addition to
-the brackets delimiting the bracket list.)
+the brackets delimiting the bracket expression.)
 
-Most metacharacters lose their special meaning inside lists.
+Most meta-characters lose their special meaning inside bracket expressions.
 
 @table @samp
 @item ]
-ends the list if it's not the first list item.  So, if you want to make
-the @samp{]} character a list item, you must put it first.
+ends the bracket expression if it's not the first list item.
+So, if you want to make the @samp{]} character a list item,
+you must put it first.
 
 @item [.
 represents the open collating symbol.
@@ -995,11 +1151,13 @@
 
 @end table
 
-@section Backslash Character
+@node The Backslash Character and Special Expressions
+@section The Backslash Character and Special Expressions
 @cindex backslash
 
-The @samp{\} when followed by certain ordinary characters take a special
-meaning :
+The @samp{\} character,
+when followed by certain ordinary characters,
+takes a special meaning:
 
 @table @samp
 
@@ -1019,49 +1177,52 @@
 Match word constituent, it is a synonym for @samp{[[:alnum:]]}.
 
 @item @samp{\W}
-Match non word constituent, it is a synonym for @samp{[^[:alnum:]]}.
+Match non-word constituent, it is a synonym for @samp{[^[:alnum:]]}.
 
 @end table
 
-For example , @samp{\brat\b} matches the separate word @samp{rat},
-@samp{c\Brat\Be} matches @samp{crate}, but @samp{dirty \Brat} doesn't
-match @samp{dirty rat}.
+For example, @samp{\brat\b} matches the separate word @samp{rat},
+@samp{\Brat\B} matches @samp{crate} but not @samp{furry rat}.
 
+@node Anchoring
 @section Anchoring
 @cindex anchoring
 
-The caret @samp{^} and the dollar sign @samp{$} are metacharacters that
+The caret @samp{^} and the dollar sign @samp{$} are meta-characters that
 respectively match the empty string at the beginning and end of a line.
 
-@section Back-reference
+@node Back-references and Subexpressions
+@section Back-references and Subexpressions
+@cindex subexpression
 @cindex back-reference
 
 The back-reference @samp{\@var{n}}, where @var{n} is a single digit, matches
 the substring previously matched by the @var{n}th parenthesized subexpression
 of the regular expression. For example, @samp{(a)\1} matches @samp{aa}.
-When use with alternation if the group does not participate in the match, then
+When used with alternation, if the group does not participate in the match then
 the back-reference makes the whole match fail.  For example, @samp{a(.)|b\1}
 will not match @samp{ba}.  When multiple regular expressions are given with
-@samp{-e} or from a file @samp{-f file}, the back-referecences are local to
-each expression.
+@samp{-e} or from a file (@samp{-f file}),
+back-references are local to each expression.
 
+@node Basic vs Extended
 @section Basic vs Extended
 @cindex basic regular expressions
 
-In basic regular expressions the metacharacters @samp{?}, @samp{+},
+In basic regular expressions the meta-characters @samp{?}, @samp{+},
 @samp{@{}, @samp{|}, @samp{(}, and @samp{)} lose their special meaning;
 instead use the backslashed versions @samp{\?}, @samp{\+}, @samp{\@{},
 @samp{\|}, @samp{\(}, and @samp{\)}.
 
 @cindex interval specifications
-Traditional @command{egrep} did not support the @samp{@{} metacharacter,
+Traditional @command{egrep} did not support the @samp{@{} meta-character,
 and some @command{egrep} implementations support @samp{\@{} instead, so
 portable scripts should avoid @samp{@{} in @samp{grep@ -E} patterns and
 should use @samp{[@{]} to match a literal @samp{@{}.
 
 @sc{gnu} @command{grep@ -E} attempts to support traditional usage by
 assuming that @samp{@{} is not special if it would be the start of an
-invalid interval specification.  For example, the shell command
+invalid interval specification.  For example, the command
 @samp{grep@ -E@ '@{1'} searches for the two-character string @samp{@{1}
 instead of reporting a syntax error in the regular expression.
 @sc{posix.2} allows this behavior as an extension, but portable scripts
@@ -1071,7 +1232,7 @@
 @chapter Usage
 
 @cindex Usage, examples
-Here is an example shell command that invokes @sc{gnu} @command{grep}:
+Here is an example command that invokes @sc{gnu} @command{grep}:
 
 @example
 grep -i 'hello.*world' menu.h main.c
@@ -1111,25 +1272,31 @@
 @end example
 
 @noindent
-searches for @samp{hello} in all files under the directory
-@file{/home/gigi}.  For more control of which files are searched, use
-@command{find}, @command{grep} and @command{xargs}.  For example,
-the following command searches only C files:
+searches for @samp{hello} in all files
+under the @file{/home/gigi} directory.
+For more control over which files are searched,
+use @command{find}, @command{grep}, and @command{xargs}.
+For example, the following command searches only C files:
 
-@smallexample
-find /home/gigi -name '*.c' -print | xargs grep 'hello' /dev/null
-@end smallexample
+@example
+find /home/gigi -name '*.c' -print0 | xargs -0r grep -H 'hello'
+@end example
 
 This differs from the command:
 
 @example
-grep -r 'hello' *.c
+grep -rH 'hello' *.c
 @end example
 
 which merely looks for @samp{hello} in all files in the current
 directory whose names end in @samp{.c}.  Here the @option{-r} is
 probably unnecessary, as recursion occurs only in the unlikely event
 that one of @samp{.c} files is a directory.
+The @samp{find ...} command line above is more similar to the command:
+
+@example
+grep -rH --include='*.c' 'hello' /home/gigi
+@end example
 
 @item
 What if a pattern has a leading @samp{-}?
@@ -1174,7 +1341,7 @@
 prints two lines of context around each matching line.
 
 @item
-How do I force grep to print the name of the file?
+How do I force @command{grep} to print the name of the file?
 
 Append @file{/dev/null}:
 
@@ -1184,9 +1351,15 @@
 
 gets you:
 
-@smallexample
-/etc/passwd:eli:DNGUTF58.IMe.:98:11:Eli Smith:/home/do/eli:/bin/bash
-@end smallexample
+@example
+/etc/passwd:eli:x:2098:1000:Eli Smith:/home/eli:/bin/bash
+@end example
+
+Alternatively, use @samp{-H}, which is a @sc{gnu} extension:
+
+@example
+grep -H 'eli' /etc/passwd
+@end example
 
 @item
 Why do people use strange regular expressions on @command{ps} output?
@@ -1198,8 +1371,9 @@
 If the pattern had been written without the square brackets, it would
 have matched not only the @command{ps} output line for @command{cron},
 but also the @command{ps} output line for @command{grep}.
-Note that some platforms @command{ps} limit the ouput to the width
-of the screen, grep does not have any limit on the length of a line
+Note that on some platforms,
+@command{ps} limits the output to the width of the screen;
+@command{grep} does not have any limit on the length of a line
 except the available memory.
 
 @item
@@ -1215,7 +1389,7 @@
 @samp{--binary-files=without-match} option.
 
 @item
-Why doesn't @samp{grep -lv} print nonmatching file names?
+Why doesn't @samp{grep -lv} print non-matching file names?
 
 @samp{grep -lv} lists the names of all files containing one or more
 lines that do not match.  To list the names of all files that contain no
@@ -1245,8 +1419,9 @@
 @cindex palindromes
 How to express palindromes in a regular expression?
 
-It can be done by using the back referecences, for example a palindrome
-of 4 chararcters can be written in BRE.
+It can be done by using back-references;
+for example,
+a palindrome of 4 characters can be written with a BRE:
 
 @example
 grep -w -e '\(.\)\(.\).\2\1' file
@@ -1254,15 +1429,16 @@
 
 It matches the word "radar" or "civic".
 
-Guglielmo Bondioni proposed a single RE that finds all the palindromes up to 19
-characters long.
+Guglielmo Bondioni proposed a single RE
+that finds all palindromes up to 19 characters long
+using @w{9 subexpressions} and @w{9 back-references}:
 
-@example
+@smallexample
 grep -E -e '^(.?)(.?)(.?)(.?)(.?)(.?)(.?)(.?)(.?).?\9\8\7\6\5\4\3\2\1$' file
-@end example
+@end smallexample
 
-Note this is done by using GNU ERE extensions, it might not be portable on
-other greps.
+Note this is done by using @sc{gnu} ERE extensions;
+it might not be portable to other implementations of @command{grep}.
 
 @item
 Why is this back-reference failing?
@@ -1280,9 +1456,10 @@
 @item
 What do @command{grep}, @command{fgrep}, and @command{egrep} stand for?
 
-The name @command{grep} comes from the way line editing was done on Unix.  For
-example, @command{ed} uses the following syntax to print a list of matching
-lines on the screen:
+The name @command{grep} comes from the way line editing was done on Unix.
+For example,
+@command{ed} uses the following syntax
+to print a list of matching lines on the screen:
 
 @example
 global/regular expression/print
@@ -1300,10 +1477,13 @@
 @cindex Bugs, reporting
 Email bug reports to @email{bug-grep@@gnu.org}.
 
+@section Known Bugs
+@cindex Bugs, known
+
 Large repetition counts in the @samp{@{n,m@}} construct may cause
 @command{grep} to use lots of memory.  In addition, certain other
 obscure regular expressions require exponential time and
-space, and may cause grep to run out of memory.
+space, and may cause @command{grep} to run out of memory.
 Back-references are very slow, and may require exponential time.
 
 @node Copying, GNU General Public License, Reporting Bugs, Top
