[PATCH] doc: move numfmt info to the 'Numeric operations' section

[Pádraig Brady]

* doc/coreutils.texi: Move numfmt info to this section,
as numfmt functionality aligns more with seq and factor,
than fmt and pr etc.
---
 doc/coreutils.texi | 1403 ++++++++++++++++++++++++++--------------------------
 1 file changed, 702 insertions(+), 701 deletions(-)

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 6110cec..819e31f 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,508 +2316,186 @@ leaving the code unchanged.
 
 @exitstatus
 
-@node numfmt invocation
-@section @command{numfmt}: Reformat numbers
+@node pr invocation
+@section @command{pr}: Paginate or columnate files for printing
 
-@pindex numfmt
+@pindex pr
+@cindex printing, preparing files for
+@cindex multicolumn output, generating
+@cindex merging files in parallel
 
-@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}).
+@command{pr} writes each @var{file} (@samp{-} means standard input), or
+standard input if none are given, to standard output, paginating and
+optionally outputting in multicolumn format; optionally merges all
+@var{file}s, printing all in parallel, one per column.  Synopsis:
 
 @example
-numfmt [@var{option}]@dots{} [@var{number}]
+pr [@var{option}]@dots{} [@var{file}]@dots{}
 @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
+@vindex LC_MESSAGES
+By default, a 5-line header is printed at each page: two blank lines;
+a line with the date, the file name, and the page count; and two more
+blank lines.  A footer of five blank lines is also printed.
+The default @var{page_length} is 66
+lines.  The default number of text lines is therefore 56.
+The text line of the header takes the form
+@samp{@var{date} @var{string} @var{page}}, with spaces inserted around
+@var{string} so that the line takes up the full @var{page_width}.  Here,
+@var{date} is the date (see the @option{-D} or @option{--date-format}
+option for details), @var{string} is the centered header string, and
+@var{page} identifies the page number.  The @env{LC_MESSAGES} locale
+category affects the spelling of @var{page}; in the default C locale, it
+is @samp{Page @var{number}} where @var{number} is the decimal page
+number.
 
-See @option{--invalid} for additional information regarding exit status.
+Form feeds in the input cause page breaks in the output.  Multiple form
+feeds produce empty pages.
 
-@subsection General options
+Columns are of equal width, separated by an optional string (default
+is @samp{space}).  For multicolumn output, lines will always be truncated to
+@var{page_width} (default 72), unless you use the @option{-J} option.
+For single
+column output no line truncation occurs by default.  Use @option{-W} option to
+truncate lines in that case.
 
 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 +@var{first_page}[:@var{last_page}]
+@itemx --pages=@var{first_page}[:@var{last_page}]
+@c The two following @opindex lines evoke warnings because they contain ':'
+@c The 'info' spec does not permit that.  If we use those lines, we end
+@c up with truncated index entries that don't work.
+@c @opindex +@var{first_page}[:@var{last_page}]
+@c @opindex --pages=@var{first_page}[:@var{last_page}]
+@opindex +@var{page_range}
+@opindex --pages=@var{page_range}
+Begin printing with page @var{first_page} and stop with @var{last_page}.
+Missing @samp{:@var{last_page}} implies end of file.  While estimating
+the number of skipped pages each form feed in the input file results
+in a new page.  Page counting with and without @samp{+@var{first_page}}
+is identical.  By default, counting starts with the first page of input
+file (not first page printed).  Line numbering may be altered by @option{-N}
+option.
 
-@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 -@var{column}
+@itemx --columns=@var{column}
+@opindex -@var{column}
+@opindex --columns
+@cindex down columns
+With each single @var{file}, produce @var{column} columns of output
+(default is 1) and print columns down, unless @option{-a} is used.  The
+column width is automatically decreased as @var{column} increases; unless
+you use the @option{-W/-w} option to increase @var{page_width} as well.
+This option might well cause some lines to be truncated.  The number of
+lines in the columns on each page are balanced.  The options @option{-e}
+and @option{-i} are on for multiple text-column output.  Together with
+@option{-J} option column alignment and line truncation is turned off.
+Lines of full length are joined in a free field format and @option{-S}
+option may set field separators.  @option{-@var{column}} may not be used
+with @option{-m} option.
 
-@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 -a
+@itemx --across
+@opindex -a
+@opindex --across
+@cindex across columns
+With each single @var{file}, print columns across rather than down.  The
+@option{-@var{column}} option must be given with @var{column} greater than one.
+If a line is too long to fit in a column, it is truncated.
 
