From cjc@cc942873-a.ewndsr1.nj.home.com  Tue Mar  7 11:53:04 2000
Return-Path: <cjc@cc942873-a.ewndsr1.nj.home.com>
Received: from cc942873-a.ewndsr1.nj.home.com (cc942873-a.ewndsr1.nj.home.com [24.2.89.207])
	by hub.freebsd.org (Postfix) with ESMTP id 1CDA837B8EF
	for <FreeBSD-gnats-submit@freebsd.org>; Tue,  7 Mar 2000 11:53:03 -0800 (PST)
	(envelope-from cjc@cc942873-a.ewndsr1.nj.home.com)
Received: (from cjc@localhost)
	by cc942873-a.ewndsr1.nj.home.com (8.9.3/8.9.3) id OAA73013;
	Tue, 7 Mar 2000 14:58:34 -0500 (EST)
	(envelope-from cjc)
Message-Id: <200003071958.OAA73013@cc942873-a.ewndsr1.nj.home.com>
Date: Tue, 7 Mar 2000 14:58:34 -0500 (EST)
From: "Crist J. Clark" <cjc@cc942873-a.ewndsr1.nj.home.com>
Reply-To: cjc@cc942873-a.ewndsr1.nj.home.com
To: FreeBSD-gnats-submit@freebsd.org
Subject: Unclear language on date(1) manpage for -r option
X-Send-Pr-Version: 3.2

>Number:         17250
>Category:       docs
>Synopsis:       Unclear language on date(1) manpage for -r option
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    sheldonh
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Tue Mar  7 12:00:01 PST 2000
>Closed-Date:    Tue Mar 7 12:56:29 PST 2000
>Last-Modified:  Tue Mar  7 12:57:52 PST 2000
>Originator:     Crist J. Clark
>Release:        FreeBSD 3.4-STABLE i386
>Organization:
>Environment:

	FreeBSD 3-STABLE, FreeBSD 2.2-STABLE

>Description:

	The '-r' option for the date(1) command reads in the manpage,

     -r      Print out the date and time in seconds from the Epoch.

Which to me sounds like it is going to return the time in that
form. However, what that is supposed to mean is that the UNIX Epoch
time in seconds is takenn as the argument and printed out in the
default format or whatever format the user has specified with a
'+format' argument.

>How-To-Repeat:

	% date -r 0
        Wed Dec 31 19:00:00 EST 1969
	% date -r 0  +%m/%d/%y
        12/31/69
	% date -r 0  +%s
        0
	% man date

>Fix:
	
	I think the simple change from 'in' to 'at' in the above quote
from the manpage should do it, but add a few more words on the UNIX
Epoch to aid the uninitiated since it comes up no where else on this
manpage. 

--- /usr/src/bin/date/date.1    Fri Dec 17 06:32:08 1999
+++ date.1      Tue Mar  7 14:55:12 2000
@@ -92,9 +92,9 @@
 .Nm
 from setting the time for other than the current machine.
 .It Fl r
-Print out the date and time in
+Print out the date and time at
 .Ar seconds
-from the Epoch.
+from the start of the UNIX Epoch (Thu Jan  1 00:00:00 GMT 1970).
 .It Fl t
 Set the kernel's value for minutes west of
 .Tn GMT .

>Release-Note:
>Audit-Trail:

From: Sheldon Hearn <sheldonh@uunet.co.za>
To: cjc@cc942873-a.ewndsr1.nj.home.com
Cc: FreeBSD-gnats-submit@FreeBSD.ORG
Subject: Re: docs/17250: Unclear language on date(1) manpage for -r option 
Date: Tue, 07 Mar 2000 22:13:33 +0200

 On Tue, 07 Mar 2000 14:58:34 EST, "Crist J. Clark" wrote:
 
 >      -r      Print out the date and time in seconds from the Epoch.
 > 
 > Which to me sounds like it is going to return the time in that
 > form.
 
 You're right, our manual page is confusing.  I prefer what the NetBSD
 manual page has to what you propose in your patch:
 
 .It Fl r
 Print out the date and time that is
 .Ar seconds
 from the Epoch.
 
 Would you be happy with that?
 
 Ciao,
 Sheldon.
 
Responsible-Changed-From-To: freebsd-doc->sheldonh 
Responsible-Changed-By: sheldonh 
Responsible-Changed-When: Tue Mar 7 12:34:18 PST 2000 
Responsible-Changed-Why:  
I'll take this one. 

From: "Crist J. Clark" <cjc@cc942873-a.ewndsr1.nj.home.com>
To: Sheldon Hearn <sheldonh@uunet.co.za>
Cc: FreeBSD-gnats-submit@FreeBSD.ORG
Subject: Re: docs/17250: Unclear language on date(1) manpage for -r option
Date: Tue, 7 Mar 2000 15:35:02 -0500

 On Tue, Mar 07, 2000 at 10:13:33PM +0200, Sheldon Hearn wrote:
 > 
 > 
 > On Tue, 07 Mar 2000 14:58:34 EST, "Crist J. Clark" wrote:
 > 
 > >      -r      Print out the date and time in seconds from the Epoch.
 > > 
 > > Which to me sounds like it is going to return the time in that
 > > form.
 > 
 > You're right, our manual page is confusing.  I prefer what the NetBSD
 > manual page has to what you propose in your patch:
 > 
 > .It Fl r
 > Print out the date and time that is
 > .Ar seconds
 > from the Epoch.
 > 
 > Would you be happy with that?
 
 It works for me, but I wonder if somewhere in the page, if not there,
 we should have a definition of "the Epoch" for those who may not be
 aware of the cosmic sigificance of Jan  1 00:00:00 UTC 1970.
 -- 
 Crist J. Clark                           cjclark@home.com
 

From: Sheldon Hearn <sheldonh@uunet.co.za>
To: cjclark@home.com
Cc: FreeBSD-gnats-submit@FreeBSD.ORG
Subject: Re: docs/17250: Unclear language on date(1) manpage for -r option 
Date: Tue, 07 Mar 2000 22:34:07 +0200

 On Tue, 07 Mar 2000 15:35:02 EST, "Crist J. Clark" wrote:
 
 > It works for me, but I wonder if somewhere in the page, if not there,
 > we should have a definition of "the Epoch" for those who may not be
 > aware of the cosmic sigificance of Jan  1 00:00:00 UTC 1970.
 
 Okay.  I was hoping to keep in line with NetBSD, but you're right about
 this, so hopefully they'll consider our extension to their patch. :-)
 
 Ciao,
 Sheldon
 
State-Changed-From-To: open->closed 
State-Changed-By: sheldonh 
State-Changed-When: Tue Mar 7 12:56:29 PST 2000 
State-Changed-Why:  
Committed a fix in rev 1.34.  Merged to STABLE in rev 1.26.2.5. 
Thanks! 
>Unformatted:
