Bug 18792 - date man page has misleading description of -r option
Summary: date man page has misleading description of -r option
Status: Closed FIXED
Alias: None
Product: Documentation
Classification: Unclassified
Component: Books & Articles (show other bugs)
Version: Latest
Hardware: Any Any
: Normal Affects Only Me
Assignee: freebsd-doc (Nobody)
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2000-05-24 16:20 UTC by bobj
Modified: 2014-04-29 07:10 UTC (History)
0 users

See Also:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description bobj 2000-05-24 16:20:00 UTC
"man date" says

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

which isn't really accurate.	It prints the time that is a 
user-specified number of seconds from the Epoch.

Fix: 

Change it to say 

 -r     Print out the date and time that is _seconds_ seconds from the Epoch.
How-To-Repeat: man date

Note that synopsis specifies _seconds_ argument to the -r option.
Comment 1 Rasmus Kaj 2000-06-26 19:28:52 UTC
I agree, so heres a diff for /usr/src/bin/date/date.1, in case someone
with a commit bit also agrees:

-- start of diff --
--- date.1.orig Mon Jun 26 20:25:02 2000
+++ date.1      Mon Jun 26 20:23:17 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 that is
 .Ar seconds
-from the Epoch.
+seconds from the Epoch.
 .It Fl t
 Set the kernel's value for minutes west of
 .Tn GMT .
-- end of diff --

-- 
Rasmus Kaj -------------------- rasmus@kaj.se - http://Raditex.se/~kaj/
 \                      Machines should work. People should think. -IBM
  \------------------------------------------------- http://Raditex.se/
Comment 2 dannyboy freebsd_committer freebsd_triage 2000-07-08 02:35:42 UTC
State Changed
From-To: open->closed
Comment 3 dannyboy freebsd_committer freebsd_triage 2000-07-08 02:41:54 UTC
State Changed
From-To: closed->open

AARGH.  Sorry, shouldn't have closed this.
Comment 4 ben freebsd_committer freebsd_triage 2000-07-11 02:42:16 UTC
The man page now says:

     -r      Print out the date and time that is seconds from the Epoch
             (00:00:00 UTC, January 1, 1970; see time(3)).

I'm not sure when this was changed, but is that any better?  I don't
really like it because it's not valid English really, although it makes
more sense in the real manpage because _seconds_ is underlined.  Still,
I'd prefer the following:

--- date.1      2000/06/28 09:20:06     1.39
+++ date.1      2000/07/11 01:32:00
@@ -45,7 +45,7 @@
 .Nm date
 .Op Fl jnu
 .Op Fl d Ar dst
-.Op Fl r Ar seconds
+.Op Fl r Ar sec
 .Op Fl t Ar minutes_west
 .Oo
 .Fl v
@@ -113,7 +113,8 @@
 from setting the time for other than the current machine.
 .It Fl r
 Print out the date and time that is
-.Ar seconds
+.Ar sec
+seconds
 from the Epoch
 .Po
 00:00:00 UTC, January 1, 1970;

So you'll get

SYNOPSIS
	date ... [-r sec] ...

...

	-r	Print out the date and time that is _sec_ seconds ...

Is that ok?  If Jeroen (my mentor) approves this and no-one objects then
I'll commit it.  If people think the current text is fine I'll just
close the PR.

-- 
Ben Smithurst / ben@FreeBSD.org / PGP: 0x99392F7D
Comment 5 Jeroen Ruigrok van der Werven freebsd_committer freebsd_triage 2000-07-11 07:38:18 UTC
-On [20000711 04:01], Ben Smithurst (ben@FreeBSD.org) wrote:
>The man page now says:
>
>     -r      Print out the date and time that is seconds from the Epoch
>             (00:00:00 UTC, January 1, 1970; see time(3)).
>
>I'm not sure when this was changed, but is that any better?  I don't
>really like it because it's not valid English really, although it makes
>more sense in the real manpage because _seconds_ is underlined.  Still,
>I'd prefer the following:

>--- date.1      2000/06/28 09:20:06     1.39
>+++ date.1      2000/07/11 01:32:00
>@@ -45,7 +45,7 @@
> .Nm date
> .Op Fl jnu
> .Op Fl d Ar dst
>-.Op Fl r Ar seconds
>+.Op Fl r Ar sec
> .Op Fl t Ar minutes_west
> .Oo
> .Fl v

[snip]

>	-r	Print out the date and time that is _sec_ seconds ...
>
>Is that ok?  If Jeroen (my mentor) approves this and no-one objects then
>I'll commit it.  If people think the current text is fine I'll just
>close the PR.

Yeah, the change might make it more clear for non native english
speakers (and probably the english ones as well).

It looks clearer to me.

But don't forget that:

[8:36] [asmodai@daemon] (356) $ date ?
date: illegal time format
usage: date [-nu] [-d dst] [-r seconds] [-t west] [-v[+|-]val[ymwdHMS]] ... 
            [-f fmt date | [[[[[cc]yy]mm]dd]HH]MM[.ss]] [+format]

You cannot change the function arguments (.Fa) around for sake of
clarity, since it would now conflict with the shown arguments. =)
I am sure you can find another wording for the paragraph which solves
this riddle.

-- 
Jeroen Ruigrok vd Werven/Asmodai    asmodai@[wxs.nl|bart.nl|freebsd.org]
Documentation nutter/C-rated Coder BSD: Technical excellence at its best  
The BSD Programmer's Documentation Project <http://home.wxs.nl/~asmodai>
So take a look at me now, well there's just an empty space...
Comment 6 ben freebsd_committer freebsd_triage 2000-07-11 12:47:42 UTC
Jeroen Ruigrok/Asmodai wrote:

> Yeah, the change might make it more clear for non native english
> speakers (and probably the english ones as well).
> 
> It looks clearer to me.
> 
> But don't forget that:
> 
> [8:36] [asmodai@daemon] (356) $ date ?
> date: illegal time format
> usage: date [-nu] [-d dst] [-r seconds] [-t west] [-v[+|-]val[ymwdHMS]] ... 
>             [-f fmt date | [[[[[cc]yy]mm]dd]HH]MM[.ss]] [+format]
> 
> You cannot change the function arguments (.Fa) around for sake of
> clarity, since it would now conflict with the shown arguments. =)

hmm, ok.  I suppose .c files are out of my allowed area?

> I am sure you can find another wording for the paragraph which solves

I thought of something like

"Print the date and time which is the specified number of seconds from the
Epoch."

but then you wouldn't be showing the function argument (with .Ar
seconds) so that might not be right.  If you used .Ar on the 'seconds'
in that sentence it wouldn't be right either.

"Print the data and time which is the specified time, _seconds_, from the
Epoch."

A bit better, perhaps.

-- 
Ben Smithurst / ben@FreeBSD.org / PGP: 0x99392F7D
Comment 7 jruigrok 2000-07-11 12:58:20 UTC
-On [20000711 13:55], Ben Smithurst (ben@FreeBSD.org) wrote:
>Jeroen Ruigrok/Asmodai wrote:
>
>> Yeah, the change might make it more clear for non native english
>> speakers (and probably the english ones as well).
>> 
>> It looks clearer to me.
>> 
>> But don't forget that:
>> 
>> [8:36] [asmodai@daemon] (356) $ date ?
>> date: illegal time format
>> usage: date [-nu] [-d dst] [-r seconds] [-t west] [-v[+|-]val[ymwdHMS]] ... 
>>             [-f fmt date | [[[[[cc]yy]mm]dd]HH]MM[.ss]] [+format]
>> 
>> You cannot change the function arguments (.Fa) around for sake of
>> clarity, since it would now conflict with the shown arguments. =)
>
>hmm, ok.  I suppose .c files are out of my allowed area?

Not really.  But sometimes changes need not be that drastically. ;)
When you have a hammer, everything looks like a nail.