-@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 -c
+@itemx --show-control-chars
+@opindex -c
+@opindex --show-control-chars
+Print control characters using hat notation (e.g., @samp{^G}); print
+other nonprinting characters in octal backslash notation.  By default,
+nonprinting characters are not changed.
 
-@item --header[=@var{n}]
-@opindex --header
-@opindex --header=N
-Print the first @var{n} (default: 1) lines without any conversion.
+@item -d
+@itemx --double-space
+@opindex -d
+@opindex --double-space
+@cindex double spacing
+Double space the output.
 
-@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{format}
+@itemx --date-format=@var{format}
+@cindex time formats
+@cindex formatting times
+Format header dates using @var{format}, using the same conventions as
+for the command @samp{date +@var{format}}.  @xref{date invocation}.
+Except for directives, which start with
+@samp{%}, characters in @var{format} are printed unchanged.  You can use
+this option to specify an arbitrary string in place of the header date,
+e.g., @option{--date-format="Monday morning"}.
 
-@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).
+@vindex POSIXLY_CORRECT
+@vindex LC_TIME
+The default date format is @samp{%Y-%m-%d %H:%M} (for example,
+@samp{2001-12-04 23:59});
+but if the @env{POSIXLY_CORRECT} environment variable is set
+and the @env{LC_TIME} locale category specifies the POSIX
+locale, the default is @samp{%b %e %H:%M %Y} (for example,
+@samp{Dec@ @ 4 23:59 2001}.
 
-@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}.
+@vindex TZ
+Time stamps are listed according to the time zone rules specified by
+the @env{TZ} environment variable, or by the system default rules if
+@env{TZ} is not set.  @xref{TZ Variable,, Specifying the Time Zone
+with @env{TZ}, libc, The GNU C Library Reference Manual}.
 
-@item --suffix=@var{suffix}
-@opindex --suffix
-Add @samp{SUFFIX} to the output numbers, and accept optional @samp{SUFFIX} in
-input numbers.
+@item -e[@var{in-tabchar}[@var{in-tabwidth}]]
+@itemx --expand-tabs[=@var{in-tabchar}[@var{in-tabwidth}]]
+@opindex -e
+@opindex --expand-tabs
+@cindex input tabs
+Expand @var{tab}s to spaces on input.  Optional argument @var{in-tabchar} is
+the input tab character (default is the TAB character).  Second optional
+argument @var{in-tabwidth} is the input tab character's width (default
+is 8).
 
-@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 -f
+@itemx -F
+@itemx --form-feed
+@opindex -F
+@opindex -f
+@opindex --form-feed
+Use a form feed instead of newlines to separate output pages.  This does
+not alter the default page length of 66 lines.
 
-@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 -h @var{header}
+@itemx --header=@var{header}
+@opindex -h
+@opindex --header
+Replace the file name in the header with the centered string @var{header}.
+When using the shell, @var{header} should be quoted and should be
+separated from @option{-h} by a space.
 
-@end table
+@item -i[@var{out-tabchar}[@var{out-tabwidth}]]
+@itemx --output-tabs[=@var{out-tabchar}[@var{out-tabwidth}]]
+@opindex -i
+@opindex --output-tabs
+@cindex output tabs
+Replace spaces with @var{tab}s on output.  Optional argument @var{out-tabchar}
+is the output tab character (default is the TAB character).  Second optional
+argument @var{out-tabwidth} is the output tab character's width (default
+is 8).
 
