From oberman@es.net  Tue Nov 19 13:16:12 2002
Return-Path: <oberman@es.net>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id BCEB237B401
	for <FreeBSD-gnats-submit@freebsd.org>; Tue, 19 Nov 2002 13:16:12 -0800 (PST)
Received: from postal2.es.net (postal2.es.net [198.128.3.206])
	by mx1.FreeBSD.org (Postfix) with ESMTP id 3141443E75
	for <FreeBSD-gnats-submit@freebsd.org>; Tue, 19 Nov 2002 13:16:12 -0800 (PST)
	(envelope-from oberman@es.net)
Received: from ptavv.es.net ([198.128.4.29])
        by postal2.es.net (Postal Node 2) with ESMTP id MUA74016
        for <FreeBSD-gnats-submit@freebsd.org>; Tue, 19 Nov 2002 13:16:10 -0800
Received: by ptavv.es.net (Tachyon Server, from userid 9381)
	id C26055D06; Tue, 19 Nov 2002 13:16:10 -0800 (PST)
Message-Id: <20021119211610.C26055D06@ptavv.es.net>
Date: Tue, 19 Nov 2002 13:16:10 -0800 (PST)
From: Kevin Oberman <oberman@es.net>
Reply-To: Kevin Oberman <oberman@es.net>
To: FreeBSD-gnats-submit@freebsd.org
Cc:
Subject: Confusing comment in /etc/crontab
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>Number:         45493
>Category:       misc
>Synopsis:       Confusing comment in /etc/crontab
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-bugs
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          change-request
>Submitter-Id:   current-users
>Arrival-Date:   Tue Nov 19 13:20:01 PST 2002
>Closed-Date:    Fri Nov 22 08:17:48 PST 2002
>Last-Modified:  Fri Nov 22 08:17:48 PST 2002
>Originator:     Kevin Oberman
>Release:        FreeBSD 4.7-STABLE i386
>Organization:
ESnet--The Energy Sciences Network
>Environment:
System: FreeBSD ptavv.es.net 4.7-STABLE FreeBSD 4.7-STABLE #15: Wed Nov 6 16:11:56 PST 2002 oberman@ptavv.es.net:/usr/obj/usr/src/sys/PTAVV i386

>Description:
	The comment for the adjkerntz entry in /etc/crontab is not
clear. The comma usage makes it unclear which cadse is the accepted
and which is rejected.
>How-To-Repeat:
	Not applicable.
>Fix:

--- crontab	Mon Jun 10 21:20:09 2002
+++ crontab.new	Tue Nov 19 13:14:47 2002
@@ -19,6 +19,6 @@
 30	5	1	*	*	root	periodic monthly
 #
 # time zone change adjustment for wall cmos clock,
-# does nothing, if you have UTC cmos clock.
+# does nothing if you have UTC cmos clock.
 # See adjkerntz(8) for details.
 1,31	0-5	*	*	*	root	adjkerntz -a
>Release-Note:
>Audit-Trail:

From: Bruce Evans <bde@zeta.org.au>
To: Kevin Oberman <oberman@es.net>
Cc: FreeBSD-gnats-submit@FreeBSD.ORG
Subject: Re: misc/45493: Confusing comment in /etc/crontab
Date: Wed, 20 Nov 2002 17:47:26 +1100 (EST)

 On Tue, 19 Nov 2002, Kevin Oberman wrote:
 
 > >Description:
 > 	The comment for the adjkerntz entry in /etc/crontab is not
 > clear. The comma usage makes it unclear which cadse is the accepted
 > and which is rejected.
 > >How-To-Repeat:
 > 	Not applicable.
 > >Fix:
 >
 > --- crontab	Mon Jun 10 21:20:09 2002
 > +++ crontab.new	Tue Nov 19 13:14:47 2002
 > @@ -19,6 +19,6 @@
 >  30	5	1	*	*	root	periodic monthly
 >  #
 >  # time zone change adjustment for wall cmos clock,
 > -# does nothing, if you have UTC cmos clock.
 > +# does nothing if you have UTC cmos clock.
 >  # See adjkerntz(8) for details.
 >  1,31	0-5	*	*	*	root	adjkerntz -a
 
 Something should be done about the first comma too.  crontab is apparently
 supposed to be written in non-English with all "sentences" in comments not
 beginning with a capital letter and not ending with a period, but the
 comment about adjkerntz violates this by using bad English (a comma splice)
 in its first line, the stray comma and a period in its second line, and
 actual English in its last line.
 
 Bruce
 

From: Tom Hukins <tom@FreeBSD.org>
To: FreeBSD-gnats-submit@freebsd.org, Kevin Oberman <oberman@es.net>,
	Bruce Evans <bde@zeta.org.au>
Cc:  
Subject: Re: misc/45493: Confusing comment in /etc/crontab
Date: Thu, 21 Nov 2002 11:42:56 +0000

 I'd appreciate your feedback on this patch which fixes the ambiguous
 adjkerntz(8) statement in /etc/crontab and generally tidies up the
 grammar used in comments.
 
 Thanks,
 Tom
 
 Index: crontab
 ===================================================================
 RCS file: /home/ncvs/src/etc/crontab,v
 retrieving revision 1.31
 diff -u -r1.31 crontab
 --- crontab	19 Feb 2001 02:47:41 -0000	1.31
 +++ crontab	21 Nov 2002 10:09:19 -0000
 @@ -10,18 +10,17 @@
  #
  */5	*	*	*	*	root	/usr/libexec/atrun
  #
 -# save some entropy so that /dev/random can reseed on boot
 +# Save some entropy so that /dev/random can reseed on boot.
  */11	*	*	*	*	operator /usr/libexec/save-entropy
  #
 -# rotate log files every hour, if necessary
 +# Rotate log files every hour, if necessary.
  0	*	*	*	*	root	newsyslog
  #
 -# do daily/weekly/monthly maintenance
 +# Perform daily/weekly/monthly maintenance.
  1	3	*	*	*	root	periodic daily
  15	4	*	*	6	root	periodic weekly
  30	5	1	*	*	root	periodic monthly
  #
 -# time zone change adjustment for wall cmos clock,
 -# does nothing, if you have UTC cmos clock.
 -# See adjkerntz(8) for details.
 +# Timezone adjustment for wall CMOS clock.  Does nothing for UTC CMOS
 +# clock.  See adjkerntz(8) for details.
  1,31	0-5	*	*	*	root	adjkerntz -a

From: Giorgos Keramidas <keramida@freebsd.org>
To: Tom Hukins <tom@freebsd.org>
Cc: bug-followup@freebsd.org
Subject: Re: misc/45493: Confusing comment in /etc/crontab
Date: Thu, 21 Nov 2002 14:29:13 +0200

 On 2002-11-21 03:50, Tom Hukins <tom@FreeBSD.org> wrote:
 > I'd appreciate your feedback on this patch which fixes the ambiguous
 > adjkerntz(8) statement in /etc/crontab and generally tidies up the
 > grammar used in comments.
 
 It looks fine, except for one minor detail.  The following is still a
 bit strange, since "Does nothing for UTC CMOS clock." is not a valid,
 complete sentence.
 
 >  +# Timezone adjustment for wall CMOS clock.  Does nothing for UTC CMOS
 >  +# clock.  See adjkerntz(8) for details.
 
 "This does nothing..."
 "It does nothing..."
 "adjkerntz(8) does nothing..."
 
 You can pick whichever you like :)
 

