--- Begin Message ---
|
Subject: |
[PATCH] doc: document that input pattern is a list. |
|
Date: |
Wed, 09 May 2018 16:16:05 -0700 |
|
User-agent: |
Roundcube Webmail/0.9.2 |
From 2f4c7860efd4dc8610574732a4f2ec2609dab326 Mon Sep 17 00:00:00 2001
From: Kaz Kylheku <address@hidden>
Date: Wed, 9 May 2018 14:41:48 -0700
Subject: [PATCH] doc: document that input pattern is a list.
Both the manual page and Info documentation now make it clear that the
pattern is actually a list of patterns separated by newlines.
---
doc/grep.in.1 | 39 +++++++++++++++++++++++++++------------
doc/grep.texi | 42 ++++++++++++++++++++++++++----------------
2 files changed, 53 insertions(+), 28 deletions(-)
diff --git a/doc/grep.in.1 b/doc/grep.in.1
index e260085..627798f 100644
--- a/doc/grep.in.1
+++ b/doc/grep.in.1
@@ -142,13 +142,13 @@ grep, egrep, fgrep \- print lines matching a
pattern
.SH SYNOPSIS
.B grep
.RI [ OPTIONS ]
-.I PATTERN
+.I PATTERNS
.RI [ FILE .\|.\|.]
.br
.B grep
.RI [ OPTIONS ]
.B \-e
-.I PATTERN
+.I PATTERNS
\&.\|.\|.\&
.RI [ FILE .\|.\|.]
.br
@@ -162,9 +162,22 @@ grep, egrep, fgrep \- print lines matching a
pattern
.SH DESCRIPTION
.B grep
searches for
-.I PATTERN
+.I PATTERNS
in each
.IR FILE .
+
+The
+.I PATTERNS
+argument specifies one or more patterns. In the most common usage of
+.BR grep ,
+a single pattern
+is specified. If the argument contains embedded newline characters,
+they are interpreted as the separators in a list which contains
+multiple patterns. If the first or last character of
+.I PATTERNS
+is a newline, then the list contains an empty pattern, which matches
+anything.
+
A
.I FILE
of
@@ -203,20 +216,22 @@ and exit.
.TP
.BR \-E ", " \-\^\-extended\-regexp
Interpret
-.I PATTERN
-as an extended regular expression (ERE, see below).
+.I PATTERNS
+as extended regular expressions (ERE, see below).
.TP
.BR \-F ", " \-\^\-fixed\-strings
Interpret
-.I PATTERN
+.I PATTERNS
as a list of fixed strings (instead of regular expressions),
separated by newlines,
-any of which is to be matched.
+any of which is to be matched. There is no way to escape a newline
+character such that it is interpreted as an element of a fixed string
+pattern rather than a separator.
.TP
.BR \-G ", " \-\^\-basic\-regexp
Interpret
-.I PATTERN
-as a basic regular expression (BRE, see below).
+.I PATTERNS
+as basic regular expressions (BRE, see below).
This is the default.
.TP
.BR \-P ", " \-\^\-perl\-regexp
@@ -226,10 +241,10 @@ This is experimental and
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 )
diff --git a/doc/grep.texi b/doc/grep.texi
index 872ba07..319f696 100644
--- a/doc/grep.texi
+++ b/doc/grep.texi
@@ -37,7 +37,7 @@ Texts. A copy of the license is included in the
section entitled
@end direntry
@titlepage
address@hidden GNU Grep: Print lines matching a pattern
address@hidden GNU Grep: Print lines matching a pattern or 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 a pattern or
multiple patterns.
This manual is for version @value{VERSION} of GNU Grep.
@@ -97,18 +97,26 @@ 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{options} @var{pattern_list} @var{input_file_names}
@end example
@noindent
There can be zero or more @var{options}.
address@hidden will only be seen as such
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}}
+(by using the @samp{-e@ @var{pattern_list}}
or @samp{-f@ @var{file}} options).
There can be zero or more @var{input_file_names}.
+The @var{pattern_list} usually specifies a single pattern. If embedded
+newline characters occur in @var{pattern_list}, they are interpreted
+as the separators in a list which specifies multiple patterns.
+Note that if @var{pattern_list} begins or ends with an embedded
newline, this
+newline is also treated as a separator rather than a terminator, and an
empty
+pattern is thereby included in the pattern list. The empty pattern
+matches every input line.
+
@menu
* Command-line Options:: Short and long names, grouped by
category.
* Environment Variables:: POSIX, GNU generic, and GNU grep
specific.
@@ -170,12 +178,12 @@ 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{pattern_list}
address@hidden address@hidden
@opindex -e
address@hidden address@hidden
address@hidden address@hidden
@cindex pattern list
-Use @var{pattern} as the pattern.
+Use @var{pattern_list} as the pattern list.
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.)
@@ -617,7 +625,7 @@ this is equivalent to the @option{-a} option.
When @var{type} is @samp{binary}, @command{grep} may treat non-text
bytes as line terminators even without the @option{-z}
(@option{--null-data}) option. This means choosing @samp{binary}
-versus @samp{text} can affect whether a pattern matches a file. For
+versus @samp{text} can affect whether a pattern list matches a file.
For
example, when @var{type} is @samp{binary} the pattern @samp{q$} might
match @samp{q} immediately followed by a null byte, even though this
is not matched when @var{type} is @samp{text}. Conversely, when
@@ -742,7 +750,7 @@ directory, recursively, following all symbolic
links.
@cindex option delimiter
Delimit the option list. Later arguments, if any, are treated as
operands even if they begin with @samp{-}. For example, @samp{grep PAT
--
--file1 file2} searches for the pattern PAT in the files named
@file{-file1}
+-file1 file2} searches for the patterns PAT in the files named
@file{-file1}
and @file{file2}.
@item --line-buffered
@@ -1103,7 +1111,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 pattern list.
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 +1127,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 the pattern list as one or more basic regular expressions
(BRE-s).
This is the default.
@item -E
@@ -1127,7 +1135,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 the patterns as a extended regular expressions (ERE-s).
(@option{-E} is specified by POSIX.)
@item -F
@@ -1135,8 +1143,10 @@ 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
+Interpret the pattern list as a list of fixed strings (instead of
regular
expressions), separated by newlines, any of which is to be matched.
+There is no way to escape a newline such that it is interpreted as part
+of a fixed pattern, rather than a separator.
(@option{-F} is specified by POSIX.)
@item -P
@@ -1144,7 +1154,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 the patterns as a Perl-compatible regular expressions
(PCRE-s).
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.
--
2.9.3
--- End Message ---
0001-doc-pattern-vs-patterns.patch