From nobody@FreeBSD.org  Wed Mar  7 23:02:55 2012
Return-Path: <nobody@FreeBSD.org>
Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34])
	by hub.freebsd.org (Postfix) with ESMTP id 27DEE106566C
	for <freebsd-gnats-submit@FreeBSD.org>; Wed,  7 Mar 2012 23:02:55 +0000 (UTC)
	(envelope-from nobody@FreeBSD.org)
Received: from red.freebsd.org (red.freebsd.org [IPv6:2001:4f8:fff6::22])
	by mx1.freebsd.org (Postfix) with ESMTP id 003A28FC18
	for <freebsd-gnats-submit@FreeBSD.org>; Wed,  7 Mar 2012 23:02:55 +0000 (UTC)
Received: from red.freebsd.org (localhost [127.0.0.1])
	by red.freebsd.org (8.14.4/8.14.4) with ESMTP id q27N2sjp054299
	for <freebsd-gnats-submit@FreeBSD.org>; Wed, 7 Mar 2012 23:02:54 GMT
	(envelope-from nobody@red.freebsd.org)
Received: (from nobody@localhost)
	by red.freebsd.org (8.14.4/8.14.4/Submit) id q27N2s9i054298;
	Wed, 7 Mar 2012 23:02:54 GMT
	(envelope-from nobody)
Message-Id: <201203072302.q27N2s9i054298@red.freebsd.org>
Date: Wed, 7 Mar 2012 23:02:54 GMT
From: Robert Simmons <rsimmons0@gmail.com>
To: freebsd-gnats-submit@FreeBSD.org
Subject: Grammar improvement and text clarification for adjkerntz(8) man page
X-Send-Pr-Version: www-3.1
X-GNATS-Notify:

>Number:         165841
>Category:       docs
>Synopsis:       Grammar improvement and text clarification for adjkerntz(8) man page
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    eadler
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Wed Mar 07 23:10:12 UTC 2012
>Closed-Date:    Tue Jun 05 05:15:39 UTC 2012
>Last-Modified:  Tue Jun 05 05:15:39 UTC 2012
>Originator:     Robert Simmons
>Release:        HEAD
>Organization:
>Environment:
>Description:
My next step in proofreading man pages (more to come).  I've made a couple of parts of the man page read a bit clearer and I've cleaned up a few grammar and punctuation mistakes.
>How-To-Repeat:

>Fix:
I've attached a patch in unified diff format that fixes the problems.

Patch attached with submission follows:

--- src/sbin/adjkerntz/adjkerntz.8	2005-02-13 17:25:15.000000000 -0500
+++ src/sbin/adjkerntz/adjkerntz.8.new	2012-03-07 17:56:50.000000000 -0500
@@ -29,7 +29,8 @@
 .Os
 .Sh NAME
 .Nm adjkerntz
-.Nd "adjust local time CMOS clock to reflect time zone changes and keep current timezone offset for the kernel"
+.Nd "adjust the local time CMOS clock to reflect time zone changes and keep the current timezone
+offset for the kernel"
 .Sh SYNOPSIS
 .Nm
 .Fl i
@@ -38,24 +39,22 @@
 .Sh DESCRIPTION
 The
 .Nm
-utility maintains the proper relationship between the kernel clock, which
-is always set to UTC, and the CMOS clock, which may be set to local
-time.
+utility maintains the proper relationship between the kernel clock, which is
+always set to UTC and the CMOS clock, which may be set to local time.
 The
 .Nm
-utility also informs the kernel about machine timezone shifts to
+utility also informs the kernel about machine timezone shifts in order to
 maintain proper timestamps for local time file systems such as the MS-DOS
 file system.
-The main purpose of this thing is not general fixing of
-initially broken MS-DOS file timestamp idea but keeping
-the same timestamps between
+The main purpose of maintaining these timestamps properly is to keep the
+timestamps of a
 .Fx
-MS-DOS file system
-and MS-DOS operating system installed on the same
-machine.
+MS-DOS file system and an MS-DOS operating system synchronized when they are
+installed on the same system rather than generally fixing broken MS-DOS file
+timestamps.
 If the file
 .Pa /etc/wall_cmos_clock
