From swear@blarg.net  Thu Mar 28 17:26:34 2002
Return-Path: <swear@blarg.net>
Received: from lists.blarg.net (lists.blarg.net [206.124.128.17])
	by hub.freebsd.org (Postfix) with ESMTP id E047237B417
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 28 Mar 2002 17:26:33 -0800 (PST)
Received: from thig.blarg.net (thig.blarg.net [206.124.128.18])
	by lists.blarg.net (Postfix) with ESMTP id 9CB09BD60
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 28 Mar 2002 17:26:33 -0800 (PST)
Received: from localhost.localdomain ([206.124.139.115])
	by thig.blarg.net (8.9.3/8.9.3) with ESMTP id RAA12020
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 28 Mar 2002 17:26:32 -0800
Received: (from jojo@localhost)
	by localhost.localdomain (8.11.6/8.11.3) id g2T1P7f96276;
	Thu, 28 Mar 2002 17:25:07 -0800 (PST)
	(envelope-from swear@blarg.net)
Message-Id: <m4r8m4go7g.8m4@localhost.localdomain>
Date: 28 Mar 2002 17:25:07 -0800
From: "Gary W. Swearingen" <swear@blarg.net>
Reply-To: swear@blarg.net
To: FreeBSD-gnats-submit@freebsd.org
Subject: intro(8) manual is missing command status explanation
X-GNATS-Notify:

>Number:         36448
>Category:       docs
>Synopsis:       intro(8) manual is missing command status explanation
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    trhodes
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Thu Mar 28 17:30:01 PST 2002
>Closed-Date:    Fri Apr 12 09:29:26 PDT 2002
>Last-Modified:  Fri Apr 12 09:29:26 PDT 2002
>Originator:     Gary W. Swearingen
>Release:        FreeBSD 4.5-STABLE i386
>Organization:
none
>Environment:
n/a
================
>Description:

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.
================
>How-To-Repeat:
n/a
================
>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.
>Release-Note:
>Audit-Trail:

From: <trhodes@FreeBSD.org>
To: FreeBSD-gnats-submit@FreeBSD.org
Cc:  
Subject: Re: docs/36448: [PATCH] intro(8)
Date: Mon, 1 Apr 2002 18:19:50 -0800 (PST)

 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

From: Peter Pentchev <roam@ringlet.net>
To: Tom Rhodes <darklogik@pittgoth.com>
Cc: bug-followup@FreeBSD.org
Subject: Re: docs/36448: [PATCH] intro(8)
Date: Tue, 2 Apr 2002 13:57:23 +0300

 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.
Responsible-Changed-From-To: freebsd-doc->trhodes 
Responsible-Changed-By: trhodes 
Responsible-Changed-When: Wed Apr 3 09:57:12 PST 2002 
Responsible-Changed-Why:  
I will oversee the successful close of this PR 

http://www.freebsd.org/cgi/query-pr.cgi?pr=36448 

From: <trhodes@FreeBSD.org>
To: FreeBSD-gnats-submit@FreeBSD.org
Cc:  
Subject: Re: docs/36448: [PATCH] intro(8)
Date: Wed, 3 Apr 2002 09:53:08 -0800 (PST)

 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
State-Changed-From-To: open->patched 
State-Changed-By: trhodes 
State-Changed-When: Tue Apr 9 14:05:42 PDT 2002 
State-Changed-Why:  
Patch applied to CURRENT and I'll commit to STABLE in 3 days, thanks Gary! 

http://www.freebsd.org/cgi/query-pr.cgi?pr=36448 
State-Changed-From-To: patched->closed 
State-Changed-By: trhodes 
State-Changed-When: Fri Apr 12 09:28:43 PDT 2002 
State-Changed-Why:  
Committed to STABLE, this completes patched phase, and takes us to closed 
phase, thanks Gary! 

http://www.freebsd.org/cgi/query-pr.cgi?pr=36448 
>Unformatted:
