Subject: Re: bug#18651: Clarify exit status description

From: Paul Eggert <[email-masked]>
Date: Tue, 07 Oct 2014 09:27:02 -0700

Hmmm, well, to me the proposed clarification is not that clear either.  
And the man page is no place for a chatty discussion about what POSIX 
allows of other implementations; the full manual is the place for that 
sort of thing.  So, how about the attached patches instead?  I've pushed 
them.
>From 69fa2ecde962b3469effccfa630ad346fcad367d Mon Sep 17 00:00:00 2001
From: Paul Eggert <[email-masked]>
Date: Tue, 7 Oct 2014 08:23:21 -0700
Subject: [PATCH 1/2] doc: clarify exit status
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Reported by Santiago Ruano Rincón in: http://bugs.gnu.org/18651
* doc/grep.in.1 (EXIT STATUS):
* doc/grep.texi (Exit Status): Clarify.
---
 doc/grep.in.1 | 16 ++++------------
 doc/grep.texi | 17 ++++++-----------
 2 files changed, 10 insertions(+), 23 deletions(-)

diff --git a/doc/grep.in.1 b/doc/grep.in.1
index 00d030a..16b94b2 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
+Normally the exit status is 0 if a line is selected, 1 if no lines
+were selected, and 2 if an error occurred.  However, if the
 .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.
+is used and a line is selected, the exit status is 0 even if an error
+occurred.
 .
 .SH COPYRIGHT
 Copyright 1998-2000, 2002, 2005-2014 Free Software Foundation, Inc.
diff --git a/doc/grep.texi b/doc/grep.texi
index d7adcad..da9a1be 100644
--- a/doc/grep.texi
+++ b/doc/grep.texi
@@ -1025,17 +1025,12 @@ 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.
-
+Normally the exit status is 0 if a line is selected, 1 if no lines
+were selected, and 2 if an error occurred.  However, if the
+@option{-q} or @option{--quiet} or @option{--silent} option is used
+and a line is selected, the exit status is 0 even if an error
+occurred.  Other @command{grep} implementations may exit with status
+greater than 2 on error.
 
 @node grep Programs
 @section @command{grep} Programs
-- 
1.9.3

>From 136b65844472b0ec250ff407b6c6c6b6b16cd658 Mon Sep 17 00:00:00 2001
From: Paul Eggert <[email-masked]>
Date: Tue, 7 Oct 2014 09:22:27 -0700
Subject: [PATCH 2/2] doc: modernize and simplify man page

* doc/grep.in.1 (Tx, Id): Remove.  All uses removed.
(MTO, URL): New macros, used for email and URL.
Use them when appropriate.
In main text, omit chatty discussions of other implementations;
the full manual suffices for this sort of thing.
---
 doc/grep.in.1 | 168 ++++++++++++----------------------------------------------
 1 file changed, 35 insertions(+), 133 deletions(-)

diff --git a/doc/grep.in.1 b/doc/grep.in.1
index 16b94b2..b6362ee 100644
--- a/doc/grep.in.1
+++ b/doc/grep.in.1
@@ -9,18 +9,17 @@
 .		if \w'\(rq' .ds rq "\(rq
 .	\}
 .\}