-exists, it means that CMOS clock keeps local time (MS-DOS and MS-Windows
+exists, it means that the CMOS clock keeps local time (MS-DOS and MS-Windows
 compatible mode).
 If that file does not exist, it means that the CMOS clock keeps UTC time.
 The
@@ -64,8 +63,8 @@
 .Pa machdep.wall_cmos_clock
 kernel variable.
 .Pp
-Adjustments may be needed at system startup and shutdown, and
-whenever a time zone change occurs.
+Adjustments may be needed at system startup and shutdown, and whenever a time
+zone change occurs.
 To handle these different situations,
 .Nm
 is invoked in two ways:
@@ -82,11 +81,11 @@
 utility puts itself into the background.
 Then, for a local time CMOS clock,
 .Nm
-reads the local time from it
-and sets the kernel clock to the corresponding UTC time.
+reads the local time from it and sets the kernel clock to the
+corresponding UTC time.
 The
 .Nm
-utility also stores the local time zone offset into the
+utility also stores the local time zone offset in the
 .Pa machdep.adjkerntz
 kernel variable, for use by subsequent invocations of
 .Em "'adjkerntz -a'"
@@ -94,8 +93,8 @@
 .Pp
 For a local time CMOS clock
 .Em "'adjkerntz -i'"
-pauses, and remains inactive as a background daemon until it
-receives a SIGTERM.
+pauses and remains inactive as a background daemon until it receives a
+SIGTERM.
 The SIGTERM will normally be sent by
 .Xr init 8
 when the system leaves multi-user mode (usually, because the system
@@ -120,7 +119,7 @@
 calculate a new time zone offset.
 It stores the new offset into the
 .Pa machdep.adjkerntz
-kernel variable, and updates the wall CMOS clock to the new local time.
+kernel variable and updates the wall CMOS clock to the new local time.
 If
 .Em "'adjkerntz -a'"
 was started at a nonexistent time (during a timezone change), it exits


>Release-Note:
>Audit-Trail:
Responsible-Changed-From-To: freebsd-doc->eadler 
Responsible-Changed-By: eadler 
Responsible-Changed-When: Wed Mar 7 23:12:46 UTC 2012 
Responsible-Changed-Why:  
I'll take it. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=165841 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/165841: commit references a PR
Date: Fri,  9 Mar 2012 01:32:24 +0000 (UTC)

 Author: eadler
 Date: Fri Mar  9 01:32:05 2012
 New Revision: 232712
 URL: http://svn.freebsd.org/changeset/base/232712
 
 Log:
   Fix a variety of grammar and style nits
   
   PR:		docs/165841
   Submitted by:	Robert Simmons <rsimmons0@gmail.com>
   Approved by:	brd
   MFC after:	1 week
 
 Modified:
   head/sbin/adjkerntz/adjkerntz.8
 
 Modified: head/sbin/adjkerntz/adjkerntz.8
 ==============================================================================
 --- head/sbin/adjkerntz/adjkerntz.8	Fri Mar  9 00:53:54 2012	(r232711)
 +++ head/sbin/adjkerntz/adjkerntz.8	Fri Mar  9 01:32:05 2012	(r232712)
 @@ -24,12 +24,12 @@
  .\"
  .\" $FreeBSD$
  .\"
 -.Dd April 4, 1996
 +.Dd March 8, 2012
  .Dt ADJKERNTZ 8
  .Os
  .Sh NAME
  .Nm adjkerntz
 -.Nd "adjust local time CMOS clock to reflect time zone changes and keep current timezone offset for the kernel"
 +.Nd adjust the local time CMOS clock to reflect time zone changes and keep the current timezone offset for the kernel
  .Sh SYNOPSIS
  .Nm
  .Fl i
 @@ -39,23 +39,21 @@
  The
  .Nm
  utility maintains the proper relationship between the kernel clock, which
 -is always set to UTC, and the CMOS clock, which may be set to local
 -time.
 +is always set to UTC and the CMOS clock, which may be set to local time.
  The
  .Nm
 -utility also informs the kernel about machine timezone shifts to
 +utility also informs the kernel about machine timezone shifts in order to
  maintain proper timestamps for local time file systems such as the MS-DOS
  file system.
 -The main purpose of this thing is not general fixing of
 -initially broken MS-DOS file timestamp idea but keeping
 -the same timestamps between
 +The main purpose of maintaining these timestamps properly is to keep the
 +timestamps of a
  .Fx
 -MS-DOS file system
 -and MS-DOS operating system installed on the same
 -machine.
 +MS-DOS file system and an MS-DOS operating system synchronized when they are
 +installed on the same system rather than fixing broken MS-DOS file
 +timestamps.
  If the file
  .Pa /etc/wall_cmos_clock
 -exists, it means that CMOS clock keeps local time (MS-DOS and MS-Windows
 +exists, it means that the CMOS clock keeps local time (MS-DOS and MS-Windows
  compatible mode).
  If that file does not exist, it means that the CMOS clock keeps UTC time.
  The
 @@ -86,7 +84,7 @@ reads the local time from it
  and sets the kernel clock to the corresponding UTC time.
  The
  .Nm
 -utility also stores the local time zone offset into the
 +utility also stores the local time zone offset in the
  .Pa machdep.adjkerntz
  kernel variable, for use by subsequent invocations of
  .Em "'adjkerntz -a'"
 @@ -94,7 +92,7 @@ and by local time file systems.
  .Pp
  For a local time CMOS clock
  .Em "'adjkerntz -i'"
 -pauses, and remains inactive as a background daemon until it
 +pauses and remains inactive as a background daemon until it
  receives a SIGTERM.
  The SIGTERM will normally be sent by
  .Xr init 8
 @@ -120,7 +118,7 @@ time zone offset, and the changed time z
  calculate a new time zone offset.
  It stores the new offset into the
  .Pa machdep.adjkerntz
 -kernel variable, and updates the wall CMOS clock to the new local time.
 +kernel variable and updates the wall CMOS clock to the new local time.
  If
  .Em "'adjkerntz -a'"
  was started at a nonexistent time (during a timezone change), it exits
 _______________________________________________
 svn-src-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/svn-src-all
 To unsubscribe, send any mail to "svn-src-all-unsubscribe@freebsd.org"
 
State-Changed-From-To: open->patched 
State-Changed-By: eadler 
State-Changed-When: Fri Mar 9 01:43:01 UTC 2012 
State-Changed-Why:  
committed in r232712 

http://www.freebsd.org/cgi/query-pr.cgi?pr=165841 

From: "b. f." <bf1783@googlemail.com>
To: bug-followup@freebsd.org, eadler@freebsd.org
Cc:  
Subject: Re: docs/165841: Grammar improvement and text clarification for
 adjkerntz(8) man page
Date: Fri, 9 Mar 2012 04:25:28 +0000

 I am glad to see that someone is taking the time to clean up some of
 the manpages, many of which need some attention.  However, I feel
 submissions of this kind need to be read with a more critical eye (and
 ear).  Many of the suggested changes in punctuation don't correct
 "mistakes", but just reflect the different taste of the submitter, who
 seems to feel that fewer commas are better, which is not always the
 case.  I am indifferent to most of them, which leads me to suggest
 that many of them need not have been made.  The first, however, is a
 regression:
 
 >utility maintains the proper relationship between the kernel clock, which
 >-is always set to UTC, and the CMOS clock, which may be set to local
 >-time.
 >+utility maintains the proper relationship between the kernel clock, which is
 >+always set to UTC and the CMOS clock, which may be set to local time.
 
 The comma that was removed (after "UTC"), together with the first
 comma that remains (after "clock"), served to separate a nonessential
 adjective clause from the rest of the sentence.  The new punctuation
 has reduced the clarity of this passage, and the removal of such a
 comma is widely considered to be a punctuation "mistake".  Please
 restore this comma.
 
 I would also suggest that a comma be  inserted before "rather", to
 make the new wording of the following long sentence more readable:
 
 >-MS-DOS file system
 >-and MS-DOS operating system installed on the same
 >-machine.
 >+MS-DOS file system and an MS-DOS operating system synchronized when they are
 >+installed on the same system rather than generally fixing broken MS-DOS file
 >+timestamps.
 
 b.

From: Eitan Adler <eadler@freebsd.org>
To: bf1783@gmail.com
Cc: bug-followup@freebsd.org
Subject: Re: docs/165841: Grammar improvement and text clarification for
 adjkerntz(8) man page
Date: Fri, 9 Mar 2012 00:14:14 -0500

 On Thu, Mar 8, 2012 at 11:25 PM, b. f. <bf1783@googlemail.com> wrote:
 > I am glad to see that someone is taking the time to clean up some of
 > the manpages, many of which need some attention. =C2=A0However, I feel
 > submissions of this kind need to be read with a more critical eye (and
 > ear).
 
 I happen to agree with most of the changes (note that the patch I
 committed was not identical to the one submitted)
 
 > Many of the suggested changes in punctuation don't correct
 > "mistakes", but just reflect the different taste of the submitter, who
 > seems to feel that fewer commas are better, which is not always the
 > case.
 
 I read the sentence aloud to myself to see if the change made sense.
 
 > I am indifferent to most of them, which leads me to suggest
 > that many of them need not have been made. =C2=A0The first, however, is a
 > regression:
 
 > The comma that was removed (after "UTC"), together with the first
 > comma that remains (after "clock"), served to separate a nonessential
 > adjective clause from the rest of the sentence. =C2=A0The new punctuation
 > has reduced the clarity of this passage, and the removal of such a
 > comma is widely considered to be a punctuation "mistake". =C2=A0Please
 > restore this comma.
 
 I misread this sentence originally leading me to believe the comma was
 making it unclear. Reading it again now I see how it is unclear.
 
 > I would also suggest that a comma be =C2=A0inserted before "rather", to
 > make the new wording of the following long sentence more readable:
 >
 >>-MS-DOS file system
 >>-and MS-DOS operating system installed on the same
 >>-machine.
 >>+MS-DOS file system and an MS-DOS operating system synchronized when they=
  are
 >>+installed on the same system rather than generally fixing broken MS-DOS =
 file
 >>+timestamps.
 
 I'll take a closer look at this patch soon. Thanks for the submission.
 
 Feel free to review any other patches submitted. I can't be perfect
 and it is a good think if more people look at proposed content
 changes.
 
 --=20
 Eitan Adler
 Source & Ports committer
 X11, Bugbusting teams

From: "b. f." <bf1783@googlemail.com>
To: Eitan Adler <eadler@freebsd.org>
Cc: bug-followup@freebsd.org
Subject: Re: docs/165841: Grammar improvement and text clarification for
 adjkerntz(8) man page
Date: Fri, 9 Mar 2012 06:28:36 +0000

 On 3/9/12, Eitan Adler <eadler@freebsd.org> wrote:
 > On Thu, Mar 8, 2012 at 11:25 PM, b. f. <bf1783@googlemail.com> wrote:
 
 >
 >> Many of the suggested changes in punctuation don't correct
 >> "mistakes", but just reflect the different taste of the submitter, who
 >> seems to feel that fewer commas are better, which is not always the
 >> case.
 >
 > I read the sentence aloud to myself to see if the change made sense.
 
 Right, but the bar is higher than that.  We should commit if we are
 correcting a clear error or making a substantial improvement, but we
 are not obliged to make changes, and we should not, to avoid churn, if
 the proposed change just reflects a minor difference in style.  Some
 of the changes in this PR are clearly of the latter variety.  Remember
 that some punctuation that we supply mentally, if it is absent, or
 that we would not add ourselves when speaking aloud, supplies valuable
 cues to readers, especially those for whom English is not a first
 language.
 
 b.

From: Robert Simmons <rsimmons0@gmail.com>
To: bug-followup@freebsd.org
Cc: bf1783@googlemail.com, eadler@freebsd.org
Subject: Re: docs/165841: Grammar improvement and text clarification for
 adjkerntz(8) man page
Date: Sun, 11 Mar 2012 17:58:32 -0400

 Hi,
 
 I appreciate you catching my mistake, bf1783@googlemail.com.  I had
 misread that sentence.  However, a comma should not be added before
 "rather than".  This is a subordinating conjunction.  Only when used
 at the beginning of a sentence is a comma used.
 
 Additionally, I will keep all further changes to an absolute minimum;
 only making significant improvements.  But I would have to disagree
 with your assessment of my changes reflecting minor differences in
 style.  This is where a style guide enters the picture.  This way
 there is only one style, and there are no differences of style.  As
 far as I know, the style guide that FreeBSD uses is Strunk and White,
 correct?
 
 Also, I disagree with your assessment of the purpose of punctuation.
 It's purpose is to improve the readability and clarity of orthography.
  It is not to assist non-native speakers and second language learners,
 so you cannot just add punctuation where you feel that it would help.
 There are rules.  English is fortunately not like French where there
 is some central governing body that makes decisions as to what English
 is and what it is not.  In place of this, groups of speakers agree on
 their own sets of rules.  When it comes to written English for
 publication, these groups either write their own style guide (the
 Associated Press is an example), or they agree upon an pre-existing
 style guide (The Elements of Style) in our case.
 
 I apologize for the regression and I will try harder and review what I
 change with a closer eye.

From: Eitan Adler <eadler@freebsd.org>
To: Robert Simmons <rsimmons0@gmail.com>
Cc: bug-followup@freebsd.org, bf1783@googlemail.com
Subject: Re: docs/165841: Grammar improvement and text clarification for
 adjkerntz(8) man page
Date: Sun, 11 Mar 2012 18:05:34 -0400

 On Sun, Mar 11, 2012 at 5:58 PM, Robert Simmons <rsimmons0@gmail.com> wrote=
 :
 > This is where a style guide enters the picture. =C2=A0This way
 > there is only one style, and there are no differences of style. =C2=A0As
 > far as I know, the style guide that FreeBSD uses is Strunk and White,
 > correct?
 
 No, and hopefully we won't in the future. ;)
 Our style guide is available here:
 http://www.freebsd.org/doc/en/books/fdp-primer/writing-style.html
 
 > Also, I disagree with your assessment of the purpose of punctuation.
 > It's purpose is to improve the readability and clarity of orthography.
 > =C2=A0It is not to assist non-native speakers and second language learner=
 s,
 > so you cannot just add punctuation where you feel that it would help.
 > There are rules.
 
 These rules are descriptive of how people that speak and write clearly
 do use their punctuation. They are not prescriptive of how one must or
 should write.
 
 > In place of this, groups of speakers agree on
 > their own sets of rules.
 
 Precisely
 
 > I apologize for the regression and I will try harder and review what I
 > change with a closer eye.
 
 People can not always find their own mistakes, especially when it
 comes to documentation. The only way to solve these problems is have
 more review. I will try to find more people to look at the changes
 prior to committing in the future.
 
 
 Please continue working on this though! The more we can improve our
 documentation the better.
 
 
 
 --=20
 Eitan Adler
 Source & Ports committer
 X11, Bugbusting teams

From: "b. f." <bf1783@googlemail.com>
To: Robert Simmons <rsimmons0@gmail.com>
Cc: bug-followup@freebsd.org, eadler@freebsd.org
Subject: Re: docs/165841: Grammar improvement and text clarification for
 adjkerntz(8) man page
Date: Fri, 16 Mar 2012 13:13:34 +0000

 On 3/11/12, Robert Simmons <rsimmons0@gmail.com> wrote:
 
 ...
 
 > However, a comma should not be added before
 > "rather than".  This is a subordinating conjunction.  Only when used
 > at the beginning of a sentence is a comma used.
 
 Despite the various systems that have been set forth, punctuation is
 not (and never has been) completely mechanical.  Some writers (mostly
 those who take a narrow view of punctuation as a purely grammatical
 tool) proscribe the use of commas in this circumstance.  But many
 others suggest that it is appropriate to do so, particularly (but not
 only) since "rather than fixing broken MS-DOS file timestamps" is
 nonessential and contrasting.  If you would prefer to recast this
 sentence, that's fine.  I am just pointing out that it is now long and
 not very easy to read.
 
 ...
 
 > But I would have to disagree
 > with your assessment of my changes reflecting minor differences in
 > style.  This is where a style guide enters the picture.  This way
 > there is only one style, and there are no differences of style.  As
 > far as I know, the style guide that FreeBSD uses is Strunk and White,
 > correct?
 
 As far as I know, yes (and in my opinion it has a benign influence).
 But any style guide leaves some room for discretion.
 
 ...
 
 > Also, I disagree with your assessment of the purpose of punctuation.
 > It's purpose is to improve the readability and clarity of orthography.
 >  It is not to assist non-native speakers and second language learners,
 > so you cannot just add punctuation where you feel that it would help.
 > There are rules.
 
 I don't disagree with this statement of the purpose of punctuation,
 and I don't know how you inferred that I did.  I am merely saying that
 reasonable rules governing punctuation don't always rigidly dictate
 what punctuation is used, or where -- and in those circumstances we
 should consider the needs of our readers.
 
 I'd echo Eitan's comments that we do need to continue to fix some
 errors or infelicities in our manpages, and that we value your
 contributions, even if we don't agree with every part of them.
 
 b.
State-Changed-From-To: patched->closed 
State-Changed-By: eadler 
State-Changed-When: Tue Jun 5 05:15:38 UTC 2012 
State-Changed-Why:  
Committed. Thanks! 

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