>> I am sure you can find another wording for the paragraph which solves
>
>I thought of something like
>
>"Print the date and time which is the specified number of seconds from the
>Epoch."
>
>but then you wouldn't be showing the function argument (with .Ar
>seconds) so that might not be right.  If you used .Ar on the 'seconds'
>in that sentence it wouldn't be right either.
>
>"Print the data and time which is the specified time, _seconds_, from the
>Epoch."

Print the date and time, specified by x _seconds_ from the Epoch?

-- 
Jeroen Ruigrok van der Werven          Network- and systemadministrator
<jruigrok@via-net-works.nl>            VIA Net.Works The Netherlands
BSD: Technical excellence at its best  http://www.via-net-works.nl
``...by God I *KNOW* what this network is for, and you can't have it.''
	-- Russ Albery
Comment 8 ben freebsd_committer freebsd_triage 2000-07-12 02:30:31 UTC
Jeroen Ruigrok van der Werven wrote:

> Print the date and time, specified by x _seconds_ from the Epoch?

Hmm, I don't like the "x".  This manpage was changed relatively recently
anyway to be less confusing:

===
revision 1.34
date: 2000/03/07 20:54:17;  author: sheldonh;  state: Exp;  lines: +8 -3
branches:  1.34.2;
Correct confusing description of the -r option.

PR:             17250
Submitted by:   cjclark@home.com (Crist J. Clark)
===

And I think the current text is ok, to be honest, certainly better than
it was.  We're going round in circles trying to find something better
anyway, and I think Sheldon knows what he's doing. :-) Also, there's
another PR (18880, unassigned) which suggested bringing in a load of
enhancements to the date(1) manpage from OpenBSD, which might address
this.  I think the PR should either be closed, or we should change the
usage() and SYNOPSIS so it can say "... _sec_ seconds ..." since that's
the only version I'm really happy with.

-- 
Ben Smithurst / ben@FreeBSD.org / PGP: 0x99392F7D
Comment 9 stonewall 2000-07-13 20:10:47 UTC
How about:

	-r print out the date and time represented by _seconds_, which is
	   the number of seconds since the Epoch (00:00:00 UTC, January 1,
	   1970; see time(3))

or

	-r print _seconds_ as a date and time, where _seconds_ is the number of
	   seconds since the Epoch (00:00:00 UTC, January 1, 1970; see
time(3)).

-- 
  If I buy a copy of WinDelete, and it doesn't delete Windows,
  am I entitled to my money back?
________________________________________________________________
      FreeBSD - The Power To Serve http://www.freebsd.org
      My Webpage http://ukug.uk.freebsd.org/~mark/
mailto:marko@freebsd.org             http://www.radan.com
Comment 10 marko freebsd_committer freebsd_triage 2000-07-15 17:51:35 UTC
State Changed
From-To: open->closed

Committed with minor changes, Thanks!
Comment 11 dfilter service freebsd_committer freebsd_triage 2014-04-29 07:00:09 UTC
Author: miwi
Date: Tue Apr 29 06:00:06 2014
New Revision: 352577
URL: http://svnweb.freebsd.org/changeset/ports/352577
QAT: https://qat.redports.org/buildarchive/r352577/

Log:
  - Force commit to fix prev entry
  - Update to version 2.2.3
  
  PR:		18792
  Submitted by:	ports fury

Modified:
  head/irc/scrollz/Makefile

Modified: head/irc/scrollz/Makefile
==============================================================================
--- head/irc/scrollz/Makefile	Tue Apr 29 05:57:28 2014	(r352576)
+++ head/irc/scrollz/Makefile	Tue Apr 29 06:00:06 2014	(r352577)
@@ -1,6 +1,6 @@
 # Created by: Will Andrews <andrews@technologist.com>
 # $FreeBSD$
-
+ 
 PORTNAME=	scrollz
 PORTVERSION=	2.2.3
 CATEGORIES=	irc ipv6
_______________________________________________
svn-ports-all@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/svn-ports-all
To unsubscribe, send any mail to "svn-ports-all-unsubscribe@freebsd.org"