From: Tom Hukins <tom@FreeBSD.org>
To: Giorgos Keramidas <keramida@freebsd.org>
Cc: bug-followup@freebsd.org
Subject: Re: misc/45493: Confusing comment in /etc/crontab
Date: Thu, 21 Nov 2002 13:02:57 +0000

 On Thu, Nov 21, 2002 at 02:29:13PM +0200, Giorgos Keramidas wrote:
 > On 2002-11-21 03:50, Tom Hukins <tom@FreeBSD.org> wrote:
 > 
 > The following is still a bit strange, since "Does nothing for UTC
 > CMOS clock." is not a valid, complete sentence.
 > 
 > >  +# Timezone adjustment for wall CMOS clock.  Does nothing for UTC CMOS
 > >  +# clock.  See adjkerntz(8) for details.
 
 Yes, on reflection "Adjust the time zone only if the CMOS clock keeps
 local time.  See adjkerntz(8) for details." seems clearer to me.
 
 Tom

From: Ceri Davies <ceri@FreeBSD.org>
To: Tom Hukins <tom@FreeBSD.org>
Cc: freebsd-gnats-submit@FreeBSD.org
Subject: Re: misc/45493: Confusing comment in /etc/crontab
Date: Thu, 21 Nov 2002 13:16:10 +0000

 On Thu, Nov 21, 2002 at 05:10:05AM -0800, Tom Hukins wrote:
 
 >  Yes, on reflection "Adjust the time zone only if the CMOS clock keeps
 >  local time.  See adjkerntz(8) for details." seems clearer to me.
 
 What other time does it keep? ;)
 
 "Adjust the time zone only if local time is kept by the CMOS clock" ?
 
 Ceri
 -- 
 By the gems of the blood, you shall meet your end!

From: Tom Hukins <tom@FreeBSD.org>
To: Ceri Davies <ceri@FreeBSD.org>, freebsd-gnats-submit@FreeBSD.org
Cc:  
Subject: Re: misc/45493: Confusing comment in /etc/crontab
Date: Thu, 21 Nov 2002 13:29:40 +0000

 On Thu, Nov 21, 2002 at 01:16:10PM +0000, Ceri Davies wrote:
 > On Thu, Nov 21, 2002 at 05:10:05AM -0800, Tom Hukins wrote:
 > 
 > >  Yes, on reflection "Adjust the time zone only if the CMOS clock keeps
 > >  local time.  See adjkerntz(8) for details." seems clearer to me.
 > 
 > What other time does it keep? ;)
 
 "Adjust the time zone if the CMOS clock keeps local time, as opposed
 to UTC time."
 
 Third time lucky?
 
 Tom

From: Giorgos Keramidas <keramida@freebsd.org>
To: Ceri Davies <ceri@freebsd.org>, Tom Hukins <tom@freebsd.org>
Cc: bug-followup@freebsd.org
Subject: Re: misc/45493: Confusing comment in /etc/crontab
Date: Thu, 21 Nov 2002 15:30:58 +0200

 On 2002-11-21 05:20, Ceri Davies <ceri@FreeBSD.ORG> wrote:
 > On Thu, Nov 21, 2002 at 05:10:05AM -0800, Tom Hukins wrote:
 > >  Yes, on reflection "Adjust the time zone only if the CMOS clock keeps
 > >  local time.  See adjkerntz(8) for details." seems clearer to me.
 >
 > What other time does it keep? ;)
 
 UTC obviously.
 
 > "Adjust the time zone only if local time is kept by the CMOS clock" ?
 
 This is equivalent to the one Tom suggested.  It doesn't add or remove
 anything to the meaning.  It also uses a passive form that is sometimes
 considered to be bad style :p
 
 If the comment needs to describe two cases, there should be two
 simpler sentences instead of one that doesn't quite cut it.  I'd
 probably prefer this written as:
 
 # Adjust the time zone.  See adjkerntz(8) for details.  If your CMOS
 # clock is set to UTC instead of the local time, this does nothing.

