1 files changed, 29 insertions, 8 deletions
diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi
index 69b6c859f65..745baacc297 100644
--- a/doc/lispref/objects.texi
+++ b/doc/lispref/objects.texi
@@ -166,7 +166,10 @@ latter are unique to Emacs Lisp.
 @node Integer Type
 @subsection Integer Type
 
-  The range of values for an integer depends on the machine.  The
+  Under the hood, there are two kinds of integers---small integers,
+called @dfn{fixnums}, and large integers, called @dfn{bignums}.
+
+  The range of values for a fixnum depends on the machine.  The
 minimum range is @minus{}536,870,912 to 536,870,911 (30 bits; i.e.,
 @ifnottex
 @minus{}2**29
@@ -182,8 +185,15 @@ to
 @math{2^{29}-1})
 @end tex
 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.
+
+  Bignums can have arbitrary precision.  Operations that overflow a
+fixnum will return a bignum instead.
+
+  Fixnums can be compared with @code{eq}, but bignums require
+@code{eql} or @code{=}.  To test whether an integer is a fixnum or a
+bignum, you can compare it to @code{most-negative-fixnum} and
+@code{most-positive-fixnum}, or you can use the convenience predicates
+@code{fixnump} and @code{bignump} on any object.
 
   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
@@ -200,11 +210,6 @@ leading @samp{+} or a final @samp{.}.
 @end example
 
 @noindent
-As a special exception, if a sequence of digits specifies an integer
-too large or too small to be a valid integer object, the Lisp reader
-reads it as a floating-point number (@pxref{Floating-Point Type}).
-For instance, if Emacs integers are 30 bits, @code{536870912} is read
-as the floating-point number @code{536870912.0}.
 
   @xref{Numbers}, for more information.
 
@@ -1895,6 +1900,9 @@ with references to further information.
 @item arrayp
 @xref{Array Functions, arrayp}.
 
+@item bignump
+@xref{Predicates on Numbers, floatp}.
+
 @item bool-vector-p
 @xref{Bool-Vectors, bool-vector-p}.
 
@@ -1928,6 +1936,9 @@ with references to further information.
 @item custom-variable-p
 @xref{Variable Definitions, custom-variable-p}.
 
+@item fixnump
+@xref{Predicates on Numbers, floatp}.
+
 @item floatp
 @xref{Predicates on Numbers, floatp}.
 
@@ -2083,6 +2094,10 @@ strings), two arguments with the same contents or elements are not
 necessarily @code{eq} to each other: they are @code{eq} only if they
 are the same object, meaning that a change in the contents of one will
 be reflected by the same change in the contents of the other.
+For other types of objects whose contents cannot be changed (e.g.,
+floats), two arguments with the same contents might or might not be
+the same object, and @code{eq} returns @code{t} or @code{nil}
+depending on whether the Lisp interpreter created one object or two.
 
 @example
 @group
@@ -2096,6 +2111,12 @@ be reflected by the same change in the contents of the other.
 @end group
 
 @group
+(eq 3.0 3.0)
+     @result{} t @r{or} nil
+;; @r{The result is implementation-dependent.}
+@end group
+
+@group
 (eq "asdf" "asdf")
      @result{} nil
 @end group