-@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
-
-@pindex pr
-@cindex printing, preparing files for
-@cindex multicolumn output, generating
-@cindex merging files in parallel
-
-@command{pr} writes each @var{file} (@samp{-} means standard input), or
-standard input if none are given, to standard output, paginating and
-optionally outputting in multicolumn format; optionally merges all
-@var{file}s, printing all in parallel, one per column.  Synopsis:
-
-@example
-pr [@var{option}]@dots{} [@var{file}]@dots{}
-@end example
-
-@vindex LC_MESSAGES
-By default, a 5-line header is printed at each page: two blank lines;
-a line with the date, the file name, and the page count; and two more
-blank lines.  A footer of five blank lines is also printed.
-The default @var{page_length} is 66
-lines.  The default number of text lines is therefore 56.
-The text line of the header takes the form
-@samp{@var{date} @var{string} @var{page}}, with spaces inserted around
-@var{string} so that the line takes up the full @var{page_width}.  Here,
-@var{date} is the date (see the @option{-D} or @option{--date-format}
-option for details), @var{string} is the centered header string, and
-@var{page} identifies the page number.  The @env{LC_MESSAGES} locale
-category affects the spelling of @var{page}; in the default C locale, it
-is @samp{Page @var{number}} where @var{number} is the decimal page
-number.
-
-Form feeds in the input cause page breaks in the output.  Multiple form
-feeds produce empty pages.
-
-Columns are of equal width, separated by an optional string (default
-is @samp{space}).  For multicolumn output, lines will always be truncated to
-@var{page_width} (default 72), unless you use the @option{-J} option.
-For single
-column output no line truncation occurs by default.  Use @option{-W} option to
-truncate lines in that case.
-
-The program accepts the following options.  Also see @ref{Common options}.
-
-@table @samp
-
-@item +@var{first_page}[:@var{last_page}]
-@itemx --pages=@var{first_page}[:@var{last_page}]
-@c The two following @opindex lines evoke warnings because they contain ':'
-@c The 'info' spec does not permit that.  If we use those lines, we end
-@c up with truncated index entries that don't work.
-@c @opindex +@var{first_page}[:@var{last_page}]
-@c @opindex --pages=@var{first_page}[:@var{last_page}]
-@opindex +@var{page_range}
-@opindex --pages=@var{page_range}
-Begin printing with page @var{first_page} and stop with @var{last_page}.
-Missing @samp{:@var{last_page}} implies end of file.  While estimating
-the number of skipped pages each form feed in the input file results
-in a new page.  Page counting with and without @samp{+@var{first_page}}
-is identical.  By default, counting starts with the first page of input
-file (not first page printed).  Line numbering may be altered by @option{-N}
-option.
-
-@item -@var{column}
-@itemx --columns=@var{column}
-@opindex -@var{column}
-@opindex --columns
-@cindex down columns
-With each single @var{file}, produce @var{column} columns of output
-(default is 1) and print columns down, unless @option{-a} is used.  The
-column width is automatically decreased as @var{column} increases; unless
-you use the @option{-W/-w} option to increase @var{page_width} as well.
-This option might well cause some lines to be truncated.  The number of
-lines in the columns on each page are balanced.  The options @option{-e}
-and @option{-i} are on for multiple text-column output.  Together with
-@option{-J} option column alignment and line truncation is turned off.
-Lines of full length are joined in a free field format and @option{-S}
-option may set field separators.  @option{-@var{column}} may not be used
-with @option{-m} option.
-
-@item -a
-@itemx --across
-@opindex -a
-@opindex --across
-@cindex across columns
-With each single @var{file}, print columns across rather than down.  The
-@option{-@var{column}} option must be given with @var{column} greater than one.
-If a line is too long to fit in a column, it is truncated.
-
-@item -c
-@itemx --show-control-chars
-@opindex -c
-@opindex --show-control-chars
-Print control characters using hat notation (e.g., @samp{^G}); print
-other nonprinting characters in octal backslash notation.  By default,
-nonprinting characters are not changed.
-
-@item -d
-@itemx --double-space
-@opindex -d
-@opindex --double-space
-@cindex double spacing
-Double space the output.
-
-@item -D @var{format}
-@itemx --date-format=@var{format}
-@cindex time formats
-@cindex formatting times
-Format header dates using @var{format}, using the same conventions as
-for the command @samp{date +@var{format}}.  @xref{date invocation}.
-Except for directives, which start with
-@samp{%}, characters in @var{format} are printed unchanged.  You can use
-this option to specify an arbitrary string in place of the header date,
-e.g., @option{--date-format="Monday morning"}.
-
-@vindex POSIXLY_CORRECT
-@vindex LC_TIME
-The default date format is @samp{%Y-%m-%d %H:%M} (for example,
-@samp{2001-12-04 23:59});
-but if the @env{POSIXLY_CORRECT} environment variable is set
-and the @env{LC_TIME} locale category specifies the POSIX
-locale, the default is @samp{%b %e %H:%M %Y} (for example,
-@samp{Dec@ @ 4 23:59 2001}.
-
-@vindex TZ
-Time stamps are listed according to the time zone rules specified by
-the @env{TZ} environment variable, or by the system default rules if
-@env{TZ} is not set.  @xref{TZ Variable,, Specifying the Time Zone
-with @env{TZ}, libc, The GNU C Library Reference Manual}.
-
-@item -e[@var{in-tabchar}[@var{in-tabwidth}]]
-@itemx --expand-tabs[=@var{in-tabchar}[@var{in-tabwidth}]]
-@opindex -e
-@opindex --expand-tabs
-@cindex input tabs
-Expand @var{tab}s to spaces on input.  Optional argument @var{in-tabchar} is
-the input tab character (default is the TAB character).  Second optional
-argument @var{in-tabwidth} is the input tab character's width (default
-is 8).
-
-@item -f
-@itemx -F
-@itemx --form-feed
-@opindex -F
-@opindex -f
-@opindex --form-feed
-Use a form feed instead of newlines to separate output pages.  This does
-not alter the default page length of 66 lines.
-
-@item -h @var{header}
-@itemx --header=@var{header}
-@opindex -h
-@opindex --header
-Replace the file name in the header with the centered string @var{header}.
-When using the shell, @var{header} should be quoted and should be
-separated from @option{-h} by a space.
-
-@item -i[@var{out-tabchar}[@var{out-tabwidth}]]
-@itemx --output-tabs[=@var{out-tabchar}[@var{out-tabwidth}]]
-@opindex -i
-@opindex --output-tabs
-@cindex output tabs
-Replace spaces with @var{tab}s on output.  Optional argument @var{out-tabchar}
-is the output tab character (default is the TAB character).  Second optional
-argument @var{out-tabwidth} is the output tab character's width (default
-is 8).
-
-@item -J
-@itemx --join-lines
-@opindex -J
-@opindex --join-lines
-Merge lines of full length.  Used together with the column options
-@option{-@var{column}}, @option{-a -@var{column}} or @option{-m}.  Turns off
-@option{-W/-w} line truncation;
-no column alignment used; may be used with
-@option{--sep-string[=@var{string}]}.  @option{-J} has been introduced
-(together with @option{-W} and @option{--sep-string})
-to disentangle the old (POSIX-compliant) options @option{-w} and
-@option{-s} along with the three column options.
+@item -J
+@itemx --join-lines
+@opindex -J
+@opindex --join-lines
+Merge lines of full length.  Used together with the column options
+@option{-@var{column}}, @option{-a -@var{column}} or @option{-m}.  Turns off
+@option{-W/-w} line truncation;
+no column alignment used; may be used with
+@option{--sep-string[=@var{string}]}.  @option{-J} has been introduced
+(together with @option{-W} and @option{--sep-string})
+to disentangle the old (POSIX-compliant) options @option{-w} and
+@option{-s} along with the three column options.
 
 
 @item -l @var{page_length}
