Bug 32082

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").

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 ,

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

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

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 ,

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.)

Comment 7 ru 2001-11-20 09:22:13 UTC

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

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

Comment 9 ru 2001-11-20 11:12:33 UTC

State Changed
From-To: open->closed

Hopefully the new text is less confusing. 

Comment 10 ru 2001-11-20 11:12:33 UTC

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