Index: grep/ChangeLog
===================================================================
RCS file: /cvsroot/grep/grep/ChangeLog,v
retrieving revision 1.280
diff -u -r1.280 ChangeLog
--- grep/ChangeLog	10 Nov 2005 19:57:54 -0000	1.280
+++ grep/ChangeLog	11 Nov 2005 05:00:08 -0000
@@ -1,3 +1,35 @@
+2005-11-11  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.
+	* 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: Create a new @menu and @nodes for the "Invoking grep"
+	  @chapter.  Create a new "POSIX Options" @section.  Create a new
+	  @menu, @nodes, and @subsections for the "GNU Extensions Options"
+	  @section: "Generic Program Information", "Context Line Control",
+	  "Output Line Prefix Control", "File and Directory Selection",
+	  and "Other Options".  Reorganize existing options accordingly.
+	  @xref to the "grep Programs" @chapter earlier in the one above.
+	  Merge synonym options under the main name and explain their status.
+	  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.
+	  Update copyright notice years according to CVS logs (1998-2005).
+	  Fix various typographical and source code formatting details.
+	* 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-10  Charles Levert  <charles_levert@gna.org>
 
 	The introduction of the --only-matching and --color GNU extensions
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	11 Nov 2005 04:57:39 -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,6 +90,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
 .BI \-C " NUM" "\fR,\fP \-\^\-context=" NUM
 Print
@@ -94,6 +103,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 \-b ", " \-\^\-byte-offset
 Print the byte offset within the input file before
@@ -203,7 +217,9 @@
 .BR \- .
 .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
@@ -244,7 +260,7 @@
 and the input files.
 .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
@@ -350,7 +366,7 @@
 Suppress error messages about nonexistent or unreadable files.
 Portability note: unlike \s-1GNU\s0
 .BR grep ,
-7th Edition Unix
+7th Edition -s-1UNIX-s0
 .B grep
 did not conform to \s-1POSIX\s0, because it lacked
 .B \-q
@@ -394,7 +410,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 +427,21 @@
 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 \s-1UNIX\s0-style byte offsets.
+This switch causes
 .B grep
-to report byte offsets as if the file were Unix-style text file, i.e., with
+to report byte offsets as if the file were \s-1UNIX\s0-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 \s-1UNIX\s0 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
@@ -471,9 +490,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.
@@ -683,7 +701,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
@@ -848,7 +867,9 @@
 .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
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	11 Nov 2005 04:37:35 -0000
@@ -36,7 +36,7 @@
 Boston, MA 02110-1301, USA
 
 @c man begin COPYRIGHT
-Copyright @copyright{} 2000, 2001 Free Software Foundation, Inc.
+Copyright @copyright{} 1998--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
@@ -68,7 +68,7 @@
 
 @page
 @vskip 0pt plus 1filll
-Copyright @copyright{} 2000, 2001 Free Software Foundation, Inc.
+Copyright @copyright{} 1998--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
@@ -132,8 +132,24 @@
 @node Invoking
 @chapter Invoking @command{grep}
 
-@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.
+
+Several additional options control
+which variant of the @command{grep} matching engine is used.
+@xref{grep Programs}.
+
+@menu
+* POSIX Options::               Standard short options and their long names.
+* GNU Options::                 GNU extensions, grouped by categories.
+* Environment Variables::       POSIX, GNU generic, and GNU grep specific.
+@end menu
+
+@node POSIX Options
+@section @sc{posix} Options
+
+The long option names are a @sc{gnu} extension in themselves,
+but these options as such are from @sc{posix} specifications.
 
 @table @samp
 
@@ -163,11 +179,14 @@
 file contains zero patterns, and therefore matches nothing.
 
 @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.
 
 @item -l
 @itemx --files-with-matches
@@ -185,14 +204,6 @@
 @cindex line numbering
 Prefix each line of output with the line number within its input file.
 
-@item -o
-@itemx --only-matching
-@opindex -o
-@opindex --only-matching
-@cindex only matching
-Print only the non-empty parts of matching lines
-that actually match @var{pattern}.
-
 @item -q
 @itemx --quiet
 @itemx --silent
@@ -210,7 +221,7 @@
 @opindex --no-messages
 @cindex suppress error messages
 Suppress error messages about nonexistent or unreadable files.
