* [PATCH 2/4] docs: fix some wording and formatting in man page of swapon
2014-10-27 21:18 [PATCH 1/4] docs: spelling, wording, and grammar fixes in the man page of whereis Benno Schulenberg
@ 2014-10-27 21:18 ` Benno Schulenberg
2014-10-31 9:48 ` Karel Zak
2014-10-27 21:18 ` [PATCH 3/4] textual: slice up the usage text of swapon for ease of translation Benno Schulenberg
` (2 subsequent siblings)
3 siblings, 1 reply; 18+ messages in thread
From: Benno Schulenberg @ 2014-10-27 21:18 UTC (permalink / raw)
To: util-linux
Signed-off-by: Benno Schulenberg <bensberg@justemail.net>
---
sys-utils/swapon.8 | 17 +++++++++--------
1 files changed, 9 insertions(+), 8 deletions(-)
diff --git a/sys-utils/swapon.8 b/sys-utils/swapon.8
index e88e2f1..2aa6fe2 100644
--- a/sys-utils/swapon.8
+++ b/sys-utils/swapon.8
@@ -38,7 +38,7 @@
.\" Mon Sep 25 14:12:38 1995: Added -v and -p information
.\" Tue Apr 30 03:32:07 1996: Added some text from A. Koppenhoefer
.\"
-.TH SWAPON 8 "July 2014" "util-linux" "System Administration"
+.TH SWAPON 8 "October 2014" "util-linux" "System Administration"
.SH NAME
swapon, swapoff \- enable/disable devices and files for paging and swapping
.SH SYNOPSIS
@@ -131,14 +131,15 @@ Use the partition that has the specified
is needed.)
.TP
.BR \-o , " \-\-options " \fIopts\fP
-Specify swap options by fstab compatible comma separated string. For example:
+Specify swap options by an fstab-compatible comma-separated string.
+For example:
.RS
.RS
.sp
.B "swapon -o pri=1,discard=pages,nofail /dev/sda2"
.sp
.RE
-The \fIopts\fP string is evaluated as the last and overrides all another
+The \fIopts\fP string is evaluated last and overrides all other
options.
.RE
.TP
@@ -154,15 +155,15 @@ to the option field of
.I /etc/fstab
for use with
.BR "swapon -a" .
-When priority is not defined it defaults to \-1.
+When no priority is defined, it defaults to \-1.
.TP
.BR \-s , " \-\-summary"
Display swap usage summary by device. Equivalent to "cat /proc/swaps".
Not available before Linux 2.1.25. This output format is DEPRECATED in favour
of \fB\-\-show\fR that provides better control on output data.
.TP
-.BR " \-\-show" [ =\fIcolumn\fR]
-Display definable table of swap areas. See
+.BR \-\-show [ =\fIcolumn\fR ...]
+Display a definable table of swap areas. See the
.B \-\-help
output for a list of available columns.
.TP
@@ -185,10 +186,10 @@ output instead of in user-friendly units.
Use the partition that has the specified
.IR uuid .
.TP
-.B "\-v, \-\-verbose"
+.BR \-v , " \-\-verbose"
Be verbose.
.TP
-.B "\-V, \-\-version"
+.BR \-V , " \-\-version"
Display version information and exit.
.SH NOTES
You should not use
--
1.7.0.4
^ permalink raw reply related [flat|nested] 18+ messages in thread* [PATCH 3/4] textual: slice up the usage text of swapon for ease of translation
2014-10-27 21:18 [PATCH 1/4] docs: spelling, wording, and grammar fixes in the man page of whereis Benno Schulenberg
2014-10-27 21:18 ` [PATCH 2/4] docs: fix some wording and formatting in man page of swapon Benno Schulenberg
@ 2014-10-27 21:18 ` Benno Schulenberg
2014-10-27 21:24 ` Benno Schulenberg
2014-10-31 9:48 ` Karel Zak
2014-10-27 21:18 ` [PATCH 4/4] docs: improve wording and formattin of man page of hwclock Benno Schulenberg
2014-10-31 9:47 ` [PATCH 1/4] docs: spelling, wording, and grammar fixes in the man page of whereis Karel Zak
3 siblings, 2 replies; 18+ messages in thread
From: Benno Schulenberg @ 2014-10-27 21:18 UTC (permalink / raw)
To: util-linux
A new option was added recently; seize this opportunity to cut the
usage text into small and easily managed chunks.
Signed-off-by: Benno Schulenberg <bensberg@justemail.net>
---
sys-utils/swapon.c | 24 ++++++++++++------------
1 files changed, 12 insertions(+), 12 deletions(-)
diff --git a/sys-utils/swapon.c b/sys-utils/swapon.c
index 8609ea2..f66461e 100644
--- a/sys-utils/swapon.c
+++ b/sys-utils/swapon.c
@@ -728,18 +728,18 @@ static void __attribute__ ((__noreturn__)) usage(FILE * out)
fprintf(out, _(" %s [options] [<spec>]\n"), program_invocation_short_name);
fputs(USAGE_OPTIONS, out);
- fputs(_(" -a, --all enable all swaps from /etc/fstab\n"
- " -d, --discard[=<policy>] enable swap discards, if supported by device\n"
- " -e, --ifexists silently skip devices that do not exist\n"
- " -f, --fixpgsz reinitialize the swap space if necessary\n"
- " -o, --options <list> comma-separated list of swap options\n"
- " -p, --priority <prio> specify the priority of the swap device\n"
- " -s, --summary display summary about used swap devices (DEPRECATED)\n"
- " --show[=<columns>] display summary in definable table\n"
- " --noheadings don't print headings, use with --show\n"
- " --raw use the raw output format, use with --show\n"
- " --bytes display swap size in bytes in --show output\n"
- " -v, --verbose verbose mode\n"), out);
+ fputs(_(" -a, --all enable all swaps from /etc/fstab\n"), out);
+ fputs(_(" -d, --discard[=<policy>] enable swap discards, if supported by device\n"), out);
+ fputs(_(" -e, --ifexists silently skip devices that do not exist\n"), out);
+ fputs(_(" -f, --fixpgsz reinitialize the swap space if necessary\n"), out);
+ fputs(_(" -o, --options <list> comma-separated list of swap options\n"), out);
+ fputs(_(" -p, --priority <prio> specify the priority of the swap device\n"), out);
+ fputs(_(" -s, --summary display summary about used swap devices (DEPRECATED)\n"), out);
+ fputs(_(" --show[=<columns>] display summary in definable table\n"), out);
+ fputs(_(" --noheadings don't print table heading (with --show)\n"), out);
+ fputs(_(" --raw use the raw output format (with --show)\n"), out);
+ fputs(_(" --bytes display swap size in bytes in --show output\n"), out);
+ fputs(_(" -v, --verbose verbose mode\n"), out);
fputs(USAGE_SEPARATOR, out);
fputs(USAGE_HELP, out);
--
1.7.0.4
^ permalink raw reply related [flat|nested] 18+ messages in thread* Re: [PATCH 3/4] textual: slice up the usage text of swapon for ease of translation
2014-10-27 21:18 ` [PATCH 3/4] textual: slice up the usage text of swapon for ease of translation Benno Schulenberg
@ 2014-10-27 21:24 ` Benno Schulenberg
2014-10-31 9:32 ` Karel Zak
2014-10-31 9:48 ` Karel Zak
1 sibling, 1 reply; 18+ messages in thread
From: Benno Schulenberg @ 2014-10-27 21:24 UTC (permalink / raw)
To: Util-Linux
On Mon, Oct 27, 2014, at 22:18, Benno Schulenberg wrote:
> + fputs(_(" -v, --verbose verbose mode\n"), out);
>
> fputs(USAGE_SEPARATOR, out);
> fputs(USAGE_HELP, out);
A bit further down in the usage text it says this:
fputs(_("\nAvailable discard policy types (for --discard):\n"
" once : only single-time area discards are issued. (swapon)\n"
" pages : discard freed pages before they are reused.\n"
" * if no policy is selected both discard types are enabled. (default)\n"), out);
Why is this "(swapon)" there? What does it mean?
Benno
--
http://www.fastmail.fm - The professional email service
^ permalink raw reply [flat|nested] 18+ messages in thread* Re: [PATCH 3/4] textual: slice up the usage text of swapon for ease of translation
2014-10-27 21:24 ` Benno Schulenberg
@ 2014-10-31 9:32 ` Karel Zak
0 siblings, 0 replies; 18+ messages in thread
From: Karel Zak @ 2014-10-31 9:32 UTC (permalink / raw)
To: Benno Schulenberg; +Cc: Util-Linux
On Mon, Oct 27, 2014 at 10:24:35PM +0100, Benno Schulenberg wrote:
>
> On Mon, Oct 27, 2014, at 22:18, Benno Schulenberg wrote:
> > + fputs(_(" -v, --verbose verbose mode\n"), out);
> >
> > fputs(USAGE_SEPARATOR, out);
> > fputs(USAGE_HELP, out);
>
> A bit further down in the usage text it says this:
>
> fputs(_("\nAvailable discard policy types (for --discard):\n"
> " once : only single-time area discards are issued. (swapon)\n"
> " pages : discard freed pages before they are reused.\n"
> " * if no policy is selected both discard types are enabled. (default)\n"), out);
>
> Why is this "(swapon)" there? What does it mean?
Nothing, good catch, I'll remove it..
Karel
--
Karel Zak <kzak@redhat.com>
http://karelzak.blogspot.com
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH 3/4] textual: slice up the usage text of swapon for ease of translation
2014-10-27 21:18 ` [PATCH 3/4] textual: slice up the usage text of swapon for ease of translation Benno Schulenberg
2014-10-27 21:24 ` Benno Schulenberg
@ 2014-10-31 9:48 ` Karel Zak
1 sibling, 0 replies; 18+ messages in thread
From: Karel Zak @ 2014-10-31 9:48 UTC (permalink / raw)
To: Benno Schulenberg; +Cc: util-linux
On Mon, Oct 27, 2014 at 10:18:12PM +0100, Benno Schulenberg wrote:
> sys-utils/swapon.c | 24 ++++++++++++------------
> 1 files changed, 12 insertions(+), 12 deletions(-)
Applied, thanks.
--
Karel Zak <kzak@redhat.com>
http://karelzak.blogspot.com
^ permalink raw reply [flat|nested] 18+ messages in thread
* [PATCH 4/4] docs: improve wording and formattin of man page of hwclock
2014-10-27 21:18 [PATCH 1/4] docs: spelling, wording, and grammar fixes in the man page of whereis Benno Schulenberg
2014-10-27 21:18 ` [PATCH 2/4] docs: fix some wording and formatting in man page of swapon Benno Schulenberg
2014-10-27 21:18 ` [PATCH 3/4] textual: slice up the usage text of swapon for ease of translation Benno Schulenberg
@ 2014-10-27 21:18 ` Benno Schulenberg
2014-10-28 1:09 ` JWP
2014-10-31 9:47 ` [PATCH 1/4] docs: spelling, wording, and grammar fixes in the man page of whereis Karel Zak
3 siblings, 1 reply; 18+ messages in thread
From: Benno Schulenberg @ 2014-10-27 21:18 UTC (permalink / raw)
To: util-linux
Signed-off-by: Benno Schulenberg <bensberg@justemail.net>
---
sys-utils/hwclock.8.in | 73 +++++++++++++++++++++++-------------------------
1 files changed, 35 insertions(+), 38 deletions(-)
diff --git a/sys-utils/hwclock.8.in b/sys-utils/hwclock.8.in
index 30f191b..9219218 100644
--- a/sys-utils/hwclock.8.in
+++ b/sys-utils/hwclock.8.in
@@ -1,4 +1,4 @@
-.TH HWCLOCK 8 "July 2014" "util-linux" "System Administration"
+.TH HWCLOCK 8 "October 2014" "util-linux" "System Administration"
.SH NAME
hwclock \- query or set the hardware clock (RTC)
.SH SYNOPSIS
@@ -22,15 +22,16 @@ gains time at a certain rate when left to run).
Since v2.26
.B hwclock
does not update the Hardware Clock's drift factor in @ADJTIME_PATH@ by default.
-It is necessary to use \fB\-\-update-drift\fR, with \fB\-\-set\fR or
+It is necessary to use the option \fB\-\-update-drift\fR, with \fB\-\-set\fR or
\fB\-\-systohc\fR, to force drift factor updates.
Since v2.26
.B hwclock \-\-hctosys
-automatically compensates time read from the Hardware Clock to account for
-systematic drift before using it to set the System Clock. Therefore,
-\fB\-\-adjust\fR is no longer necessary during boot. This functionality makes
-hwclock usable early in the boot process when the root filesystem is read-only.
+automatically takes a systematic drift of the Hardware Clock into account,
+setting the System Clock to the drift-compensated time. Therefore the option
+\fB\-\-adjust\fR is no longer necessary during boot. This feature makes
+.B hwclock
+usable early on in the boot process when the root filesystem is read-only.
.SH FUNCTIONS
You need exactly one of the following options to tell
@@ -101,9 +102,8 @@ When used in a startup script, making it the first caller of
.BR settimeofday (2)
from boot, it will set the NTP 11 minute mode time scale via the
.I persistent_clock_is_local
-kernel variable. See the discussion below, under
-.B Automatic Hardware Clock Synchronization by the
-.BR Kernel.
+kernel variable. See the discussion below, under
+.BR "Automatic Hardware Clock Synchronization by the Kernel" .
.sp
This is a good option to use in one of the system startup scripts.
.sp
@@ -358,15 +358,13 @@ else. This is useful, especially in conjunction with
in learning about the internal operations of hwclock.
.TP
-.B \-\-update\-drift
+.B \-\-update-drift
Update the Hardware Clock's drift factor in
.IR @ADJTIME_PATH@ .
It is used with
.BR --set\ or \ --systohc ,
otherwise it is ignored.
-See the discussion below, under
-.B The Adjust
-.BR Function.
+See the discussion below, under \fBThe Adjust Function\fR.
.TP
.BR \-u , \ \-\-utc
@@ -442,8 +440,7 @@ 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
-.B Automatic Hardware Clock Synchronization by the
-.BR Kernel.
+.BR "Automatic Hardware Clock Synchronization by the Kernel" .
.PP
.B hwclock
sets the kernel timezone to the value indicated by TZ and/or
@@ -551,35 +548,35 @@ keeps a file,
that keeps some historical information. This is called the adjtime file.
.PP
Suppose you start with no adjtime file. You issue a
-.I hwclock \-\-set
+.B hwclock \-\-set
command to set the Hardware Clock to the true current time.
.B hwclock
creates the adjtime file and records in it the current time as the
last time the clock was calibrated.
-5 days later, the clock has gained 10 seconds, so you issue the
-.I hwclock \-\-set \-\-update\-drift
+Five days later, the clock has gained 10 seconds, so you issue a
+.B hwclock \-\-set \-\-update-drift
command to set it back 10 seconds.
.B hwclock
updates the adjtime file to show the current time as the last time the
clock was calibrated, and records 2 seconds per day as the systematic
drift rate. 24 hours go by, and then you issue a
-.I hwclock \-\-adjust
+.B hwclock \-\-adjust
command.
.B hwclock
consults the adjtime file and sees that the clock gains 2 seconds per
day when left alone and that it has been left alone for exactly one
day. So it subtracts 2 seconds from the Hardware Clock. It then
records the current time as the last time the clock was adjusted.
-Another 24 hours goes by and you issue another
-.IR "hwclock \-\-adjust" .
+Another 24 hours go by and you issue another
+.BR "hwclock \-\-adjust" .
.B hwclock
does the same thing: subtracts 2 seconds and updates the adjtime file
with the current time as the last time the clock was adjusted.
.PP
When you use the
-.I \-\-update\-drift
+.B \-\-update-drift
option with
-.IR \-\-set\ or \ \-\-systohc ,
+.BR \-\-set\ or \ \-\-systohc ,
the systematic drift rate is (re)calculated based on how long it has been
since the last calibration, how long it has been since the last
adjustment, what drift rate was assumed in any intervening
@@ -589,19 +586,19 @@ drift factor is then saved in
.PP
A small amount of error creeps in when
the Hardware Clock is set, so
-.I \-\-adjust
+.B \-\-adjust
refrains from making any adjustment that is less
than 1 second. Later on, when you request an adjustment again, the accumulated
drift will be more than 1 second and
-.I \-\-adjust
+.B \-\-adjust
will make the adjustment including any fractional amount.
.PP
-.IR "hwclock \-\-hctosys"
+.B hwclock \-\-hctosys
also uses the adjtime file data to compensate the value read from the Hardware
Clock before using it to set the System Time. It does not share the 1 second
-limitation of --adjust, and will correct sub-second drift values immediately.
+limitation of \fB--adjust\fR, and will correct sub-second drift values immediately.
It does not change the Hardware Clock time or the adjtime file. This may
-eliminate the need to use --adjust, unless something else on the system needs
+eliminate the need to use \fB--adjust\fR, unless something else on the system needs
the Hardware Clock to be compensated. The drift compensation can be inhibited
by using the
.B --noadjfile
@@ -613,14 +610,14 @@ in remembering information from one invocation to the next.
.PP
The format of the adjtime file is, in ASCII:
.PP
-Line 1: 3 numbers, separated by blanks: 1) systematic drift rate in
-seconds per day, floating point decimal; 2) Resulting number of
+Line 1: Three numbers, separated by blanks: 1) the systematic drift rate
+in seconds per day, floating point decimal; 2) the resulting number of
seconds since 1969 UTC of most recent adjustment or calibration,
decimal integer; 3) zero (for compatibility with
.BR clock (8))
as a decimal integer.
.PP
-Line 2: 1 number: Resulting number of seconds since 1969 UTC of most
+Line 2: One number: the resulting number of seconds since 1969 UTC of most
recent calibration. Zero if there has been no calibration yet or it
is known that any previous calibration is moot (for example, because
the Hardware Clock has been found, since that calibration, not to
@@ -650,28 +647,28 @@ network or to a radio clock hooked up to your system. See RFC 1305.)
This mode (we'll call it "11 minute mode") is off until something
turns it on. The ntp daemon ntpd is one thing that turns it on. You
can turn it off by running anything, including
-.IR "hwclock \-\-hctosys" ,
+.BR "hwclock \-\-hctosys" ,
that sets the System Time the old fashioned way. However, if the ntp daemon is
still running, it will turn 11 minute mode back on again the next time it
synchronizes the System Clock.
.PP
If your system runs with 11 minute mode on, it may need
-.I hwclock \-\-hctosys
+.B hwclock \-\-hctosys
in a startup script, especially if the Hardware Clock is configured to to use
the local timescale.
The first user space command to set the System Clock informs the
-kernel what timescale the Hardware Clock is using. This happens via the
+kernel what timescale the Hardware Clock is using. This happens via the
.I persistent_clock_is_local
-kernel variable. If
-.I hwclock \-\-hctosys
+kernel variable. If
+.B hwclock \-\-hctosys
is the first, it will set this variable according to the adjtime file or the
-appropriate command line argument. Note that when using this capability and the
+appropriate command-line argument. Note that when using this capability and the
Hardware Clock timescale configuration is changed, then a reboot is required to
notify the kernel.
Don't use
-.I hwclock \-\-adjust
+.B hwclock \-\-adjust
with 11 minute mode. You'll just make a mess.
.SS ISA Hardware Clock Century value
--
1.7.0.4
^ permalink raw reply related [flat|nested] 18+ messages in thread
* Re: [PATCH 4/4] docs: improve wording and formattin of man page of hwclock
2014-10-27 21:18 ` [PATCH 4/4] docs: improve wording and formattin of man page of hwclock Benno Schulenberg
@ 2014-10-28 1:09 ` JWP
2014-10-28 20:02 ` Benno Schulenberg
0 siblings, 1 reply; 18+ messages in thread
From: JWP @ 2014-10-28 1:09 UTC (permalink / raw)
To: Benno Schulenberg, util-linux
On 10/27/2014 05:18 PM, Benno Schulenberg wrote:
> Signed-off-by: Benno Schulenberg <bensberg@justemail.net>
> ---
> sys-utils/hwclock.8.in | 73 +++++++++++++++++++++++-------------------------
> 1 files changed, 35 insertions(+), 38 deletions(-)
>
> diff --git a/sys-utils/hwclock.8.in b/sys-utils/hwclock.8.in
> index 30f191b..9219218 100644
> --- a/sys-utils/hwclock.8.in
> +++ b/sys-utils/hwclock.8.in
> @@ -1,4 +1,4 @@
> -.TH HWCLOCK 8 "July 2014" "util-linux" "System Administration"
> +.TH HWCLOCK 8 "October 2014" "util-linux" "System Administration"
> .SH NAME
> hwclock \- query or set the hardware clock (RTC)
> .SH SYNOPSIS
> @@ -22,15 +22,16 @@ gains time at a certain rate when left to run).
> Since v2.26
> .B hwclock
> does not update the Hardware Clock's drift factor in @ADJTIME_PATH@ by default.
> -It is necessary to use \fB\-\-update-drift\fR, with \fB\-\-set\fR or
> +It is necessary to use the option \fB\-\-update-drift\fR, with \fB\-\-set\fR or
> \fB\-\-systohc\fR, to force drift factor updates.
The rest of the manual uses 'the --xxxx option'.
>
> Since v2.26
> .B hwclock \-\-hctosys
> -automatically compensates time read from the Hardware Clock to account for
> -systematic drift before using it to set the System Clock. Therefore,
> -\fB\-\-adjust\fR is no longer necessary during boot. This functionality makes
> -hwclock usable early in the boot process when the root filesystem is read-only.
> +automatically takes a systematic drift of the Hardware Clock into account,
> +setting the System Clock to the drift-compensated time. Therefore the option
> +\fB\-\-adjust\fR is no longer necessary during boot. This feature makes
> +.B hwclock
> +usable early on in the boot process when the root filesystem is read-only.
"a systematic drift"? That entire phrase does not sound natural to me.
You've re-injected the ambiguity of Karel's original sentence. Hwclock has always
compensated for drift by *setting* the Hardware Clock. I think it is important to
stress that *the_time_read* from the Clock is what is being compensated as this is
a new behavior. Other than setting hwclock to bold, I don't see any of this change
as an improvement.
Thank you for fixing the other formatting issues.
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH 4/4] docs: improve wording and formattin of man page of hwclock
2014-10-28 1:09 ` JWP
@ 2014-10-28 20:02 ` Benno Schulenberg
2014-10-31 9:51 ` Karel Zak
0 siblings, 1 reply; 18+ messages in thread
From: Benno Schulenberg @ 2014-10-28 20:02 UTC (permalink / raw)
To: JWP; +Cc: Util-Linux
On Tue, Oct 28, 2014, at 02:09, JWP wrote:
> On 10/27/2014 05:18 PM, Benno Schulenberg wrote:
> > Since v2.26
> > .B hwclock
> > does not update the Hardware Clock's drift factor in @ADJTIME_PATH@ by default.
> > -It is necessary to use \fB\-\-update-drift\fR, with \fB\-\-set\fR or
> > +It is necessary to use the option \fB\-\-update-drift\fR, with \fB\-\-set\fR or
> > \fB\-\-systohc\fR, to force drift factor updates.
>
> The rest of the manual uses 'the --xxxx option'.
Well, I can't explain, but in this case "the option --xxxx" is better.
> > Since v2.26
> > .B hwclock \-\-hctosys
> > -automatically compensates time read from the Hardware Clock to account for
> > -systematic drift before using it to set the System Clock. Therefore,
> > -\fB\-\-adjust\fR is no longer necessary during boot. This functionality makes
> > -hwclock usable early in the boot process when the root filesystem is read-only.
> > +automatically takes a systematic drift of the Hardware Clock into account,
> > +setting the System Clock to the drift-compensated time. Therefore the option
> > +\fB\-\-adjust\fR is no longer necessary during boot. This feature makes
> > +.B hwclock
> > +usable early on in the boot process when the root filesystem is read-only.
>
> "a systematic drift"? That entire phrase does not sound natural to me.
:|
> I think it is important to
> stress that *the_time_read* from the Clock is what is being compensated as this is
> a new behavior.
Well, then suggest how exactly to phrase that.
Benno
--
http://www.fastmail.fm - Or how I learned to stop worrying and
love email again
^ permalink raw reply [flat|nested] 18+ messages in thread* Re: [PATCH 4/4] docs: improve wording and formattin of man page of hwclock
2014-10-28 20:02 ` Benno Schulenberg
@ 2014-10-31 9:51 ` Karel Zak
2014-11-02 17:53 ` JWP
0 siblings, 1 reply; 18+ messages in thread
From: Karel Zak @ 2014-10-31 9:51 UTC (permalink / raw)
To: Benno Schulenberg; +Cc: JWP, Util-Linux
On Tue, Oct 28, 2014 at 09:02:12PM +0100, Benno Schulenberg wrote:
>
> On Tue, Oct 28, 2014, at 02:09, JWP wrote:
> > On 10/27/2014 05:18 PM, Benno Schulenberg wrote:
> > > Since v2.26
> > > .B hwclock
> > > does not update the Hardware Clock's drift factor in @ADJTIME_PATH@ by default.
> > > -It is necessary to use \fB\-\-update-drift\fR, with \fB\-\-set\fR or
> > > +It is necessary to use the option \fB\-\-update-drift\fR, with \fB\-\-set\fR or
> > > \fB\-\-systohc\fR, to force drift factor updates.
> >
> > The rest of the manual uses 'the --xxxx option'.
>
> Well, I can't explain, but in this case "the option --xxxx" is better.
>
> > > Since v2.26
> > > .B hwclock \-\-hctosys
> > > -automatically compensates time read from the Hardware Clock to account for
> > > -systematic drift before using it to set the System Clock. Therefore,
> > > -\fB\-\-adjust\fR is no longer necessary during boot. This functionality makes
> > > -hwclock usable early in the boot process when the root filesystem is read-only.
> > > +automatically takes a systematic drift of the Hardware Clock into account,
> > > +setting the System Clock to the drift-compensated time. Therefore the option
> > > +\fB\-\-adjust\fR is no longer necessary during boot. This feature makes
> > > +.B hwclock
> > > +usable early on in the boot process when the root filesystem is read-only.
> >
> > "a systematic drift"? That entire phrase does not sound natural to me.
>
> :|
>
> > I think it is important to
> > stress that *the_time_read* from the Clock is what is being compensated as this is
> > a new behavior.
>
> Well, then suggest how exactly to phrase that.
I'll wait for the final patch :-)
Karel
--
Karel Zak <kzak@redhat.com>
http://karelzak.blogspot.com
^ permalink raw reply [flat|nested] 18+ messages in thread* Re: [PATCH 4/4] docs: improve wording and formattin of man page of hwclock
2014-10-31 9:51 ` Karel Zak
@ 2014-11-02 17:53 ` JWP
2014-11-03 21:15 ` Benno Schulenberg
0 siblings, 1 reply; 18+ messages in thread
From: JWP @ 2014-11-02 17:53 UTC (permalink / raw)
To: Karel Zak, Benno Schulenberg; +Cc: Util-Linux
On 10/31/2014 05:51 AM, Karel Zak wrote:
> On Tue, Oct 28, 2014 at 09:02:12PM +0100, Benno Schulenberg wrote:
>>
>> On Tue, Oct 28, 2014, at 02:09, JWP wrote:
>>> On 10/27/2014 05:18 PM, Benno Schulenberg wrote:
>>>> Since v2.26
>>>> .B hwclock
>>>> does not update the Hardware Clock's drift factor in @ADJTIME_PATH@ by default.
>>>> -It is necessary to use \fB\-\-update-drift\fR, with \fB\-\-set\fR or
>>>> +It is necessary to use the option \fB\-\-update-drift\fR, with \fB\-\-set\fR or
>>>> \fB\-\-systohc\fR, to force drift factor updates.
>>>
>>> The rest of the manual uses 'the --xxxx option'.
>>
>> Well, I can't explain, but in this case "the option --xxxx" is better.
>>
>>>> Since v2.26
>>>> .B hwclock \-\-hctosys
>>>> -automatically compensates time read from the Hardware Clock to account for
>>>> -systematic drift before using it to set the System Clock. Therefore,
>>>> -\fB\-\-adjust\fR is no longer necessary during boot. This functionality makes
>>>> -hwclock usable early in the boot process when the root filesystem is read-only.
>>>> +automatically takes a systematic drift of the Hardware Clock into account,
>>>> +setting the System Clock to the drift-compensated time. Therefore the option
>>>> +\fB\-\-adjust\fR is no longer necessary during boot. This feature makes
>>>> +.B hwclock
>>>> +usable early on in the boot process when the root filesystem is read-only.
>>>
>>> "a systematic drift"? That entire phrase does not sound natural to me.
>>
>> :|
>>
>>> I think it is important to
>>> stress that *the_time_read* from the Clock is what is being compensated as this is
>>> a new behavior.
>>
>> Well, then suggest how exactly to phrase that.
>
> I'll wait for the final patch :-)
>
> Karel
Karel and Benno,
I did not intent to comment further on this, because I find discourse
on human language illogical and frustrating. No doubt, that is why I
am drawn to the language of machines, but there's no escaping strings;)
I suppose it is impolite of me to leave the topic dangling though.
The first issue seems so trivial as to not justify any debate. I will
however, expand on my original comment: if there is no grammar rule to
decide a style choice, then the super-class style rule of 'be consistent'
should be applied. I do not find 'because I say so' to be a compelling
argument.
With regard to the second issue, I suggested 'how exactly to phrase that'
when I edited it the first time. Unless it can be rewritten in a way that
does not change its meaning, I feel it should remain as it is.
So there you have my opinions; I will leave the matter in both of your hands
to make a good choice.
Will
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH 4/4] docs: improve wording and formattin of man page of hwclock
2014-11-02 17:53 ` JWP
@ 2014-11-03 21:15 ` Benno Schulenberg
2014-11-04 13:16 ` JWP
0 siblings, 1 reply; 18+ messages in thread
From: Benno Schulenberg @ 2014-11-03 21:15 UTC (permalink / raw)
To: JWP; +Cc: Karel Zak, Util-Linux
On Sun, Nov 2, 2014, at 18:53, JWP wrote:
> The first issue seems so trivial as to not justify any debate. I will
> however, expand on my original comment: if there is no grammar rule to
> decide a style choice, then the super-class style rule of 'be consistent'
> should be applied. I do not find 'because I say so' to be a compelling
> argument.
Fine. But as you've said yourself: human language is illogical. :)
> With regard to the second issue, I suggested 'how exactly to phrase that'
> when I edited it the first time.
Ah. When I edited it I didn't realize the v2.26 notes had been changed
after Karel had added them. And now it took me a moment to realize that
JWP is the same as J William Piggott. ... Okay, never mind.
> Unless it can be rewritten in a way that
> does not change its meaning, I feel it should remain as it is.
Well, there are several problems with your (and also Karels) version
of the text. First, "automatically". The word suggests to me that
there is/was a way to do this unautomatically, that is: by the use of
an option. But is was never possible to make hwclock set the System
Clock to a drift-compensated time without touching the Hardware Clock
nor the adjtime file. Second, "compensates time [...] to account for".
The expression in English is " to compensate something /for/ a deviance" --
there should be no "to account". But the interposing of "read from the
Hardware Clock" makes the use of this expression difficult to grasp.
So it's better to rewrite the whole thing. Third, a "the" is needed
before "time". Fourth, the "This functionality" referring to --adjust
no longer being necessary during boot is awkward; it's second word
can simply de dropped.
So... my suggestion:
"Since v2.26 hwclock --hctosys does a better job at setting the System Clock:
it no longer simply copies the time from the Hardware Clock to the System Clock,
but it reads the Hardware Clock, applies a compensation for the systematic drift
to this read time, and sets the System Clock to the resulting time. Thus it is
no longer necessary to run hwclock --adjust before doing hwclock --hctosys, and
therefore hwclock can be used very early on in the boot process when the root
filesystem is still read-only."
Any amendments?
Benno
--
http://www.fastmail.fm - Does exactly what it says on the tin
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH 4/4] docs: improve wording and formattin of man page of hwclock
2014-11-03 21:15 ` Benno Schulenberg
@ 2014-11-04 13:16 ` JWP
2014-11-18 13:05 ` Karel Zak
0 siblings, 1 reply; 18+ messages in thread
From: JWP @ 2014-11-04 13:16 UTC (permalink / raw)
To: Benno Schulenberg; +Cc: Karel Zak, Util-Linux
On 11/03/2014 04:15 PM, Benno Schulenberg wrote:
> Well, there are several problems with your (and also Karels) version
> of the text. First, "automatically". The word suggests to me that
> there is/was a way to do this unautomatically, that is: by the use of
> an option. But is was never possible to make hwclock set the System
> Clock to a drift-compensated time without touching the Hardware Clock
> nor the adjtime file. Second, "compensates time [...] to account for".
> The expression in English is " to compensate something /for/ a deviance" --
> there should be no "to account". But the interposing of "read from the
> Hardware Clock" makes the use of this expression difficult to grasp.
> So it's better to rewrite the whole thing. Third, a "the" is needed
> before "time". Fourth, the "This functionality" referring to --adjust
> no longer being necessary during boot is awkward; it's second word
> can simply de dropped.
I do not disagree with you here. I did not want to be heavy handed when
editing Karel's words, because it is his project and I am new here. I only
wanted to make clear to the reader that the Hardware Clock itself was not
being altered.
>
> So... my suggestion:
>
> "Since v2.26 hwclock --hctosys does a better job at setting the System Clock:
> it no longer simply copies the time from the Hardware Clock to the System Clock,
> but it reads the Hardware Clock, applies a compensation for the systematic drift
> to this read time, and sets the System Clock to the resulting time. Thus it is
> no longer necessary to run hwclock --adjust before doing hwclock --hctosys, and
> therefore hwclock can be used very early on in the boot process when the root
> filesystem is still read-only."
>
> Any amendments?
Nope, that seems quite complete Benno!
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH 4/4] docs: improve wording and formattin of man page of hwclock
2014-11-04 13:16 ` JWP
@ 2014-11-18 13:05 ` Karel Zak
2014-11-18 19:48 ` Benno Schulenberg
0 siblings, 1 reply; 18+ messages in thread
From: Karel Zak @ 2014-11-18 13:05 UTC (permalink / raw)
To: JWP; +Cc: Benno Schulenberg, Util-Linux
On Tue, Nov 04, 2014 at 08:16:18AM -0500, JWP wrote:
> I do not disagree with you here. I did not want to be heavy handed when
> editing Karel's words, because it is his project and I am new here.
Karel is not always right. Don't care who is author, bugs have to be
fixed.
> > "Since v2.26 hwclock --hctosys does a better job at setting the System Clock:
> > it no longer simply copies the time from the Hardware Clock to the System Clock,
> > but it reads the Hardware Clock, applies a compensation for the systematic drift
> > to this read time, and sets the System Clock to the resulting time. Thus it is
> > no longer necessary to run hwclock --adjust before doing hwclock --hctosys, and
> > therefore hwclock can be used very early on in the boot process when the root
> > filesystem is still read-only."
> >
> > Any amendments?
>
> Nope, that seems quite complete Benno!
Benno, re-send a complete patch with this change. Please.
Karel
--
Karel Zak <kzak@redhat.com>
http://karelzak.blogspot.com
^ permalink raw reply [flat|nested] 18+ messages in thread* Re: [PATCH 4/4] docs: improve wording and formattin of man page of hwclock
2014-11-18 13:05 ` Karel Zak
@ 2014-11-18 19:48 ` Benno Schulenberg
2014-11-19 7:26 ` Karel Zak
0 siblings, 1 reply; 18+ messages in thread
From: Benno Schulenberg @ 2014-11-18 19:48 UTC (permalink / raw)
To: Karel Zak; +Cc: JWP, Util-Linux
On Tue, Nov 18, 2014, at 14:05, Karel Zak wrote:
> Karel is not always right. Don't care who is author, bugs have to be
> fixed.
>
> [...]
>
> Benno, re-send a complete patch with this change. Please.
But, but... you have already applied it. :)
(commit df48a721613f30a607d8616f5d8808d11ebfab25)
Or was it your intention to give a live demonstration of
"Karel is sometimes confused and mistaken"?
:)
Benno
--
http://www.fastmail.com - IMAP accessible web-mail
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH 1/4] docs: spelling, wording, and grammar fixes in the man page of whereis
2014-10-27 21:18 [PATCH 1/4] docs: spelling, wording, and grammar fixes in the man page of whereis Benno Schulenberg
` (2 preceding siblings ...)
2014-10-27 21:18 ` [PATCH 4/4] docs: improve wording and formattin of man page of hwclock Benno Schulenberg
@ 2014-10-31 9:47 ` Karel Zak
3 siblings, 0 replies; 18+ messages in thread
From: Karel Zak @ 2014-10-31 9:47 UTC (permalink / raw)
To: Benno Schulenberg; +Cc: util-linux
On Mon, Oct 27, 2014 at 10:18:10PM +0100, Benno Schulenberg wrote:
> misc-utils/whereis.1 | 37 +++++++++++++++++++------------------
> 1 files changed, 19 insertions(+), 18 deletions(-)
Applied, thanks.
--
Karel Zak <kzak@redhat.com>
http://karelzak.blogspot.com
^ permalink raw reply [flat|nested] 18+ messages in thread