bug#7877: sleep takes undocumented hex args

[Paul Eggert]

On 01/21/2011 01:24 AM, Jim Meyering wrote:
> My first reflex was to make sleep reject args like 0x... and inf.

My reflex was just the opposite: why reject a notation
that might be useful?

Several other programs (printf, seq, sort, tail, plus many
other GNU programs) also use strtod or strtold.  If 'sleep' is
changed to reject hexadecimal and infinity, shouldn't they
be changed too, for consistency?

I expect it's better to leave these programs alone.  Not only
is this simpler, and a tiny bit cheaper at runtime, it's slightly
less likely to break existing usage.

Anyway, whatever we do, we should document it better.  To start the ball
rolling on that, I pushed the following change, which documents the
existing behavior.  We can change this if we change the behavior.

>From df79069b2cfb8435e8b33693c9e03e8689b2659b Mon Sep 17 00:00:00 2001
From: Paul Eggert <address@hidden>
Date: Fri, 21 Jan 2011 10:59:32 -0800
Subject: [PATCH] manual: document floating point better

* doc/coreutils.texi (Floating point): New section.
(od invocation, tail invocation, sort invocation, printf invocation):
(sleep invocation, seq invocation): Refer and defer to it.  See
<http://lists.gnu.org/archive/html/bug-coreutils/2011-01/msg00031.html>.
---
 doc/coreutils.texi |   52 +++++++++++++++++++++++++++++++++++++++-------------
 1 files changed, 39 insertions(+), 13 deletions(-)

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 8a1b3b6..926171c 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -217,6 +217,7 @@ Common Options
 * Exit status::                  Indicating program success or failure
 * Backup options::               Backup options
 * Block size::                   Block size
+* Floating point::               Floating point number representation
 * Signal specifications::        Specifying signals
 * Disambiguating names and IDs:: chgrp and chown owner and group syntax
 * Random sources::               Sources of random data
@@ -729,6 +730,7 @@ name.
 * Exit status::                 Indicating program success or failure.
 * Backup options::              -b -S, in some programs.
 * Block size::                  BLOCK_SIZE and --block-size, in some programs.
+* Floating point::              Floating point number representation.
 * Signal specifications::       Specifying signals using the --signal option.
 * Disambiguating names and IDs:: chgrp and chown owner and group syntax
 * Random sources::              --random-source, in some programs.
@@ -1011,6 +1013,34 @@ set.  The @option{-h} or @option{--human-readable} 
option is equivalent to
 @option{--block-size=human-readable}.  The @option{--si} option is
 equivalent to @option{--block-size=si}.
 
address@hidden Floating point
address@hidden Floating point numbers
address@hidden floating point
address@hidden IEEE floating point
+
+Commands that accept or produce floating point numbers employ the
+floating point representation of the underlying system, and suffer
+from rounding error, overflow, and similar floating-point issues.
+Almost all modern systems use IEEE-754 floating point, and it is
+typically portable to assume IEEE-754 behavior these days.  IEEE-754
+has positive and negative infinity, distinguishes positive from
+negative zero, and uses special values called NaNs to represent
+invalid computations such as dividing zero by itself.  For more
+information, please see David Goldberg's paper
address@hidden://@/www.validlab.com/@/goldberg/@/paper.pdf, What Every
+Computer Scientist Should Know About Floating-Point Arithmetic}.
+
address@hidden LC_NUMERIC
+Commands that accept floating point numbers as options, operands or
+input use the standard C functions @code{strtod} and @code{strtold} to
+convert from text to floating point numbers.  These floating point
+numbers therefore can use scientific notation like @code{1.0e-34} and
address@hidden  Modern C implementations also accept hexadecimal
+floating point numbers such as @code{-0x.ep-3}, which stands for
address@hidden/16 times @math{2^-3}, which equals @minus{}0.109375.  The
address@hidden locale determines the decimal-point character.
address@hidden of Floats,,, libc, The GNU C Library Reference Manual}.
+
 @node Signal specifications
 @section Signal specifications
 @cindex signals, specifying
@@ -1880,7 +1910,7 @@ named character, ignoring high-order bit
 @item d
 signed decimal
 @item f
-floating point
+floating point (@pxref{Floating point})
 @item o
 octal
 @item u
@@ -2820,8 +2850,7 @@ During one iteration, every specified file is checked to 
see if it has
 changed size.
 Historical implementations of @command{tail} have required that
 @var{number} be an integer.  However, GNU @command{tail} accepts
-an arbitrary floating point number (using a period before any
-fractional digits).
+an arbitrary floating point number.  @xref{Floating point}.
 When @command{tail} uses inotify, this polling-related option is ignored.
 
 @itemx address@hidden
@@ -3883,11 +3912,8 @@ the final result, after the throwing away.))
 @opindex --sort
 @cindex general numeric sort
 @vindex LC_NUMERIC
-Sort numerically, using the standard C function @code{strtold} to convert
-a prefix of each line to a long double-precision floating point number.
-This allows floating point numbers to be specified in scientific notation,
-like @code{1.0e-34} and @code{10e100}.
-The @env{LC_NUMERIC} locale determines the decimal-point character.
+Sort numerically, converting a prefix of each line to a long
+double-precision floating point number.  @xref{Floating point}.
 Do not report overflow, underflow, or conversion errors.
 Use the following collating sequence:
 
@@ -11209,6 +11235,7 @@ digits, but is printed according to the 
@env{LC_NUMERIC} category of the
 current locale.  For example, in a locale whose radix character is a
 comma, the command @samp{printf %g 3.14} outputs @samp{3,14} whereas
 the command @samp{printf %g 3,14} is an error.
address@hidden point}.
 
 @kindex address@hidden
 @kindex address@hidden
@@ -15664,8 +15691,7 @@ days
 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 (using a period before any fractional
-digits).
+arbitrary floating point numbers.  @xref{Floating point}.
 
 The only options are @option{--help} and @option{--version}.  @xref{Common
 options}.
@@ -15765,8 +15791,7 @@ When @var{increment} is not specified, it defaults to 
@samp{1},
 even when @var{first} is larger than @var{last}.
 @var{first} also defaults to @samp{1}.  So @code{seq 1} prints
 @samp{1}, but @code{seq 0} and @code{seq 10 5} produce no output.
-Floating-point numbers
-may be specified (using a period before any fractional digits).
+Floating-point numbers may be specified.  @xref{Floating point}.
 
 The program accepts the following options.  Also see @ref{Common options}.
 Options must precede operands.
@@ -15843,7 +15868,8 @@ of @code{%x}.
 
 On most systems, seq can produce whole-number output for values up to
 at least @math{2^{53}}.  Larger integers are approximated.  The details
-differ depending on your floating-point implementation, but a common
+differ depending on your floating-point implementation.
address@hidden point}.  A common
 case is that @command{seq} works with integers through @math{2^{64}},
 and larger integers may not be numerically correct:
 
-- 
1.7.3