From 0269180966fe6e084b8d8af1a61a3d521ad7e081 Mon Sep 17 00:00:00 2001
From: Paul Eggert <address@hidden>
Date: Sun, 10 Apr 2016 21:27:35 -0700
Subject: [PATCH] grep: minor doc tweaks inspired by Debian
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Problem reported by Santiago Ruano Rincón in: http://bugs.gnu.org/22911
* doc/grep.in.1:
* doc/grep.texi (Matching Control, grep Programs)
(Regular Expressions):
Document -e, -f, and PCRE more carefully.
---
 doc/grep.in.1 | 18 +++++++++++-------
 doc/grep.texi | 18 ++++++++++--------
 2 files changed, 21 insertions(+), 15 deletions(-)

diff --git a/doc/grep.in.1 b/doc/grep.in.1
index ade11b4..1a3b7d2 100644
--- a/doc/grep.in.1
+++ b/doc/grep.in.1
@@ -98,9 +98,7 @@ as a basic regular expression (BRE, see below).
 This is the default.
 .TP
 .BR \-P ", " \-\^\-perl\-regexp
-Interpret
-.I PATTERN
-as a Perl regular expression (PCRE, see below).
+Interpret the pattern as a Perl-compatible regular expression (PCRE).
 This is highly experimental and
 .B "grep \-P"
 may warn of unimplemented features.
@@ -110,14 +108,20 @@ may warn of unimplemented features.
 Use
 .I PATTERN
 as the pattern.
-This can be used to specify multiple search patterns,
-or to protect a pattern beginning with a hyphen
-.RB ( \- ).
+If this option is used multiple times or is combined with the
+.B \-f
+.RB ( \-\-file )
+option, search for all patterns given.
+This option can be used to protect a pattern beginning with \*(lq\-\*(rq.
 .TP
 .BI \-f " FILE" "\fR,\fP \-\^\-file=" FILE
 Obtain patterns from
 .IR FILE ,
 one per line.
+If this option is used multiple times or is combined with the
+.B \-e
+.RB ( \-\-regexp )
+option, search for all patterns given.
 The empty file contains zero patterns, and therefore matches nothing.
 .TP
 .BR \-i ", " \-\^\-ignore\-case
@@ -545,7 +549,7 @@ extended syntaxes.
 In other implementations, basic regular expressions are less powerful.
 The following description applies to extended regular expressions;
 differences for basic regular expressions are summarized afterwards.
-Perl regular expressions give additional functionality, and are
+Perl-compatible regular expressions give additional functionality, and are
 documented in pcresyntax(3) and pcrepattern(3), but work only if
 PCRE is available in the system.
 .PP
diff --git a/doc/grep.texi b/doc/grep.texi
index 4e0e48e..80768dd 100644
--- a/doc/grep.texi
+++ b/doc/grep.texi
@@ -175,8 +175,8 @@ This version number should be included in all bug reports.
 @opindex address@hidden
 @cindex pattern list
 Use @var{pattern} as the pattern.
-This can be used to specify multiple search patterns,
-or to protect a pattern beginning with a @samp{-}.
+If this option is used multiple times or is combined with the
address@hidden (@option{--file}) option, search for all patterns given.
 (@option{-e} is specified by POSIX.)
 
 @item -f @var{file}
@@ -185,6 +185,8 @@ or to protect a pattern beginning with a @samp{-}.
 @opindex --file
 @cindex pattern from file
 Obtain patterns from @var{file}, one per line.
+If this option is used multiple times or is combined with the
address@hidden (@option{--regexp}) option, search for all patterns given.
 The empty file contains zero patterns, and therefore matches nothing.
 (@option{-f} is specified by POSIX.)
 
@@ -1116,8 +1118,8 @@ expressions), separated by newlines, any of which is to be matched.
 @itemx --perl-regexp
 @opindex -P
 @opindex --perl-regexp
address@hidden matching Perl regular expressions
-Interpret the pattern as a Perl regular expression.
address@hidden matching Perl-compatible regular expressions
+Interpret the pattern as a Perl-compatible regular expression (PCRE).
 This is highly experimental and
 @samp{grep@ -P} may warn of unimplemented features.
 
@@ -1142,16 +1144,16 @@ Regular expressions are constructed analogously to arithmetic expressions,
 by using various operators to combine smaller expressions.
 @command{grep} understands
 three different versions of regular expression syntax:
-``basic,'' (BRE) ``extended'' (ERE) and ``perl''.
+``basic'' (BRE), ``extended'' (ERE) and ``perl'' (PCRE).
 In GNU @command{grep},
 there is no difference in available functionality between the basic and
 extended syntaxes.
 In other implementations, basic regular expressions are less powerful.
 The following description applies to extended regular expressions;
 differences for basic regular expressions are summarized afterwards.
-Perl regular expressions give additional functionality, and are
-documented in the @i{pcresyntax}(3) and @i{pcrepattern}(3) manual pages,
-but work only if PCRE is available in the system.
+Perl-compatible regular expressions give additional functionality, and
+are documented in the @i{pcresyntax}(3) and @i{pcrepattern}(3) manual
+pages, but work only if PCRE is available in the system.
 
 @menu
 * Fundamental Structure::
-- 
2.5.5