@@ -16864,301 +16541,625 @@ the exit status of @var{command} otherwise
 @end display
 
 
-@node timeout invocation
-@section @command{timeout}: Run a command with a time limit
+@node timeout invocation
+@section @command{timeout}: Run a command with a time limit
+
+@pindex timeout
+@cindex time limit
+@cindex run commands with bounded time
+
+@command{timeout} runs the given @var{command} and kills it if it is
+still running after the specified time interval.  Synopsis:
+
+@example
+timeout [@var{option}] @var{duration} @var{command} [@var{arg}]@dots{}
+@end example
+
+@var{command} must not be a special built-in utility (@pxref{Special
+built-in utilities}).
+
+The program accepts the following options.  Also see @ref{Common options}.
+Options must precede operands.
+
+@table @samp
+@item --preserve-status
+@opindex --preserve-status
+Return the exit status of the managed @var{command} on timeout, rather than
+a specific exit status indicating a timeout.  This is useful if the
+managed @var{command} supports running for an indeterminate amount of time.
+
+@item --foreground
+@opindex --foreground
+Don't create a separate background program group, so that
+the managed @var{command} can use the foreground TTY normally.
+This is needed to support timing out commands not started
+directly from an interactive shell, in two situations.
+@enumerate
+@item
+@var{command} is interactive and needs to read from the terminal for example
+@item
+the user wants to support sending signals directly to @var{command}
+from the terminal (like Ctrl-C for example)
+@end enumerate
+
+Note in this mode of operation, any children of @var{command}
+will not be timed out.
+
+@item -k @var{duration}
+@itemx --kill-after=@var{duration}
+@opindex -k
+@opindex --kill-after
+Ensure the monitored @var{command} is killed by also sending a @samp{KILL}
+signal, after the specified @var{duration}.  Without this option, if the
+selected signal proves not to be fatal, @command{timeout} does not kill
+the @var{command}.
+
+@item -s @var{signal}
+@itemx --signal=@var{signal}
+@opindex -s
+@opindex --signal
+Send this @var{signal} to @var{command} on timeout, rather than the
+default @samp{TERM} signal.  @var{signal} may be a name like @samp{HUP}
+or a number.  @xref{Signal specifications}.
+@end table
+
+@cindex time units
+@var{duration} is a floating point number followed by an optional unit:
+@display
+@samp{s} for seconds (the default)
+@samp{m} for minutes
+@samp{h} for hours
+@samp{d} for days
+@end display
+A duration of 0 disables the associated timeout.
+Note that the actual timeout duration is dependent on system conditions,
+which should be especially considered when specifying sub-second timeouts.
+
+@cindex exit status of @command{timeout}
+Exit status:
+
+@display
+124 if @var{command} times out
+125 if @command{timeout} itself fails
+126 if @var{command} is found but cannot be invoked
+127 if @var{command} cannot be found
+137 if @var{command} is sent the KILL(9) signal (128+9)
+the exit status of @var{command} otherwise
+@end display
+
+
+@node Process control
+@chapter Process control
+
+@cindex processes, commands for controlling
+@cindex commands for controlling processes
+
+@menu
+* kill invocation::             Sending a signal to processes.
+@end menu
+
+
+@node kill invocation
+@section @command{kill}: Send a signal to processes
+
+@pindex kill
+@cindex send a signal to processes
+
+The @command{kill} command sends a signal to processes, causing them
+to terminate or otherwise act upon receiving the signal in some way.
+Alternatively, it lists information about signals.  Synopses:
+
+@example
+kill [-s @var{signal} | --signal @var{signal} | -@var{signal}] @var{pid}@dots{}
+kill [-l | --list | -t | --table] [@var{signal}]@dots{}
+@end example
+
+@mayConflictWithShellBuiltIn{kill}
+
+The first form of the @command{kill} command sends a signal to all
+@var{pid} arguments.  The default signal to send if none is specified
+is @samp{TERM}@.  The special signal number @samp{0} does not denote a
+valid signal, but can be used to test whether the @var{pid} arguments
+specify processes to which a signal could be sent.
+
+If @var{pid} is positive, the signal is sent to the process with the
+process ID @var{pid}.  If @var{pid} is zero, the signal is sent to all
+processes in the process group of the current process.  If @var{pid}
+is @minus{}1, the signal is sent to all processes for which the user has
+permission to send a signal.  If @var{pid} is less than @minus{}1, the signal
+is sent to all processes in the process group that equals the absolute
+value of @var{pid}.
+
+If @var{pid} is not positive, a system-dependent set of system
+processes is excluded from the list of processes to which the signal
+is sent.
+
+If a negative @var{pid} argument is desired as the first one, it
+should be preceded by @option{--}.  However, as a common extension to
+POSIX, @option{--} is not required with @samp{kill
+-@var{signal} -@var{pid}}.  The following commands are equivalent:
+
+@example
+kill -15 -1
+kill -TERM -1
+kill -s TERM -- -1
+kill -- -1
+@end example
+
+The first form of the @command{kill} command succeeds if every @var{pid}
+argument specifies at least one process that the signal was sent to.
+
+The second form of the @command{kill} command lists signal information.
+Either the @option{-l} or @option{--list} option, or the @option{-t}
+or @option{--table} option must be specified.  Without any
+@var{signal} argument, all supported signals are listed.  The output
+of @option{-l} or @option{--list} is a list of the signal names, one
+per line; if @var{signal} is already a name, the signal number is
+printed instead.  The output of @option{-t} or @option{--table} is a
+table of signal numbers, names, and descriptions.  This form of the
+@command{kill} command succeeds if all @var{signal} arguments are valid
+and if there is no output error.
+
+The @command{kill} command also supports the @option{--help} and
+@option{--version} options.  @xref{Common options}.
+
+A @var{signal} may be a signal name like @samp{HUP}, or a signal
+number like @samp{1}, or an exit status of a process terminated by the
+signal.  A signal name can be given in canonical form or prefixed by
+@samp{SIG}@.  The case of the letters is ignored, except for the
+@option{-@var{signal}} option which must use upper case to avoid
+ambiguity with lower case option letters.
+@xref{Signal specifications}, for a list of supported
+signal names and numbers.
+
+@node Delaying
+@chapter Delaying
+
+@cindex delaying commands
+@cindex commands for delaying
+
+@c Perhaps @command{wait} or other commands should be described here also?
+
+@menu
+* sleep invocation::            Delay for a specified time.
+@end menu
+
+
+@node sleep invocation
+@section @command{sleep}: Delay for a specified time
+
+@pindex sleep
+@cindex delay for a specified time
+
+@command{sleep} pauses for an amount of time specified by the sum of
+the values of the command line arguments.
+Synopsis:
+
+@example
+sleep @var{number}[smhd]@dots{}
+@end example
+
+@cindex time units
+Each argument is a number followed by an optional unit; the default
+is seconds.  The units are:
+
+@table @samp
+@item s
+seconds
+@item m
+minutes
+@item h
+hours
+@item d
+days
+@end table
+
+Historical implementations of @command{sleep} have required that
+@var{number} be an integer, and only accepted a single argument
+without a suffix.  However, GNU @command{sleep} accepts
+arbitrary floating point numbers.  @xref{Floating point}.
+
+The only options are @option{--help} and @option{--version}.  @xref{Common
+options}.
+
+@c sleep is a shell built-in at least with Solaris 11's /bin/sh
+@mayConflictWithShellBuiltIn{sleep}
+
+@exitstatus
+
+
+@node Numeric operations
+@chapter Numeric operations
+
+@cindex numeric operations
+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
+
+
+@node factor invocation
+@section @command{factor}: Print prime factors
+
+@pindex factor
+@cindex prime factors
+
+@command{factor} prints prime factors.  Synopses:
+
+@example
+factor [@var{number}]@dots{}
+factor @var{option}
+@end example
+
+If no @var{number} is specified on the command line, @command{factor} reads
+numbers from standard input, delimited by newlines, tabs, or spaces.
+
+The @command{factor} command supports only a small number of options:
+
+@table @samp
+@item --help
+Print a short help on standard output, then exit without further
+processing.
 