-.ie t .ds Tx \s-1T\v'.4n'\h'-.1667'E\v'-.4n'\h'-.125'X\s0
-. el  .ds Tx TeX
-.de Id
-. ds Yr \\$4
-. substring Yr 0 3
-. ds Mn \\$4
-. substring Mn 5 6
-. ds Dy \\$4
-. substring Dy 8 9
-. \" ISO 8601 date, complete format, extended representation
-. ds Dt \\*(Yr-\\*(Mn-\\*(Dy
+.
+.ie \n[.g] .mso www.tmac
+.el \{\
+. de MTO
+\\$2 \(laemail: \\$1 \(ra\\$3
+..
+. de URL
+\\$2 \(laURL: \\$1 \(ra\\$3
 ..
+.\}
+.
 .TH GREP 1 \*(Dt "GNU grep @VERSION@" "User Commands"
 .hy 0
 .
@@ -46,64 +45,50 @@ grep, egrep, fgrep \- print lines matching a pattern
 .B grep
 searches the named input
 .IR FILE s
-(or standard input if no files are named,
-or if a single hyphen-minus
-.RB ( \- )
-is given as file name)
 for lines containing a match to the given
 .IR PATTERN .
+If no files are specified, or if the file
+.RB "\*(lq" \- "\*(rq"
+is given,
+.B grep
+searches standard input.
 By default,
 .B grep
 prints the matching lines.
 .PP
-In addition, two variant programs
+In addition, the variant programs
 .B egrep
 and
 .B fgrep
-are available.
-.B egrep
-is the same as
-.BR "grep\ \-E" .
-.B fgrep
-is the same as
-.BR "grep\ \-F" .
-Direct invocation as either
-.B egrep
-or
-.B fgrep
-is deprecated,
-but is provided to allow historical applications
-that rely on them to run unmodified.
+are the same as
+.B "grep\ \-E"
+and
+.BR "grep\ \-F" ,
+respectively.
+These variants are deprecated, but are provided for backward compatibility.
 .
 .SH OPTIONS
 .SS "Generic Program Information"
 .TP
 .B \-\^\-help
-Print a usage message briefly summarizing these command-line options
-and the bug-reporting address, then exit.
+Output a usage message and exit.
 .TP
 .BR \-V ", " \-\^\-version
-Print the version number of
+Output the version number of
 .B grep
-to the standard output stream.
-This version number should
-be included in all bug reports (see below).
+and exit.
 .SS "Matcher Selection"
 .TP
 .BR \-E ", " \-\^\-extended\-regexp
 Interpret
 .I PATTERN
 as an extended regular expression (ERE, see below).
-.RB ( \-E
-is specified by \s-1POSIX\s0.)
 .TP
 .BR \-F ", " \-\^\-fixed\-strings
 Interpret
 .I PATTERN
 as a list of fixed strings, separated by newlines,
 any of which is to be matched.
-.RB ( \-F
-is specified by \s-1POSIX\s0.)
 .TP
 .BR \-G ", " \-\^\-basic\-regexp
 Interpret
@@ -127,28 +112,20 @@ as the pattern.
 This can be used to specify multiple search patterns,
 or to protect a pattern beginning with a hyphen
 .RB ( \- ).
-.RB ( \-e
-is specified by \s-1POSIX\s0.)
 .TP
 .BI \-f " FILE" "\fR,\fP \-\^\-file=" FILE
 Obtain patterns from
 .IR FILE ,
 one per line.
 The empty file contains zero patterns, and therefore matches nothing.
-.RB ( \-f
-is specified by \s-1POSIX\s0.)
 .TP
 .BR \-i ", " \-\^\-ignore\-case
 Ignore case distinctions in both the
 .I PATTERN
 and the input files.
-.RB ( \-i
-is specified by \s-1POSIX\s0.)
 .TP
 .BR \-v ", " \-\^\-invert\-match
 Invert the sense of matching, to select non-matching lines.
-.RB ( \-v
-is specified by \s-1POSIX\s0.)
 .TP
 .BR \-w ", " \-\^\-word\-regexp
 Select only those lines containing matches that form whole words.
@@ -161,8 +138,6 @@ Word-constituent characters are letters, digits, and the underscore.
 .TP
 .BR \-x ", " \-\^\-line\-regexp
 Select only those matches that exactly match the whole line.
-.RB ( \-x
-is specified by \s-1POSIX\s0.)
 .TP
 .B \-y
 Obsolete synonym for
@@ -175,8 +150,6 @@ matching lines for each input file.
 With the
 .BR \-v ", " \-\^\-invert\-match
 option (see below), count non-matching lines.
-.RB ( \-c
-is specified by \s-1POSIX\s0.)
 .TP
 .BR \-\^\-color [ =\fIWHEN\fP "], " \-\^\-colour [ =\fIWHEN\fP ]
 Surround the matched (non-empty) strings, matching lines, context lines,
@@ -203,8 +176,6 @@ Suppress normal output; instead print
 the name of each input file from which output
 would normally have been printed.
 The scanning will stop on the first match.
-.RB ( \-l
-is specified by \s-1POSIX\s0.)
 .TP
 .BI \-m " NUM" "\fR,\fP \-\^\-max\-count=" NUM
 Stop reading a file after
@@ -255,41 +226,9 @@ Also see the
 or
 .B \-\^\-no\-messages
 option.
-.RB ( \-q
-is specified by \s-1POSIX\s0.)
 .TP
 .BR \-s ", " \-\^\-no\-messages
 Suppress error messages about nonexistent or unreadable files.
-Portability note: unlike \s-1GNU\s0
-.BR grep ,
-7th Edition Unix
-.B grep
-did not conform to \s-1POSIX\s0, because it lacked
-.B \-q
-and its
-.B \-s
-option behaved like \s-1GNU\s0
-.BR grep 's
-.B \-q
-option.
-\s-1USG\s0-style
-.B grep
-also lacked
-.B \-q
-but its
-.B \-s
-option behaved like \s-1GNU\s0
-.BR grep .
-Portable shell scripts
-should avoid both
-.B \-q
-and
-.B \-s
-and should redirect standard and error output to
-.B /dev/null
-instead.
-.RB ( \-s
-is specified by \s-1POSIX\s0.)
 .SS "Output Line Prefix Control"
 .TP
 .BR \-b ", " \-\^\-byte\-offset
@@ -324,8 +263,6 @@ option.
 .BR \-n ", " \-\^\-line\-number
 Prefix each line of output with the 1-based line number
 within its input file.
-.RB ( \-n
-is specified by \s-1POSIX\s0.)
 .TP
 .BR \-T ", " \-\^\-initial\-tab
 Make sure that the first character of actual line content lies on a
@@ -789,37 +726,6 @@ versions
 .BR \e( ,
 and
 .BR \e) .
-.PP
-Traditional
-.B egrep
-did not support the
-.B {
-meta-character, and some
-.B egrep
-implementations support
-.B \e{
-instead, so portable scripts should avoid
-.B {
-in
-.B "grep\ \-E"
-patterns and should use
-.B [{]
-to match a literal
-.BR { .
-.PP
-\s-1GNU\s0
-.B "grep\ \-E"
-attempts to support traditional usage by assuming that
-.B {
-is not special if it would be the start of an invalid interval
-specification.
-For example, the command
-.B "grep\ \-E\ '{1'"
-searches for the two-character string
-.B {1
-instead of reporting a syntax error in the regular expression.
-\s-1POSIX\s0 allows this behavior as an extension, but portable scripts
-should avoid it.
 .
 .SH "ENVIRONMENT VARIABLES"
 The behavior of
@@ -1164,12 +1070,12 @@ not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 .SH BUGS
 .SS "Reporting Bugs"
 Email bug reports to
-.RB < bug\[email-masked] >,
-a mailing list whose web page is
-.RB < http://lists.gnu.org/mailman/listinfo/bug\-grep >.
-.BR grep 's
-bug tracker is located at
-.RB < http://debbugs.gnu.org/cgi/pkgreport.cgi?package=grep >.
+.MTO [email-masked] "the bug-reporting address" .
+An
+.URL http://lists.gnu.org/mailman/listinfo/bug-grep "email archive"
+and a
+.URL http://debbugs.gnu.org/cgi/pkgreport.cgi?package=grep "bug tracker"
+are available.
 .SS "Known Bugs"
 Large repetition counts in the
 .BI { n , m }
@@ -1194,11 +1100,10 @@ terminfo(5),
 glob(7), regex(7).
 .SS "\s-1POSIX\s0 Programmer's Manual Page"
 grep(1p).
-.SS "\*(Txinfo Documentation"
-The full documentation for
-.B grep
-is maintained as a \*(Txinfo manual,
-which you can read at http://www.gnu.org/software/grep/manual/.
+.SS "Full Documentation"
+A
+.URL http://www.gnu.org/software/grep/manual/ "complete manual"
+is available.
 If the
 .B info
 and
@@ -1212,8 +1117,5 @@ should give you access to the complete manual.
 .SH NOTES
 This man page is maintained only fitfully;
 the full documentation is often more up-to-date.
-.PP
-\s-1GNU\s0's not Unix, but Unix is a beast;
-its plural form is Unixen.
 .\" Work around problems with some troff -man implementations.
 .br
-- 
1.9.3