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

Previous Next

Full log

View this message in rfc822 format

From: help-debbugs <at> gnu.org (GNU bug Tracking System)
To: Benno Schulenberg <bensberg <at> justemail.net>
Subject: bug#13681: closed (Re: bug#13681: [patches] numfmt: standardize
 synopsis and docstring,  and slice up helptext)
Date: Sun, 10 Feb 2013 20:02:02 +0000

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

Your bug report

#13681: [patches] numfmt: standardize synopsis and docstring, and slice up helptext

which was filed against the coreutils package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to 13681 <at> debbugs.gnu.org.

-- 
13681: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=13681
GNU Bug Tracking System
Contact help-debbugs <at> gnu.org with problems

[Message part 2 (message/rfc822, inline)]

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 part 3 (message/rfc822, inline)]

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 4 (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)]

Previous Next

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