[PATCH 1/3] hwclock: remove an untrue phrase from the man page

[PATCH 1/3] hwclock: remove an untrue phrase from the man page

[Benno Schulenberg]

Signed-off-by: Benno Schulenberg <bensberg@justemail.net>
---
 sys-utils/hwclock.8.in |    5 -----
 1 files changed, 0 insertions(+), 5 deletions(-)

diff --git a/sys-utils/hwclock.8.in b/sys-utils/hwclock.8.in
index 96c57d4..9682244 100644
--- a/sys-utils/hwclock.8.in
+++ b/sys-utils/hwclock.8.in
@@ -298,11 +298,6 @@ the true year.  That way, the Hardware Clock inserts leap days where
 they belong.  Again, if you let the Hardware Clock run for more than a
 year without setting it, this scheme could be defeated and you could
 end up losing a day.
-.sp
-.B \%hwclock
-warns you that you probably need
-.B \%\-\-badyear
-whenever it finds your Hardware Clock set to 1994 or 1995.
 .
 .TP
 .BI \%\-\-date= date_string
-- 
1.7.0.4

[PATCH 2/3] hwclock: remove unneeded stuff from the man-page header

[Benno Schulenberg]

Signed-off-by: Benno Schulenberg <bensberg@justemail.net>
---
 sys-utils/hwclock.8.in |   21 +++------------------
 1 files changed, 3 insertions(+), 18 deletions(-)

diff --git a/sys-utils/hwclock.8.in b/sys-utils/hwclock.8.in
index 9682244..145e089 100644
--- a/sys-utils/hwclock.8.in
+++ b/sys-utils/hwclock.8.in
@@ -1,24 +1,9 @@
 .\" hwclock.8.in -- man page for util-linux' hwclock
 .\"
-.\" 2015-01-07 J William Piggott
-.\" Authored new section: DATE-TIME CONFIGURATION.
-.\" Subsections: Keeping Time..., LOCAL vs UTC, POSIX vs 'RIGHT'.
-.\" Errata and drop outdated language.
-.\" Updates for v2.26
-.\"
-.\"
-.\" -------------------------------
-.\" Included for troff portability.
-.\" Continuation line for .TP header.
-.de TQ
-.  br
-.  ns
-.  TP \\$1\" no doublequotes around argument!
-..
-.
-.\" -------------------------------
+.\" Copyright 1996 Bryan Henderson <bryanh@giraffe-data.com>
+.\" Copyright 2015 J. William Piggott <elseifthen@gmx.com>
 .
-.TH HWCLOCK 8 "January 2015" "util-linux" "System Administration"
+.TH HWCLOCK 8 "March 2015" "util-linux" "System Administration"
 .SH NAME
 hwclock \- read or set the hardware clock (RTC)
 .SH SYNOPSIS
-- 
1.7.0.4

[PATCH 3/3] hwclock: fix spelling, punctuation and formatting mistakes in the man page

[Benno Schulenberg]

Also improve some wordings.

Signed-off-by: Benno Schulenberg <bensberg@justemail.net>
---
 sys-utils/hwclock.8.in |   78 +++++++++++++++++++++++------------------------
 1 files changed, 38 insertions(+), 40 deletions(-)

diff --git a/sys-utils/hwclock.8.in b/sys-utils/hwclock.8.in
index 145e089..a884ccc 100644
--- a/sys-utils/hwclock.8.in
+++ b/sys-utils/hwclock.8.in
@@ -23,16 +23,15 @@ Hardware Clock values based on its drift rate.
 .PP
 Since v2.26 important changes were made to the
 .B \-\-hctosys
-function, the
+function and the
 .B \-\-directisa
 option, and a new option
 .B \-\-update\-drift
-was added. See their respective sections below.
+was added.  See their respective descriptions below.
 .
 .SH FUNCTIONS
 The following functions are mutually exclusive, only one can be given at
-a time. If none are given the default is
-.BR \-\-show .
+a time.  If none is given, the default is \fB\-\-show\fR.
 .TP
 .B \-\-adjust
 Add or subtract time from the Hardware Clock to account for systematic
@@ -59,9 +58,9 @@ that the year counter in your Hardware Clock contains the number of
 full years since 1952, then the kernel's Hardware Clock epoch value
 must be 1952.
 .sp
-The set function requires using the
+The \fB\%\-\-setepoch\fR function requires using the
 .B \%\-\-epoch
-option.
+option to specify the year.
 .sp
 This epoch value is used whenever
 .B \%hwclock
@@ -123,7 +122,7 @@ function does this based upon the information in the
 .I @ADJTIME_PATH@
 file or the command line arguments
 .BR \%\-\-localtime " and " \-\-utc .
-Note: no daylight saving adjustment is made. See the discussion below under
+Note: no daylight saving adjustment is made.  See the discussion below, under
 .BR "LOCAL vs UTC" .
 .sp
 The kernel also keeps a timezone value, the
@@ -153,7 +152,7 @@ This is a good function to use in one of the system startup scripts before the
 file systems are mounted read/write.
 .sp
 This function should never be used on a running system. Jumping system time
-will cause problems, such as, corrupted filesystem timestamps.  Also, if
+will cause problems, such as corrupted filesystem timestamps.  Also, if
 something has changed the Hardware Clock, like NTP's \%'11\ minute\ mode', then
 .B \%\-\-hctosys
 will set the time incorrectly by including drift compensation.
@@ -230,9 +229,9 @@ changed then a reboot would be required to inform the kernel.
 .BR \-w , \ \-\-systohc
 Set the Hardware Clock from the System Clock, and update the timestamps in
 .IR @ADJTIME_PATH@ .
-With the
+When the
 .B --update-drift