-@pindex timeout
-@cindex time limit
-@cindex run commands with bounded time
+@item --version
+Print the program version on standard output, then exit without further
+processing.
+@end table
 
-@command{timeout} runs the given @var{command} and kills it if it is
-still running after the specified time interval.  Synopsis:
+Factoring the product of the eighth and ninth Mersenne primes
+takes about 30 milliseconds of CPU time on a 2.2 GHz Athlon.
 
 @example
-timeout [@var{option}] @var{duration} @var{command} [@var{arg}]@dots{}
+M8=$(echo 2^31-1|bc)
+M9=$(echo 2^61-1|bc)
+n=$(echo "$M8 * $M9" | bc)
+/usr/bin/time -f %U factor $n
+4951760154835678088235319297: 2147483647 2305843009213693951
+0.03
 @end example
 
-@var{command} must not be a special built-in utility (@pxref{Special
-built-in utilities}).
+Similarly, factoring the eighth Fermat number @math{2^{256}+1} takes
+about 20 seconds on the same machine.
 
-The program accepts the following options.  Also see @ref{Common options}.
-Options must precede operands.
+Factoring large numbers is, in general, hard.  The Pollard Rho
+algorithm used by @command{factor} is particularly effective for
+numbers with relatively small factors.  If you wish to factor large
+numbers which do not have small factors (for example, numbers which
+are the product of two large primes), other methods are far better.
 
