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 <bensb...@justemail.net>
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 <bensb...@justemail.net>
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
