[PATCH 0/5] pull request

[PATCH 0/5] pull request

[J William Piggott]

The following changes since commit 07fd6640c80ffd7a2067844aadcb6162431b3525:

  Merge branch 'path-fixes' of https://github.com/rudimeier/util-linux (2017-06-29 15:29:33 +0200)

are available in the git repository at:

  git@github.com:jwpi/util-linux.git 170701

for you to fetch changes up to 9c50e384c89d5f9391c3eaed8df89ec965f2fda7:

  hwclock: sync one-liner descriptions (2017-07-02 14:09:41 -0400)

----------------------------------------------------------------
J William Piggott (5):
      hwclock: remove from usage() FILE *out = stdout
      hwclock: usage() use program_invocation_short_name
      hwclock: final usage() strings slice
      docs: update boilerplate.c usage()
      hwclock: sync one-liner descriptions

 Documentation/boilerplate.c | 37 ++++++++++++------------
 sys-utils/hwclock.8.in      |  4 +--
 sys-utils/hwclock.c         | 68 +++++++++++++++++++++++----------------------
 3 files changed, 55 insertions(+), 54 deletions(-)

[PATCH 1/5] hwclock: remove from usage() FILE *out = stdout

[J William Piggott]

Signed-off-by: J William Piggott <elseifthen@gmx.com>
---
 sys-utils/hwclock.c | 65 ++++++++++++++++++++++++++---------------------------
 1 file changed, 32 insertions(+), 33 deletions(-)

diff --git a/sys-utils/hwclock.c b/sys-utils/hwclock.c
index a0a48dd..8b1e2f3 100644
--- a/sys-utils/hwclock.c
+++ b/sys-utils/hwclock.c
@@ -1202,48 +1202,47 @@ static void out_version(void)
 static void __attribute__((__noreturn__))
 usage(const struct hwclock_control *ctl)
 {
-	FILE *out = stdout;
-	fputs(USAGE_HEADER, out);
-	fputs(_(" hwclock [function] [option...]\n"), out);
-
-	fputs(USAGE_SEPARATOR, out);
-	fputs(_("Query or set the RTC (Real Time Clock / Hardware Clock)\n"), out);
-
-	fputs(USAGE_FUNCTIONS, out);
-	fputs(_(" -r, --show           display the RTC time\n"), out);
-	fputs(_("     --get            display drift corrected RTC time\n"), out);
-	fputs(_("     --set            set the RTC according to --date\n"), out);
-	fputs(_(" -s, --hctosys        set the system time from the RTC\n"), out);
-	fputs(_(" -w, --systohc        set the RTC from the system time\n"), out);
-	fputs(_("     --systz          send timescale configurations to the kernel\n"), out);
-	fputs(_("     --adjust         adjust the RTC to account for systematic drift\n"), out);
+	fputs(USAGE_HEADER, stdout);
+	puts(_(" hwclock [function] [option...]"));
+
+	fputs(USAGE_SEPARATOR, stdout);
+	puts(_("Query or set the RTC (Real Time Clock / Hardware Clock)"));
+
+	fputs(USAGE_FUNCTIONS, stdout);
+	puts(_(" -r, --show           display the RTC time"));
+	puts(_("     --get            display drift corrected RTC time"));
+	puts(_("     --set            set the RTC according to --date"));
+	puts(_(" -s, --hctosys        set the system time from the RTC"));
+	puts(_(" -w, --systohc        set the RTC from the system time"));
+	puts(_("     --systz          send timescale configurations to the kernel"));
+	puts(_("     --adjust         adjust the RTC to account for systematic drift"));
 #if defined(__linux__) && defined(__alpha__)
-	fputs(_("     --getepoch       display the RTC epoch\n"), out);
-	fputs(_("     --setepoch       set the RTC epoch according to --epoch\n"), out);
+	puts(_("     --getepoch       display the RTC epoch"));
+	puts(_("     --setepoch       set the RTC epoch according to --epoch"));
 #endif
-	fputs(_("     --predict        predict the drifted RTC time according to --date\n"), out);
-	fputs(USAGE_OPTIONS, out);
-	fputs(_(" -u, --utc            inform hwclock the RTC timescale is UTC\n"), out);
-	fputs(_(" -l, --localtime      inform hwclock the RTC timescale is Local\n"), out);
+	puts(_("     --predict        predict the drifted RTC time according to --date"));
+	fputs(USAGE_OPTIONS, stdout);
+	puts(_(" -u, --utc            inform hwclock the RTC timescale is UTC"));
+	puts(_(" -l, --localtime      inform hwclock the RTC timescale is Local"));
 #ifdef __linux__
 	printf(_(
-		" -f, --rtc <file>     use an alternate file to %1$s\n"), _PATH_RTC_DEV);
+	       " -f, --rtc <file>     use an alternate file to %1$s\n"), _PATH_RTC_DEV);
 #endif
 	printf(_(
-		"     --directisa      use the ISA bus instead of %1$s access\n"), _PATH_RTC_DEV);
-	fputs(_("     --date <time>    date/time input for --set and --predict\n"), out);
+	       "     --directisa      use the ISA bus instead of %1$s access\n"), _PATH_RTC_DEV);
+	puts(_("     --date <time>    date/time input for --set and --predict"));
 #if defined(__linux__) && defined(__alpha__)
-	fputs(_("     --epoch <year>   epoch input for --setepoch\n"), out);
+	puts(_("     --epoch <year>   epoch input for --setepoch"));
 #endif
-	fputs(_("     --update-drift   update the RTC drift factor\n"), out);
-	fprintf(out, _(
-		"     --noadjfile      do not use %1$s\n"
-		"     --adjfile <file> use an alternate file to %1$s\n"), _PATH_ADJTIME);
-	fputs(_("     --test           dry run; use -D to view what would have happened\n"), out);
-	fputs(_(" -D, --debug          use debug mode\n"), out);
-	fputs(USAGE_SEPARATOR, out);
+	puts(_("     --update-drift   update the RTC drift factor"));
+	printf(_(
+	       "     --noadjfile      do not use %1$s\n"
+	       "     --adjfile <file> use an alternate file to %1$s\n"), _PATH_ADJTIME);
+	puts(_("     --test           dry run; use -D to view what would have happened"));
+	puts(_(" -D, --debug          use debug mode"));
+	fputs(USAGE_SEPARATOR, stdout);
 	print_usage_help_options(22);
-	fprintf(out, USAGE_MAN_TAIL("hwclock(8)"));
+	printf(USAGE_MAN_TAIL("hwclock(8)"));
 	hwclock_exit(ctl, EXIT_SUCCESS);
 }
 

[PATCH 2/5] hwclock: usage() use program_invocation_short_name

[J William Piggott]

Signed-off-by: J William Piggott <elseifthen@gmx.com>
---
 sys-utils/hwclock.c | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/sys-utils/hwclock.c b/sys-utils/hwclock.c
index 8b1e2f3..eeb68e7 100644
--- a/sys-utils/hwclock.c
+++ b/sys-utils/hwclock.c
@@ -1203,7 +1203,7 @@ static void __attribute__((__noreturn__))
 usage(const struct hwclock_control *ctl)
 {
 	fputs(USAGE_HEADER, stdout);
-	puts(_(" hwclock [function] [option...]"));
+	printf(_(" %s [function] [option...]\n"), program_invocation_short_name);
 
 	fputs(USAGE_SEPARATOR, stdout);
 	puts(_("Query or set the RTC (Real Time Clock / Hardware Clock)"));
@@ -1222,8 +1222,10 @@ usage(const struct hwclock_control *ctl)
 #endif
 	puts(_("     --predict        predict the drifted RTC time according to --date"));
 	fputs(USAGE_OPTIONS, stdout);
-	puts(_(" -u, --utc            inform hwclock the RTC timescale is UTC"));
-	puts(_(" -l, --localtime      inform hwclock the RTC timescale is Local"));
+	printf(_(
+	       " -u, --utc            inform %s the RTC timescale is UTC\n"), program_invocation_short_name);
+	printf(_(
+	       " -l, --localtime      inform %s the RTC timescale is Local\n"), program_invocation_short_name);
 #ifdef __linux__
 	printf(_(
 	       " -f, --rtc <file>     use an alternate file to %1$s\n"), _PATH_RTC_DEV);

Re: [PATCH 2/5] hwclock: usage() use program_invocation_short_name

[Ruediger Meier]

On Sunday 02 July 2017, J William Piggott wrote:
> 
> Signed-off-by: J William Piggott <elseifthen@gmx.com>
> ---
>  sys-utils/hwclock.c | 8 +++++---
>  1 file changed, 5 insertions(+), 3 deletions(-)
> 
> diff --git a/sys-utils/hwclock.c b/sys-utils/hwclock.c
> index 8b1e2f3..eeb68e7 100644
> --- a/sys-utils/hwclock.c
> +++ b/sys-utils/hwclock.c
> @@ -1203,7 +1203,7 @@ static void __attribute__((__noreturn__))
>  usage(const struct hwclock_control *ctl)
>  {
>  	fputs(USAGE_HEADER, stdout);
> -	puts(_(" hwclock [function] [option...]"));
> +	printf(_(" %s [function] [option...]\n"), program_invocation_short_name);
>  
>  	fputs(USAGE_SEPARATOR, stdout);
>  	puts(_("Query or set the RTC (Real Time Clock / Hardware Clock)"));
> @@ -1222,8 +1222,10 @@ usage(const struct hwclock_control *ctl)
>  #endif
>  	puts(_("     --predict        predict the drifted RTC time according to --date"));
>  	fputs(USAGE_OPTIONS, stdout);
> -	puts(_(" -u, --utc            inform hwclock the RTC timescale is UTC"));
> -	puts(_(" -l, --localtime      inform hwclock the RTC timescale is Local"));
> +	printf(_(
> +	       " -u, --utc            inform %s the RTC timescale is UTC\n"), program_invocation_short_name);
> +	printf(_(
> +	       " -l, --localtime      inform %s the RTC timescale is Local\n"), program_invocation_short_name);
>  #ifdef __linux__
>  	printf(_(
>  	       " -f, --rtc <file>     use an alternate file to %1$s\n"), _PATH_RTC_DEV);

I'm not sure if this makes really sense. I wouldn't overuse the program
name in general. And in this case I would rather remove the reduntant
term "inform hwclock" as *all* options "inform hwclock" about something. 

cu,
Rudi

Re: [PATCH 2/5] hwclock: usage() use program_invocation_short_name

[J William Piggott]

On 07/03/2017 04:46 AM, Ruediger Meier wrote:
> On Sunday 02 July 2017, J William Piggott wrote:
>>
>> Signed-off-by: J William Piggott <elseifthen@gmx.com>
>> ---
>>  sys-utils/hwclock.c | 8 +++++---
>>  1 file changed, 5 insertions(+), 3 deletions(-)
>>
>> diff --git a/sys-utils/hwclock.c b/sys-utils/hwclock.c
>> index 8b1e2f3..eeb68e7 100644
>> --- a/sys-utils/hwclock.c
>> +++ b/sys-utils/hwclock.c
>> @@ -1203,7 +1203,7 @@ static void __attribute__((__noreturn__))
>>  usage(const struct hwclock_control *ctl)
>>  {
>>  	fputs(USAGE_HEADER, stdout);
>> -	puts(_(" hwclock [function] [option...]"));
>> +	printf(_(" %s [function] [option...]\n"), program_invocation_short_name);
>>  
>>  	fputs(USAGE_SEPARATOR, stdout);
>>  	puts(_("Query or set the RTC (Real Time Clock / Hardware Clock)"));
>> @@ -1222,8 +1222,10 @@ usage(const struct hwclock_control *ctl)
>>  #endif
>>  	puts(_("     --predict        predict the drifted RTC time according to --date"));
>>  	fputs(USAGE_OPTIONS, stdout);
>> -	puts(_(" -u, --utc            inform hwclock the RTC timescale is UTC"));
>> -	puts(_(" -l, --localtime      inform hwclock the RTC timescale is Local"));
>> +	printf(_(
>> +	       " -u, --utc            inform %s the RTC timescale is UTC\n"), program_invocation_short_name);
>> +	printf(_(
>> +	       " -l, --localtime      inform %s the RTC timescale is Local\n"), program_invocation_short_name);
>>  #ifdef __linux__
>>  	printf(_(
>>  	       " -f, --rtc <file>     use an alternate file to %1$s\n"), _PATH_RTC_DEV);
> 
> I'm not sure if this makes really sense. I wouldn't overuse the program
> name in general. And in this case I would rather remove the reduntant
> term "inform hwclock" as *all* options "inform hwclock" about something. 

Most options are requesting a behavior. Some are giving the command
configuration information, 'informing'.

The reason for the stressing the point here is because when these options
are used elsewhere they are requesting an behavior. For example:

$ date
Mon Jul  3 10:49:12 EDT 2017
$ date --utc
Mon Jul  3 14:49:18 UTC 2017

It is reasonable that users might make the same assumption for hwclock
since it is, to some degree, an analog of 'date'. But they would not get
the expected result.

This unique situation also causes the options to have different affects
depending on the function. It would be nice to make them mutually
exclusive with 'read' functions, but if there is no /etc/adjtime file
then they are needed, well --localtime is needed.

So I am stressing that these options are giving hwclock information
about the Hardware Clock that it otherwise has no way of determining; as
opposed to telling hwclock to use the specified timescale for it's
actions, like displaying the Hardware Clock time in utc.

I think the name choice for these options is unfortunate, but it is what
it is.


> 
> cu,
> Rudi
> --
> To unsubscribe from this list: send the line "unsubscribe util-linux" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> 

Re: [PATCH 2/5] hwclock: usage() use program_invocation_short_name

[J William Piggott]

On 07/03/2017 11:14 AM, J William Piggott wrote:
> 
> 
> On 07/03/2017 04:46 AM, Ruediger Meier wrote:
>> On Sunday 02 July 2017, J William Piggott wrote:
>>>
>>> Signed-off-by: J William Piggott <elseifthen@gmx.com>
>>> ---
>>>  sys-utils/hwclock.c | 8 +++++---
>>>  1 file changed, 5 insertions(+), 3 deletions(-)
>>>
>>> diff --git a/sys-utils/hwclock.c b/sys-utils/hwclock.c
>>> index 8b1e2f3..eeb68e7 100644
>>> --- a/sys-utils/hwclock.c
>>> +++ b/sys-utils/hwclock.c
>>> @@ -1203,7 +1203,7 @@ static void __attribute__((__noreturn__))
>>>  usage(const struct hwclock_control *ctl)
>>>  {
>>>  	fputs(USAGE_HEADER, stdout);
>>> -	puts(_(" hwclock [function] [option...]"));
>>> +	printf(_(" %s [function] [option...]\n"), program_invocation_short_name);
>>>  
>>>  	fputs(USAGE_SEPARATOR, stdout);
>>>  	puts(_("Query or set the RTC (Real Time Clock / Hardware Clock)"));
>>> @@ -1222,8 +1222,10 @@ usage(const struct hwclock_control *ctl)
>>>  #endif
>>>  	puts(_("     --predict        predict the drifted RTC time according to --date"));
>>>  	fputs(USAGE_OPTIONS, stdout);
>>> -	puts(_(" -u, --utc            inform hwclock the RTC timescale is UTC"));
>>> -	puts(_(" -l, --localtime      inform hwclock the RTC timescale is Local"));
>>> +	printf(_(
>>> +	       " -u, --utc            inform %s the RTC timescale is UTC\n"), program_invocation_short_name);
>>> +	printf(_(
>>> +	       " -l, --localtime      inform %s the RTC timescale is Local\n"), program_invocation_short_name);
>>>  #ifdef __linux__
>>>  	printf(_(
>>>  	       " -f, --rtc <file>     use an alternate file to %1$s\n"), _PATH_RTC_DEV);
>>
>> I'm not sure if this makes really sense. I wouldn't overuse the program
>> name in general. And in this case I would rather remove the reduntant
>> term "inform hwclock" as *all* options "inform hwclock" about something. 
> 
> Most options are requesting a behavior. Some are giving the command
> configuration information, 'informing'.
> 
> The reason for the stressing the point here is because when these options
> are used elsewhere they are requesting an behavior. For example:
> 
> $ date
> Mon Jul  3 10:49:12 EDT 2017
> $ date --utc
> Mon Jul  3 14:49:18 UTC 2017
> 
> It is reasonable that users might make the same assumption for hwclock
> since it is, to some degree, an analog of 'date'. But they would not get
> the expected result.
> 
> This unique situation also causes the options to have different affects
> depending on the function. It would be nice to make them mutually
> exclusive with 'read' functions, but if there is no /etc/adjtime file
> then they are needed, well --localtime is needed.
> 
> So I am stressing that these options are giving hwclock information
> about the Hardware Clock that it otherwise has no way of determining; as
> opposed to telling hwclock to use the specified timescale for it's
> actions, like displaying the Hardware Clock time in utc.
> 
> I think the name choice for these options is unfortunate, but it is what
> it is.
>

Okay, I stripped the 'inform hwclock' and pushed the results. The
difference is to subtle to argue about and it does make the code cleaner.

> 
>>
>> cu,
>> Rudi
>> --
>> To unsubscribe from this list: send the line "unsubscribe util-linux" in
>> the body of a message to majordomo@vger.kernel.org
>> More majordomo info at  http://vger.kernel.org/majordomo-info.html
>>
> --
> To unsubscribe from this list: send the line "unsubscribe util-linux" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> 

[PATCH 3/5] hwclock: final usage() strings slice

[J William Piggott]

Signed-off-by: J William Piggott <elseifthen@gmx.com>
---
 sys-utils/hwclock.c | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/sys-utils/hwclock.c b/sys-utils/hwclock.c
index eeb68e7..19d7652 100644
--- a/sys-utils/hwclock.c
+++ b/sys-utils/hwclock.c
@@ -1238,7 +1238,8 @@ usage(const struct hwclock_control *ctl)
 #endif
 	puts(_("     --update-drift   update the RTC drift factor"));
 	printf(_(
-	       "     --noadjfile      do not use %1$s\n"
+	       "     --noadjfile      do not use %1$s\n"), _PATH_ADJTIME);
+	printf(_(
 	       "     --adjfile <file> use an alternate file to %1$s\n"), _PATH_ADJTIME);
 	puts(_("     --test           dry run; use -D to view what would have happened"));
 	puts(_(" -D, --debug          use debug mode"));

Re: [PATCH 3/5] hwclock: final usage() strings slice

[Ruediger Meier]

On Sunday 02 July 2017, J William Piggott wrote:
> 
> Signed-off-by: J William Piggott <elseifthen@gmx.com>
> ---
>  sys-utils/hwclock.c | 3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)
> 
> diff --git a/sys-utils/hwclock.c b/sys-utils/hwclock.c
> index eeb68e7..19d7652 100644
> --- a/sys-utils/hwclock.c
> +++ b/sys-utils/hwclock.c
> @@ -1238,7 +1238,8 @@ usage(const struct hwclock_control *ctl)
>  #endif
>  	puts(_("     --update-drift   update the RTC drift factor"));
>  	printf(_(
> -	       "     --noadjfile      do not use %1$s\n"
> +	       "     --noadjfile      do not use %1$s\n"), _PATH_ADJTIME);
> +	printf(_(
>  	       "     --adjfile <file> use an alternate file to %1$s\n"), _PATH_ADJTIME);
>  	puts(_("     --test           dry run; use -D to view what would have happened"));
>  	puts(_(" -D, --debug          use debug mode"));

What about




> --
> To unsubscribe from this list: send the line "unsubscribe util-linux" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> 
> 

What about the mentioned whitespaces for puts() to get printf
on one line? 

  puts(  _("     --update-drift   update the RTC drift factor"));
  printf(_("     --noadjfile      do not use %1$s\n"), _PATH_ADJTIME);
  printf(_("     --adjfile <file> use an alternate file to %1$s\n"), _PATH_ADJTIME);
  puts(  _("     --test           dry run; use -D to view what would have happened"));
  puts(  _(" -D, --debug          use debug mode"));

cu,
Rudi

Re: [PATCH 3/5] hwclock: final usage() strings slice

[J William Piggott]

On 07/03/2017 04:51 AM, Ruediger Meier wrote:
> On Sunday 02 July 2017, J William Piggott wrote:
>>
>> Signed-off-by: J William Piggott <elseifthen@gmx.com>
>> ---
>>  sys-utils/hwclock.c | 3 ++-
>>  1 file changed, 2 insertions(+), 1 deletion(-)
>>
>> diff --git a/sys-utils/hwclock.c b/sys-utils/hwclock.c
>> index eeb68e7..19d7652 100644
>> --- a/sys-utils/hwclock.c
>> +++ b/sys-utils/hwclock.c
>> @@ -1238,7 +1238,8 @@ usage(const struct hwclock_control *ctl)
>>  #endif
>>  	puts(_("     --update-drift   update the RTC drift factor"));
>>  	printf(_(
>> -	       "     --noadjfile      do not use %1$s\n"
>> +	       "     --noadjfile      do not use %1$s\n"), _PATH_ADJTIME);
>> +	printf(_(
>>  	       "     --adjfile <file> use an alternate file to %1$s\n"), _PATH_ADJTIME);
>>  	puts(_("     --test           dry run; use -D to view what would have happened"));
>>  	puts(_(" -D, --debug          use debug mode"));
> 
> What about
> 
> 
> 
> 
>> --
>> To unsubscribe from this list: send the line "unsubscribe util-linux" in
>> the body of a message to majordomo@vger.kernel.org
>> More majordomo info at  http://vger.kernel.org/majordomo-info.html
>>
>>
> 
> What about the mentioned whitespaces for puts() to get printf
> on one line? 
> 
>   puts(  _("     --update-drift   update the RTC drift factor"));
>   printf(_("     --noadjfile      do not use %1$s\n"), _PATH_ADJTIME);
>   printf(_("     --adjfile <file> use an alternate file to %1$s\n"), _PATH_ADJTIME);
>   puts(  _("     --test           dry run; use -D to view what would have happened"));
>   puts(  _(" -D, --debug          use debug mode"));

Sure, if that is what Karel wants (it can be a separate patch).

The only thing that I don't like about that choice is that it can cause
puts() lines to wrap that otherwise would not. Since puts() is a lot
more common than printf(), it seems like putting the alignment burden on
printf() makes more sense.

But I don't have a strong opinion about it. Whatever Karel wants is fine
with me.

Make the change Karel?


> 
> cu,
> Rudi
> --
> To unsubscribe from this list: send the line "unsubscribe util-linux" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> 

Re: [PATCH 3/5] hwclock: final usage() strings slice

[Karel Zak]

On Mon, Jul 03, 2017 at 11:35:01AM -0400, J William Piggott wrote:
> >> To unsubscribe from this list: send the line "unsubscribe util-linux" in
> >> the body of a message to majordomo@vger.kernel.org
> >> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> >>
> >>
> > 
> > What about the mentioned whitespaces for puts() to get printf
> > on one line? 
> > 
> >   puts(  _("     --update-drift   update the RTC drift factor"));
> >   printf(_("     --noadjfile      do not use %1$s\n"), _PATH_ADJTIME);
> >   printf(_("     --adjfile <file> use an alternate file to %1$s\n"), _PATH_ADJTIME);
> >   puts(  _("     --test           dry run; use -D to view what would have happened"));
> >   puts(  _(" -D, --debug          use debug mode"));
> 
> Sure, if that is what Karel wants (it can be a separate patch).
> 
> The only thing that I don't like about that choice is that it can cause
> puts() lines to wrap that otherwise would not. Since puts() is a lot
> more common than printf(), it seems like putting the alignment burden on
> printf() makes more sense.

I think the idea is to use the extra space only if you mix printf and
puts in the same code block. We have on many place only puts (or
fputs) -- in this case the extra space is unnecessary.

    Karel

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

Re: [PATCH 3/5] hwclock: final usage() strings slice

[Bernhard Voelker]

On 07/04/2017 09:58 AM, Karel Zak wrote:
> I think the idea is to use the extra space only if you mix printf and
> puts in the same code block. We have on many place only puts (or
> fputs) -- in this case the extra space is unnecessary.

What about putting the strings on an extra line regardless whether
that is output via printf or fputf or ...; e.g.
  http://git.savannah.gnu.org/cgit/coreutils.git/tree/src/du.c#n278
?

Have a nice day,
Berny

Re: [PATCH 3/5] hwclock: final usage() strings slice

[Ruediger Meier]

On Tuesday 04 July 2017, Bernhard Voelker wrote:
> On 07/04/2017 09:58 AM, Karel Zak wrote:
> > I think the idea is to use the extra space only if you mix printf
> > and puts in the same code block. We have on many place only puts
> > (or fputs) -- in this case the extra space is unnecessary.
>
> What about putting the strings on an extra line regardless whether
> that is output via printf or fputf or ...; e.g.
>   http://git.savannah.gnu.org/cgit/coreutils.git/tree/src/du.c#n278
> ?

Yes this is nice because easy to count that no usage output is longer 
than 80 chars. But I guess there are too many different opinions about 
these stylish things. I'd also like to have just one string and only 
one printf command for all options (like mkfs.cramfs.c). But this may 
cause more work for translators each time we add a new option. Don't 
know if that would be a real problem.

cu,
Rudi

Re: [PATCH 3/5] hwclock: final usage() strings slice

[Bernhard Voelker]

On 07/04/2017 10:55 AM, Ruediger Meier wrote:
> Yes this is nice because easy to count that no usage output is longer 
> than 80 chars. But I guess there are too many different opinions about 
> these stylish things. I'd also like to have just one string and only 
> one printf command for all options (like mkfs.cramfs.c). But this may 
> cause more work for translators each time we add a new option. Don't 
> know if that would be a real problem.

In coreutils, we got the feedback from the translators that they'd prefer
one string per option.  Otherwise, changes are harder to track for them.

Have a nice day,
Berny

Re: [PATCH 3/5] hwclock: final usage() strings slice

[Karel Zak]

On Tue, Jul 04, 2017 at 10:55:05AM +0200, Ruediger Meier wrote:
> On Tuesday 04 July 2017, Bernhard Voelker wrote:
> > On 07/04/2017 09:58 AM, Karel Zak wrote:
> > > I think the idea is to use the extra space only if you mix printf
> > > and puts in the same code block. We have on many place only puts
> > > (or fputs) -- in this case the extra space is unnecessary.
> >
> > What about putting the strings on an extra line regardless whether
> > that is output via printf or fputf or ...; e.g.
> >   http://git.savannah.gnu.org/cgit/coreutils.git/tree/src/du.c#n278
> > ?
> 
> Yes this is nice because easy to count that no usage output is longer 
> than 80 chars. But I guess there are too many different opinions about 
> these stylish things. I'd also like to have just one string and only 
> one printf command for all options (like mkfs.cramfs.c). But this may 
> cause more work for translators each time we add a new option. Don't 
> know if that would be a real problem.

The one line for one option is what we want and what has been
requested by translators years ago. I really don't like the example
from the coreutils. Sorry :-)

    Karel

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

Re: [PATCH 3/5] hwclock: final usage() strings slice

[Karel Zak]

On Tue, Jul 04, 2017 at 06:53:50PM +0200, Karel Zak wrote:
> On Tue, Jul 04, 2017 at 10:55:05AM +0200, Ruediger Meier wrote:
> > On Tuesday 04 July 2017, Bernhard Voelker wrote:
> > > On 07/04/2017 09:58 AM, Karel Zak wrote:
> > > > I think the idea is to use the extra space only if you mix printf
> > > > and puts in the same code block. We have on many place only puts
> > > > (or fputs) -- in this case the extra space is unnecessary.
> > >
> > > What about putting the strings on an extra line regardless whether
> > > that is output via printf or fputf or ...; e.g.
> > >   http://git.savannah.gnu.org/cgit/coreutils.git/tree/src/du.c#n278
> > > ?
> > 
> > Yes this is nice because easy to count that no usage output is longer 
> > than 80 chars. But I guess there are too many different opinions about 
> > these stylish things. I'd also like to have just one string and only 
> > one printf command for all options (like mkfs.cramfs.c). But this may 
> > cause more work for translators each time we add a new option. Don't 
> > know if that would be a real problem.
> 
> The one line for one option is what we want and what has been
> requested by translators years ago. I really don't like the example
> from the coreutils. Sorry :-)

More information: http://www.spinics.net/lists/util-linux-ng/msg07489.html

    Karel

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

Re: [PATCH 3/5] hwclock: final usage() strings slice

[J William Piggott]

On 07/04/2017 03:58 AM, Karel Zak wrote:
> On Mon, Jul 03, 2017 at 11:35:01AM -0400, J William Piggott wrote:
>>>> To unsubscribe from this list: send the line "unsubscribe util-linux" in
>>>> the body of a message to majordomo@vger.kernel.org
>>>> More majordomo info at  http://vger.kernel.org/majordomo-info.html
>>>>
>>>>
>>>
>>> What about the mentioned whitespaces for puts() to get printf
>>> on one line? 
>>>
>>>   puts(  _("     --update-drift   update the RTC drift factor"));
>>>   printf(_("     --noadjfile      do not use %1$s\n"), _PATH_ADJTIME);
>>>   printf(_("     --adjfile <file> use an alternate file to %1$s\n"), _PATH_ADJTIME);
>>>   puts(  _("     --test           dry run; use -D to view what would have happened"));
>>>   puts(  _(" -D, --debug          use debug mode"));
>>
>> Sure, if that is what Karel wants (it can be a separate patch).
>>
>> The only thing that I don't like about that choice is that it can cause
>> puts() lines to wrap that otherwise would not. Since puts() is a lot
>> more common than printf(), it seems like putting the alignment burden on
>> printf() makes more sense.
> 
> I think the idea is to use the extra space only if you mix printf and
> puts in the same code block. We have on many place only puts (or
> fputs) -- in this case the extra space is unnecessary.

True. I meant that in mixed conditions *puts() seems more common. So if
you have a full column of *puts() and one *printf(), forcing the puts
lines to add whitespace could make many of them wrap, thus adding more
ugliness to the source than if the alignment burden is on *printf().

Again, this is an anecdotal comment only, I don't have a strong opinion
about it. For messy usage() blocks I typically toggle nowrap in my
editor; so the alignment choice is not a big deal for me.

If there aren't any other objections you could commit this set; the
alignment change qualifies for a separate commit, I think.


> 
>     Karel
> 

[PATCH 4/5] docs: update boilerplate.c usage()

[J William Piggott]

Signed-off-by: J William Piggott <elseifthen@gmx.com>
---
 Documentation/boilerplate.c | 37 ++++++++++++++++++-------------------
 1 file changed, 18 insertions(+), 19 deletions(-)

diff --git a/Documentation/boilerplate.c b/Documentation/boilerplate.c
index c97ad46..ae3fb5c 100644
--- a/Documentation/boilerplate.c
+++ b/Documentation/boilerplate.c
@@ -36,28 +36,27 @@
  */
 static void __attribute__((__noreturn__)) usage(void)
 {
-	FILE *out = stdout;
-	fputs(USAGE_HEADER, out);
-	fprintf(out, _(" %s [options] file...\n"), program_invocation_short_name);
+	fputs(USAGE_HEADER, stdout);
+	printf(_(" %s [options] file...\n"), program_invocation_short_name);
 
-        fputs(USAGE_SEPARATOR, out);
-        fputs(_("Short program description.\n"), out);
+	fputs(USAGE_SEPARATOR, stdout);
+	puts(_("Short program description."));
 
-	fputs(USAGE_OPTIONS, out);
-	fputs(_(" -n, --no-argument       option does not use argument\n"), out);
-	fputs(_("     --optional[=<arg>]  option argument is optional\n"), out);
-	fputs(_(" -r, --required <arg>    option requires an argument\n"), out);
-	fputs(_(" -z                      no long option\n"), out);
-	fputs(_("     --xyzzy             a long option only\n"), out);
-	fputs(_(" -e, --extremely-long-long-option\n"
-		"                         use next line for description when needed\n"), out);
-	fputs(_(" -l, --long-explanation  an example of very verbose, and chatty option\n"
-		"                           description on two, or multiple lines, where the\n"
-		"                           consecutive lines are intended by two spaces\n"), out);
-	fputs(_(" -f, --foobar            next option description resets indent\n"), out);
-	fputs(USAGE_SEPARATOR, out);
+	fputs(USAGE_OPTIONS, stdout);
+	puts(_(" -n, --no-argument       option does not use argument"));
+	puts(_("     --optional[=<arg>]  option argument is optional"));
+	puts(_(" -r, --required <arg>    option requires an argument"));
+	puts(_(" -z                      no long option"));
+	puts(_("     --xyzzy             a long option only"));
+	puts(_(" -e, --extremely-long-long-option\n"
+	       "                         use next line for description when needed"));
+	puts(_(" -l, --long-explanation  an example of very verbose, and chatty option\n"
+	       "                           description on two, or multiple lines, where the\n"
+	       "                           consecutive lines are intended by two spaces"));
+	puts(_(" -f, --foobar            next option description resets indent"));
+	fputs(USAGE_SEPARATOR, stdout);
 	print_usage_help_options(25); /* char offset to align option descriptions */
-	fprintf(out, USAGE_MAN_TAIL("fixme-command-name(1)"));
+	printf(USAGE_MAN_TAIL("fixme-command-name(1)"));
 	exit(EXIT_SUCCESS);
 }
 

[PATCH 5/5] hwclock: sync one-liner descriptions

[J William Piggott]

Make whatisdb/manpage and usage() one-line descriptions match.

Also update the description; hwclock has evolved into much more
than reading and setting the Hardware Clock. It also sets the
System Clock, warps the System Clock, sets the kernel time
configurations, and more.

Signed-off-by: J William Piggott <elseifthen@gmx.com>
---
 sys-utils/hwclock.8.in | 4 ++--
 sys-utils/hwclock.c    | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/sys-utils/hwclock.8.in b/sys-utils/hwclock.8.in
index 72b842e..fa8a19a 100644
--- a/sys-utils/hwclock.8.in
+++ b/sys-utils/hwclock.8.in
@@ -6,7 +6,7 @@
 .\"
 .TH HWCLOCK 8 "April 2015" "util-linux" "System Administration"
 .SH NAME
-hwclock \- read or set the hardware clock (RTC)
+hwclock \- time clocks utility
 .SH SYNOPSIS
 .B hwclock
 .RI [ function ]
@@ -14,7 +14,7 @@ hwclock \- read or set the hardware clock (RTC)
 .
 .SH DESCRIPTION
 .B hwclock
-is a tool for accessing the Hardware Clock.  It can: display the
+is an administration tool for the time clocks.  It can: display the
 Hardware Clock time; set the Hardware Clock to a specified time; set the
 Hardware Clock from the System Clock; set the System Clock from the
 Hardware Clock; compensate for Hardware Clock drift; correct the System
diff --git a/sys-utils/hwclock.c b/sys-utils/hwclock.c
index 19d7652..5320683 100644
--- a/sys-utils/hwclock.c
+++ b/sys-utils/hwclock.c
@@ -1206,7 +1206,7 @@ usage(const struct hwclock_control *ctl)
 	printf(_(" %s [function] [option...]\n"), program_invocation_short_name);
 
 	fputs(USAGE_SEPARATOR, stdout);
-	puts(_("Query or set the RTC (Real Time Clock / Hardware Clock)"));
+	puts(_("Time clocks utility."));
 
 	fputs(USAGE_FUNCTIONS, stdout);
 	puts(_(" -r, --show           display the RTC time"));

[PING - REBASED][PATCH 0/5] pull request

[J William Piggott]

On 07/02/2017 03:45 PM, J William Piggott wrote:
> 
> The following changes since commit 07fd6640c80ffd7a2067844aadcb6162431b3525:
> 
>   Merge branch 'path-fixes' of https://github.com/rudimeier/util-linux (2017-06-29 15:29:33 +0200)
> 
> are available in the git repository at:
> 
>   git@github.com:jwpi/util-linux.git 170701
> 
> for you to fetch changes up to 9c50e384c89d5f9391c3eaed8df89ec965f2fda7:
> 
>   hwclock: sync one-liner descriptions (2017-07-02 14:09:41 -0400)
> 
> ----------------------------------------------------------------
> J William Piggott (5):
>       hwclock: remove from usage() FILE *out = stdout
>       hwclock: usage() use program_invocation_short_name
>       hwclock: final usage() strings slice
>       docs: update boilerplate.c usage()
>       hwclock: sync one-liner descriptions
> 
>  Documentation/boilerplate.c | 37 ++++++++++++------------
>  sys-utils/hwclock.8.in      |  4 +--
>  sys-utils/hwclock.c         | 68 +++++++++++++++++++++++----------------------
>  3 files changed, 55 insertions(+), 54 deletions(-)
> --
> To unsubscribe from this list: send the line "unsubscribe util-linux" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> 

Re: [PING - REBASED][PATCH 0/5] pull request

[Karel Zak]

On Mon, Jul 10, 2017 at 07:34:55PM -0400, J William Piggott wrote:
> On 07/02/2017 03:45 PM, J William Piggott wrote:
> > 
> > The following changes since commit 07fd6640c80ffd7a2067844aadcb6162431b3525:
> > 
> >   Merge branch 'path-fixes' of https://github.com/rudimeier/util-linux (2017-06-29 15:29:33 +0200)
> > 
> > are available in the git repository at:
> > 
> >   git@github.com:jwpi/util-linux.git 170701
> > 
> > for you to fetch changes up to 9c50e384c89d5f9391c3eaed8df89ec965f2fda7:
> > 
> >   hwclock: sync one-liner descriptions (2017-07-02 14:09:41 -0400)
> > 
> > ----------------------------------------------------------------
> > J William Piggott (5):
> >       hwclock: remove from usage() FILE *out = stdout
> >       hwclock: usage() use program_invocation_short_name
> >       hwclock: final usage() strings slice
> >       docs: update boilerplate.c usage()
> >       hwclock: sync one-liner descriptions
> > 
> >  Documentation/boilerplate.c | 37 ++++++++++++------------
> >  sys-utils/hwclock.8.in      |  4 +--
> >  sys-utils/hwclock.c         | 68 +++++++++++++++++++++++----------------------
> >  3 files changed, 55 insertions(+), 54 deletions(-)

Merged. (Sorry for delay, I had vacation since Wed).

    Karel

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

Re: [PING - REBASED][PATCH 0/5] pull request

[J William Piggott]

On 07/11/2017 04:06 AM, Karel Zak wrote:
> On Mon, Jul 10, 2017 at 07:34:55PM -0400, J William Piggott wrote:
>> On 07/02/2017 03:45 PM, J William Piggott wrote:
>>>
>>> The following changes since commit 07fd6640c80ffd7a2067844aadcb6162431b3525:
>>>
>>>   Merge branch 'path-fixes' of https://github.com/rudimeier/util-linux (2017-06-29 15:29:33 +0200)
>>>
>>> are available in the git repository at:
>>>
>>>   git@github.com:jwpi/util-linux.git 170701
>>>
>>> for you to fetch changes up to 9c50e384c89d5f9391c3eaed8df89ec965f2fda7:
>>>
>>>   hwclock: sync one-liner descriptions (2017-07-02 14:09:41 -0400)
>>>
>>> ----------------------------------------------------------------
>>> J William Piggott (5):
>>>       hwclock: remove from usage() FILE *out = stdout
>>>       hwclock: usage() use program_invocation_short_name
>>>       hwclock: final usage() strings slice
>>>       docs: update boilerplate.c usage()
>>>       hwclock: sync one-liner descriptions
>>>
>>>  Documentation/boilerplate.c | 37 ++++++++++++------------
>>>  sys-utils/hwclock.8.in      |  4 +--
>>>  sys-utils/hwclock.c         | 68 +++++++++++++++++++++++----------------------
>>>  3 files changed, 55 insertions(+), 54 deletions(-)
> 
> Merged. (Sorry for delay, I had vacation since Wed).

Thank you! (No problem, I hope you had a good holiday).

> 
>     Karel
>