-@table @samp
-@item --preserve-status
-@opindex --preserve-status
-Return the exit status of the managed @var{command} on timeout, rather than
-a specific exit status indicating a timeout.  This is useful if the
-managed @var{command} supports running for an indeterminate amount of time.
+If @command{factor} is built without using GNU MP, only
+single-precision arithmetic is available, and so large numbers
+(typically @math{2^{64}} and above) will not be supported.  The 
single-precision
+code uses an algorithm which is designed for factoring smaller
+numbers.
 
-@item --foreground
-@opindex --foreground
-Don't create a separate background program group, so that
-the managed @var{command} can use the foreground TTY normally.
-This is needed to support timing out commands not started
-directly from an interactive shell, in two situations.
-@enumerate
-@item
-@var{command} is interactive and needs to read from the terminal for example
-@item
-the user wants to support sending signals directly to @var{command}
-from the terminal (like Ctrl-C for example)
-@end enumerate
+@exitstatus
 
-Note in this mode of operation, any children of @var{command}
-will not be timed out.
 
-@item -k @var{duration}
-@itemx --kill-after=@var{duration}
-@opindex -k
-@opindex --kill-after
-Ensure the monitored @var{command} is killed by also sending a @samp{KILL}
-signal, after the specified @var{duration}.  Without this option, if the
-selected signal proves not to be fatal, @command{timeout} does not kill
-the @var{command}.
+@node numfmt invocation
+@section @command{numfmt}: Reformat numbers
 
-@item -s @var{signal}
-@itemx --signal=@var{signal}
-@opindex -s
-@opindex --signal
-Send this @var{signal} to @var{command} on timeout, rather than the
-default @samp{TERM} signal.  @var{signal} may be a name like @samp{HUP}
-or a number.  @xref{Signal specifications}.
-@end table
+@pindex numfmt
 
