[PATCH 1/4] docs: spelling, wording, and grammar fixes in the man page of whereis

[PATCH 1/4] docs: spelling, wording, and grammar fixes in the man page of whereis

[Benno Schulenberg]

Signed-off-by: Benno Schulenberg <bensberg@justemail.net>
---
 misc-utils/whereis.1 |   37 +++++++++++++++++++------------------
 1 files changed, 19 insertions(+), 18 deletions(-)

diff --git a/misc-utils/whereis.1 b/misc-utils/whereis.1
index e8e4327..243fc14 100644
--- a/misc-utils/whereis.1
+++ b/misc-utils/whereis.1
@@ -30,7 +30,7 @@
 .\" SUCH DAMAGE.
 .\"
 .\" @(#)whereis.1 from UCB 4.2
-.TH WHEREIS 1 "March 2013" "util-linux" "User Commands"
+.TH WHEREIS 1 "October 2014" "util-linux" "User Commands"
 .SH NAME
 whereis \- locate the binary, source, and manual page files for a command
 .SH SYNOPSIS
@@ -56,26 +56,27 @@ in the places specified by
 .B $PATH
 and
 .BR $MANPATH .
-
-The search restrinctions (options \fB\-b\fP, \fB\-m\fP and \fB\-s\fP) are
-cumulative and always applied for the next \fIname\fP patterns specified on
-command line. The first search restrinction resets the search mask. For example
+.sp
+The search restrictions (options \fB\-b\fP, \fB\-m\fP and \fB\-s\fP)
+are cumulative and apply to the subsequent \fIname\fP patterns on
+the command line.  Any new search restriction resets the search mask.
+For example,
 .RS
 .sp
 .B "whereis -bm ls tr -m gcc"
 .sp
 .RE
-searchs for "ls" and "tr" binaries and man pages, and "gcc" man pages only.
-
-The options \fB\-B\fP, \fB\-M\fP and \fB\-S\fP resets search paths for the next
-\fIname\fP patterns. For example
+searches for "ls" and "tr" binaries and man pages, and for "gcc" man pages only.
+.sp
+The options \fB\-B\fP, \fB\-M\fP and \fB\-S\fP reset search paths for the
+subsequent \fIname\fP patterns.  For example,
 .RS
 .sp
 .B "whereis -m ls -M /usr/share/man/man1 -f cal"
 .sp
 .RE
-searchs for "ls" man pages in all default paths, but for "cal" in
-/usr/share/man/man1 directory only.
+searches for "ls" man pages in all default paths, but for "cal" in
+the /usr/share/man/man1 directory only.
 
 .SH OPTIONS
 .TP
@@ -114,15 +115,15 @@ or
 .BR \-S
 options is used.
 .IP "\fB\-l"
-Output list of effective lookup paths the
+Output the list of effective lookup paths that
 .B whereis
-is using.  When non of
+is using.  When none of
 .BR \-B ,
 .BR \-M ,
 or
 .BR \-S
-is specified the option will out hard coded paths that the command was able to
-find on system.
+is specified, the option will output the hard-coded paths
+that the command was able to find on the system.
 .SH EXAMPLE
 To find all files in
 .B /usr/\:bin
@@ -132,14 +133,14 @@ in
 or have no source in
 .BR /usr/\:src :
 .IP
-.B $ cd /usr/bin
+.B cd /usr/bin
 .br
-.B $ whereis \-u \-ms \-M /usr/man/man1 \-S /usr/src \-f *
+.B whereis \-u \-ms \-M /usr/man/man1 \-S /usr/src \-f *
 .SH "FILE SEARCH PATHS"
 By default
 .B whereis
 tries to find files from hard-coded paths, which are defined with glob
-patterns. The command attempst to use contents of
+patterns.  The command attempst to use contents of
 .B $PATH
 and
 .B $MANPATH
-- 
1.7.0.4

[PATCH 2/4] docs: fix some wording and formatting in man page of swapon

[Benno Schulenberg]

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

[PATCH 3/4] textual: slice up the usage text of swapon for ease of translation

[Benno Schulenberg]

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

[PATCH 4/4] docs: improve wording and formattin of man page of hwclock

[Benno Schulenberg]

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

Re: [PATCH 3/4] textual: slice up the usage text of swapon for ease of translation

[Benno Schulenberg]

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

Re: [PATCH 4/4] docs: improve wording and formattin of man page of hwclock

[JWP]

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.


 

Re: [PATCH 4/4] docs: improve wording and formattin of man page of hwclock

[Benno Schulenberg]

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

Re: [PATCH 3/4] textual: slice up the usage text of swapon for ease of translation

[Karel Zak]

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

Re: [PATCH 1/4] docs: spelling, wording, and grammar fixes in the man page of whereis

[Karel Zak]

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

Re: [PATCH 2/4] docs: fix some wording and formatting in man page of swapon

[Karel Zak]

On Mon, Oct 27, 2014 at 10:18:11PM +0100, Benno Schulenberg wrote:
>  sys-utils/swapon.8 |   17 +++++++++--------
>  1 files changed, 9 insertions(+), 8 deletions(-)

 Applied, thanks.

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

Re: [PATCH 3/4] textual: slice up the usage text of swapon for ease of translation

[Karel Zak]

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

Re: [PATCH 4/4] docs: improve wording and formattin of man page of hwclock

[Karel Zak]

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

Re: [PATCH 4/4] docs: improve wording and formattin of man page of hwclock

[JWP]

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

Re: [PATCH 4/4] docs: improve wording and formattin of man page of hwclock

[Benno Schulenberg]

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

Re: [PATCH 4/4] docs: improve wording and formattin of man page of hwclock

[JWP]

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!

Re: [PATCH 4/4] docs: improve wording and formattin of man page of hwclock

[Karel Zak]

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

Re: [PATCH 4/4] docs: improve wording and formattin of man page of hwclock

[Benno Schulenberg]

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

Re: [PATCH 4/4] docs: improve wording and formattin of man page of hwclock

[Karel Zak]

On Tue, Nov 18, 2014 at 08:48:00PM +0100, Benno Schulenberg wrote:
> >  Benno, re-send a complete patch with this change. Please.
> 
> But, but... you have already applied it.  :)
> 
> (commit df48a721613f30a607d8616f5d8808d11ebfab25)

OK, forgot to remove the email from util-linux folder. Thanks.

    Karel

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