mirror of
https://https.git.savannah.gnu.org/git/coreutils.git
synced 2026-01-27 01:44:21 +00:00
doc: standardize helptext of numfmt and slice into single options
* src/numfmt.c (usage): Correct synopsis and make command description clearer. 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; sort options alphabetically. * doc/coreutils.texi (numfmt invocation): Sort numfmt options alphabetically. Enforce double-blank-after-period style. This addresses http://bugs.gnu.org/13681. Improved-by: Bernhard Voelker
This commit is contained in:
Benno Schulenberg
Bernhard Voelker
parent
3309e880fb
commit
b5f45b640c
@ -2242,7 +2242,7 @@ leaving the code unchanged.
|
||||
@pindex numfmt
|
||||
|
||||
@command{numfmt} reads numbers in various representations and reformats them
|
||||
as requested. The most common usage is converting numbers to/from @emph{human}
|
||||
as requested. The most common usage is converting numbers to/from @emph{human}
|
||||
representation (e.g. @samp{4G} @expansion{} @samp{4,000,000,000}).
|
||||
|
||||
@example
|
||||
@ -2250,8 +2250,8 @@ numfmt [@var{option}]@dots{} [@var{number}]
|
||||
@end example
|
||||
|
||||
@command{numfmt} converts each @var{number} on the command-line according to the
|
||||
specified options (see below). If no @var{number}s are given, it reads numbers
|
||||
from standard input. @command{numfmt} can optionally extract numbers from
|
||||
specified options (see below). If no @var{number}s are given, it reads numbers
|
||||
from standard input. @command{numfmt} can optionally extract numbers from
|
||||
specific columns, maintaining proper line padding and alignment.
|
||||
|
||||
@exitstatus
|
||||
@ -2264,28 +2264,67 @@ The program accepts the following options. Also see @ref{Common options}.
|
||||
|
||||
@table @samp
|
||||
|
||||
@item --debug
|
||||
@opindex --debug
|
||||
Print (to standard error) warning messages about possible erroneous usage.
|
||||
|
||||
@item -d @var{d}
|
||||
@itemx --delimiter=@var{d}
|
||||
@opindex -d
|
||||
@opindex --delimiter
|
||||
Use the character @var{d} as input field separator (default: whitespace).
|
||||
@emph{Note}: Using non-default delimiter turns off automatic padding.
|
||||
|
||||
@item --field=@var{n}
|
||||
@opindex --field
|
||||
Convert the number in input field @var{n} (default: 1).
|
||||
|
||||
@item --format=@var{format}
|
||||
@opindex --format
|
||||
Use printf-style floating FORMAT string. The @var{format} string must contain
|
||||
one @samp{%f} directive, optionally with @samp{'}, @samp{-}, or width
|
||||
modifiers. The @samp{'} modifier will enable @option{--grouping}, the @samp{-}
|
||||
modifier will enable left-aligned @option{--padding} and the width modifier will
|
||||
enable right-aligned @option{--padding}.
|
||||
|
||||
@item --from=@var{unit}
|
||||
@opindex --from
|
||||
Auto-scales input numbers according to @var{unit}. See @emph{Units} below.
|
||||
Auto-scales input numbers according to @var{unit}. See UNITS below.
|
||||
The default is no scaling, meaning suffixes (e.g. @samp{M}, @samp{G}) will
|
||||
trigger an error.
|
||||
|
||||
@item --from-unit=@var{n}
|
||||
@opindex --from-unit
|
||||
Specify the input unit size (instead of the default 1). Use this option when the
|
||||
input numbers represent other units (e.g. if the input number @samp{10}
|
||||
Specify the input unit size (instead of the default 1). Use this option when
|
||||
the input numbers represent other units (e.g. if the input number @samp{10}
|
||||
represents 10 units of 512 bytes, use @samp{--from=unit=512}).
|
||||
|
||||
@item --to=@var{unit}
|
||||
@opindex --to
|
||||
Auto-scales output numbers according to @var{unit}. See @emph{Units} below.
|
||||
The default is no scaling, meaning all the digits of the number are printed.
|
||||
@item --grouping
|
||||
@opindex --grouping
|
||||
Group digits in output numbers according to the current locale's grouping rules
|
||||
(e.g @emph{Thousands Separator} character, commonly @samp{.} (dot) or @samp{,}
|
||||
comma). This option has no effect in @samp{POSIX/C} locale.
|
||||
|
||||
@item --to-unit=@var{n}
|
||||
@opindex --to-unit
|
||||
Specify the output unit size (instead of the default 1). Use this option when
|
||||
the output numbers represent other units (e.g. to represent @samp{4,000,000}
|
||||
bytes in blocks of 1KB, use @samp{--to=si --to=units=1000}).
|
||||
@item --header[=@var{n}]
|
||||
@opindex --header
|
||||
@opindex --header=N
|
||||
Print the first @var{n} (default: 1) lines without any conversion.
|
||||
|
||||
@item --invalid=@var{mode}
|
||||
@opindex --invalid
|
||||
The default action on input errors is to exit immediately with status code 2.
|
||||
@option{--invalid=@samp{abort}} explicitly specifies this default mode.
|
||||
With a @var{mode} of @samp{fail}, print a warning for @emph{each} conversion
|
||||
error, and exit with status 2. With a @var{mode} of @samp{warn}, exit with
|
||||
status 0, even in the presence of conversion errors, and with a @var{mode} of
|
||||
@samp{ignore} do not even print diagnostics.
|
||||
|
||||
@item --padding=@var{n}
|
||||
@opindex --padding
|
||||
Pad the output numbers to @var{n} characters, by adding spaces. If @var{n} is
|
||||
a positive number, numbers will be right-aligned. If @var{n} is a negative
|
||||
number, numbers will be left-aligned. By default, numbers are automatically
|
||||
aligned based on the input line's width (only with the default delimiter).
|
||||
|
||||
@item --round=@var{method}
|
||||
@opindex --round
|
||||
@ -2303,55 +2342,16 @@ When converting number representations, round the number according to
|
||||
Add @samp{SUFFIX} to the output numbers, and accept optional @samp{SUFFIX} in
|
||||
input numbers.
|
||||
|
||||
@item --padding=@var{n}
|
||||
@opindex --padding
|
||||
Pad the output numbers to @var{n} characters, by adding spaces. If @var{n} is
|
||||
a positive number, numbers will be right-aligned. If @var{n} is a negative
|
||||
number, numbers will be left-aligned. By default, numbers are automatically
|
||||
aligned based on the input line's width (only with the default delimiter).
|
||||
@item --to=@var{unit}
|
||||
@opindex --to
|
||||
Auto-scales output numbers according to @var{unit}. See @emph{Units} below.
|
||||
The default is no scaling, meaning all the digits of the number are printed.
|
||||
|
||||
@item --grouping
|
||||
@opindex --grouping
|
||||
Group digits in output numbers according to the current locale's grouping rules
|
||||
(e.g @emph{Thousands Separator} character, commonly @samp{.} (dot) or @samp{,}
|
||||
comma). This option has no effect in @samp{POSIX/C} locale.
|
||||
|
||||
@item --header[=@var{n}]
|
||||
@opindex --header
|
||||
@opindex --header=N
|
||||
Print the first @var{n} (default: 1) lines without any conversion.
|
||||
|
||||
@item --field=@var{n}
|
||||
@opindex --field
|
||||
Convert the number in input field @var{n} (default: 1).
|
||||
|
||||
@item --format=@var{format}
|
||||
@opindex --format
|
||||
Use printf-style floating FORMAT string. The @var{format} string must contain
|
||||
one @samp{%f} directive, optionally with @samp{'}, @samp{-}, or width
|
||||
modifiers. @samp{'} modified will enable @option{--grouping}. @samp{-} modifier
|
||||
will enable left-aligned @option{--padding}. Width modifier will enable
|
||||
right-aligned @option{--padding}.
|
||||
|
||||
@item --invalid=@var{mode}
|
||||
@opindex --invalid
|
||||
The default action on input errors is to exit immediately with status code 2.
|
||||
@option{--invalid=@samp{abort}} explicitly specifies this default mode.
|
||||
With a @var{mode} of @samp{fail}, print a warning for @emph{each} conversion
|
||||
error, and exit with status 2. With a @var{mode} of @samp{warn}, exit with
|
||||
status 0, even in the presence of conversion errors, and with a @var{mode} of
|
||||
@samp{ignore} do not even print diagnostics.
|
||||
|
||||
@item -d @var{d}
|
||||
@itemx --delimiter=@var{d}
|
||||
@opindex -d
|
||||
@opindex --delimiter
|
||||
Use the character @var{d} as input field separator (default: whitespace).
|
||||
@emph{Note}: Using non-default delimiter turns off automatic padding.
|
||||
|
||||
@item --debug
|
||||
@opindex --debug
|
||||
Print (to standard error) warning messages about possible erroneous usage.
|
||||
@item --to-unit=@var{n}
|
||||
@opindex --to-unit
|
||||
Specify the output unit size (instead of the default 1). Use this option when
|
||||
the output numbers represent other units (e.g. to represent @samp{4,000,000}
|
||||
bytes in blocks of 1KB, use @samp{--to=si --to=units=1000}).
|
||||
|
||||
@end table
|
||||
|
||||
@ -2363,8 +2363,8 @@ The following are the possible @var{unit} options with @option{--from=UNITS} and
|
||||
@table @var
|
||||
|
||||
@item none
|
||||
No scaling is performed. For input numbers, no suffixes are accepted, and any
|
||||
trailing characters following the number will trigger an error. For output
|
||||
No scaling is performed. For input numbers, no suffixes are accepted, and any
|
||||
trailing characters following the number will trigger an error. For output
|
||||
numbers, all digits of the numbers will be printed.
|
||||
|
||||
@item si
|
||||
@ -2405,7 +2405,7 @@ one of the following suffixes:
|
||||
|
||||
The @option{iec} option uses a single letter suffix (e.g. @samp{G}), which is
|
||||
not fully standard, as the @emph{iec} standard recommends a two-letter symbol
|
||||
(e.g @samp{Gi}) - but in practice, this method common. Compare with
|
||||
(e.g @samp{Gi}) - but in practice, this method common. Compare with
|
||||
the @option{iec-i} option.
|
||||
|
||||
@item iec-i
|
||||
@ -2428,10 +2428,10 @@ one of the following suffixes:
|
||||
|
||||
The @option{iec-i} option uses a two-letter suffix symbol (e.g. @samp{Gi}),
|
||||
as the @emph{iec} standard recommends, but this is not always common in
|
||||
practice. Compare with the @option{iec} option.
|
||||
practice. Compare with the @option{iec} option.
|
||||
|
||||
@item auto
|
||||
@samp{auto} can only be used with @option{--from}. With this method, numbers
|
||||
@samp{auto} can only be used with @option{--from}. With this method, numbers
|
||||
with @samp{K},@samp{M},@samp{G},@samp{T},@samp{P},@samp{E},@samp{Z},@samp{Y}
|
||||
suffixes are interpreted as @emph{SI} values, and numbers with @samp{Ki},
|
||||
@samp{Mi},@samp{Gi},@samp{Ti},@samp{Pi},@samp{Ei},@samp{Zi},@samp{Yi} suffixes
|
||||
@ -2530,8 +2530,8 @@ $ du -s * | numfmt --to=si --padding="%-10f"
|
||||
@end example
|
||||
|
||||
With locales that support grouping digits, using @option{--grouping} or
|
||||
@option{--format} enables grouping. In @samp{POSIX} locale, grouping is silently
|
||||
ignored:
|
||||
@option{--format} enables grouping. In @samp{POSIX} locale, grouping is
|
||||
silently ignored:
|
||||
|
||||
@example
|
||||
$ LC_ALL=C numfmt --from=iec --grouping 2G
|
||||
|
||||
144
src/numfmt.c
144
src/numfmt.c
@ -796,93 +796,114 @@ 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 (_("\
|
||||
--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\
|
||||
up, down, from-zero (default), towards-zero, nearest\n\
|
||||
--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\
|
||||
--field N replace the number in input field N (default is 1)\n\
|
||||
-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\
|
||||
--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\
|
||||
--debug print warnings about invalid input\n\
|
||||
"), stdout);
|
||||
fputs (_("\
|
||||
-d, --delimiter=X use X instead of whitespace for field delimiter\n\
|
||||
"), stdout);
|
||||
fputs (_("\
|
||||
--field=N replace the number in input field N (default is 1)\n\
|
||||
"), stdout);
|
||||
fputs (_("\
|
||||
--format=FORMAT use printf style floating-point FORMAT;\n\
|
||||
see FORMAT below for details\n\
|
||||
"), stdout);
|
||||
fputs (_("\
|
||||
--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 (_("\
|
||||
--grouping use locale-defined grouping of digits, e.g. 1,000,000\n\
|
||||
(which means it has 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 (_("\
|
||||
--invalid=MODE failure mode for invalid numbers: MODE can be:\n\
|
||||
abort (default), fail, warn, ignore\n\
|
||||
"), stdout);
|
||||
fputs (_("\
|
||||
--padding=N pad the output to N characters; positive N will\n\
|
||||
right-align; negative N will left-align;\n\
|
||||
padding is ignored if the output is wider than N;\n\
|
||||
the default is to automatically pad if a whitespace\n\
|
||||
is found\n\
|
||||
"), stdout);
|
||||
fputs (_("\
|
||||
--round=METHOD use METHOD for rounding 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\n\
|
||||
SUFFIX in input numbers\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 (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\
|
||||
UNIT options:\n"), stdout);
|
||||
fputs (_("\
|
||||
none no auto-scaling is done; suffixes will trigger an error\n\
|
||||
"), stdout);
|
||||
|
||||
fputs (_("\
|
||||
\n\
|
||||
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\
|
||||
@ -897,8 +918,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);
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user