GNU bug report logs - #13681
[patches] numfmt: standardize synopsis and docstring, and slice up helptext

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 13681 in the body.
You can then email your comments to 13681 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Benno Schulenberg <bensberg <at> justemail.net>
To: Coreutils <bug-coreutils <at> gnu.org>
Subject: [patches] numfmt: standardize synopsis and docstring,
	and slice up helptext
Date: Sun, 10 Feb 2013 20:10:53 +0100

[Message part 1 (text/plain, inline)]

Hi,

The synopsis of numfmt currently says:

  Usage: %s [OPTIONS] [NUMBER]

But multiple numbers are allowed, and a single option too,
so it should read:

  Usage: %s [OPTION]... [NUMBER]...

Further, the command description says:

  Reformat NUMBER(s) from stdin or command arguments.

This is double, because the NUMBER(s) already are the command
arguments.  Furthermore, it is usual to refer to "standard input",
in full, not with the abbreviation.

Also, several of the option descriptions start with an uppercase
letter, some not.  It is customary to start with a lowercase one,
and also to not use a period at the end, and a semicolon if there
is needed for multiple phrases.

Since now all of the descriptions change, the attached patch
takes the opportunity to slice the big help text (which is a
nuisance for translators) into strings that encompass a single
option.  (This follows the preference of the vast majority of
translators.  Sami Kerola, who does a lot of work on util-linux,
conducted a small but telling survey:
http://www.spinics.net/lists/util-linux-ng/msg07489.html)

Regards,

Benno

-- 
http://www.fastmail.fm - Does exactly what it says on the tin

[0002-doc-standardize-the-synopsis-and-docstring-of-comman.patch (text/x-patch, attachment)]

[0003-doc-standardize-helptext-of-numfmt-and-slice-into-si.patch (text/x-patch, attachment)]

Message #10 received at 13681-done <at> debbugs.gnu.org (full text, mbox):

From: Pádraig Brady <P <at> draigBrady.com>
To: Benno Schulenberg <bensberg <at> justemail.net>
Cc: 13681-done <at> debbugs.gnu.org
Subject: Re: bug#13681: [patches] numfmt: standardize synopsis and docstring, 
	and slice up helptext
Date: Sun, 10 Feb 2013 20:01:16 +0000

On 02/10/2013 07:10 PM, Benno Schulenberg wrote:
>
> Hi,
>
> The synopsis of numfmt currently says:
>
>    Usage: %s [OPTIONS] [NUMBER]
>
> But multiple numbers are allowed, and a single option too,
> so it should read:
>
>    Usage: %s [OPTION]... [NUMBER]...
>
> Further, the command description says:
>
>    Reformat NUMBER(s) from stdin or command arguments.
>
> This is double, because the NUMBER(s) already are the command
> arguments.  Furthermore, it is usual to refer to "standard input",
> in full, not with the abbreviation.
>
> Also, several of the option descriptions start with an uppercase
> letter, some not.  It is customary to start with a lowercase one,
> and also to not use a period at the end, and a semicolon if there
> is needed for multiple phrases.
>
> Since now all of the descriptions change, the attached patch
> takes the opportunity to slice the big help text (which is a
> nuisance for translators) into strings that encompass a single
> option.  (This follows the preference of the vast majority of
> translators.  Sami Kerola, who does a lot of work on util-linux,
> conducted a small but telling survey:
> http://www.spinics.net/lists/util-linux-ng/msg07489.html)

Thanks very much Benno.

I'll apply this for the upcoming release.

Pádraig.

Message #13 received at 13681-done <at> debbugs.gnu.org (full text, mbox):

From: Benno Schulenberg <bensberg <at> justemail.net>
To: Pádraig Brady <P <at> draigBrady.com>
Cc: 13681-done <at> debbugs.gnu.org
Subject: Re: bug#13681: [patches] numfmt: standardize synopsis and docstring, 
	and slice up helptext
Date: Sun, 10 Feb 2013 21:34:50 +0100

On Sun, Feb 10, 2013, at 21:01, Pádraig Brady wrote:
> I'll apply this for the upcoming release.

Thanks.  Just to be sure: this will require a pre3, if translations
are meant (where possible) to be complete.

Oh, and one small overlooked typo still:
-"positive N will right-aligned;"
+"positive N will right-align;"

Benno

-- 
http://www.fastmail.fm - Send your email first class

Message #16 received at 13681-done <at> debbugs.gnu.org (full text, mbox):

From: Bernhard Voelker <mail <at> bernhard-voelker.de>
To: Benno Schulenberg <bensberg <at> justemail.net>
Cc: 13681-done <at> debbugs.gnu.org,
	Pádraig Brady <P <at> draigBrady.com>
Subject: Re: bug#13681: [patches] numfmt: standardize synopsis and docstring, 
	and slice up helptext
Date: Sun, 10 Feb 2013 23:11:02 +0100

[Message part 1 (text/plain, inline)]

On 02/10/2013 09:34 PM, Benno Schulenberg wrote:
> 
> On Sun, Feb 10, 2013, at 21:01, Pádraig Brady wrote:
>> I'll apply this for the upcoming release.
> 
> Thanks.  Just to be sure: this will require a pre3, if translations
> are meant (where possible) to be complete.
> 
> Oh, and one small overlooked typo still:
> -"positive N will right-aligned;"
> +"positive N will right-align;"

Thank you.

Besides fixing a few too long lines (to silence make syntax-check),
I have also sorted the options alphabetically and improved the
indentation for short/long options, plus 2 spaces between the options
and the description.
I changed a few option descriptions. I hope this is okay for you.

Furthermore, I've also sorted the options in the texinfo documentation.
While already there, I fixed the style to have a double-blank
after periods.

I'll push tomorrow unless I receive further comments.

Have a nice day,
Berny

[numfmt-usage.patch.xz (application/x-xz, attachment)]

Message #19 received at 13681 <at> debbugs.gnu.org (full text, mbox):

From: Pádraig Brady <P <at> draigBrady.com>
To: Bernhard Voelker <mail <at> bernhard-voelker.de>
Cc: 13681 <at> debbugs.gnu.org, Benno Schulenberg <bensberg <at> justemail.net>
Subject: Re: bug#13681: [patches] numfmt: standardize synopsis and docstring, 
	and slice up helptext
Date: Mon, 11 Feb 2013 01:42:01 +0000

On 02/10/2013 10:11 PM, Bernhard Voelker wrote:
> On 02/10/2013 09:34 PM, Benno Schulenberg wrote:
>>
>> On Sun, Feb 10, 2013, at 21:01, Pádraig Brady wrote:
>>> I'll apply this for the upcoming release.
>>
>> Thanks.  Just to be sure: this will require a pre3, if translations
>> are meant (where possible) to be complete.
>>
>> Oh, and one small overlooked typo still:
>> -"positive N will right-aligned;"
>> +"positive N will right-align;"
>
> Thank you.
>
> Besides fixing a few too long lines (to silence make syntax-check),
> I have also sorted the options alphabetically and improved the
> indentation for short/long options, plus 2 spaces between the options
> and the description.
> I changed a few option descriptions. I hope this is okay for you.
>
> Furthermore, I've also sorted the options in the texinfo documentation.
> While already there, I fixed the style to have a double-blank
> after periods.
>
> I'll push tomorrow unless I receive further comments.

+1

thanks!
Pádraig.

Message #22 received at 13681-done <at> debbugs.gnu.org (full text, mbox):

From: Bernhard Voelker <mail <at> bernhard-voelker.de>
To: Pádraig Brady <P <at> draigBrady.com>
Cc: 13681-done <at> debbugs.gnu.org, Benno Schulenberg <bensberg <at> justemail.net>
Subject: Re: bug#13681: [patches] numfmt: standardize synopsis and docstring, 
	and slice up helptext
Date: Mon, 11 Feb 2013 08:29:48 +0100

On 02/11/2013 02:42 AM, Pádraig Brady wrote:
> On 02/10/2013 10:11 PM, Bernhard Voelker wrote:
>> I'll push tomorrow unless I receive further comments.
> 
> +1

Thanks, pushed:
http://git.sv.gnu.org/cgit/coreutils.git/commit/?id=b5f45b64

Marking as done.

Have a nice day,
Berny

Message #25 received at 13681 <at> debbugs.gnu.org (full text, mbox):

From: Pádraig Brady <P <at> draigBrady.com>
To: 13681 <at> debbugs.gnu.org
Subject: Re: bug#13681: [patches] numfmt: standardize synopsis and docstring, 
	and slice up helptext
Date: Mon, 11 Feb 2013 09:31:20 +0000

[Message part 1 (text/plain, inline)]

On 02/11/2013 07:29 AM, Bernhard Voelker wrote:
> On 02/11/2013 02:42 AM, Pádraig Brady wrote:
>> On 02/10/2013 10:11 PM, Bernhard Voelker wrote:
>>> I'll push tomorrow unless I receive further comments.
>>
>> +1
>
> Thanks, pushed:
> http://git.sv.gnu.org/cgit/coreutils.git/commit/?id=b5f45b64

Actually I noticed a small issue with man page formatting,
which I addressed with the attached.

thanks,
Pádraig.

[numfmt-man.patch (text/x-patch, attachment)]

Message #28 received at 13681 <at> debbugs.gnu.org (full text, mbox):

From: Bernhard Voelker <mail <at> bernhard-voelker.de>
To: Pádraig Brady <P <at> draigBrady.com>
Cc: 13681 <at> debbugs.gnu.org
Subject: Re: bug#13681: [patches] numfmt: standardize synopsis and docstring, 
	and slice up helptext
Date: Mon, 11 Feb 2013 10:43:31 +0100

On 02/11/2013 10:31 AM, Pádraig Brady wrote:
> Actually I noticed a small issue with man page formatting,
> which I addressed with the attached.

Good catch, thanks!

+1

Have a nice day,
Berny

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.