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 <egg...@cs.ucla.edu>
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 <egg...@cs.ucla.edu>
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\-g...@gnu.org >,
-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 bug-grep@gnu.org "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