-Portability note: unlike @sc{gnu} @command{grep}, 7th Edition Unix
+Portability note: unlike @sc{gnu} @command{grep}, 7th Edition @sc{unix}
 @command{grep} did not conform to @sc{posix}, because it
 lacked @samp{-q} and its @samp{-s} option behaved like @sc{gnu}
 @command{grep}'s @samp{-q} option.  @sc{usg}-style @command{grep}
@@ -236,7 +247,45 @@
 
 @end table
 
-@section @sc{gnu} Extensions
+@node GNU Options
+@section @sc{gnu} Extensions Options
+
+@menu
+* Generic Program Information::
+* Context Line Control::
+* Output Line Prefix 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 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,12 +306,225 @@
 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 -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 non-zero 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.
+
+@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 may have been 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 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 --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 -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 @sc{unix}-style byte offsets.
+This option causes @command{grep} to report byte offsets
+as if the file were a @sc{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 @sc{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
+
+@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},
+@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.
+@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 -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.
+
+@item -d @var{action}
+@itemx --directories=@var{action}
+@opindex -d
+@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 --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 --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.
+
+@item -r
+@itemx -R
+@itemx --recursive
+@opindex -r
+@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.
+
+@end table
+
+@node Other Options
+@subsection Other Options
+
+@table @samp
+
 @item --color[=@var{WHEN}]
 @itemx --colour[=@var{WHEN}]
 @opindex --color
@@ -281,103 +543,11 @@
 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.
-
-@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},
-@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.
-@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.
-
-@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.
-
-@item -d @var{action}
-@itemx --directories=@var{action}
-@opindex -d
-@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}
-
 @item -L
 @itemx --files-without-match
 @opindex -L
@@ -386,20 +556,87 @@
 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 -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 -I
-Process a binary file as if it did not contain matching data; this is
-equivalent to the @samp{--binary-files=without-match} option.
 
+@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 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 --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 -o
+@itemx --only-matching
+@opindex -o
+@opindex --only-matching
+@cindex only matching
+Print only the non-empty parts of matching lines
+that actually match @var{pattern}.
+
+@item -U
+@itemx --binary
+@opindex -U
+@opindex --binary
+@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 -w
 @itemx --word-regexp
 @opindex -w
@@ -413,147 +650,6 @@
 a non-word constituent character.  Word-constituent
 characters are letters, digits, and the underscore.
 
-@item -r
-@itemx -R
-@itemx --recursive
-@opindex -r
-@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.
-
-@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}.
-
-@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.
-
 @item -z
 @itemx --null-data
 @opindex -z
@@ -566,9 +662,7 @@
 
 @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
@@ -717,7 +811,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.
@@ -1023,9 +1117,8 @@
 
 @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}.
 
 @section Anchoring
 @cindex anchoring
@@ -1039,10 +1132,10 @@
 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
+@samp{-e} or from a file (@samp{-f file}), the back-references are local to
 each expression.
 
 @section Basic vs Extended
@@ -1061,7 +1154,7 @@
 
 @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 +1164,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
@@ -1112,7 +1205,7 @@
 
 @noindent
 searches for @samp{hello} in all files under the directory
-@file{/home/gigi}.  For more control of which files are searched, use
+@file{/home/gigi}.  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:
 
@@ -1174,7 +1267,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}:
 
@@ -1198,8 +1291,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
@@ -1245,8 +1339,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
@@ -1255,14 +1350,14 @@
 It matches the word "radar" or "civic".
 
 Guglielmo Bondioni proposed a single RE that finds all the palindromes up to 19
-characters long.
+characters long:
 
 @example
 grep -E -e '^(.?)(.?)(.?)(.?)(.?)(.?)(.?)(.?)(.?).?\9\8\7\6\5\4\3\2\1$' file
 @end example
 
-Note this is done by using GNU ERE extensions, it might not be portable on
-other greps.
+Note this is done by using GNU ERE extensions;
+it might not be portable to other implementations of @command{grep}.
 
 @item
 Why is this back-reference failing?
@@ -1280,9 +1375,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 @sc{unix}.
+For example,
+@command{ed} uses the following syntax
+to print a list of matching lines on the screen:
 
 @example
 global/regular expression/print
@@ -1303,7 +1399,7 @@
 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
