Thanks for pointing out the problem. That patch is large enough to
require papers. Rather than hassling with that, I went to the source and
derived the attached patch independently, and installed it. I hope I
caught everything you did; if not please let us know (and perhaps it's
time to get papers from you for Grep too....).
>From 2ff0ebc82a12bc2df19500260a1d53b7f228fdcb Mon Sep 17 00:00:00 2001
From: Paul Eggert <egg...@cs.ucla.edu>
Date: Fri, 11 May 2018 08:30:12 -0700
Subject: [PATCH] =?UTF-8?q?doc:=20=E2=80=9Cpattern=E2=80=9D=20vs=20?=
=?UTF-8?q?=E2=80=9Cpatterns=E2=80=9D?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
* doc/grep.in.1, doc/grep.texi, src/grep.c (usage): Be more
careful about saying that an argument or option specifies one or
more patterns, not just a single pattern. Problem reported by Kaz
Kylheku (Bug#31400).
---
doc/grep.in.1 | 71 +++++++++++++++++++++++++++------------------------
doc/grep.texi | 57 ++++++++++++++++++++---------------------
src/grep.c | 32 +++++++++++------------
3 files changed, 81 insertions(+), 79 deletions(-)
diff --git a/doc/grep.in.1 b/doc/grep.in.1
index e260085..9d0d494 100644
--- a/doc/grep.in.1
+++ b/doc/grep.in.1
@@ -2,7 +2,7 @@
.de dT
.ds Dt \\$2
..
-.dT Time-stamp: "2018-04-21"
+.dT Time-stamp: "2018-05-11"
.\" Update the above date whenever a change to either this file or
.\" grep.c's 'usage' function results in a nontrivial change to the man page.
.\" In Emacs, you can update the date by running 'M-x time-stamp'
@@ -137,34 +137,39 @@
.hy 0
.
.SH NAME
-grep, egrep, fgrep \- print lines matching a pattern
+grep, egrep, fgrep \- print lines that match patterns
.
.SH SYNOPSIS
.B grep
-.RI [ OPTIONS ]
-.I PATTERN
+.RI [ OPTION .\|.\|.]\&
+.I PATTERNS
.RI [ FILE .\|.\|.]
.br
.B grep
-.RI [ OPTIONS ]
+.RI [ OPTION .\|.\|.]\&
.B \-e
-.I PATTERN
+.I PATTERNS
\&.\|.\|.\&
.RI [ FILE .\|.\|.]
.br
.B grep
-.RI [ OPTIONS ]
+.RI [ OPTION .\|.\|.]\&
.B \-f
-.I FILE
+.I PATTERN_FILE
\&.\|.\|.\&
.RI [ FILE .\|.\|.]
.
.SH DESCRIPTION
.B grep
searches for
-.I PATTERN
+.I PATTERNS
in each
.IR FILE .
+.I PATTERNS
+is one or patterns separated by newline characters, and
+.B grep
+prints each line that matches a pattern.
+.PP
A
.I FILE
of
@@ -174,9 +179,6 @@ If no
.I FILE
is given, recursive searches examine the working directory,
and nonrecursive searches read standard input.
-By default,
-.B grep
-prints the matching lines.
.PP
In addition, the variant programs
.B egrep
@@ -203,36 +205,37 @@ and exit.
.TP
.BR \-E ", " \-\^\-extended\-regexp
Interpret
-.I PATTERN
-as an extended regular expression (ERE, see below).
+.I PATTERNS
+as extended regular expressions (EREs, see below).
.TP
.BR \-F ", " \-\^\-fixed\-strings
Interpret
-.I PATTERN
-as a list of fixed strings (instead of regular expressions),
-separated by newlines,
-any of which is to be matched.
+.I PATTERNS
+as fixed strings, not regular expressions.
.TP
.BR \-G ", " \-\^\-basic\-regexp
Interpret
-.I PATTERN
-as a basic regular expression (BRE, see below).
+.I PATTERNS
+as basic regular expressions (BREs, see below).
This is the default.
.TP
.BR \-P ", " \-\^\-perl\-regexp
-Interpret the pattern as a Perl-compatible regular expression (PCRE).
-This is experimental and
+Interpret PATTERNS as Perl-compatible regular expressions (PCREs).
+This option is experimental when combined with the
+.B \-z
+.RB ( \-\^\-null\-data )
+option, and
.B "grep \-P"
may warn of unimplemented features.
.SS "Matching Control"
.TP
-.BI \-e " PATTERN" "\fR,\fP \-\^\-regexp=" PATTERN
+.BI \-e " PATTERNS" "\fR,\fP \-\^\-regexp=" PATTERNS
Use
-.I PATTERN
-as the pattern.
+.I PATTERNS
+as the patterns.
If this option is used multiple times or is combined with the
.B \-f
-.RB ( \-\-file )
+.RB ( \-\^\-file )
option, search for all patterns given.
This option can be used to protect a pattern beginning with \*(lq\-\*(rq.
.TP
@@ -242,7 +245,7 @@ Obtain patterns from
one per line.
If this option is used multiple times or is combined with the
.B \-e
-.RB ( \-\-regexp )
+.RB ( \-\^\-regexp )
option, search for all patterns given.
The empty file contains zero patterns, and therefore matches nothing.
.TP
@@ -389,7 +392,7 @@ Display input actually coming from standard input as input coming from file
This is especially useful when implementing tools like
.BR zgrep ,
e.g.,
-.BR "gzip -cd foo.gz | grep --label=foo -H something" .
+.BR "gzip \-cd foo.gz | grep \-\^\-label=foo \-H something" .
See also the
.B \-H
option.
@@ -511,7 +514,7 @@ matches, or no message if there is no match.
If
.I TYPE
is
-.BR without-match ,
+.BR without\-match ,
when
.B grep
discovers that a file is binary it assumes that the rest of the file
@@ -635,13 +638,13 @@ as wildcards, and
.B \e
to quote a wildcard or backslash character literally.
.TP
-.BI \-\^\-exclude-from= FILE
+.BI \-\^\-exclude\-from= FILE
Skip files whose base name matches any of the file-name globs read from
.I FILE
(using wildcard matching as described under
.BR \-\^\-exclude ).
.TP
-.BI \-\^\-exclude-dir= GLOB
+.BI \-\^\-exclude\-dir= GLOB
Skip any command-line directory with a name suffix that matches the
pattern
.IR GLOB .
@@ -654,7 +657,7 @@ Ignore any redundant trailing slashes in
.BR \-I
Process a binary file as if it did not contain matching data; this is
equivalent to the
-.B \-\^\-binary\-files=without-match
+.B \-\^\-binary\-files=without\-match
option.
.TP
.BI \-\^\-include= GLOB
@@ -987,10 +990,10 @@ have priority over it.
It can only specify the color used to highlight
the matching non-empty text in any matching line
(a selected line when the
-.B -v
+.B \-v
command-line option is omitted,
or a context line when
-.B -v
+.B \-v
is specified).
The default is
.BR 01;31 ,
diff --git a/doc/grep.texi b/doc/grep.texi
index 872ba07..1b37c98 100644
--- a/doc/grep.texi
+++ b/doc/grep.texi
@@ -33,11 +33,11 @@ Texts. A copy of the license is included in the section entitled
@dircategory Text creation and manipulation
@direntry
-* grep: (grep). Print lines matching a pattern.
+* grep: (grep). Print lines that match patterns.
@end direntry
@titlepage
-@title GNU Grep: Print lines matching a pattern
+@title GNU Grep: Print lines that match patterns
@subtitle version @value{VERSION}, @value{UPDATED}
@author Alain Magloire et al.
@page
@@ -52,7 +52,7 @@ Texts. A copy of the license is included in the section entitled
@node Top
@top grep
-@command{grep} prints lines that contain a match for a pattern.
+@command{grep} prints lines that contain a match for one or more patterns.
This manual is for version @value{VERSION} of GNU Grep.
@@ -74,10 +74,10 @@ This manual is for version @value{VERSION} of GNU Grep.
@node Introduction
@chapter Introduction
-@cindex searching for a pattern
+@cindex searching for patterns
-@command{grep} searches input files
-for lines containing a match to a given pattern list.
+Given one or more patterns, @command{grep} searches input files
+for matches to the patterns.
When it finds a match in a line,
it copies the line to standard output (by default),
or produces whatever other sort of output you have requested with options.
@@ -97,17 +97,16 @@ there is no way to match newline characters in a text.
The general synopsis of the @command{grep} command line is
@example
-grep @var{options} @var{pattern} @var{input_file_names}
+grep [@var{option}...] [@var{patterns}] [@var{file}...]
@end example
@noindent
-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}
-(by using the @samp{-e@ @var{pattern}}
-or @samp{-f@ @var{file}} options).
-There can be zero or more @var{input_file_names}.
+
+There can be zero or more @var{option} arguments, and zero or more
+@var{file} arguments. The @var{patterns} argument contains one or
+more patterns separated by newlines, and is omitted when patterns are
+given via the @samp{-e@ @var{patterns}} or @samp{-f@ @var{file}}
+options.
@menu
* Command-line Options:: Short and long names, grouped by category.
@@ -170,12 +169,13 @@ This version number should be included in all bug reports.
@table @option
-@item -e @var{pattern}
-@itemx --regexp=@var{pattern}
+@item -e @var{patterns}
+@itemx --regexp=@var{patterns}
@opindex -e
-@opindex --regexp=@var{pattern}
-@cindex pattern list
-Use @var{pattern} as the pattern.
+@opindex --regexp=@var{patterns}
+@cindex patterns option
+Use @var{patterns} as one or more patterns; newlines within
+@var{patterns} separate each pattern from the next.
If this option is used multiple times or is combined with the
@option{-f} (@option{--file}) option, search for all patterns given.
(@option{-e} is specified by POSIX.)
@@ -184,7 +184,7 @@ If this option is used multiple times or is combined with the
@itemx --file=@var{file}
@opindex -f
@opindex --file
-@cindex pattern from file
+@cindex patterns from file
Obtain patterns from @var{file}, one per line.
If this option is used multiple times or is combined with the
@option{-e} (@option{--regexp}) option, search for all patterns given.
@@ -240,7 +240,7 @@ This option has no effect if @option{-x} is also specified.
Because the @option{-w} option can match a substring that does not
begin and end with word constituents, it differs from surrounding a
-pattern with @samp{\<} and @samp{\>}. For example, although
+regular expression with @samp{\<} and @samp{\>}. For example, although
@samp{grep -w @@} matches a line containing only @samp{@@}, @samp{grep
'\<@@\>'} cannot match any line because @samp{@@} is not a
word constituent. @xref{The Backslash Character and Special
@@ -252,7 +252,7 @@ Expressions}.
@opindex --line-regexp
@cindex match the whole line
Select only those matches that exactly match the whole line.
-For a regular expression pattern, this is like parenthesizing the
+For regular expression patterns, this is like parenthesizing each
pattern and then surrounding it with @samp{^} and @samp{$}.
(@option{-x} is specified by POSIX.)
@@ -1103,7 +1103,7 @@ greater than 2 on error.
@cindex variants of @command{grep}
@command{grep} searches the named input files
-for lines containing a match to the given pattern.
+for lines containing a match to the given patterns.
By default, @command{grep} prints the matching lines.
A file named @file{-} stands for standard input.
If no input is specified, @command{grep} searches the working
@@ -1119,7 +1119,7 @@ controlled by the following options.
@opindex -G
@opindex --basic-regexp
@cindex matching basic regular expressions
-Interpret the pattern as a basic regular expression (BRE).
+Interpret patterns as basic regular expressions (BREs).
This is the default.
@item -E
@@ -1127,7 +1127,7 @@ This is the default.
@opindex -E
@opindex --extended-regexp
@cindex matching extended regular expressions
-Interpret the pattern as an extended regular expression (ERE).
+Interpret patterns as extended regular expressions (EREs).
(@option{-E} is specified by POSIX.)
@item -F
@@ -1135,8 +1135,7 @@ Interpret the pattern as an extended regular expression (ERE).
@opindex -F
@opindex --fixed-strings
@cindex matching fixed strings
-Interpret the pattern as a list of fixed strings (instead of regular
-expressions), separated by newlines, any of which is to be matched.
+Interpret patterns as fixed strings, not regular expressions.
(@option{-F} is specified by POSIX.)
@item -P
@@ -1144,7 +1143,7 @@ expressions), separated by newlines, any of which is to be matched.
@opindex -P
@opindex --perl-regexp
@cindex matching Perl-compatible regular expressions
-Interpret the pattern as a Perl-compatible regular expression (PCRE).
+Interpret patterns as Perl-compatible regular expressions (PCREs).
PCRE support is here to stay, but consider this option experimental when
combined with the @option{-z} (@option{--null-data}) option, and note that
@samp{grep@ -P} may warn of unimplemented features.
@@ -1846,7 +1845,7 @@ Aho--Corasick algorithm is used to match multiple fixed patterns.
@cindex locales
Generally speaking @command{grep} operates more efficiently in
single-byte locales, since it can avoid the special processing needed
-for multi-byte characters. If your pattern will work just as well
+for multi-byte characters. If your patterns will work just as well
that way, setting @env{LC_ALL} to a single-byte locale can help
performance considerably. Setting @samp{LC_ALL='C'} can be
particularly efficient, as @command{grep} is tuned for that locale.
diff --git a/src/grep.c b/src/grep.c
index 6754e4e..f4ae5f5 100644
--- a/src/grep.c
+++ b/src/grep.c
@@ -1905,31 +1905,32 @@ usage (int status)
{
if (status != 0)
{
- fprintf (stderr, _("Usage: %s [OPTION]... PATTERN [FILE]...\n"),
+ fprintf (stderr, _("Usage: %s [OPTION]... PATTERNS [FILE]...\n"),
getprogname ());
fprintf (stderr, _("Try '%s --help' for more information.\n"),
getprogname ());
}
else
{
- printf (_("Usage: %s [OPTION]... PATTERN [FILE]...\n"), getprogname ());
- printf (_("Search for PATTERN in each FILE.\n"));
+ printf (_("Usage: %s [OPTION]... PATTERNS [FILE]...\n"), getprogname ());
+ printf (_("Search for PATTERNS in each FILE.\n"));
printf (_("\
Example: %s -i 'hello world' menu.h main.c\n\
+PATTERNS can contain multiple patterns separated by newlines.\n\
\n\
Pattern selection and interpretation:\n"), getprogname ());
printf (_("\
- -E, --extended-regexp PATTERN is an extended regular expression\n\
- -F, --fixed-strings PATTERN is a set of newline-separated strings\n\
- -G, --basic-regexp PATTERN is a basic regular expression (default)\n\
- -P, --perl-regexp PATTERN is a Perl regular expression\n"));
+ -E, --extended-regexp PATTERNS are extended regular expressions\n\
+ -F, --fixed-strings PATTERNS are strings\n\
+ -G, --basic-regexp PATTERNS are basic regular expressions\n\
+ -P, --perl-regexp PATTERNS are Perl regular expressions\n"));
/* -X is deliberately undocumented. */
printf (_("\
- -e, --regexp=PATTERN use PATTERN for matching\n\
- -f, --file=FILE obtain PATTERN from FILE\n\
+ -e, --regexp=PATTERNS use PATTERNS for matching\n\
+ -f, --file=FILE take PATTERNS from FILE\n\
-i, --ignore-case ignore case distinctions\n\
- -w, --word-regexp force PATTERN to match only whole words\n\
- -x, --line-regexp force PATTERN to match only whole lines\n\
+ -w, --word-regexp match only whole words\n\
+ -x, --line-regexp match only whole lines\n\
-z, --null-data a data line ends in 0 byte, not newline\n"));
printf (_("\
\n\
@@ -1950,7 +1951,7 @@ Output control:\n\
--label=LABEL use LABEL as the standard input file name prefix\n\
"));
printf (_("\
- -o, --only-matching show only nonempty parts of lines matching PATTERN\n\
+ -o, --only-matching show only nonempty parts of lines that match\n\
-q, --quiet, --silent suppress all normal output\n\
--binary-files=TYPE assume that binary files are TYPE;\n\
TYPE is 'binary', 'text', or 'without-match'\n\
@@ -1966,11 +1967,10 @@ Output control:\n\
-R, --dereference-recursive likewise, but follow all symlinks\n\
"));
printf (_("\
- --include=FILE_PATTERN search only files that match FILE_PATTERN\n\
- --exclude=FILE_PATTERN skip files and directories matching\
- FILE_PATTERN\n\
+ --include=GLOB search only files that match GLOB (a file pattern)\n\
+ --exclude=GLOB skip files and directories matching GLOB\n\
--exclude-from=FILE skip files matching any file pattern from FILE\n\
- --exclude-dir=PATTERN directories that match PATTERN will be skipped.\n\
+ --exclude-dir=GLOB skip directories that match GLOB\n\
"));
printf (_("\
-L, --files-without-match print only names of FILEs with no selected lines\n\
--
2.17.0
