Bug 36448

Summary:	intro(8) manual is missing command status explanation
Product:	Documentation	Reporter:	Gary W. Swearingen <swear>
Component:	Books & Articles	Assignee:	Tom Rhodes <trhodes>
Status:	Closed FIXED
Severity:	Affects Only Me
Priority:	Normal
Version:	Latest
Hardware:	Any
OS:	Any

Description Gary W. Swearingen 2002-03-29 01:30:01 UTC

The "Description" section of the intro(8) manual should have a new
second paragraph which is a (near) copy of the command status
explanation from the intro(1) manual.
================

Fix: 

Either add this exact copy from intro(1):
- - - - - -
.Pp
All commands set a status value upon exit which may be tested
to see if the command completed normally.
Traditionally, the value 0 signifies successful
completion of the command, while a value >0 indicates an error.
Some commands attempt to describe the nature of the failure by using
errors codes as defined in
.Xr sysexits 3 ,
while others simply set the status to an arbitrary value >0 (typically 1).
- - - - - -
Or, better yet, add this new-and-improved version:
- - - - - -
.Pp
All commands set an exit status.  Its value may be tested
to see if the command completed normally.
Unless otherwise noted (rare), the value 0 signifies successful
completion of the command, while a value >0 indicates an error.
Some commands attempt to describe the nature of the failure by using
errors codes defined in
.Xr sysexits 3 ,
or set the status to arbitrary values >0 (typically 1), but many
such values are not described in the manuals.
How-To-Repeat: n/a
================

Comment 1 Tom Rhodes freebsd_committer

2002-04-02 03:19:50 UTC

Gary, what do you think of the following patch to intro(8)?

--
Tom (darklogik) Rhodes

--- intro.8.old	Mon Apr  1 21:05:13 2002
+++ intro.8	Mon Apr  1 21:06:52 2002
@@ -65,6 +65,19 @@
 .Ql Xr crash
 should be consulted to understand how to interpret system
 crash dumps.
+
+.Pp
+All commands set an exit status.  Its value may be tested
+to see if the command completed normally.
+Unless otherwise noted (rare), the value 0 signifies successful
+completion of the command, while a value >0 indicates an error.
+Some commands attempt to describe the nature of the failure by using
+errors codes defined in
+.Xr sysexits 3 ,
+or set the status to arbitrary values >0 (typically 1), but many
+such values are not described in the manuals.
+
+
 .Sh HISTORY
 The
 .Nm

Comment 2 Peter Pentchev 2002-04-02 11:57:23 UTC

On Mon, Apr 01, 2002 at 09:37:17PM -0500, Tom Rhodes wrote:
> On Mon, 1 Apr 2002 18:20:02 -0800 (PST) > <trhodes@FreeBSD.ORG> wrote:
> > 
> >  Gary, what do you think of the following patch to intro(8)?
> >  
> >  --
> >  Tom (darklogik) Rhodes
> >  
> >  --- intro.8.old	Mon Apr  1 21:05:13 2002
> >  +++ intro.8	Mon Apr  1 21:06:52 2002
> >  @@ -65,6 +65,19 @@
> >   .Ql Xr crash
> >   should be consulted to understand how to interpret system
> >   crash dumps.
> >  +
> >  +.Pp
> >  +All commands set an exit status.  Its value may be tested
> >  +to see if the command completed normally.
> >  +Unless otherwise noted (rare), the value 0 signifies successful
> >  +completion of the command, while a value >0 indicates an error.
> >  +Some commands attempt to describe the nature of the failure by
> >  using+errors codes defined in
> >  +.Xr sysexits 3 ,
> >  +or set the status to arbitrary values >0 (typically 1), but many
> >  +such values are not described in the manuals.
> >  +
> >  +
> >   .Sh HISTORY
> >   The
> >   .Nm
> 
> oooops, I fixed the blank lines in a new diff...  If/when committed,
> the diff will not have them ;)  sorry hehe

You may also want to break the second sentence, 'Its value may be..',
onto a new line :)  Also, 'errors codes' might be better as 'error
codes' (singular 'error'), and the final 'manuals' might be replaced
with 'manual pages'.  But then, this is just MHO :)

G'luck,
Peter

-- 
Peter Pentchev	roam@ringlet.net	roam@FreeBSD.org
PGP key:	http://people.FreeBSD.org/~roam/roam.key.asc
Key fingerprint	FDBA FD79 C26F 3C51 C95E  DF9E ED18 B68D 1619 4553
If there were no counterfactuals, this sentence would not have been paradoxical.

Comment 3 Tom Rhodes freebsd_committer

2002-04-03 18:53:08 UTC

Gary, hows this patch look.  Reproduced after review of -doc ;)

--
Tom (darklogik) Rhodes


--- intro.8.old	Wed Apr  3 11:24:38 2002
+++ intro.8	Wed Apr  3 10:57:26 2002
@@ -65,6 +65,17 @@
 .Ql Xr crash
 should be consulted to understand how to interpret system
 crash dumps.
+.Pp
+All commands set an exit status.
+Its value may be tested
+to see if the command completed normally.
+Unless otherwise noted (rare), the value 0 signifies successful
+completion of the command, while a value >0 indicates an error.
+Some commands attempt to describe the nature of the failure by using
+error codes defined in
+.Xr sysexits 3 ,
+or set the status to arbitrary values >0 (typically 1), but many
+such values are not described in the manual.
 .Sh HISTORY
 The
 .Nm

Comment 4 Tom Rhodes freebsd_committer

2002-04-03 18:57:12 UTC

Responsible Changed
From-To: freebsd-doc->trhodes

I will oversee the successful close of this PR

Comment 5 Tom Rhodes freebsd_committer

2002-04-09 22:05:42 UTC

State Changed
From-To: open->patched

Patch applied to CURRENT and I'll commit to STABLE in 3 days, thanks Gary!

Comment 6 Tom Rhodes freebsd_committer

2002-04-12 17:28:43 UTC

State Changed
From-To: patched->closed

Committed to STABLE, this completes patched phase, and takes us to closed 
phase, thanks Gary!