From: Ceri Davies <ceri@FreeBSD.org>
To: Giorgos Keramidas <keramida@freebsd.org>
Cc: freebsd-gnats-submit@FreeBSD.org, tom@FreeBSD.org
Subject: Re: misc/45493: Confusing comment in /etc/crontab
Date: Thu, 21 Nov 2002 13:44:39 +0000

 On Thu, Nov 21, 2002 at 05:40:04AM -0800, Giorgos Keramidas wrote:
 > The following reply was made to PR misc/45493; it has been noted by GNATS.
 > 
 >  On 2002-11-21 05:20, Ceri Davies <ceri@FreeBSD.ORG> wrote:
 >  > On Thu, Nov 21, 2002 at 05:10:05AM -0800, Tom Hukins wrote:
 >  > >  Yes, on reflection "Adjust the time zone only if the CMOS clock keeps
 >  > >  local time.  See adjkerntz(8) for details." seems clearer to me.
 >  >
 >  > What other time does it keep? ;)
 >  
 >  UTC obviously.
 
 OK, you got me.
 
 >  If the comment needs to describe two cases, there should be two
 >  simpler sentences instead of one that doesn't quite cut it.  I'd
 >  probably prefer this written as:
 >  
 >  # Adjust the time zone.  See adjkerntz(8) for details.  If your CMOS
 >  # clock is set to UTC instead of the local time, this does nothing.
 
 Good.
 
 Ceri
 -- 
 The stalwart Urgrosh has come!

From: "Kevin Oberman" <oberman@es.net>
To: Tom Hukins <tom@FreeBSD.org>
Cc: FreeBSD-gnats-submit@freebsd.org, Bruce Evans <bde@zeta.org.au>
Subject: Re: misc/45493: Confusing comment in /etc/crontab 
Date: Thu, 21 Nov 2002 06:04:59 -0800

 > Date: Thu, 21 Nov 2002 11:42:56 +0000
 > From: Tom Hukins <tom@FreeBSD.org>
 > 
 > I'd appreciate your feedback on this patch which fixes the ambiguous
 > adjkerntz(8) statement in /etc/crontab and generally tidies up the
 > grammar used in comments.
 > 
 > Thanks,
 > Tom
 
 I'd suggest one extremely minor change. If you can't spot it, I
 hyphenated te word "re-seed".
 
 R. Kevin Oberman, Network Engineer
 Energy Sciences Network (ESnet)
 Ernest O. Lawrence Berkeley National Laboratory (Berkeley Lab)
 E-mail: oberman@es.net			Phone: +1 510 486-8634
 
 Index: crontab
 ===================================================================
 RCS file: /home/ncvs/src/etc/crontab,v
 retrieving revision 1.31
 diff -u -r1.31 crontab
 --- crontab	19 Feb 2001 02:47:41 -0000	1.31
 +++ crontab	21 Nov 2002 14:03:42 -0000
 @@ -10,18 +10,17 @@
  #
  */5	*	*	*	*	root	/usr/libexec/atrun
  #
 -# save some entropy so that /dev/random can reseed on boot
 +# Save some entropy so that /dev/random can re-seed on boot.
  */11	*	*	*	*	operator /usr/libexec/save-entropy
  #
 -# rotate log files every hour, if necessary
 +# Rotate log files every hour, if necessary.
  0	*	*	*	*	root	newsyslog
  #
 -# do daily/weekly/monthly maintenance
 +# Perform daily/weekly/monthly maintenance.
  1	3	*	*	*	root	periodic daily
  15	4	*	*	6	root	periodic weekly
  30	5	1	*	*	root	periodic monthly
  #
 -# time zone change adjustment for wall cmos clock,
 -# does nothing, if you have UTC cmos clock.
 -# See adjkerntz(8) for details.
 +# Timezone adjustment for wall CMOS clock.  Does nothing for UTC CMOS
 +# clock.  See adjkerntz(8) for details.
  1,31	0-5	*	*	*	root	adjkerntz -a
 
State-Changed-From-To: open->closed 
State-Changed-By: tom 
State-Changed-When: Fri Nov 22 08:17:04 PST 2002 
State-Changed-Why:  
I have clarified the adjkerntz(8) comment in revision 1.32 of /etc/crontab. 

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