Bug 165841

Comment 1 Eitan Adler 2012-03-07 23:12:46 UTC

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

I'll take it.

Comment 2 dfilter service 2012-03-09 01:32:24 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"

Comment 3 Eitan Adler 2012-03-09 01:43:01 UTC

State Changed
From-To: open->patched

committed in r232712

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.

Comment 5 Eitan Adler 2012-03-09 05:14:14 UTC

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

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.

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.

Comment 8 Eitan Adler 2012-03-11 22:05:34 UTC

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

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.

Comment 10 Eitan Adler 2012-06-05 06:15:38 UTC

State Changed
From-To: patched->closed

Committed. Thanks!