-option (re)calculate the drift factor.
+option is given, then also (re)calculate the drift factor.
 .
 .TP
 .BR \-V , \ \-\-version
@@ -298,7 +297,7 @@ The value of this option is used as an argument to the
 option.  For example:
 .RS
 .IP "" 4
-.BI "\%hwclock\ \-\-set\ \-\-date='" 2011-08-14\ 16:45:05 '
+.B "hwclock\ \-\-set\ \-\-date='2011-08-14\ 16:45:05'
 .PP
 The argument must be in local time, even if you keep your Hardware Clock in
 UTC.  See the
@@ -381,7 +380,7 @@ as recorded in
 will be used.  If the adjtime file doesn't exist, the default is UTC.
 .sp
 Note: daylight saving time changes may be inconsistent when the
-Hardware Clock is kept in local time. See the discussion below under
+Hardware Clock is kept in local time.  See the discussion below, under
 .BR "LOCAL vs UTC" .
 .
 .TP
@@ -447,9 +446,9 @@ option to be used.  See the discussion below, under
 .TP
 .B \-\-arc
 This option is equivalent to
-.BI \%\-\-epoch= 1980
+.B \%\-\-epoch=1980
 and is used to specify the most common epoch on Alphas
-with ARC console (but Ruffians have an epoch of 1900).
+with an ARC console (although Ruffians have an epoch of 1900).
 .
 .TP
 .BI \-\-epoch= year
@@ -462,7 +461,7 @@ option to set the kernel's idea of the epoch of the Hardware Clock.
 For example, on a Digital Unix machine:
 .RS
 .IP "" 4
-.BI hwclock\ \-\-setepoch\ \-\-epoch= 1952
+.B hwclock\ \-\-setepoch\ \-\-epoch=1952
 .RE
 .
 .TP
@@ -481,15 +480,15 @@ is mounted.
 option is used for Jensen models;
 .B \%\-\-funky\-toy
 means that the machine requires the UF bit instead of the UIP bit in
-the Hardware Clock to detect a time transition.  "Toy" in the option
+the Hardware Clock to detect a time transition.  The "toy" in the option
 name refers to the Time Of Year facility of the machine.
 .
 .TP
 .B \-\-srm
 This option is equivalent to
-.BI \%\-\-epoch= 1900
+.B \%\-\-epoch=1900
 and is used to specify the most common epoch on Alphas
-with SRM console.
+with an SRM console.
 .
 .SH NOTES
 .
@@ -556,11 +555,11 @@ file, as explained in the man page for
 However, some programs and fringe parts of the Linux kernel such as filesystems
 use the kernel's timezone value.  An example is the vfat filesystem.  If the
 kernel timezone value is wrong, the vfat filesystem will report and set the
-wrong timestamps on files. Another example is the kernel's NTP \%'11\ minute\ mode.'
+wrong timestamps on files.  Another example is the kernel's NTP \%'11\ minute\ mode'.
 If the kernel's timezone value and/or the
 .I \%persistent_clock_is_local
 variable are wrong, then the Hardware Clock will be set incorrectly
-by \%'11\ minute\ mode.'  See the discussion below, under
+by \%'11\ minute\ mode'.  See the discussion below, under
 .BR "Automatic Hardware Clock Synchronization by the Kernel" .
 .PP
 .B \%hwclock
@@ -588,7 +587,7 @@ compatible system, there is probably no need for users to have the direct
 ISA I/O method, so do not bother.  See the
 .BR \-\-rtc " option."
 .PP
-In any case, hwclock will not allow you to set anything unless you have the
+In any case, \fBhwclock\fR will not allow you to set anything unless you have the
 superuser real uid.  (This restriction is not necessary if you haven't
 installed setuid root, but it's there for now.)
 .
@@ -781,7 +780,7 @@ Hardware Clock timescale configuration is changed, then a reboot is required to
 notify the kernel.
 .PP
 .B \%hwclock\ \-\-adjust
-should not be used with NTP \%'11\ minute\ mode.'
+should not be used with NTP \%'11\ minute\ mode'.
 .
 .SS ISA Hardware Clock Century value
 .PP
@@ -809,15 +808,15 @@ are supported by the hardware.
 .PP
 This discussion is based on the following conditions:
 .IP \(bu 2
-Nothing is running that alters the date-time clocks, e.g.,
-.BR \%ntpd "(1), cron jobs, et al."
+Nothing is running that alters the date-time clocks, as for example
+.BR \%ntpd "(1) or a cron job."
 .IP \(bu 2
-The system timezone is configured for the correct local time.  See below
+The system timezone is configured for the correct local time.  See below, under
 .BR "POSIX vs 'RIGHT'" .
 .IP \(bu 2
-Early in startup the following are called in this order:
+Early during startup the following are called, in this order:
 .br
-.BI \%adjtimex\ \-\-tick \ <value>\  \-\-frequency \ <value>
+.BI \%adjtimex\ \-\-tick \ value\  \-\-frequency \ value
 .br
 .B \%hwclock\ \-\-hctosys
 .IP \(bu 2
@@ -842,8 +841,7 @@ different for each of them.  However, most systems are configured to
 exchange values between these two clocks at startup and shutdown.  Now
 the individual device's time keeping errors are transferred back and
 forth between each other.  Attempt to configure drift correction for only
-one of them, and the other's drift will be overlaid upon it.  If the big
-picture is not kept in mind, confusion will soon ensue.
+one of them, and the other's drift will be overlaid upon it.
 .PP
 This problem can be avoided when configuring drift correction for the
 System Clock by simply not shutting down the machine.  This, plus the
@@ -855,11 +853,11 @@ should be done first.
 .PP
 The System Clock drift is corrected with the
 .BR \%adjtimex "(8) command's " \-\-tick " and " \%\-\-frequency
-options.  These two work together, tick is the course adjustment and
-frequency is the fine adjustment. (For system that do not have an
+options.  These two work together; tick is the coarse adjustment and
+frequency is the fine adjustment.  (For systems that do not have an
 .BR \%adjtimex " package,"
-.BI \%ntptime\ \-f\  <ppm>
-may be use instead.)
+.BI \%ntptime\ \-f\  ppm
+may be used instead.)
 .PP
 Some Linux distributions attempt to automatically calculate the System
 Clock drift with
@@ -887,27 +885,27 @@ Once the System Clock is ticking smoothly, move on to the Hardware Clock.
 .PP
 As a rule, cold drift will work best for most use cases.  This should be
 true even for 24/7 machines whose normal downtime consists of a reboot.
-In that case the drift factor value makes little difference, but on the
-rare occasion that the machine is shutdown for an extended period then
+In that case the drift factor value makes little difference.  But on the
+rare occasion that the machine is shut down for an extended period, then
 cold drift should yield better results.
 .PP
 .B Steps to calculate cold drift:
 .IP 1 2
-.RB "Confirm that " ntpd "(1) will not be launched at startup."
+.RB "Ensure that " ntpd "(1) will not be launched at startup."
 .IP 2 2
 .RI The " System Clock " "time must be correct at shutdown!"
 .IP 3 2
-Shutdown the system.
+Shut down the system.
 .IP 4 2
 Let an extended period pass without changing the Hardware Clock.
 .IP 5 2
 Start the system.
 .IP 6 2
-.RB "Immediately use " hwclock " to set the correct time with the"
+.RB "Immediately use " hwclock " to set the correct time, adding the"
 .BR \%\-\-update\-drift " option."
 .PP
-Note: if step six uses
-.RB \%\-\-systohc ,
+Note: if step 6 uses
+.BR \%\-\-systohc ,
 then the System Clock must be set correctly (step 6a) just before doing so.
 .PP
 .RB "Having " hwclock
-- 
1.7.0.4

Re: [PATCH 3/3] hwclock: fix spelling, punctuation and formatting mistakes in the man page

[J William Piggott]

On 03/17/2015 04:34 PM, Benno Schulenberg wrote:
> Also improve some wordings.
> 
> Signed-off-by: Benno Schulenberg <bensberg@justemail.net>
> ---
>  sys-utils/hwclock.8.in |   78 +++++++++++++++++++++++------------------------
>  1 files changed, 38 insertions(+), 40 deletions(-)
> 
> diff --git a/sys-utils/hwclock.8.in b/sys-utils/hwclock.8.in
> index 145e089..a884ccc 100644
> --- a/sys-utils/hwclock.8.in
> +++ b/sys-utils/hwclock.8.in
> @@ -23,16 +23,15 @@ Hardware Clock values based on its drift rate.
>  .PP
>  Since v2.26 important changes were made to the
>  .B \-\-hctosys
> -function, the
> +function and the
>  .B \-\-directisa
>  option, and a new option
>  .B \-\-update\-drift
> -was added. See their respective sections below.
> +was added.  See their respective descriptions below.

What guide says this is the proper style for an inline list?
What guide says that its current form is incorrect?

>  .
>  .SH FUNCTIONS
>  The following functions are mutually exclusive, only one can be given at
> -a time. If none are given the default is
> -.BR \-\-show .
> +a time.  If none is given, the default is \fB\-\-show\fR.

We've already been through this; 'none' in this context is plural and
countable, justifying the use of a plural verb. Do you want me to quote
your reference again? Secondly, I took the time to remove inline font
escapes, because I find using macros easier to maintain.

>  .TP
>  .B \-\-adjust
>  Add or subtract time from the Hardware Clock to account for systematic
> @@ -59,9 +58,9 @@ that the year counter in your Hardware Clock contains the number of
>  full years since 1952, then the kernel's Hardware Clock epoch value
>  must be 1952.
>  .sp
> -The set function requires using the
> +The \fB\%\-\-setepoch\fR function requires using the
>  .B \%\-\-epoch
> -option.
> +option to specify the year.

This is completely unnecessary verbosity.

>  .sp
>  This epoch value is used whenever
>  .B \%hwclock
> @@ -123,7 +122,7 @@ function does this based upon the information in the
>  .I @ADJTIME_PATH@
>  file or the command line arguments
>  .BR \%\-\-localtime " and " \-\-utc .
> -Note: no daylight saving adjustment is made. See the discussion below under
> +Note: no daylight saving adjustment is made.  See the discussion below, under
>  .BR "LOCAL vs UTC" .
>  .sp
>  The kernel also keeps a timezone value, the
> @@ -153,7 +152,7 @@ This is a good function to use in one of the system startup scripts before the
>  file systems are mounted read/write.
>  .sp
>  This function should never be used on a running system. Jumping system time
> -will cause problems, such as, corrupted filesystem timestamps.  Also, if
> +will cause problems, such as corrupted filesystem timestamps.  Also, if
>  something has changed the Hardware Clock, like NTP's \%'11\ minute\ mode', then
>  .B \%\-\-hctosys
>  will set the time incorrectly by including drift compensation.
> @@ -230,9 +229,9 @@ changed then a reboot would be required to inform the kernel.
>  .BR \-w , \ \-\-systohc
>  Set the Hardware Clock from the System Clock, and update the timestamps in
>  .IR @ADJTIME_PATH@ .
> -With the
> +When the
>  .B --update-drift
> -option (re)calculate the drift factor.
> +option is given, then also (re)calculate the drift factor.

Again, unnecessary verbosity.

>  .
>  .TP
>  .BR \-V , \ \-\-version
> @@ -298,7 +297,7 @@ The value of this option is used as an argument to the
>  option.  For example:
>  .RS
>  .IP "" 4
> -.BI "\%hwclock\ \-\-set\ \-\-date='" 2011-08-14\ 16:45:05 '
> +.B "hwclock\ \-\-set\ \-\-date='2011-08-14\ 16:45:05'

It is common practice for option arguments to be in italic. I've already
explained to you that the soft hyphen prevents this command structure
from wrapping on narrow windows when multitasking.

>  .PP
>  The argument must be in local time, even if you keep your Hardware Clock in
>  UTC.  See the
> @@ -381,7 +380,7 @@ as recorded in
>  will be used.  If the adjtime file doesn't exist, the default is UTC.
>  .sp
>  Note: daylight saving time changes may be inconsistent when the
> -Hardware Clock is kept in local time. See the discussion below under
> +Hardware Clock is kept in local time.  See the discussion below, under
>  .BR "LOCAL vs UTC" .
>  .
>  .TP
> @@ -447,9 +446,9 @@ option to be used.  See the discussion below, under
>  .TP
>  .B \-\-arc
>  This option is equivalent to
> -.BI \%\-\-epoch= 1980
> +.B \%\-\-epoch=1980

Option arguments should be in italic.

>  and is used to specify the most common epoch on Alphas
> -with ARC console (but Ruffians have an epoch of 1900).
> +with an ARC console (although Ruffians have an epoch of 1900).
>  .
>  .TP
>  .BI \-\-epoch= year
> @@ -462,7 +461,7 @@ option to set the kernel's idea of the epoch of the Hardware Clock.
>  For example, on a Digital Unix machine:
>  .RS
>  .IP "" 4
> -.BI hwclock\ \-\-setepoch\ \-\-epoch= 1952
> +.B hwclock\ \-\-setepoch\ \-\-epoch=1952

Option arguments should be in italic.

>  .RE
>  .
>  .TP
> @@ -481,15 +480,15 @@ is mounted.
>  option is used for Jensen models;
>  .B \%\-\-funky\-toy
>  means that the machine requires the UF bit instead of the UIP bit in
> -the Hardware Clock to detect a time transition.  "Toy" in the option
> +the Hardware Clock to detect a time transition.  The "toy" in the option

What style guide is this from? Unnecessary, you're making changes for
the sake of making changes.

>  name refers to the Time Of Year facility of the machine.
>  .
>  .TP
>  .B \-\-srm
>  This option is equivalent to
> -.BI \%\-\-epoch= 1900
> +.B \%\-\-epoch=1900

Option arguments should be in italic.

>  and is used to specify the most common epoch on Alphas
> -with SRM console.
> +with an SRM console.
>  .
>  .SH NOTES
>  .
> @@ -556,11 +555,11 @@ file, as explained in the man page for
>  However, some programs and fringe parts of the Linux kernel such as filesystems
>  use the kernel's timezone value.  An example is the vfat filesystem.  If the
>  kernel timezone value is wrong, the vfat filesystem will report and set the
> -wrong timestamps on files. Another example is the kernel's NTP \%'11\ minute\ mode.'
> +wrong timestamps on files.  Another example is the kernel's NTP \%'11\ minute\ mode'.
>  If the kernel's timezone value and/or the
>  .I \%persistent_clock_is_local
>  variable are wrong, then the Hardware Clock will be set incorrectly
> -by \%'11\ minute\ mode.'  See the discussion below, under
> +by \%'11\ minute\ mode'.  See the discussion below, under
>  .BR "Automatic Hardware Clock Synchronization by the Kernel" .
>  .PP
>  .B \%hwclock
> @@ -588,7 +587,7 @@ compatible system, there is probably no need for users to have the direct
>  ISA I/O method, so do not bother.  See the
>  .BR \-\-rtc " option."
>  .PP
> -In any case, hwclock will not allow you to set anything unless you have the
> +In any case, \fBhwclock\fR will not allow you to set anything unless you have the

I'd prefer macros.

>  superuser real uid.  (This restriction is not necessary if you haven't
>  installed setuid root, but it's there for now.)
>  .
> @@ -781,7 +780,7 @@ Hardware Clock timescale configuration is changed, then a reboot is required to
>  notify the kernel.
>  .PP
>  .B \%hwclock\ \-\-adjust
> -should not be used with NTP \%'11\ minute\ mode.'
> +should not be used with NTP \%'11\ minute\ mode'.
>  .
>  .SS ISA Hardware Clock Century value
>  .PP
> @@ -809,15 +808,15 @@ are supported by the hardware.
>  .PP
>  This discussion is based on the following conditions:
>  .IP \(bu 2
> -Nothing is running that alters the date-time clocks, e.g.,
> -.BR \%ntpd "(1), cron jobs, et al."
> +Nothing is running that alters the date-time clocks, as for example
> +.BR \%ntpd "(1) or a cron job."

s/as for example/for example/

http://www.merriam-webster.com/dictionary/e.g.

>  .IP \(bu 2
> -The system timezone is configured for the correct local time.  See below
> +The system timezone is configured for the correct local time.  See below, under
>  .BR "POSIX vs 'RIGHT'" .
>  .IP \(bu 2
> -Early in startup the following are called in this order:
> +Early during startup the following are called, in this order:
>  .br
> -.BI \%adjtimex\ \-\-tick \ <value>\  \-\-frequency \ <value>
> +.BI \%adjtimex\ \-\-tick \ value\  \-\-frequency \ value

How does the reader know they do not literally enter 'value'?

>  .br
>  .B \%hwclock\ \-\-hctosys
>  .IP \(bu 2
> @@ -842,8 +841,7 @@ different for each of them.  However, most systems are configured to
>  exchange values between these two clocks at startup and shutdown.  Now
>  the individual device's time keeping errors are transferred back and
>  forth between each other.  Attempt to configure drift correction for only
> -one of them, and the other's drift will be overlaid upon it.  If the big
> -picture is not kept in mind, confusion will soon ensue.
> +one of them, and the other's drift will be overlaid upon it.

This is true and valuable information. I know from experience.

>  .PP
>  This problem can be avoided when configuring drift correction for the
>  System Clock by simply not shutting down the machine.  This, plus the
> @@ -855,11 +853,11 @@ should be done first.
>  .PP
>  The System Clock drift is corrected with the
>  .BR \%adjtimex "(8) command's " \-\-tick " and " \%\-\-frequency
> -options.  These two work together, tick is the course adjustment and
> -frequency is the fine adjustment. (For system that do not have an
> +options.  These two work together; tick is the coarse adjustment and
> +frequency is the fine adjustment.  (For systems that do not have an

Improper use of a semicolon, "These two work together" is incomplete.

>  .BR \%adjtimex " package,"
> -.BI \%ntptime\ \-f\  <ppm>
> -may be use instead.)
> +.BI \%ntptime\ \-f\  ppm
> +may be used instead.)

How does the reader know they do not literally enter 'ppm'?

>  .PP
>  Some Linux distributions attempt to automatically calculate the System
>  Clock drift with
> @@ -887,27 +885,27 @@ Once the System Clock is ticking smoothly, move on to the Hardware Clock.
>  .PP
>  As a rule, cold drift will work best for most use cases.  This should be
>  true even for 24/7 machines whose normal downtime consists of a reboot.
> -In that case the drift factor value makes little difference, but on the
> -rare occasion that the machine is shutdown for an extended period then
> +In that case the drift factor value makes little difference.  But on the
> +rare occasion that the machine is shut down for an extended period, then
>  cold drift should yield better results.
>  .PP
>  .B Steps to calculate cold drift:
>  .IP 1 2
> -.RB "Confirm that " ntpd "(1) will not be launched at startup."
> +.RB "Ensure that " ntpd "(1) will not be launched at startup."

They were instructed at the beginning of the section to do this. There
is nothing wrong with 'confirm'. Changes for the sake of changes.

>  .IP 2 2
>  .RI The " System Clock " "time must be correct at shutdown!"
>  .IP 3 2
> -Shutdown the system.
> +Shut down the system.

This is wrong.

http://www.merriam-webster.com/dictionary/shutdown
http://www.merriam-webster.com/dictionary/shut%20down


>  .IP 4 2
>  Let an extended period pass without changing the Hardware Clock.
>  .IP 5 2
>  Start the system.
>  .IP 6 2
> -.RB "Immediately use " hwclock " to set the correct time with the"
> +.RB "Immediately use " hwclock " to set the correct time, adding the"
>  .BR \%\-\-update\-drift " option."
>  .PP
> -Note: if step six uses
> -.RB \%\-\-systohc ,
> +Note: if step 6 uses
> +.BR \%\-\-systohc ,
>  then the System Clock must be set correctly (step 6a) just before doing so.
>  .PP
>  .RB "Having " hwclock
> 

Re: [PATCH 2/3] hwclock: remove unneeded stuff from the man-page header

[J William Piggott]

First, you have no right to assign my name to anything, let alone a
legal notice.

Second, we've already been through this. The decision was left to Karel
and he accepted it as is. There is nothing wrong with a man-page having
some top comments.

On 03/17/2015 04:34 PM, Benno Schulenberg wrote:
> Signed-off-by: Benno Schulenberg <bensberg@justemail.net>
> ---
>  sys-utils/hwclock.8.in |   21 +++------------------
>  1 files changed, 3 insertions(+), 18 deletions(-)
> 
> diff --git a/sys-utils/hwclock.8.in b/sys-utils/hwclock.8.in
> index 9682244..145e089 100644
> --- a/sys-utils/hwclock.8.in
> +++ b/sys-utils/hwclock.8.in
> @@ -1,24 +1,9 @@
>  .\" hwclock.8.in -- man page for util-linux' hwclock
>  .\"
> -.\" 2015-01-07 J William Piggott
> -.\" Authored new section: DATE-TIME CONFIGURATION.
> -.\" Subsections: Keeping Time..., LOCAL vs UTC, POSIX vs 'RIGHT'.
> -.\" Errata and drop outdated language.
> -.\" Updates for v2.26
> -.\"
> -.\"
> -.\" -------------------------------
> -.\" Included for troff portability.
> -.\" Continuation line for .TP header.
> -.de TQ
> -.  br
> -.  ns
> -.  TP \\$1\" no doublequotes around argument!
> -..
> -.
> -.\" -------------------------------
> +.\" Copyright 1996 Bryan Henderson <bryanh@giraffe-data.com>
> +.\" Copyright 2015 J. William Piggott <elseifthen@gmx.com>
>  .
> -.TH HWCLOCK 8 "January 2015" "util-linux" "System Administration"
> +.TH HWCLOCK 8 "March 2015" "util-linux" "System Administration"
>  .SH NAME
>  hwclock \- read or set the hardware clock (RTC)
>  .SH SYNOPSIS
> 

Re: [PATCH 2/3] hwclock: remove unneeded stuff from the man-page header

[Karel Zak]

On Tue, Mar 17, 2015 at 08:35:02PM -0400, J William Piggott wrote: 
> First, you have no right to assign my name to anything, let alone a
> legal notice.

This is valid point, but it would be also nice if you guys will be able
to keep our discussions in friendly climate. This is not lkml, right? ;-)

> Second, we've already been through this. The decision was left to Karel
> and he accepted it as is. There is nothing wrong with a man-page having
> some top comments.

Well, I miss the header. It's fine (and it's recommended) to add your
copyright to header. I personally prefer git to record history than
use file header for this purpose, but I have no strong opinion for
this. More important is to have nice man pages with usable content.

Note that in code I sometimes add my name and date to the comment
before some important code block. Maybe you can use the same in man
pages.  For example add a comment before man page section rather than
use man page header for this purpose.

    Karel

-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com

Re: [PATCH 3/3] hwclock: fix spelling, punctuation and formatting mistakes in the man page

[Benno Schulenberg]

On Wed, Mar 18, 2015, at 01:29, J William Piggott wrote:
> On 03/17/2015 04:34 PM, Benno Schulenberg wrote:
> >  Since v2.26 important changes were made to the
> >  .B \-\-hctosys
> > -function, the
> > +function and the
> >  .B \-\-directisa
> >  option, and a new option
> >  .B \-\-update\-drift
> > -was added. See their respective sections below.
> > +was added.  See their respective descriptions below.
> 
> What guide says this is the proper style for an inline list?

Pfff...  It's better.  The two commas seem to suggest that
also changes were made to the third item, --update-drift,
but three words into that phrase that appears not to be
the case.  So... keep the two things that were changed
together, and mention the addition in a second phrase.

> > -The set function requires using the
> > +The \fB\%\-\-setepoch\fR function requires using the
> >  .B \%\-\-epoch
> > -option.
> > +option to specify the year.
> 
> This is completely unnecessary verbosity.

No.  It took me three readings to get that with "set"
--setepoch was meant.

> > -.BI "\%hwclock\ \-\-set\ \-\-date='" 2011-08-14\ 16:45:05 '
> > +.B "hwclock\ \-\-set\ \-\-date='2011-08-14\ 16:45:05'
> 
> It is common practice for option arguments to be in italic.

No.  They are in italics when they are fill-in arguments: something
has to be filled in instead of the word in italics.  When giving actual,
literal values, they are in bold.

> I've already
> explained to you that the soft hyphen prevents this command structure
> from wrapping on narrow windows when multitasking.

The word is at the start of a line here -- there is no need to
prevent wrapping.

> > -.BI \%\-\-epoch= 1980
> > +.B \%\-\-epoch=1980
> 
> Option arguments should be in italic.

No.  Why the repetition?  Once is enough.

> > -the Hardware Clock to detect a time transition.  "Toy" in the option
>> +the Hardware Clock to detect a time transition.  The "toy" in the option
> 
> What style guide is this from?

Again, it's better.

> > -.BI \%adjtimex\ \-\-tick \ <value>\  \-\-frequency \ <value>
> > +.BI \%adjtimex\ \-\-tick \ value\  \-\-frequency \ value
> 
> How does the reader know they do not literally enter 'value'?

Because it's in italics.  (The angular brackets are a convention
of usage texts.)

> >  Attempt to configure drift correction for only
> > -one of them, and the other's drift will be overlaid upon it.  If the big
> > -picture is not kept in mind, confusion will soon ensue.
> > +one of them, and the other's drift will be overlaid upon it.
> 
> This is true and valuable information. I know from experience.

The sentence was removed because it's repetitious, but mainly
so that it's clear what "This problem" below refers to -- not to
losing the big picture, but to the other drift getting overlaid.

> >  The System Clock drift is corrected with the
> >  .BR \%adjtimex "(8) command's " \-\-tick " and " \%\-\-frequency
> > -options.  These two work together, tick is the course adjustment and
> > -frequency is the fine adjustment. (For system that do not have an
> > +options.  These two work together; tick is the coarse adjustment and
> > +frequency is the fine adjustment.  (For systems that do not have an
> 
> Improper use of a semicolon, "These two work together" is incomplete.

Aaah, but no nice word about the spell correction from "course" to "coarse".

:)

Anyway, a comma wasn't right either.  Better make it a colon then.

> > -.RB "Confirm that " ntpd "(1) will not be launched at startup."
> > +.RB "Ensure that " ntpd "(1) will not be launched at startup."
> 
> They were instructed at the beginning of the section to do this. There
> is nothing wrong with 'confirm'.

Okay, I forgot about that, the explanations being so long...

> > -Shutdown the system.
> > +Shut down the system.
> 
> This is wrong.

No, it isn't: "shutdown" is the noun, "shut down" the verb.

https://www.wordnik.com/words/shutdown
https://www.wordnik.com/words/shut%20down

> http://www.merriam-webster.com/dictionary/shutdown
> http://www.merriam-webster.com/dictionary/shut%20down

Benno

-- 
http://www.fastmail.com - Accessible with your email software
                          or over the web

[PATCH v2] hwclock: fix spelling, punctuation and formatting mistakes in the man page

[Benno Schulenberg]

Also improve some wordings.

Signed-off-by: Benno Schulenberg <bensberg@justemail.net>
---
 sys-utils/hwclock.8.in |   78 +++++++++++++++++++++++------------------------
 1 files changed, 38 insertions(+), 40 deletions(-)

diff --git a/sys-utils/hwclock.8.in b/sys-utils/hwclock.8.in
index 145e089..affc5f5 100644
--- a/sys-utils/hwclock.8.in
+++ b/sys-utils/hwclock.8.in
@@ -23,16 +23,15 @@ Hardware Clock values based on its drift rate.
 .PP
 Since v2.26 important changes were made to the
 .B \-\-hctosys
-function, the
+function and the
 .B \-\-directisa
 option, and a new option
 .B \-\-update\-drift
-was added. See their respective sections below.
+was added.  See their respective descriptions below.
 .
 .SH FUNCTIONS
 The following functions are mutually exclusive, only one can be given at
-a time. If none are given the default is
-.BR \-\-show .
+a time.  If none is given, the default is \fB\-\-show\fR.
 .TP
 .B \-\-adjust
 Add or subtract time from the Hardware Clock to account for systematic
@@ -59,9 +58,9 @@ that the year counter in your Hardware Clock contains the number of
 full years since 1952, then the kernel's Hardware Clock epoch value
 must be 1952.
 .sp
-The set function requires using the
+The \fB\%\-\-setepoch\fR function requires using the
 .B \%\-\-epoch
-option.
+option to specify the year.
 .sp
 This epoch value is used whenever
 .B \%hwclock
@@ -123,7 +122,7 @@ function does this based upon the information in the
 .I @ADJTIME_PATH@
 file or the command line arguments
 .BR \%\-\-localtime " and " \-\-utc .
-Note: no daylight saving adjustment is made. See the discussion below under
+Note: no daylight saving adjustment is made.  See the discussion below, under
 .BR "LOCAL vs UTC" .
 .sp
 The kernel also keeps a timezone value, the
@@ -153,7 +152,7 @@ This is a good function to use in one of the system startup scripts before the
 file systems are mounted read/write.
 .sp
 This function should never be used on a running system. Jumping system time
-will cause problems, such as, corrupted filesystem timestamps.  Also, if
+will cause problems, such as corrupted filesystem timestamps.  Also, if
 something has changed the Hardware Clock, like NTP's \%'11\ minute\ mode', then
 .B \%\-\-hctosys
 will set the time incorrectly by including drift compensation.
@@ -230,9 +229,9 @@ changed then a reboot would be required to inform the kernel.
 .BR \-w , \ \-\-systohc
 Set the Hardware Clock from the System Clock, and update the timestamps in
 .IR @ADJTIME_PATH@ .
-With the
+When the
 .B --update-drift
-option (re)calculate the drift factor.
+option is given, then also (re)calculate the drift factor.
 .
 .TP
 .BR \-V , \ \-\-version
@@ -298,7 +297,7 @@ The value of this option is used as an argument to the
 option.  For example:
 .RS
 .IP "" 4
-.BI "\%hwclock\ \-\-set\ \-\-date='" 2011-08-14\ 16:45:05 '
+.B "hwclock\ \-\-set\ \-\-date='2011-08-14\ 16:45:05'
 .PP
 The argument must be in local time, even if you keep your Hardware Clock in
 UTC.  See the
@@ -381,7 +380,7 @@ as recorded in
 will be used.  If the adjtime file doesn't exist, the default is UTC.
 .sp
 Note: daylight saving time changes may be inconsistent when the
-Hardware Clock is kept in local time. See the discussion below under
+Hardware Clock is kept in local time.  See the discussion below, under
 .BR "LOCAL vs UTC" .
 .
 .TP
@@ -447,9 +446,9 @@ option to be used.  See the discussion below, under
 .TP
 .B \-\-arc
 This option is equivalent to
-.BI \%\-\-epoch= 1980
+.B \%\-\-epoch=1980
 and is used to specify the most common epoch on Alphas
-with ARC console (but Ruffians have an epoch of 1900).
+with an ARC console (although Ruffians have an epoch of 1900).
 .
 .TP
 .BI \-\-epoch= year
@@ -462,7 +461,7 @@ option to set the kernel's idea of the epoch of the Hardware Clock.
 For example, on a Digital Unix machine:
 .RS
 .IP "" 4
-.BI hwclock\ \-\-setepoch\ \-\-epoch= 1952
+.B hwclock\ \-\-setepoch\ \-\-epoch=1952
 .RE
 .
 .TP
@@ -481,15 +480,15 @@ is mounted.
 option is used for Jensen models;
 .B \%\-\-funky\-toy
 means that the machine requires the UF bit instead of the UIP bit in
-the Hardware Clock to detect a time transition.  "Toy" in the option
+the Hardware Clock to detect a time transition.  The "toy" in the option
 name refers to the Time Of Year facility of the machine.
 .
 .TP
 .B \-\-srm
 This option is equivalent to
-.BI \%\-\-epoch= 1900
+.B \%\-\-epoch=1900
 and is used to specify the most common epoch on Alphas
-with SRM console.
+with an SRM console.
 .
 .SH NOTES
 .
@@ -556,11 +555,11 @@ file, as explained in the man page for
 However, some programs and fringe parts of the Linux kernel such as filesystems
 use the kernel's timezone value.  An example is the vfat filesystem.  If the
 kernel timezone value is wrong, the vfat filesystem will report and set the
-wrong timestamps on files. Another example is the kernel's NTP \%'11\ minute\ mode.'
+wrong timestamps on files.  Another example is the kernel's NTP \%'11\ minute\ mode'.
 If the kernel's timezone value and/or the
 .I \%persistent_clock_is_local
 variable are wrong, then the Hardware Clock will be set incorrectly
-by \%'11\ minute\ mode.'  See the discussion below, under
+by \%'11\ minute\ mode'.  See the discussion below, under
 .BR "Automatic Hardware Clock Synchronization by the Kernel" .
 .PP
 .B \%hwclock
@@ -588,7 +587,7 @@ compatible system, there is probably no need for users to have the direct
 ISA I/O method, so do not bother.  See the
 .BR \-\-rtc " option."
 .PP
-In any case, hwclock will not allow you to set anything unless you have the
+In any case, \fBhwclock\fR will not allow you to set anything unless you have the
 superuser real uid.  (This restriction is not necessary if you haven't
 installed setuid root, but it's there for now.)
 .
@@ -781,7 +780,7 @@ Hardware Clock timescale configuration is changed, then a reboot is required to
 notify the kernel.
 .PP
 .B \%hwclock\ \-\-adjust
-should not be used with NTP \%'11\ minute\ mode.'
+should not be used with NTP \%'11\ minute\ mode'.
 .
 .SS ISA Hardware Clock Century value
 .PP
@@ -809,15 +808,15 @@ are supported by the hardware.
 .PP
 This discussion is based on the following conditions:
 .IP \(bu 2
-Nothing is running that alters the date-time clocks, e.g.,
-.BR \%ntpd "(1), cron jobs, et al."
+Nothing is running that alters the date-time clocks, such as
+.BR \%ntpd "(1) or a cron job."
 .IP \(bu 2
-The system timezone is configured for the correct local time.  See below
+The system timezone is configured for the correct local time.  See below, under
 .BR "POSIX vs 'RIGHT'" .
 .IP \(bu 2
-Early in startup the following are called in this order:
+Early during startup the following are called, in this order:
 .br
-.BI \%adjtimex\ \-\-tick \ <value>\  \-\-frequency \ <value>
+.BI \%adjtimex\ \-\-tick \ value\  \-\-frequency \ value
 .br
 .B \%hwclock\ \-\-hctosys
 .IP \(bu 2
@@ -842,8 +841,7 @@ different for each of them.  However, most systems are configured to
 exchange values between these two clocks at startup and shutdown.  Now
 the individual device's time keeping errors are transferred back and
 forth between each other.  Attempt to configure drift correction for only
-one of them, and the other's drift will be overlaid upon it.  If the big
-picture is not kept in mind, confusion will soon ensue.
+one of them, and the other's drift will be overlaid upon it.
 .PP
 This problem can be avoided when configuring drift correction for the
 System Clock by simply not shutting down the machine.  This, plus the
@@ -855,11 +853,11 @@ should be done first.
 .PP
 The System Clock drift is corrected with the
 .BR \%adjtimex "(8) command's " \-\-tick " and " \%\-\-frequency
-options.  These two work together, tick is the course adjustment and
-frequency is the fine adjustment. (For system that do not have an
+options.  These two work together: tick is the coarse adjustment and
+frequency is the fine adjustment.  (For systems that do not have an
 .BR \%adjtimex " package,"
-.BI \%ntptime\ \-f\  <ppm>
-may be use instead.)
+.BI \%ntptime\ \-f\  ppm
+may be used instead.)
 .PP
 Some Linux distributions attempt to automatically calculate the System
 Clock drift with
@@ -887,27 +885,27 @@ Once the System Clock is ticking smoothly, move on to the Hardware Clock.
 .PP
 As a rule, cold drift will work best for most use cases.  This should be
 true even for 24/7 machines whose normal downtime consists of a reboot.
-In that case the drift factor value makes little difference, but on the
-rare occasion that the machine is shutdown for an extended period then
+In that case the drift factor value makes little difference.  But on the
+rare occasion that the machine is shut down for an extended period, then
 cold drift should yield better results.
 .PP
 .B Steps to calculate cold drift:
 .IP 1 2
-.RB "Confirm that " ntpd "(1) will not be launched at startup."
+.RB "Ensure that " ntpd "(1) will not be launched at startup."
 .IP 2 2
 .RI The " System Clock " "time must be correct at shutdown!"
 .IP 3 2
-Shutdown the system.
+Shut down the system.
 .IP 4 2
 Let an extended period pass without changing the Hardware Clock.
 .IP 5 2
 Start the system.
 .IP 6 2
-.RB "Immediately use " hwclock " to set the correct time with the"
+.RB "Immediately use " hwclock " to set the correct time, adding the"
 .BR \%\-\-update\-drift " option."
 .PP
-Note: if step six uses
-.RB \%\-\-systohc ,
+Note: if step 6 uses
+.BR \%\-\-systohc ,
 then the System Clock must be set correctly (step 6a) just before doing so.
 .PP
 .RB "Having " hwclock
-- 
1.7.0.4

Re: [PATCH v2] hwclock: fix spelling, punctuation and formatting mistakes in the man page

[Benno Schulenberg]

On Wed, Apr 8, 2015, at 10:22, Benno Schulenberg wrote:
>  sys-utils/hwclock.8.in |   78 +++++++++++++++++++++++------------------------
>  1 files changed, 38 insertions(+), 40 deletions(-)

Ping?


-- 
http://www.fastmail.com - mmm... Fastmail...

Re: [PATCH 2/3] hwclock: remove unneeded stuff from the man-page header

[Karel Zak]

On Tue, Mar 17, 2015 at 09:34:52PM +0100, Benno Schulenberg wrote:
> -.\" -------------------------------
> -.\" Included for troff portability.
> -.\" Continuation line for .TP header.
> -.de TQ
> -.  br
> -.  ns
> -.  TP \\$1\" no doublequotes around argument!
> -..

I have little bit clean upped the man header and removed the TQ
fallback. We already use TQ on another places for years and nobody
complains, so I guess it's unnecessary (or we have to fix all the man
page rather than hwclock.8 only).

-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com

Re: [PATCH v2] hwclock: fix spelling, punctuation and formatting mistakes in the man page

[Karel Zak]

On Wed, Apr 08, 2015 at 10:22:43AM +0200, Benno Schulenberg wrote:
> Also improve some wordings.
> 
> Signed-off-by: Benno Schulenberg <bensberg@justemail.net>
> ---
>  sys-utils/hwclock.8.in |   78 +++++++++++++++++++++++------------------------
>  1 files changed, 38 insertions(+), 40 deletions(-)

 Applied, thanks. Note that we use the same manners (e.g. \fB for
 options and \fI for arguments, etc) in another man pages.

    Karel

-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com