-@cindex time units
-@var{duration} is a floating point number followed by an optional unit:
-@display
-@samp{s} for seconds (the default)
-@samp{m} for minutes
-@samp{h} for hours
-@samp{d} for days
-@end display
-A duration of 0 disables the associated timeout.
-Note that the actual timeout duration is dependent on system conditions,
-which should be especially considered when specifying sub-second timeouts.
+@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}).
 
-@cindex exit status of @command{timeout}
-Exit status:
+@example
+numfmt [@var{option}]@dots{} [@var{number}]
+@end example
 
-@display
-124 if @var{command} times out
-125 if @command{timeout} itself fails
-126 if @var{command} is found but cannot be invoked
-127 if @var{command} cannot be found
-137 if @var{command} is sent the KILL(9) signal (128+9)
-the exit status of @var{command} otherwise
-@end display
+@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
 
-@node Process control
-@chapter Process control
+See @option{--invalid} for additional information regarding exit status.
 
-@cindex processes, commands for controlling
-@cindex commands for controlling processes
+@subsection General options
 
-@menu
-* kill invocation::             Sending a signal to processes.
-@end menu
+The program accepts the following options.  Also see @ref{Common options}.
 
+@table @samp
 
-@node kill invocation
-@section @command{kill}: Send a signal to processes
+@item --debug
+@opindex --debug
+Print (to standard error) warning messages about possible erroneous usage.
 
-@pindex kill
-@cindex send a signal to processes
+@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.
 
-The @command{kill} command sends a signal to processes, causing them
-to terminate or otherwise act upon receiving the signal in some way.
-Alternatively, it lists information about signals.  Synopses:
+@item --field=@var{n}
+@opindex --field
+Convert the number in input field @var{n} (default: 1).
 
-@example
-kill [-s @var{signal} | --signal @var{signal} | -@var{signal}] @var{pid}@dots{}
-kill [-l | --list | -t | --table] [@var{signal}]@dots{}
-@end example
+@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.
 
-@mayConflictWithShellBuiltIn{kill}
+@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.
 
-The first form of the @command{kill} command sends a signal to all
-@var{pid} arguments.  The default signal to send if none is specified
-is @samp{TERM}@.  The special signal number @samp{0} does not denote a
-valid signal, but can be used to test whether the @var{pid} arguments
-specify processes to which a signal could be sent.
+@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}).
 
-If @var{pid} is positive, the signal is sent to the process with the
-process ID @var{pid}.  If @var{pid} is zero, the signal is sent to all
-processes in the process group of the current process.  If @var{pid}
-is @minus{}1, the signal is sent to all processes for which the user has
-permission to send a signal.  If @var{pid} is less than @minus{}1, the signal
-is sent to all processes in the process group that equals the absolute
-value of @var{pid}.
+@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.
 
-If @var{pid} is not positive, a system-dependent set of system
-processes is excluded from the list of processes to which the signal
-is sent.
+@item --header[=@var{n}]
+@opindex --header
+@opindex --header=N
+Print the first @var{n} (default: 1) lines without any conversion.
 
-If a negative @var{pid} argument is desired as the first one, it
-should be preceded by @option{--}.  However, as a common extension to
-POSIX, @option{--} is not required with @samp{kill
--@var{signal} -@var{pid}}.  The following commands are equivalent:
+@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.
 
-@example
-kill -15 -1
-kill -TERM -1
-kill -s TERM -- -1
-kill -- -1
-@end example
+@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).
 
-The first form of the @command{kill} command succeeds if every @var{pid}
-argument specifies at least one process that the signal was sent to.
+@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}.
 
-The second form of the @command{kill} command lists signal information.
-Either the @option{-l} or @option{--list} option, or the @option{-t}
-or @option{--table} option must be specified.  Without any
-@var{signal} argument, all supported signals are listed.  The output
-of @option{-l} or @option{--list} is a list of the signal names, one
-per line; if @var{signal} is already a name, the signal number is
-printed instead.  The output of @option{-t} or @option{--table} is a
-table of signal numbers, names, and descriptions.  This form of the
-@command{kill} command succeeds if all @var{signal} arguments are valid
-and if there is no output error.
+@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
 
-The @command{kill} command also supports the @option{--help} and
-@option{--version} options.  @xref{Common options}.
+@subsection Possible @var{unit}s:
 
-A @var{signal} may be a signal name like @samp{HUP}, or a signal
-number like @samp{1}, or an exit status of a process terminated by the
-signal.  A signal name can be given in canonical form or prefixed by
-@samp{SIG}@.  The case of the letters is ignored, except for the
-@option{-@var{signal}} option which must use upper case to avoid
-ambiguity with lower case option letters.
-@xref{Signal specifications}, for a list of supported
-signal names and numbers.
+The following are the possible @var{unit} options with @option{--from=UNITS} 
and
+@option{--to=UNITS}:
 
