Improve documentation for integer and floating-point basics.

* numbers.texi (Numbers, Integer Basics, Float Basics):
Document the basics a bit more precisely.  Say more clearly
that Emacs floating-point numbers are IEEE doubles on all
current platforms.  Give more details about frexp.
Say more clearly that '1.' is an integer.
(Predicates on Numbers): Fix wholenump typo.
* objects.texi (Integer Type): Adjust to match numbers.texi.

3 files changed, 111 insertions, 72 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 639d7e2dc9c..8bf25baeee4 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,14 @@
+2014-03-18  Paul Eggert  <eggert@cs.ucla.edu>
+
+        Improve documentation for integer and floating-point basics.
+        * numbers.texi (Numbers, Integer Basics, Float Basics):
+        Document the basics a bit more precisely.  Say more clearly
+        that Emacs floating-point numbers are IEEE doubles on all
+        current platforms.  Give more details about frexp.
+        Say more clearly that '1.' is an integer.
+        (Predicates on Numbers): Fix wholenump typo.
+        * objects.texi (Integer Type): Adjust to match numbers.texi.
+
 2014-03-18  Stefan Monnier  <monnier@iro.umontreal.ca>
 
         * functions.texi (Advising Functions): Try and improve the text.
diff --git a/doc/lispref/numbers.texi b/doc/lispref/numbers.texi
index d202877e8ad..1758a44baab 100644
--- a/doc/lispref/numbers.texi
+++ b/doc/lispref/numbers.texi
@@ -9,13 +9,14 @@
 @cindex numbers
 
   GNU Emacs supports two numeric data types: @dfn{integers} and
-@dfn{floating point numbers}.  Integers are whole numbers such as
-@minus{}3, 0, 7, 13, and 511.  Their values are exact.  Floating-point
-numbers are numbers with fractional parts, such as @minus{}4.5, 0.0, or
-2.71828.  They can also be expressed in exponential notation: 1.5e2
-equals 150; in this example, @samp{e2} stands for ten to the second
-power, and that is multiplied by 1.5.  Floating point values are not
-exact; they have a fixed, limited amount of precision.
+@dfn{floating-point numbers}.  Integers are whole numbers such as
+@minus{}3, 0, 7, 13, and 511.  Floating-point numbers are numbers with
+fractional parts, such as @minus{}4.5, 0.0, and 2.71828.  They can
+also be expressed in exponential notation: @samp{1.5e2} is the same as
+@samp{150.0}; here, @samp{e2} stands for ten to the second power, and
+that is multiplied by 1.5.  Integer computations are exact, though
+they may overflow.  Floating-point computations often involve rounding
+errors, as the numbers have a fixed amount of precision.
 
 @menu
 * Integer Basics::            Representation and range of integers.
@@ -34,7 +35,7 @@ exact; they have a fixed, limited amount of precision.
 @section Integer Basics
 
   The range of values for an integer depends on the machine.  The
