doc: move numfmt info to the 'Numeric operations' section

* doc/coreutils.texi: Move numfmt info to this section,
as numfmt functionality aligns more with seq and factor,
than fmt and pr etc.

1 files changed, 325 insertions, 324 deletions

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 3cbce63c9..ac242bfab 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -243,7 +243,6 @@ Output of entire files
 Formatting file contents
 
 * fmt invocation::               Reformat paragraph text
-* numfmt invocation::            Reformat numbers
 * pr invocation::                Paginate or columnate files for printing
 * fold invocation::              Wrap input lines to fit in specified width
 
@@ -461,6 +460,7 @@ Delaying
 Numeric operations
 
 * factor invocation::            Print prime factors
+* numfmt invocation::            Reformat numbers
 * seq invocation::               Print numeric sequences
 
 File permissions
@@ -2207,7 +2207,6 @@ These commands reformat the contents of files.
 
 @menu
 * fmt invocation::              Reformat paragraph text.
-* numfmt invocation::           Reformat numbers.
 * pr invocation::               Paginate or columnate files for printing.
 * fold invocation::             Wrap input lines to fit in specified width.
 @end menu
@@ -2317,328 +2316,6 @@ leaving the code unchanged.
 
 @exitstatus
 
-@node numfmt invocation
-@section @command{numfmt}: Reformat numbers
-
-@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}
-representation (e.g. @samp{4G} @expansion{} @samp{4,000,000,000}).
-
-@example
-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
-specific columns, maintaining proper line padding and alignment.
-
-@exitstatus
-
-See @option{--invalid} for additional information regarding exit status.
-
-@subsection General options
-
-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{-}, @samp{0}, 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}.  The @samp{0} width modifier
-(without the @samp{-} modifier) will generate leading zeros on the number,
-up to the specified width.
-
-@item --from=@var{unit}
-@opindex --from
-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}
-represents 10 units of 512 bytes, use @samp{--from=unit=512}).
-
-@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 --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
-@opindex --round=up
-@opindex --round=down
-@opindex --round=from-zero
-@opindex --round=towards-zero
-@opindex --round=nearest
-When converting number representations, round the number according to
-@var{method}, which can be @samp{up}, @samp{down},
-@samp{from-zero} (the default), @samp{towards-zero}, @samp{nearest}.
-
-@item --suffix=@var{suffix}
-@opindex --suffix
-Add @samp{SUFFIX} to the output numbers, and accept optional @samp{SUFFIX} in
-input numbers.
-
-@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 --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
-
-@subsection Possible @var{unit}s:
-
-The following are the possible @var{unit} options with @option{--from=UNITS} and
-@option{--to=UNITS}:
-
-@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
-numbers, all digits of the numbers will be printed.
-
-@item si
-Auto-scale numbers according to the @emph{International System of Units (SI)}
-standard.
-For input numbers, accept one of the following suffixes.
-For output numbers, values larger than 1000 will be rounded, and printed with
-one of the following suffixes:
-
-@example
-@samp{K}  =>  @math{1000^1 = 10^3} (Kilo)
-@samp{M}  =>  @math{1000^2 = 10^6} (Mega)
-@samp{G}  =>  @math{1000^3 = 10^9} (Giga)
-@samp{T}  =>  @math{1000^4 = 10^{12}} (Tera)
-@samp{P}  =>  @math{1000^5 = 10^{15}} (Peta)
-@samp{E}  =>  @math{1000^6 = 10^{18}} (Exa)
-@samp{Z}  =>  @math{1000^7 = 10^{21}} (Zetta)
-@samp{Y}  =>  @math{1000^8 = 10^{24}} (Yotta)
-@end example
-
-@item iec
-Auto-scale numbers according to the @emph{International Electrotechnical
-Commission (IEC)} standard.
-For input numbers, accept one of the following suffixes.
-For output numbers, values larger than 1024 will be rounded, and printed with
-one of the following suffixes:
-
-@example
-@samp{K}  =>  @math{1024^1 = 2^{10}} (Kibi)
-@samp{M}  =>  @math{1024^2 = 2^{20}} (Mebi)
-@samp{G}  =>  @math{1024^3 = 2^{30}} (Gibi)
-@samp{T}  =>  @math{1024^4 = 2^{40}} (Tebi)
-@samp{P}  =>  @math{1024^5 = 2^{50}} (Pebi)
-@samp{E}  =>  @math{1024^6 = 2^{60}} (Exbi)
-@samp{Z}  =>  @math{1024^7 = 2^{70}} (Zebi)
-@samp{Y}  =>  @math{1024^8 = 2^{80}} (Yobi)
-@end example
-
-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
-the @option{iec-i} option.
-
-@item iec-i
-Auto-scale numbers according to the @emph{International Electrotechnical
-Commission (IEC)} standard.
-For input numbers, accept one of the following suffixes.
-For output numbers, values larger than 1024 will be rounded, and printed with
-one of the following suffixes:
-
-@example
-@samp{Ki}  =>  @math{1024^1 = 2^{10}} (Kibi)
-@samp{Mi}  =>  @math{1024^2 = 2^{20}} (Mebi)
-@samp{Gi}  =>  @math{1024^3 = 2^{30}} (Gibi)
-@samp{Ti}  =>  @math{1024^4 = 2^{40}} (Tebi)
-@samp{Pi}  =>  @math{1024^5 = 2^{50}} (Pebi)
-@samp{Ei}  =>  @math{1024^6 = 2^{60}} (Exbi)
-@samp{Zi}  =>  @math{1024^7 = 2^{70}} (Zebi)
-@samp{Yi}  =>  @math{1024^8 = 2^{80}} (Yobi)
-@end example
-
-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.
-
-@item auto
-@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
-are interpreted as @emph{IEC} values.
-
-@end table
-
-@subsection Examples of using @command{numfmt}
-
-Converting a single number from/to @emph{human} representation:
-@example
-$ numfmt --to=si 500000
-500K
-
-$ numfmt --to=iec 500000
-489K
-
-$ numfmt --to=iec-i 500000
-489Ki
-
-$ numfmt --from=si 1M
-1000000
-
-$ numfmt --from=iec 1M
-1048576
-
-# with '--from=auto', M=Mega, Mi=Mebi
-$ numfmt --from=auto 1M
-1000000
-$ numfmt --from=auto 1Mi
-1048576
-@end example
-
-Converting from @samp{SI} to @samp{IEC} scales (e.g. when a harddisk capacity is
-advertised as @samp{1TB}, while checking the drive's capacity gives lower
-values):
-
-@example
-$ numfmt --from=si --to=iec 1T
-932G
-@end example
-
-
-Converting a single field from an input file / piped input (these contrived
-examples are for demonstration purposes only, as both @command{ls} and
-@command{df} support the @option{--human-readable} option to
-output sizes in human-readable format):
-
-@example
-# Third field (file size) will be shown in SI representation
-$ ls -log | numfmt --field 3 --header --to=si | head -n4
--rw-r--r--  1     94K Aug 23  2011 ABOUT-NLS
--rw-r--r--  1    3.7K Jan  7 16:15 AUTHORS
--rw-r--r--  1     36K Jun  1  2011 COPYING
--rw-r--r--  1       0 Jan  7 15:15 ChangeLog
-
-# Second field (size) will be shown in IEC representation
-$ df --block-size=1 | numfmt --field 2 --header --to=iec | head -n4
-File system   1B-blocks        Used  Available Use% Mounted on
-rootfs             132G   104741408   26554036  80% /
-tmpfs              794M        7580     804960   1% /run/shm
-/dev/sdb1          694G   651424756   46074696  94% /home
-@end example
-
-
-Output can be tweaked using @option{--padding} or @option{--format}:
-
-@example
-# Pad to 10 characters, right-aligned
-$ du -s * | numfmt --to=si --padding=10
-      2.5K config.log
-       108 config.status
-      1.7K configure
-        20 configure.ac
-
-# Pad to 10 characters, left-aligned
-$ du -s * | numfmt --to=si --padding=-10
-2.5K       config.log
-108        config.status
-1.7K       configure
-20         configure.ac
-
-# Pad to 10 characters, left-aligned, using 'format'
-$ du -s * | numfmt --to=si --format="%10f"
-      2.5K config.log
-       108 config.status
-      1.7K configure
-        20 configure.ac
-
-# Pad to 10 characters, left-aligned, using 'format'
-$ du -s * | numfmt --to=si --padding="%-10f"
-2.5K       config.log
-108        config.status
-1.7K       configure
-20         configure.ac
-@end example
-
-With locales that support grouping digits, using @option{--grouping} or
-@option{--format} enables grouping.  In @samp{POSIX} locale, grouping is
-silently ignored:
-
-@example
-$ LC_ALL=C numfmt --from=iec --grouping 2G
-2147483648
-
-$ LC_ALL=en_US.utf8 numfmt --from=iec --grouping 2G
-2,147,483,648
-
-$ LC_ALL=ta_IN numfmt --from=iec --grouping 2G
-2,14,74,83,648
-
-$ LC_ALL=C ./src/numfmt --from=iec --format="==%'15f==" 2G
-==     2147483648==
-
-$ LC_ALL=en_US.utf8 ./src/numfmt --from=iec --format="==%'15f==" 2G
-==  2,147,483,648==
-
-$ LC_ALL=en_US.utf8 ./src/numfmt --from=iec --format="==%'-15f==" 2G
-==2,147,483,648  ==
-
-$ LC_ALL=ta_IN ./src/numfmt --from=iec --format="==%'15f==" 2G
-== 2,14,74,83,648==
-@end example
-
 @node pr invocation
 @section @command{pr}: Paginate or columnate files for printing
 
@@ -17100,6 +16777,7 @@ These programs do numerically-related operations.
 
 @menu
 * factor invocation::              Show factors of numbers.
+* numfmt invocation::              Reformat numbers.
 * seq invocation::                 Print sequences of numbers.
 @end menu
 
@@ -17162,6 +16840,329 @@ numbers.
 @exitstatus
 
 
+@node numfmt invocation
+@section @command{numfmt}: Reformat numbers
+
+@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}
+representation (e.g. @samp{4G} @expansion{} @samp{4,000,000,000}).
+
+@example
+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
+specific columns, maintaining proper line padding and alignment.
+
+@exitstatus
+
+See @option{--invalid} for additional information regarding exit status.
+
+@subsection General options
+
+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{-}, @samp{0}, 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}.  The @samp{0} width modifier
+(without the @samp{-} modifier) will generate leading zeros on the number,
+up to the specified width.
+
+@item --from=@var{unit}
+@opindex --from
+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}
+represents 10 units of 512 bytes, use @samp{--from=unit=512}).
+
+@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 --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
+@opindex --round=up
+@opindex --round=down
+@opindex --round=from-zero
+@opindex --round=towards-zero
+@opindex --round=nearest
+When converting number representations, round the number according to
+@var{method}, which can be @samp{up}, @samp{down},
+@samp{from-zero} (the default), @samp{towards-zero}, @samp{nearest}.
+
+@item --suffix=@var{suffix}
+@opindex --suffix
+Add @samp{SUFFIX} to the output numbers, and accept optional @samp{SUFFIX} in
+input numbers.
+
+@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 --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
+
+@subsection Possible @var{unit}s:
+
+The following are the possible @var{unit} options with @option{--from=UNITS} and
+@option{--to=UNITS}:
+
+@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
+numbers, all digits of the numbers will be printed.
+
+@item si
+Auto-scale numbers according to the @emph{International System of Units (SI)}
+standard.
+For input numbers, accept one of the following suffixes.
+For output numbers, values larger than 1000 will be rounded, and printed with
+one of the following suffixes:
+
+@example
+@samp{K}  =>  @math{1000^1 = 10^3} (Kilo)
+@samp{M}  =>  @math{1000^2 = 10^6} (Mega)
+@samp{G}  =>  @math{1000^3 = 10^9} (Giga)
+@samp{T}  =>  @math{1000^4 = 10^{12}} (Tera)
+@samp{P}  =>  @math{1000^5 = 10^{15}} (Peta)
+@samp{E}  =>  @math{1000^6 = 10^{18}} (Exa)
+@samp{Z}  =>  @math{1000^7 = 10^{21}} (Zetta)
+@samp{Y}  =>  @math{1000^8 = 10^{24}} (Yotta)
+@end example
+
+@item iec
+Auto-scale numbers according to the @emph{International Electrotechnical
+Commission (IEC)} standard.
+For input numbers, accept one of the following suffixes.
+For output numbers, values larger than 1024 will be rounded, and printed with
+one of the following suffixes:
+
+@example
+@samp{K}  =>  @math{1024^1 = 2^{10}} (Kibi)
+@samp{M}  =>  @math{1024^2 = 2^{20}} (Mebi)
+@samp{G}  =>  @math{1024^3 = 2^{30}} (Gibi)
+@samp{T}  =>  @math{1024^4 = 2^{40}} (Tebi)
+@samp{P}  =>  @math{1024^5 = 2^{50}} (Pebi)
+@samp{E}  =>  @math{1024^6 = 2^{60}} (Exbi)
+@samp{Z}  =>  @math{1024^7 = 2^{70}} (Zebi)
+@samp{Y}  =>  @math{1024^8 = 2^{80}} (Yobi)
+@end example
+
+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
+the @option{iec-i} option.
+
+@item iec-i
+Auto-scale numbers according to the @emph{International Electrotechnical
+Commission (IEC)} standard.
+For input numbers, accept one of the following suffixes.
+For output numbers, values larger than 1024 will be rounded, and printed with
+one of the following suffixes:
+
+@example
+@samp{Ki}  =>  @math{1024^1 = 2^{10}} (Kibi)
+@samp{Mi}  =>  @math{1024^2 = 2^{20}} (Mebi)
+@samp{Gi}  =>  @math{1024^3 = 2^{30}} (Gibi)
+@samp{Ti}  =>  @math{1024^4 = 2^{40}} (Tebi)
+@samp{Pi}  =>  @math{1024^5 = 2^{50}} (Pebi)
+@samp{Ei}  =>  @math{1024^6 = 2^{60}} (Exbi)
+@samp{Zi}  =>  @math{1024^7 = 2^{70}} (Zebi)
+@samp{Yi}  =>  @math{1024^8 = 2^{80}} (Yobi)
+@end example
+
+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.
+
+@item auto
+@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
+are interpreted as @emph{IEC} values.
+
+@end table
+
+@subsection Examples of using @command{numfmt}
+
+Converting a single number from/to @emph{human} representation:
+@example
+$ numfmt --to=si 500000
+500K
+
+$ numfmt --to=iec 500000
+489K
+
+$ numfmt --to=iec-i 500000
+489Ki
+
+$ numfmt --from=si 1M
+1000000
+
+$ numfmt --from=iec 1M
+1048576
+
+# with '--from=auto', M=Mega, Mi=Mebi
+$ numfmt --from=auto 1M
+1000000
+$ numfmt --from=auto 1Mi
+1048576
+@end example
+
+Converting from @samp{SI} to @samp{IEC} scales (e.g. when a harddisk capacity is
+advertised as @samp{1TB}, while checking the drive's capacity gives lower
+values):
+
+@example
+$ numfmt --from=si --to=iec 1T
+932G
+@end example
+
+
+Converting a single field from an input file / piped input (these contrived
+examples are for demonstration purposes only, as both @command{ls} and
+@command{df} support the @option{--human-readable} option to
+output sizes in human-readable format):
+
+@example
+# Third field (file size) will be shown in SI representation
+$ ls -log | numfmt --field 3 --header --to=si | head -n4
+-rw-r--r--  1     94K Aug 23  2011 ABOUT-NLS
+-rw-r--r--  1    3.7K Jan  7 16:15 AUTHORS
+-rw-r--r--  1     36K Jun  1  2011 COPYING
+-rw-r--r--  1       0 Jan  7 15:15 ChangeLog
+
+# Second field (size) will be shown in IEC representation
+$ df --block-size=1 | numfmt --field 2 --header --to=iec | head -n4
+File system   1B-blocks        Used  Available Use% Mounted on
+rootfs             132G   104741408   26554036  80% /
+tmpfs              794M        7580     804960   1% /run/shm
+/dev/sdb1          694G   651424756   46074696  94% /home
+@end example
+
+
+Output can be tweaked using @option{--padding} or @option{--format}:
+
+@example
+# Pad to 10 characters, right-aligned
+$ du -s * | numfmt --to=si --padding=10
+      2.5K config.log
+       108 config.status
+      1.7K configure
+        20 configure.ac
+
+# Pad to 10 characters, left-aligned
+$ du -s * | numfmt --to=si --padding=-10
+2.5K       config.log
+108        config.status
+1.7K       configure
+20         configure.ac
+
+# Pad to 10 characters, left-aligned, using 'format'
+$ du -s * | numfmt --to=si --format="%10f"
+      2.5K config.log
+       108 config.status
+      1.7K configure
+        20 configure.ac
+
+# Pad to 10 characters, left-aligned, using 'format'
+$ du -s * | numfmt --to=si --padding="%-10f"
+2.5K       config.log
+108        config.status
+1.7K       configure
+20         configure.ac
+@end example
+
+With locales that support grouping digits, using @option{--grouping} or
+@option{--format} enables grouping.  In @samp{POSIX} locale, grouping is
+silently ignored:
+
+@example
+$ LC_ALL=C numfmt --from=iec --grouping 2G
+2147483648
+
+$ LC_ALL=en_US.utf8 numfmt --from=iec --grouping 2G
+2,147,483,648
+
+$ LC_ALL=ta_IN numfmt --from=iec --grouping 2G
+2,14,74,83,648
+
+$ LC_ALL=C ./src/numfmt --from=iec --format="==%'15f==" 2G
+==     2147483648==
+
+$ LC_ALL=en_US.utf8 ./src/numfmt --from=iec --format="==%'15f==" 2G
+==  2,147,483,648==
+
+$ LC_ALL=en_US.utf8 ./src/numfmt --from=iec --format="==%'-15f==" 2G
+==2,147,483,648  ==
+
+$ LC_ALL=ta_IN ./src/numfmt --from=iec --format="==%'15f==" 2G
+== 2,14,74,83,648==
+@end example
+
+
 @node seq invocation
 @section @command{seq}: Print numeric sequences