From 84d0a0599f9cd54c3c0f69fa3a20e6c8c44a264b Mon Sep 17 00:00:00 2001
From: Assaf Gordon <assafgordon@gmail.com>
Date: Tue, 18 Dec 2012 16:51:51 -0500
Subject: [PATCH] doc: Add numfmt

* doc/coreutils.texi: add numfmt section
---
 doc/coreutils.texi |  158 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 158 insertions(+), 0 deletions(-)

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 0646f82..fc467e6 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -85,6 +85,7 @@
 * nl: (coreutils)nl invocation.                 Number lines and write files.
 * nohup: (coreutils)nohup invocation.           Immunize to hangups.
 * nproc: (coreutils)nproc invocation.           Print the number of processors.
+* numfmt: (coreutils)numfmt invocation.         Reformat numbers.
 * od: (coreutils)od invocation.                 Dump files in octal, etc.
 * paste: (coreutils)paste invocation.           Merge lines of files.
 * pathchk: (coreutils)pathchk invocation.       Check file name portability.
@@ -238,6 +239,7 @@ 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
 
@@ -2114,6 +2116,7 @@ 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
@@ -2223,6 +2226,161 @@ 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
+
+@subsection General options
+
+The program accepts the following options.  Also see @ref{Common options}.
+
+@table @samp
+
+@item --from=@var{UNIT}
+@opindex --from
+Auto-scales input numbers according to @var{UNIT}. See @ref{numfmt_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 --to=@var{UNIT}
+@opindex --to
+Auto-scales output numbers according to @var{UNIT}. See @ref{numfmt_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}).
+
+@item --round=@var{METHOD}
+@opindex --round
+@opindex --round=ceiling
+@opindex --round=floor
+@opindex --round=nearest
+When converting number representations, round the number according to
+@var{METHOD} can be @samp{ceiling} (the default), @samp{floor}, @samp{nearest}.
+
+@item --suffix=@var{SUFFIX}
+@opindex --suffix
+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 --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 -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.
+
+@end table
+
+@node numfmt_units
+@subsection Possible @var{UNIT}s:
+
+The following are the possible @var{UNIT} options with @option{--from} and
+@option{--to}:
+
+@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 Electronical
+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}} (Kilo)
+@samp{M}  =>  @math{1024^2 = 2^{20}} (Mega)
+@samp{G}  =>  @math{1024^3 = 2^{30}} (Giga)
+@samp{T}  =>  @math{1024^4 = 2^{40}} (Tera)
+@samp{P}  =>  @math{1024^5 = 2^{50}} (Peta)
+@samp{E}  =>  @math{1024^6 = 2^{60}} (Exa)
+@samp{Z}  =>  @math{1024^7 = 2^{70}} (Zetta)
+@samp{Y}  =>  @math{1024^8 = 2^{80}} (Yotta)
+@end example
+
+@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
 
 @node pr invocation
 @section @command{pr}: Paginate or columnate files for printing
-- 
1.7.7.4