-@node Delaying
-@chapter Delaying
+@table @var
 
-@cindex delaying commands
-@cindex commands for delaying
+@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.
 
-@c Perhaps @command{wait} or other commands should be described here also?
+@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:
 
-@menu
-* sleep invocation::            Delay for a specified time.
-@end menu
+@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:
 
-@node sleep invocation
-@section @command{sleep}: Delay for a specified time
+@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
 
-@pindex sleep
-@cindex delay for a specified time
+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.
 
-@command{sleep} pauses for an amount of time specified by the sum of
-the values of the command line arguments.
-Synopsis:
+@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
-sleep @var{number}[smhd]@dots{}
+@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
 
-@cindex time units
-Each argument is a number followed by an optional unit; the default
-is seconds.  The units are:
+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.
 
-@table @samp
-@item s
-seconds
-@item m
-minutes
-@item h
-hours
-@item d
-days
-@end table
+@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.
 
-Historical implementations of @command{sleep} have required that
-@var{number} be an integer, and only accepted a single argument
-without a suffix.  However, GNU @command{sleep} accepts
-arbitrary floating point numbers.  @xref{Floating point}.
+@end table
 
-The only options are @option{--help} and @option{--version}.  @xref{Common
-options}.
+@subsection Examples of using @command{numfmt}
 
-@c sleep is a shell built-in at least with Solaris 11's /bin/sh
-@mayConflictWithShellBuiltIn{sleep}
+Converting a single number from/to @emph{human} representation:
+@example
+$ numfmt --to=si 500000
+500K
 
-@exitstatus
+$ numfmt --to=iec 500000
+489K
 
+$ numfmt --to=iec-i 500000
+489Ki
 
-@node Numeric operations
-@chapter Numeric operations
+$ numfmt --from=si 1M
+1000000
 
-@cindex numeric operations
-These programs do numerically-related operations.
+$ numfmt --from=iec 1M
+1048576
 
-@menu
-* factor invocation::              Show factors of numbers.
-* seq invocation::                 Print sequences of numbers.
-@end menu
+# 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):
 
-@node factor invocation
-@section @command{factor}: Print prime factors
+@example
+$ numfmt --from=si --to=iec 1T
+932G
+@end example
 
-@pindex factor
-@cindex prime factors
 
-@command{factor} prints prime factors.  Synopses:
+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
-factor [@var{number}]@dots{}
-factor @var{option}
+# 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
 
-If no @var{number} is specified on the command line, @command{factor} reads
-numbers from standard input, delimited by newlines, tabs, or spaces.
 
-The @command{factor} command supports only a small number of options:
+Output can be tweaked using @option{--padding} or @option{--format}:
 
-@table @samp
-@item --help
-Print a short help on standard output, then exit without further
-processing.
+@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
 
-@item --version
-Print the program version on standard output, then exit without further
-processing.
-@end table
+# 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
 
-Factoring the product of the eighth and ninth Mersenne primes
-takes about 30 milliseconds of CPU time on a 2.2 GHz Athlon.
+# 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
 
-@example
-M8=$(echo 2^31-1|bc)
-M9=$(echo 2^61-1|bc)
-n=$(echo "$M8 * $M9" | bc)
-/usr/bin/time -f %U factor $n
-4951760154835678088235319297: 2147483647 2305843009213693951
-0.03
+# 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
 
-Similarly, factoring the eighth Fermat number @math{2^{256}+1} takes
-about 20 seconds on the same machine.
+With locales that support grouping digits, using @option{--grouping} or
+@option{--format} enables grouping.  In @samp{POSIX} locale, grouping is
+silently ignored:
 
-Factoring large numbers is, in general, hard.  The Pollard Rho
-algorithm used by @command{factor} is particularly effective for
-numbers with relatively small factors.  If you wish to factor large
-numbers which do not have small factors (for example, numbers which
-are the product of two large primes), other methods are far better.
+@example
+$ LC_ALL=C numfmt --from=iec --grouping 2G
+2147483648
 
-If @command{factor} is built without using GNU MP, only
-single-precision arithmetic is available, and so large numbers
-(typically @math{2^{64}} and above) will not be supported.  The 
single-precision
-code uses an algorithm which is designed for factoring smaller
-numbers.
+$ LC_ALL=en_US.utf8 numfmt --from=iec --grouping 2G
+2,147,483,648
 
-@exitstatus
+$ 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
-- 
2.1.0