bug#39557: 27.0.60; Elisp manual, doc about bignums

[Paul Eggert <eggert@cs.ucla.edu>]

[-- Attachment #1: Type: text/plain, Size: 1426 bytes --]

> That's really the _last_ thing we should tell users, not the first.

I installed the first attached patch to move the distinction between fixnums and 
bignums to the end of the section.

> Shouldn't it tell you that you get a fixnum whenever the value
> is within the fixnum range (if that's in fact the case)?

It already said that, but apparently not clearly enough. I installed the second 
attached patch to try to make things clearer.

> this doc should probably also mention that the numerical value of
> a marker is an integer

It already says "Many of the functions described in this chapter accept markers 
for arguments in place of numbers.... When the argument value is a marker, its 
position value is used and its buffer is ignored."

> if you compare an integer
> against an integer numeral then you had better use
> `eql', unless you know that both are fixnums

No, it suffices if *either* is a fixnum. For example, (eq 0 FOO) tests whether 
FOO is the integer zero, and works regardless of whether FOO is a bignum.

> I'm really surprised this doc got inserted as it is.

I'm not surprised at all. The doc was an improvement over its predecessor, we're 
all busy doing other things, and the issues raised in this bug report are low 
priority.

If you're still dissatisfied with the manual, I suggest proposing specific 
wording changes so that future fixes in this area can be accomplished more 
efficiently.

[-- Attachment #2: 0001-Reorder-discussion-of-integer-basics.patch --]
[-- Type: text/x-patch, Size: 4341 bytes --]

From 290cfbedd75764ab863677f63f66db13ceb70598 Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@cs.ucla.edu>
Date: Mon, 17 Feb 2020 13:36:50 -0800
Subject: [PATCH 1/2] Reorder discussion of integer basics

* doc/lispref/numbers.texi (Integer Basics): Put the fixnum/bignum
discussion at the end of the section, not at the start (Bug#39557).
---
 doc/lispref/numbers.texi | 77 +++++++++++++++++++++-------------------
 1 file changed, 40 insertions(+), 37 deletions(-)

diff --git a/doc/lispref/numbers.texi b/doc/lispref/numbers.texi
index c8941eab73..4b9fdf2420 100644
--- a/doc/lispref/numbers.texi
+++ b/doc/lispref/numbers.texi
@@ -34,39 +34,6 @@ Numbers
 @node Integer Basics
 @section Integer Basics
 
-  Integers in Emacs Lisp are not limited to the machine word size.
-
-  Under the hood, though, there are two kinds of integers: smaller
-ones, called @dfn{fixnums}, and larger ones, called @dfn{bignums}.
-Some functions in Emacs accept only fixnums.  Also, while fixnums can
-be compared for numeric equality with @code{eq}, bignums require
-more-heavyweight equality predicates like @code{eql} and @code{=}.
-
-  The range of values for bignums is limited by the amount of main
-memory, by machine characteristics such as the size of the word used
-to represent a bignum's exponent, and by the @code{integer-width}
-variable.  These limits are typically much more generous than the
-limits for fixnums.  A bignum is never numerically equal to a fixnum;
-if Emacs computes an integer in fixnum range, it represents the
-integer as a fixnum, not a bignum.
-
-  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
-@end ifnottex
-@tex
-@math{-2^{29}}
-@end tex
-to
-@ifnottex
-2**29 @minus{} 1),
-@end ifnottex
-@tex
-@math{2^{29}-1}),
-@end tex
-but many machines provide a wider range.
-
   The Lisp reader reads an integer as a nonempty sequence
 of decimal digits with optional initial sign and optional
 final period.
@@ -145,6 +112,46 @@ Integer Basics
 give these arguments the name @var{number-or-marker}.  When the argument
 value is a marker, its position value is used and its buffer is ignored.
 
+  In Emacs Lisp, text characters are represented by integers.  Any
+integer between zero and the value of @code{(max-char)}, inclusive, is
+considered to be valid as a character.  @xref{Character Codes}.
+
+  Integers in Emacs Lisp are not limited to the machine word size.
+Under the hood, though, there are two kinds of integers: smaller ones,
+called @dfn{fixnums}, and larger ones, called @dfn{bignums}.  Although
+Emacs Lisp code ordinarily should not depend on whether an integer is
+a fixnum or a bignum, older Emacs versions support only fixnums, some
+functions in Emacs still accept only fixnums, and older Emacs Lisp
+code may have trouble when given bignums.  For example, while older
+Emacs Lisp code could safely compare integers for numeric equality
+with @code{eq}, the presence of bignums means that equality predicates
+like @code{eql} and @code{=} should now be used to compare integers.
+
+  The range of values for bignums is limited by the amount of main
+memory, by machine characteristics such as the size of the word used
+to represent a bignum's exponent, and by the @code{integer-width}
+variable.  These limits are typically much more generous than the
+limits for fixnums.  A bignum is never numerically equal to a fixnum;
+if Emacs computes an integer in fixnum range, it represents the
+integer as a fixnum, not a bignum.
+
+  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
+@end ifnottex
+@tex
+@math{-2^{29}}
+@end tex
+to
+@ifnottex
+2**29 @minus{} 1),
+@end ifnottex
+@tex
+@math{2^{29}-1}),
+@end tex
+but many machines provide a wider range.
+
 @cindex largest fixnum
 @cindex maximum fixnum
 @defvar most-positive-fixnum
@@ -207,10 +214,6 @@ Integer Basics
 creates huge integers.
 @end defvar
 
-  In Emacs Lisp, text characters are represented by integers.  Any
-integer between zero and the value of @code{(max-char)}, inclusive, is
-considered to be valid as a character.  @xref{Character Codes}.
-
 @node Float Basics
 @section Floating-Point Basics
 
-- 
2.17.1


[-- Attachment #3: 0002-Clarify-when-fixnums-are-used.patch --]
[-- Type: text/x-patch, Size: 1132 bytes --]

From 8593d449972ad2bac850c03839653223d402a682 Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@cs.ucla.edu>
Date: Mon, 17 Feb 2020 13:54:07 -0800
Subject: [PATCH 2/2] Clarify when fixnums are used.

* doc/lispref/numbers.texi (Integer Basics): Clarify.
Based on a suggestion by Noam Postavsky (Bug#39557#32).
---
 doc/lispref/numbers.texi | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/lispref/numbers.texi b/doc/lispref/numbers.texi
index 4b9fdf2420..4002b36ce5 100644
--- a/doc/lispref/numbers.texi
+++ b/doc/lispref/numbers.texi
@@ -132,8 +132,8 @@ Integer Basics
 to represent a bignum's exponent, and by the @code{integer-width}
 variable.  These limits are typically much more generous than the
 limits for fixnums.  A bignum is never numerically equal to a fixnum;
-if Emacs computes an integer in fixnum range, it represents the
-integer as a fixnum, not a bignum.
+Emacs always represents an integer in fixnum range as a fixnum, not a
+bignum.
 
   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.,
-- 
2.17.1