From setantae@submonkey.net  Sun Nov 18 12:13:25 2001
Return-Path: <setantae@submonkey.net>
Received: from relay3-gui.server.ntli.net (relay3-gui.server.ntli.net [194.168.4.200])
	by hub.freebsd.org (Postfix) with ESMTP id 09A3637B416
	for <FreeBSD-gnats-submit@freebsd.org>; Sun, 18 Nov 2001 12:13:24 -0800 (PST)
Received: from pc3-card3-0-cust122.cdf.cable.ntl.com
	([62.254.251.122] helo=rhadamanth.private.submonkey.net ident=exim)
	by relay3-gui.server.ntli.net with esmtp (Exim 3.03 #2)
	id 165YJe-0004WM-00
	for FreeBSD-gnats-submit@freebsd.org; Sun, 18 Nov 2001 20:13:22 +0000
Received: from setantae by rhadamanth.private.submonkey.net with local (Exim 3.33 #1)
	id 165YJb-000EfO-00
	for FreeBSD-gnats-submit@freebsd.org; Sun, 18 Nov 2001 20:13:19 +0000
Message-Id: <E165YJb-000EfO-00@rhadamanth.private.submonkey.net>
Date: Sun, 18 Nov 2001 20:13:19 +0000
From: Ceri <setantae@submonkey.net>
Sender: setantae <setantae@submonkey.net>
Reply-To: Ceri <setantae@submonkey.net>
To: FreeBSD-gnats-submit@freebsd.org
Cc:
Subject: true.1 totally incorrect
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>Number:         32082
>Category:       docs
>Synopsis:       true.1 totally incorrect
>Confidential:   no
>Severity:       serious
>Priority:       medium
>Responsible:    ru
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Sun Nov 18 12:20:00 PST 2001
>Closed-Date:    Tue Nov 20 03:12:33 PST 2001
>Last-Modified:  Tue Nov 20 03:14:00 PST 2001
>Originator:     setantae@submonkey.net
>Release:        FreeBSD 4.4-STABLE i386
>Organization:
>Environment:
System: FreeBSD rhadamanth.private.submonkey.net 4.4-STABLE FreeBSD 4.4-STABLE #0: Fri Nov 16 21:14:33 GMT 2001 root@rhadamanth.private.submonkey.net:/usr/obj/usr/src/sys/RHADAMANTH i386


	
>Description:
	true.1 states that the appropriate return status from true is "false".
	Which is clearly not the case.
	
>How-To-Repeat:
	man true
>Fix:
	Apply this patch :

*** src/usr.bin/true/true.1.old	Sun Nov 18 20:08:15 2001
--- src/usr.bin/true/true.1	Sun Nov 18 20:08:30 2001
***************
*** 47,53 ****
  The
  .Nm
  command is normally used in a Bourne shell script.
! It tests for the appropriate status "false" before running
  (or failing to run) a list of commands.
  .Sh SEE ALSO
  .Xr csh 1 ,
--- 47,53 ----
  The
  .Nm
  command is normally used in a Bourne shell script.
! It tests for the appropriate status "true" before running
  (or failing to run) a list of commands.
  .Sh SEE ALSO
  .Xr csh 1 ,
>Release-Note:
>Audit-Trail:

From: swear@blarg.net (Gary W. Swearingen)
To: Ceri <setantae@submonkey.net>
Cc: FreeBSD-gnats-submit@FreeBSD.ORG
Subject: Re: docs/32082: true.1 totally incorrect
Date: 18 Nov 2001 21:34:29 -0800

 Ceri <setantae@submonkey.net> writes:
 
 > >Description:
 > 	true.1 states that the appropriate return status from true is "false".
 > 	Which is clearly not the case.
 
 But it doesn't say that. It says it returns zero, which is correct.
 
 > ! It tests for the appropriate status "false" before running
 >   (or failing to run) a list of commands.
 
 The "It" here is confusingly referring to a Bourne shell script that
 it confusingly brings into the description.
 
 The whole first paragraphs, or at least the second sentences, of both
 true(1) and false(1) should be trashed, based on my quick look at it.
 Maybe moved to another section, or at least put after the real
 decription ("This command does nothing but return an exit status of X").

From: setantae <setantae@submonkey.net>
To: "Gary W. Swearingen" <swear@blarg.net>
Cc: FreeBSD-gnats-submit@FreeBSD.ORG, doc@FreeBSD.org
Subject: Re: docs/32082: true.1 totally incorrect
Date: Mon, 19 Nov 2001 11:25:58 +0000

 On Sun, Nov 18, 2001 at 09:34:29PM -0800, Gary W. Swearingen wrote:
 > Ceri <setantae@submonkey.net> writes:
 > 
 > > >Description:
 > > 	true.1 states that the appropriate return status from true is "false".
 > > 	Which is clearly not the case.
 > 
 > But it doesn't say that. It says it returns zero, which is correct.
 
 Well, it does; it says ``the appropriate status "false"'', which says to me
 that the appropriate return status from true is "false".
 But I don't really want to argue about that, as it's not the real point.
 
 > > ! It tests for the appropriate status "false" before running
 > >   (or failing to run) a list of commands.
 > 
 > The "It" here is confusingly referring to a Bourne shell script that
 > it confusingly brings into the description.
 
 Yeah, I didn't really understand that part at all, so I kind of skirted round
 it.  Now that I've got a second opinion which is agreeable, how about this
 patch instead ?
 
 diff -rc src/usr.bin.old/false/false.1 src/usr.bin/false/false.1
 *** src/usr.bin.old/false/false.1	Mon Nov 19 11:08:41 2001
 --- src/usr.bin/false/false.1	Mon Nov 19 11:17:21 2001
 ***************
 *** 46,62 ****
   .Sh DESCRIPTION
   The
   .Nm
 ! command is usually used in a Bourne shell script.
 ! It tests for the appropriate status "false" before running
 ! (or failing to run) a list of commands.
 ! .Pp
 ! The
 ! .Nm
 ! utility always exits with a value other than zero.
   .Sh SEE ALSO
   .Xr csh 1 ,
   .Xr sh 1 ,
   .Xr true 1
   .Sh STANDARDS
   The
   .Nm
 --- 46,60 ----
   .Sh DESCRIPTION
   The
   .Nm
 ! command does nothing but exit with a non-zero status.
   .Sh SEE ALSO
   .Xr csh 1 ,
   .Xr sh 1 ,
   .Xr true 1
 + .Sh DIAGNOSTICS
 + The
 + .Nm
 + utility always returns with exit code one.
   .Sh STANDARDS
   The
   .Nm
 diff -rc src/usr.bin.old/true/true.1 src/usr.bin/true/true.1
 *** src/usr.bin.old/true/true.1	Sun Nov 18 20:08:15 2001
 --- src/usr.bin/true/true.1	Mon Nov 19 11:18:11 2001
 ***************
 *** 46,54 ****
   .Sh DESCRIPTION
   The
   .Nm
 ! command is normally used in a Bourne shell script.
 ! It tests for the appropriate status "false" before running
 ! (or failing to run) a list of commands.
   .Sh SEE ALSO
   .Xr csh 1 ,
   .Xr false 1 ,
 --- 46,52 ----
   .Sh DESCRIPTION
   The
   .Nm
 ! command does nothing but return a true status code.
   .Sh SEE ALSO
   .Xr csh 1 ,
   .Xr false 1 ,
 

From: Giorgos Keramidas <charon@labs.gr>
To: setantae <setantae@submonkey.net>
Cc: "Gary W. Swearingen" <swear@blarg.net>,
	FreeBSD-gnats-submit@FreeBSD.ORG
Subject: Re: docs/32082: true.1 totally incorrect
Date: Mon, 19 Nov 2001 16:05:53 +0200

 On 2001-11-19 11:25:58, setantae wrote:
 > diff -rc src/usr.bin.old/false/false.1 src/usr.bin/false/false.1
 > ...
 > --- 46,60 ----
 >   .Sh DESCRIPTION
 >   The
 >   .Nm
 > ! command does nothing but exit with a non-zero status.
 >   .Sh SEE ALSO
 >   .Xr csh 1 ,
 >   .Xr sh 1 ,
 >   .Xr true 1
 > + .Sh DIAGNOSTICS
 > + The
 > + .Nm
 > + utility always returns with exit code one.
 
 It's either `non-zero' or `one'.  Not both.
 This certainly looks a lot better than the current manpage though :)
 
 -giorgos
 

From: setantae <setantae@submonkey.net>
To: Giorgos Keramidas <charon@labs.gr>
Cc: doc@FreeBSD.org, FreeBSD-gnats-submit@FreeBSD.ORG
Subject: Re: docs/32082: true.1 totally incorrect
Date: Mon, 19 Nov 2001 14:49:49 +0000

 On Mon, Nov 19, 2001 at 04:05:53PM +0200, Giorgos Keramidas wrote:
 > 
 > It's either `non-zero' or `one'.  Not both.
 
 True. While the version of true(1) that we are shipping will always
 exit with a status of 1, I'm not sure that's portable.
 I tried to check to see if POSIX guarantees `one', or just `non-zero',
 but it would appear that you have to be a member to look at the
 standard ??
 
 If anyone has access to the standard could they take a look and let
 me know so I can amend the patch accordingly ?
 
 Ceri
 
 -- 
 keep a mild groove on

From: setantae <setantae@submonkey.net>
To: charon@labs.gr
Cc: doc@FreeBSD.org, FreeBSD-gnats-submit@FreeBSD.ORG
Subject: Re: docs/32082: true.1 totally incorrect
Date: Mon, 19 Nov 2001 17:16:34 +0000

 On Mon, Nov 19, 2001 at 07:00:04AM -0800, setantae wrote:
 >  
 >  True. While the version of true(1) that we are shipping will always
 >  exit with a status of 1, I'm not sure that's portable.
 >  I tried to check to see if POSIX guarantees `one', or just `non-zero',
 >  but it would appear that you have to be a member to look at the
 >  standard ??
 
 I've been furnished with a copy of the standard for false(1), and
 the outcome is that it just needs to be non-zero.
 Therefore, I suggest we use this patch :
 
 diff -rc src/usr.bin.old/false/false.1 src/usr.bin/false/false.1
 *** src/usr.bin.old/false/false.1	Mon Nov 19 11:08:41 2001
 --- src/usr.bin/false/false.1	Mon Nov 19 11:17:21 2001
 ***************
 *** 46,62 ****
   .Sh DESCRIPTION
   The
   .Nm
 ! command is usually used in a Bourne shell script.
 ! It tests for the appropriate status "false" before running
 ! (or failing to run) a list of commands.
 ! .Pp
 ! The
 ! .Nm
 ! utility always exits with a value other than zero.
   .Sh SEE ALSO
   .Xr csh 1 ,
   .Xr sh 1 ,
   .Xr true 1
   .Sh STANDARDS
   The
   .Nm
 --- 46,60 ----
   .Sh DESCRIPTION
   The
   .Nm
 ! command does nothing but exit with a non-zero status.
   .Sh SEE ALSO
   .Xr csh 1 ,
   .Xr sh 1 ,
   .Xr true 1
 + .Sh DIAGNOSTICS
 + The
 + .Nm
 + utility always returns with a non-zero exit code.
   .Sh STANDARDS
   The
   .Nm
 diff -rc src/usr.bin.old/true/true.1 src/usr.bin/true/true.1
 *** src/usr.bin.old/true/true.1	Sun Nov 18 20:08:15 2001
 --- src/usr.bin/true/true.1	Mon Nov 19 11:18:11 2001
 ***************
 *** 46,54 ****
   .Sh DESCRIPTION
   The
   .Nm
 ! command is normally used in a Bourne shell script.
 ! It tests for the appropriate status "false" before running
 ! (or failing to run) a list of commands.
   .Sh SEE ALSO
   .Xr csh 1 ,
   .Xr false 1 ,
 --- 46,52 ----
   .Sh DESCRIPTION
   The
   .Nm
 ! command does nothing but exit with a status code of zero.
   .Sh SEE ALSO
   .Xr csh 1 ,
   .Xr false 1 ,

From: swear@blarg.net (Gary W. Swearingen)
To: setantae <setantae@submonkey.net>
Cc: FreeBSD-gnats-submit@FreeBSD.ORG, doc@FreeBSD.ORG
Subject: Re: docs/32082: true.1 totally incorrect
Date: 19 Nov 2001 13:12:42 -0800

 I think "true" and "false" should not bother with DIAGNOSTIC sections,
 but if used they should match the description's terminology and sense.
 
 All of "exit code", "exit status", "status" are in common use ("exit
 value", less so), but in the "sh", "ksh", and "csh" man pages "exit
 code" is used only in "sh" and there only in two adjacent sentences.
 Selection of "status" or "exit status" is more context dependent and a
 matter of taste.  (I would try to avoid using "code", even though that
 is more natural to me than "status" because of my personal experience.)
 
 It's debatable whether the status of "false" should be given as "one" or
 "non-zero".  Should man pages describe the actual program or the
 presumed specification of the program?  What specification should be
 presumed in this case?  The shell man pages sometimes say that a command
 returns "one" when "non-zero" would seem to suffice.  (I think man pages
 should describe presumed specifications, but in this case I think the
 specification should be that "false" should exit with status = "1".)
 
 Which brings up another issue.  Is an exit status code value an integer
 or a string and should they be given as numerics or English words?  (I
 guess I'd wimp out and say that people should be expected to deal with
 the small confusion and allow both forms but recommend English words in
 most contexts as demanded by standard rules of English for readability.)

From: Ruslan Ermilov <ru@FreeBSD.ORG>
To: "Gary W. Swearingen" <swear@blarg.net>
Cc: setantae <setantae@submonkey.net>,
	FreeBSD-gnats-submit@FreeBSD.ORG, doc@FreeBSD.ORG
Subject: Re: docs/32082: true.1 totally incorrect
Date: Tue, 20 Nov 2001 11:22:13 +0200

 On Mon, Nov 19, 2001 at 01:12:42PM -0800, Gary W. Swearingen wrote:
 > I think "true" and "false" should not bother with DIAGNOSTIC sections,
 > but if used they should match the description's terminology and sense.
 > 
 I agree.
 
 > All of "exit code", "exit status", "status" are in common use ("exit
 > value", less so), but in the "sh", "ksh", and "csh" man pages "exit
 > code" is used only in "sh" and there only in two adjacent sentences.
 > 
 It is also used in the sysexits(3) manpage.
 
 > Selection of "status" or "exit status" is more context dependent and a
 > matter of taste.  (I would try to avoid using "code", even though that
 > is more natural to me than "status" because of my personal experience.)
 > 
 Irrelevant.
 
 > It's debatable whether the status of "false" should be given as "one" or
 > "non-zero".  Should man pages describe the actual program or the presumed
 > specification of the program?  What specification should be presumed in
 > this case?
 > 
 These manpages clain the conformance to POSIX, and POSIX says false(1)
 should always return with a non-zero exit code, hence we should use
 "non-zero".
 
 > The shell man pages sometimes say that a command
 > returns "one" when "non-zero" would seem to suffice.  (I think man pages
 > should describe presumed specifications, but in this case I think the
 > specification should be that "false" should exit with status = "1".)
 > 
 Nope.
 
 > Which brings up another issue.  Is an exit status code value an integer
 > or a string and should they be given as numerics or English words?
 > 
 It's definitely an integer.  :-)
 
 > (I guess I'd wimp out and say that people should be expected to deal with
 > the small confusion and allow both forms but recommend English words in
 > most contexts as demanded by standard rules of English for readability.)
 > 
 Yes, both forms are allowed.
 
 Finally, I suggest to commit the following:
 
 Index: true/true.1
 ===================================================================
 RCS file: /home/ncvs/src/usr.bin/true/true.1,v
 retrieving revision 1.8
 diff -u -p -r1.8 true.1
 --- true/true.1	2001/07/15 08:01:38	1.8
 +++ true/true.1	2001/11/20 09:09:35
 @@ -46,17 +46,11 @@
  .Sh DESCRIPTION
  The
  .Nm
 -command is normally used in a Bourne shell script.
 -It tests for the appropriate status "false" before running
 -(or failing to run) a list of commands.
 +utility always returns with exit code zero.
  .Sh SEE ALSO
  .Xr csh 1 ,
  .Xr false 1 ,
  .Xr sh 1
 -.Sh DIAGNOSTICS
 -The
 -.Nm
 -utility always returns with exit code zero.
  .Sh STANDARDS
  The
  .Nm
 Index: false/false.1
 ===================================================================
 RCS file: /home/ncvs/src/usr.bin/false/false.1,v
 retrieving revision 1.8
 diff -u -p -r1.8 false.1
 --- false/false.1	2001/07/15 08:01:13	1.8
 +++ false/false.1	2001/11/20 09:09:35
 @@ -46,13 +46,7 @@
  .Sh DESCRIPTION
  The
  .Nm
 -command is usually used in a Bourne shell script.
 -It tests for the appropriate status "false" before running
 -(or failing to run) a list of commands.
 -.Pp
 -The
 -.Nm
 -utility always exits with a value other than zero.
 +utility always returns with a non-zero exit code.
  .Sh SEE ALSO
  .Xr csh 1 ,
  .Xr sh 1 ,
 
 
 Cheers,
 -- 
 Ruslan Ermilov		Oracle Developer/DBA,
 ru@sunbay.com		Sunbay Software AG,
 ru@FreeBSD.org		FreeBSD committer,
 +380.652.512.251	Simferopol, Ukraine
 
 http://www.FreeBSD.org	The Power To Serve
 http://www.oracle.com	Enabling The Information Age

From: setantae <setantae@submonkey.net>
To: Ruslan Ermilov <ru@freebsd.org>
Cc: freebsd-doc@freebsd.org, swear@blarg.net,
	FreeBSD-gnats-submit@FreeBSD.ORG
Subject: Re: docs/32082: true.1 totally incorrect
Date: Tue, 20 Nov 2001 09:39:39 +0000

 On Tue, Nov 20, 2001 at 01:30:01AM -0800, Ruslan Ermilov wrote:
 > 
 >  > I think "true" and "false" should not bother with DIAGNOSTIC sections,
 >  > but if used they should match the description's terminology and sense.
 >  > 
 >  I agree.
 
 Me too. I just tried to fit in with stuff like ls(1) and mv(1), but it
 doesn't seem necessary in these cases.
 
 >  > It's debatable whether the status of "false" should be given as "one" or
 >  > "non-zero".  Should man pages describe the actual program or the presumed
 >  > specification of the program?  What specification should be presumed in
 >  > this case?
 >  > 
 >  These manpages clain the conformance to POSIX, and POSIX says false(1)
 >  should always return with a non-zero exit code, hence we should use
 >  "non-zero".
 
 Seconded (that's why I wanted to see the standard).
 
 >  Finally, I suggest to commit the following:
 
 	<snip>
 
 Suits me.
 
 Ceri
 
 -- 
 keep a mild groove on
State-Changed-From-To: open->closed 
State-Changed-By: ru 
State-Changed-When: Tue Nov 20 03:12:33 PST 2001 
State-Changed-Why:  
Hopefully the new text is less confusing. 


Responsible-Changed-From-To: freebsd-doc->ru 
Responsible-Changed-By: ru 
Responsible-Changed-When: Tue Nov 20 03:12:33 PST 2001 
Responsible-Changed-Why:  

http://www.FreeBSD.org/cgi/query-pr.cgi?pr=32082 
>Unformatted:
