Subject: bug#13681: closed (Re: bug#13681: [patches] numfmt: standardize synopsis and docstring, and slice up helptext)

From: [email-masked] (GNU bug Tracking System)
Date: Sun, 10 Feb 2013 20:02:02 +0000

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 [email-masked].

-- 
13681: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=13681
GNU Bug Tracking System
Contact [email-masked] with problems

Subject: Re: bug#13681: [patches] numfmt: standardize synopsis and docstring, and slice up helptext
From: Pádraig Brady <[email-masked]>
To: Benno Schulenberg <[email-masked]>
Cc: [email-masked]
Date: Sun, 10 Feb 2013 20:01:16 +0000
List-Id: <debbugs-submit.debbugs.gnu.org>

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.

Subject: [patches] numfmt: standardize synopsis and docstring, and slice up helptext
From: Benno Schulenberg <[email-masked]>
To: Coreutils <[email-masked]>
Date: Sun, 10 Feb 2013 20:10:53 +0100
List-Id: <debbugs-submit.debbugs.gnu.org>

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

From 590c544d02ceecb30f5ac72e77e603a415ad8b6e Mon Sep 17 00:00:00 2001
From: Benno Schulenberg <[email-masked]>
Date: Sun, 10 Feb 2013 19:16:02 +0100
Subject: [PATCH 2/3] doc: standardize the synopsis and docstring of command 'numfmt'

* src/numfmt.c: Correct synopsis and make command description clearer.
---
 src/numfmt.c |    4 ++--
 1 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/numfmt.c b/src/numfmt.c
index 117f19b..f8593c8 100644
--- a/src/numfmt.c
+++ b/src/numfmt.c
@@ -810,10 +810,10 @@ usage (int status)
   else
     {
       printf (_("\
-Usage: %s [OPTIONS] [NUMBER]\n\
+Usage: %s [OPTION]... [NUMBER]...\n\
 "), program_name);
       fputs (_("\
-Reformat NUMBER(s) from stdin or command arguments.\n\
+Reformat NUMBER(s), or the numbers from standard input if none are specified.\n\
 "), stdout);
       emit_mandatory_arg_note ();
       fputs (_("\
-- 
1.7.0.4

From edb80a6e50138d0c9a6ebc38ff85dce0af25662c Mon Sep 17 00:00:00 2001
From: Benno Schulenberg <[email-masked]>
Date: Sun, 10 Feb 2013 19:42:02 +0100
Subject: [PATCH 3/3] doc: standardize helptext of numfmt and slice into single options

* src/numfmt.c: Start option descriptions with lowercase letter; use
semicolon instead of period where needed; indent continuation lines;
gettextize single options for ease of translation and maintenance.
---
 src/numfmt.c |  131 +++++++++++++++++++++++++++++++++-------------------------
 1 files changed, 75 insertions(+), 56 deletions(-)

diff --git a/src/numfmt.c b/src/numfmt.c
index f8593c8..f99ebb8 100644
--- a/src/numfmt.c
+++ b/src/numfmt.c
@@ -817,86 +817,106 @@ Reformat NUMBER(s), or the numbers from standard input if none are specified.\n\
 "), stdout);
       emit_mandatory_arg_note ();
       fputs (_("\
-  --from=UNIT     auto-scale input numbers to UNITs. Default is 'none'.\n\
-                  See UNIT below.\n\
-  --from-unit=N   specify the input unit size (instead of the default 1).\n\
-  --to=UNIT       auto-scale output numbers to UNITs.\n\
-                  See UNIT below.\n\
-  --to-unit=N     the output unit size (instead of the default 1).\n\
-  --round=METHOD  the rounding method to use when scaling. METHOD can be:\n\
+  --from=UNIT     auto-scale input numbers to UNITs; default is 'none';\n\
+                    see UNIT below\n\
+"), stdout);
+      fputs (_("\
+  --from-unit=N   specify the input unit size (instead of the default 1)\n\
+"), stdout);
+      fputs (_("\
+  --to=UNIT       auto-scale output numbers to UNITs; see UNIT below\n\
+"), stdout);
+      fputs (_("\
+  --to-unit=N     the output unit size (instead of the default 1)\n\
+"), stdout);
+      fputs (_("\
+  --round=METHOD  the rounding method to use when scaling; METHOD can be:\n\
                   up, down, from-zero (default), towards-zero, nearest\n\
+"), stdout);
+      fputs (_("\
   --suffix=SUFFIX add SUFFIX to output numbers, and accept optional SUFFIX\n\
-                  in input numbers.\n\
-  --padding=N     pad the output to N characters.\n\
-                  Positive N will right-aligned. Negative N will left-align.\n\
-                  Note: if the output is wider than N, padding is ignored.\n\
-                  Default is to automatically pad if whitespace is found.\n\
-  --grouping      group digits together (e.g. 1,000,000).\n\
-                  Uses the locale-defined grouping (i.e. have no effect\n\
-                  in C/POSIX locales).\n\
-  --header[=N]    print (without converting) the first N header lines.\n\
-                  N defaults to 1 if not specified.\n\
+                    in input numbers\n\
+"), stdout);
+      fputs (_("\
+  --padding=N     pad the output to N characters;\n\
+                    positive N will right-aligned; negative N will left-align;\n\
+                    note: if the output is wider than N, padding is ignored;\n\
+                    default is to automatically pad if whitespace is found\n\
+"), stdout);
+      fputs (_("\
+  --grouping      group digits for visual ease (e.g. 1,000,000);\n\
+                    uses the locale-defined grouping (which means it has\n\
+                    no effect in the C/POSIX locale)\n\
+"), stdout);
+      fputs (_("\
+  --header[=N]    print (without converting) the first N header lines;\n\
+                    N defaults to 1 if not specified\n\
+"), stdout);
+      fputs (_("\
   --field N       replace the number in input field N (default is 1)\n\
+"), stdout);
+      fputs (_("\
   -d, --delimiter=X  use X instead of whitespace for field delimiter\n\
-  --format=FORMAT use printf style floating-point FORMAT.\n\
-                  See FORMAT below for details.\n\
+"), stdout);
+      fputs (_("\
+  --format=FORMAT use printf style floating-point FORMAT;\n\
+                    see FORMAT below for details\n\
+"), stdout);
+      fputs (_("\
   --invalid=MODE  failure mode for invalid numbers: MODE can be:\n\
-                  abort (the default), fail, warn, ignore.\n\
-  --debug         print warnings about invalid input.\n\
-  \n\
+                    abort (default), fail, warn, ignore\n\
+"), stdout);
+      fputs (_("\
+  --debug         print warnings about invalid input\n\n
 "), stdout);
+
       fputs (HELP_OPTION_DESCRIPTION, stdout);
       fputs (VERSION_OPTION_DESCRIPTION, stdout);
 
-
       fputs (_("\
 \n\
-UNIT options:\n\
-  none       No auto-scaling is done. Suffixes will trigger an error.\n\
-  auto       Accept optional single-letter/two-letter suffix:\n\
-             1K  = 1000\n\
-             1Ki = 1024\n\
-             1M  = 1000000\n\
-             1Mi = 1048576\n\
-  si         Accept optional single letter suffix:\n\
-             1K = 1000\n\
-             1M = 1000000\n\
-             ...\n\
-  iec        Accept optional single letter suffix:\n\
-             1K = 1024\n\
-             1M = 1048576\n\
-             ...\n\
-  iec-i      Accept optional two-letter suffix:\n\
-             1Ki = 1024\n\
-             1Mi = 1048576\n\
-             ...\n\
-\n\
-"), stdout);
-
+UNIT options:\n"), stdout);
       fputs (_("\
-\n\
+  none       no auto-scaling is done; suffixes will trigger an error\n"), stdout);
+      fputs (_("\
+  auto       accept optional single-letter/two-letter suffix:\n\
+               1K  = 1000\n\
+               1Ki = 1024\n\
+               1M  = 1000000\n\
+               1Mi = 1048576\n"), stdout);
+      fputs (_("\
+  si         accept optional single letter suffix:\n\
+               1K = 1000\n\
+               1M = 1000000\n\
+               ...\n"), stdout);
+      fputs (_("\
+  iec        accept optional single letter suffix:\n\
+               1K = 1024\n\
+               1M = 1048576\n\
+               ...\n"), stdout);
+      fputs (_("\
+  iec-i      accept optional two-letter suffix:\n\
+               1Ki = 1024\n\
+               1Mi = 1048576\n\
+               ...\n"), stdout);
+
+      fputs (_("\n\
 FORMAT must be suitable for printing one floating-point argument '%f'.\n\
 Optional quote (%'f) will enable --grouping (if supported by current locale).\n\
 Optional width value (%10f) will pad output. Optional negative width values\n\
 (%-10f) will left-pad output.\n\
-\n\
 "), stdout);
 
-      printf (_("\
-\n\
+      printf (_("\n\
 Exit status is 0 if all input numbers were successfully converted.\n\
 By default, %s will stop at the first conversion error with exit status 2.\n\
 With --invalid='fail' a warning is printed for each conversion error\n\
 and the exit status is 2.  With --invalid='warn' each conversion error is\n\
 diagnosed, but the exit status is 0.  With --invalid='ignore' conversion\n\
 errors are not diagnosed and the exit status is 0.\n\
-\n\
 "), program_name);
 
-
-
-      printf (_("\
-\n\
+      printf (_("\n\
 Examples:\n\
   $ %s --to=si 1000\n\
             -> \"1.0K\"\n\
@@ -911,8 +931,7 @@ Examples:\n\
   $ df | %s --header --field 2 --to=si\n\
   $ ls -l | %s --header --field 5 --to=iec\n\
   $ ls -lh | %s --header --field 5 --from=iec --padding=10\n\
-  $ ls -lh | %s --header --field 5 --from=iec --format %%10f\n\
-"),
+  $ ls -lh | %s --header --field 5 --from=iec --format %%10f\n"),
               program_name, program_name, program_name,
               program_name, program_name, program_name,
               program_name, program_name, program_name);
-- 
1.7.0.4