-minimum range is @minus{}536870912 to 536870911 (30 bits; i.e.,
+minimum range is @minus{}536,870,912 to 536,870,911 (30 bits; i.e.,
 @ifnottex
 @minus{}2**29
 @end ifnottex
@@ -61,7 +62,8 @@ Emacs range is treated as a floating-point number.
  1.              ; @r{The integer 1.}
 +1               ; @r{Also the integer 1.}
 -1               ; @r{The integer @minus{}1.}
- 1073741825      ; @r{The floating point number 1073741825.0.}
+ 9000000000000000000
+                 ; @r{The floating-point number 9e18.}
  0               ; @r{The integer 0.}
 -0               ; @r{The integer 0.}
 @end example
@@ -148,15 +150,43 @@ value is a marker, its position value is used and its buffer is ignored.
 @cindex largest Lisp integer
 @cindex maximum Lisp integer
 @defvar most-positive-fixnum
-The value of this variable is the largest integer that Emacs Lisp
-can handle.
+The value of this variable is the largest integer that Emacs Lisp can
+handle.  Typical values are
+@ifnottex
+2**29 @minus{} 1
+@end ifnottex
+@tex
+@math{2^{29}-1}
+@end tex
+on 32-bit and
+@ifnottex
+2**61 @minus{} 1
+@end ifnottex
+@tex
+@math{2^{61}-1}
+@end tex
+on 64-bit platforms.
 @end defvar
 
 @cindex smallest Lisp integer
 @cindex minimum Lisp integer
 @defvar most-negative-fixnum
 The value of this variable is the smallest integer that Emacs Lisp can
-handle.  It is negative.
+handle.  It is negative.  Typical values are
+@ifnottex
+@minus{}2**29
+@end ifnottex
+@tex
+@math{-2^{29}}
+@end tex
+on 32-bit and
+@ifnottex
+@minus{}2**61
+@end ifnottex
+@tex
+@math{-2^{61}}
+@end tex
+on 64-bit platforms.
 @end defvar
 
   In Emacs Lisp, text characters are represented by integers.  Any
@@ -168,22 +198,25 @@ considered to be valid as a character.  @xref{String Basics}.
 
 @cindex @acronym{IEEE} floating point
   Floating-point numbers are useful for representing numbers that are
-not integral.  The precise range of floating-point numbers is
-machine-specific; it is the same as the range of the C data type
-@code{double} on the machine you are using.  Emacs uses the
-@acronym{IEEE} floating-point standard, which is supported by all
-modern computers.
+not integral.  The range of floating-point numbers is
+the same as the range of the C data type @code{double} on the machine
+you are using.  On all computers currently supported by Emacs, this is
+double-precision @acronym{IEEE} floating point.
 
   The read syntax for floating-point numbers requires either a decimal
-point (with at least one digit following), an exponent, or both.  For
-example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2}, @samp{1.5e3}, and
-@samp{.15e4} are five ways of writing a floating-point number whose
-value is 1500.  They are all equivalent.  You can also use a minus
-sign to write negative floating-point numbers, as in @samp{-1.0}.
-
-  Emacs Lisp treats @code{-0.0} as numerically equal to ordinary zero (with
-respect to @code{equal} and @code{=}), even though the two are
-distinguishable in the @acronym{IEEE} floating-point standard.
+point, an exponent, or both.  Optional signs (@samp{+} or @samp{-})
+precede the number and its exponent.  For example, @samp{1500.0},
+@samp{+15e2}, @samp{15.0e+2}, @samp{+1500000e-3}, and @samp{.15e4} are
+five ways of writing a floating-point number whose value is 1500.
+They are all equivalent.  Like Common Lisp, Emacs Lisp requires at
+least one digit after any decimal point in a floating-point number;
+@samp{1500.} is an integer, not a floating-point number.
+
+  Emacs Lisp treats @code{-0.0} as numerically equal to ordinary zero
+with respect to @code{equal} and @code{=}.  This follows the
+@acronym{IEEE} floating-point standard, which says @code{-0.0} and
+@code{0.0} are numerically equal even though other operations can
+distinguish them.
 
 @cindex positive infinity
 @cindex negative infinity
@@ -193,58 +226,53 @@ distinguishable in the @acronym{IEEE} floating-point standard.
 infinity and negative infinity as floating-point values.  It also
 provides for a class of values called NaN or ``not-a-number'';
 numerical functions return such values in cases where there is no
-correct answer.  For example, @code{(/ 0.0 0.0)} returns a NaN@.  (NaN
-values can also carry a sign, but for practical purposes there's no
-significant difference between different NaN values in Emacs Lisp.)
-
-When a function is documented to return a NaN, it returns an
-implementation-defined value when Emacs is running on one of the
-now-rare platforms that do not use @acronym{IEEE} floating point.  For
-example, @code{(log -1.0)} typically returns a NaN, but on
-non-@acronym{IEEE} platforms it returns an implementation-defined
-value.
+correct answer.  For example, @code{(/ 0.0 0.0)} returns a NaN@.
+Although NaN values carry a sign, for practical purposes there is no other
+significant difference between different NaN values in Emacs Lisp.
 
-Here are the read syntaxes for these special floating-point values:
+Here are read syntaxes for these special floating-point values:
 
 @table @asis
-@item positive infinity
-@samp{1.0e+INF}
-@item negative infinity
-@samp{-1.0e+INF}
-@item Not-a-number
-@samp{0.0e+NaN} or @samp{-0.0e+NaN}.
+@item infinity
+@samp{1.0e+INF} and @samp{-1.0e+INF}
+@item not-a-number
+@samp{0.0e+NaN} and @samp{-0.0e+NaN}
 @end table
 
-@defun isnan number
-This predicate tests whether its argument is NaN, and returns @code{t}
-if so, @code{nil} otherwise.  The argument must be a number.
-@end defun
-
-  The following functions are specialized for handling floating point
+  The following functions are specialized for handling floating-point
 numbers:
 
-@defun frexp x
-This function returns a cons cell @code{(@var{sig} . @var{exp})},
-where @var{sig} and @var{exp} are respectively the significand and
-exponent of the floating point number @var{x}:
+@defun isnan x
+This predicate returns @code{t} if its floating-point argument is a NaN,
+@code{nil} otherwise.
+@end defun
 
-@smallexample
-@var{x} = @var{sig} * 2^@var{exp}
-@end smallexample
+@defun frexp x
+This function returns a cons cell @code{(@var{s} . @var{e})},
+where @var{s} and @var{e} are respectively the significand and
+exponent of the floating-point number @var{x}.
 
-@var{sig} is a floating point number between 0.5 (inclusive) and 1.0
-(exclusive).  If @var{x} is zero, the return value is @code{(0 . 0)}.
+If @var{x} is finite, @var{s} is a floating-point number between 0.5
+(inclusive) and 1.0 (exclusive), @var{e} is an integer, and
+@ifnottex
+@var{x} = @var{s} * 2**@var{e}.
+@end ifnottex
+@tex
+@math{x = s 2^e}.
+@end tex
+If @var{x} is zero or infinity, @var{s} is the same as @var{x}.
+If @var{x} is a NaN, @var{s} is also a NaN.
+If @var{x} is zero, @var{e} is 0.
 @end defun
 
 @defun ldexp sig &optional exp
-This function returns a floating point number corresponding to the
+This function returns a floating-point number corresponding to the
 significand @var{sig} and exponent @var{exp}.
 @end defun
 
 @defun copysign x1 x2
 This function copies the sign of @var{x2} to the value of @var{x1},
-and returns the result.  @var{x1} and @var{x2} must be floating point
-numbers.
+and returns the result.  @var{x1} and @var{x2} must be floating point.
 @end defun
 
 @defun logb number
@@ -293,8 +321,8 @@ tests to see whether its argument is a nonnegative integer, and
 returns @code{t} if so, @code{nil} otherwise.  0 is considered
 non-negative.
 
-@findex wholenump number
-This is a synonym for @code{natnump}.
+@findex wholenump
+@code{wholenump} is a synonym for @code{natnump}.
 @end defun
 
 @defun zerop number
@@ -532,8 +560,8 @@ Except for @code{%}, each of these functions accepts both integer and
 floating-point arguments, and returns a floating-point number if any
 argument is floating point.
 
-  It is important to note that in Emacs Lisp, arithmetic functions
-do not check for overflow.  Thus @code{(1+ 536870911)} may evaluate to
+  Emacs Lisp arithmetic functions do not check for integer overflow.
+Thus @code{(1+ 536870911)} may evaluate to
 @minus{}536870912, depending on your hardware.
 
 @defun 1+ number-or-marker
diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi
index 086abecded1..4e8182ccf34 100644
--- a/doc/lispref/objects.texi
+++ b/doc/lispref/objects.texi
@@ -161,8 +161,8 @@ latter are unique to Emacs Lisp.
 @node Integer Type
 @subsection Integer Type
 
-  The range of values for integers in Emacs Lisp is @minus{}536870912 to
-536870911 (30 bits; i.e.,
+  The range of values for an integer depends on the machine.  The
+minimum range is @minus{}536,870,912 to 536,870,911 (30 bits; i.e.,
 @ifnottex
 @minus{}2**29
 @end ifnottex
@@ -176,9 +176,9 @@ to
 @tex
 @math{2^{29}-1})
 @end tex
-on typical 32-bit machines.  (Some machines provide a wider range.)
-Emacs Lisp arithmetic functions do not check for overflow.  Thus
-@code{(1+ 536870911)} is @minus{}536870912 if Emacs integers are 30 bits.
+but many machines provide a wider range.
+Emacs Lisp arithmetic functions do not check for integer overflow.  Thus
+@code{(1+ 536870911)} is @minus{}536,870,912 if Emacs integers are 30 bits.
 
   The read syntax for integers is a sequence of (base ten) digits with an
 optional sign at the beginning and an optional period at the end.  The
@@ -215,8 +215,8 @@ this records a power of 2 rather than a power of 10.
 
   The printed representation for floating-point numbers requires either
 a decimal point (with at least one digit following), an exponent, or
-both.  For example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2},
-@samp{1.5e3}, and @samp{.15e4} are five ways of writing a floating-point
+both.  For example, @samp{1500.0}, @samp{+15e2}, @samp{15.0e+2},
+@samp{+1500000e-3}, and @samp{.15e4} are five ways of writing a floating-point
 number whose value is 1500.  They are all equivalent.
 
   @xref{Numbers}, for more information.