Subject: bug#18651: closed (Re: bug#18651: Clarify exit status description)

From: [email-masked] (GNU bug Tracking System)
Date: Thu, 31 Dec 2015 08:55:02 +0000

Your bug report

#18651: Clarify exit status description

which was filed against the grep package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to [email-masked].

-- 
18651: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=18651
GNU Bug Tracking System
Contact [email-masked] with problems

Subject: Re: bug#18651: Clarify exit status description
From: Paul Eggert <[email-masked]>
To: [email-masked], Santiago Ruano Rincón<[email-masked]>
Date: Thu, 31 Dec 2015 00:54:08 -0800
List-Id: <debbugs-submit.debbugs.gnu.org>

 > here you have remaining doc-related changes included in Debian.

Thanks. I installed the attached patch, which should fix the problems noted 
(though with different wording), and am marking this bug as done.
>From f61187acad67bf34cd1fd9fbbacd2a0a8fb054b1 Mon Sep 17 00:00:00 2001
From: Paul Eggert <[email-masked]>
Date: Thu, 31 Dec 2015 00:50:43 -0800
Subject: [PATCH] doc: minor clarifications
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* doc/grep.in.1, doc/grep.texi: Minor clarifications suggested by
Debian documentation patches.  Problem reported by Santiago Ruano
Rincón in: http://bugs.gnu.org/18651
---
 doc/grep.in.1 | 17 ++++++++++++-----
 doc/grep.texi |  8 +++++---
 2 files changed, 17 insertions(+), 8 deletions(-)

diff --git a/doc/grep.in.1 b/doc/grep.in.1
index 2b513a8..8938478 100644
--- a/doc/grep.in.1
+++ b/doc/grep.in.1
@@ -87,7 +87,8 @@ as an extended regular expression (ERE, see below).
 .BR \-F ", " \-\^\-fixed\-strings
 Interpret
 .I PATTERN
-as a list of fixed strings, separated by newlines,
+as a list of fixed strings (instead of regular expressions),
+separated by newlines,
 any of which is to be matched.
 .TP
 .BR \-G ", " \-\^\-basic\-regexp
@@ -99,7 +100,7 @@ This is the default.
 .BR \-P ", " \-\^\-perl\-regexp
 Interpret
 .I PATTERN
-as a Perl regular expression.
+as a Perl regular expression (PCRE, see below).
 This is highly experimental and
 .B "grep \-P"
 may warn of unimplemented features.
@@ -138,6 +139,11 @@ Word-constituent characters are letters, digits, and the underscore.
 .TP
 .BR \-x ", " \-\^\-line\-regexp
 Select only those matches that exactly match the whole line.
+For a regular expression pattern, this is like parenthesizing the
+pattern and then surrounding it with
+.B ^
+and
+.BR $ .
 .TP
 .B \-y
 Obsolete synonym for
@@ -531,7 +537,8 @@ expressions, by using various operators to combine smaller expressions.
 .PP
 .B grep
 understands three different versions of regular expression syntax:
-\*(lqbasic,\*(rq \*(lqextended\*(rq and \*(lqperl.\*(rq In
+\*(lqbasic\*(rq (BRE), \*(lqextended\*(rq (ERE) and \*(lqperl\*(rq (PCRE).
+In
 .RB "\s-1GNU\s0\ " grep ,
 there is no difference in available functionality between basic and
 extended syntaxes.
@@ -539,8 +546,8 @@ 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 pcresyntax(3) and pcrepattern(3), but may not be
-available on every system.
+documented in pcresyntax(3) and pcrepattern(3), but work only if
+PCRE is available in the system.
 .PP
 The fundamental building blocks are the regular expressions
 that match a single character.
diff --git a/doc/grep.texi b/doc/grep.texi
index 58e7f48..73151e4 100644
--- a/doc/grep.texi
+++ b/doc/grep.texi
@@ -240,6 +240,8 @@ Word-constituent characters are letters, digits, and the underscore.
 @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
+pattern and then surrounding it with @samp{^} and @samp{$}.
 (@option{-x} is specified by POSIX.)
 
 @end table
@@ -1091,8 +1093,8 @@ 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, separated
-by newlines, any of which is to be matched.
+Interpret the pattern as a list of fixed strings (instead of regular
+expressions), separated by newlines, any of which is to be matched.
 (@option{-F} is specified by POSIX.)
 
 @item -P
@@ -1134,7 +1136,7 @@ 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 may not be available on every system.
+but work only if PCRE is available in the system.
 
 @menu
 * Fundamental Structure::
-- 
2.5.0

Subject: Clarify exit status description
From: Santiago Ruano Rincón <[email-masked]>
To: [email-masked]
Date: Tue, 7 Oct 2014 11:36:18 +0200
List-Id: <debbugs-submit.debbugs.gnu.org>

Hi,

I'm attaching to this mail an old proposal to clarify the exit status
description, included in the debian package: https://bugs.debian.org/446854

Regards,

Santiago
From 2432287712e802ce821e3158fb4f40a1a7b8b436 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Santiago=20Ruano=20Rinc=C3=B3n?= <[email-masked]>
Date: Tue, 7 Oct 2014 11:19:56 +0200
Subject: [PATCH] Simplify EXIT STATUS information

* doc/grep.in.1, doc/grep.texi: clarify information regarding exit status.
"A. Costa" <[email-masked]> wrote the original patch.
See: https://bugs.debian.org/446854
---
 doc/grep.in.1 | 16 ++++------------
 doc/grep.texi | 14 ++++----------
 2 files changed, 8 insertions(+), 22 deletions(-)

diff --git a/doc/grep.in.1 b/doc/grep.in.1
index 00d030a..44da7e9 100644
--- a/doc/grep.in.1
+++ b/doc/grep.in.1
@@ -1143,23 +1143,15 @@ when
 is not set.
 .
 .SH "EXIT STATUS"
-Normally, the exit status is 0 if selected lines are found and 1 otherwise.
-But the exit status is 2 if an error occurred, unless the
+The exit status is 0 if selected lines are found, and 1 if not found.
+If an error occurred (and
 .B \-q
 or
 .B \-\^\-quiet
 or
 .B \-\^\-silent
-option is used and a selected line is found.
-Note, however, that \s-1POSIX\s0 only mandates, for programs such as
-.BR grep ,
-.BR cmp ,
-and
-.BR diff ,
-that the exit status in case of error be greater than 1;
-it is therefore advisable, for the sake of portability,
-to use logic that tests for this general condition
-instead of strict equality with\ 2.
+are not used) the exit status is 2. (Note: POSIX error
+handling code should check for '2' or greater.)
 .
 .SH COPYRIGHT
 Copyright 1998-2000, 2002, 2005-2014 Free Software Foundation, Inc.
diff --git a/doc/grep.texi b/doc/grep.texi
index d7adcad..46361ce 100644
--- a/doc/grep.texi
+++ b/doc/grep.texi
@@ -1025,16 +1025,10 @@ and only when @env{POSIXLY_CORRECT} is not set.
 @cindex exit status
 @cindex return status
 
-Normally, the exit status is 0 if selected lines are found and 1 otherwise.
-But the exit status is 2 if an error occurred, unless the @option{-q} or
-@option{--quiet} or @option{--silent} option is used and a selected line
-is found.
-Note, however, that POSIX only mandates,
-for programs such as @command{grep}, @command{cmp}, and @command{diff},
-that the exit status in case of error be greater than 1;
-it is therefore advisable, for the sake of portability,
-to use logic that tests for this general condition
-instead of strict equality with@ 2.
+The exit status is 0 if selected lines are found, and 1 if not found.  If
+an error occurred (and @option{-q} or @option{--quiet} or
+@option{--silent} are not used) the exit status is 2. (Note: POSIX error
+handling code should check for '2' or greater.

 @node grep Programs
-- 
2.1.0