>From 2ff0ebc82a12bc2df19500260a1d53b7f228fdcb Mon Sep 17 00:00:00 2001 From: Paul Eggert 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 address@hidden GNU Grep: Print lines matching a pattern address@hidden 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 address@hidden prints lines that contain a match for a pattern. address@hidden 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 address@hidden searching for a pattern address@hidden searching for patterns address@hidden 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 address@hidden address@hidden address@hidden @end example @noindent -There can be zero or more @var{options}. address@hidden 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 address@hidden 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 address@hidden -e @var{pattern} address@hidden address@hidden address@hidden -e @var{patterns} address@hidden address@hidden @opindex -e address@hidden address@hidden address@hidden pattern list -Use @var{pattern} as the pattern. address@hidden address@hidden address@hidden patterns option +Use @var{patterns} as one or more patterns; newlines within address@hidden 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 address@hidden @opindex -f @opindex --file address@hidden pattern from file address@hidden 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