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

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

[Drew Adams]

The Elisp manual's presentation of fixnums and bignums could be
improved.  It should say something similar to what the Common Lisp
manual says:

  Common Lisp is designed to hide this distinction as much as possible;
  the distinction between fixnums and bignums is visible to the user in
  only a few places where the efficiency of representation is important.
  Exactly which integers are fixnums is implementation-dependent;
  typically they will be those integers in the range -2**n to 2**(n-1),
  inclusive, for some n not less than 15.  See most-positive-fixnum and
  most-negative-fixnum.

IOW, don't worry about whether an integer is a fixnum or a bignum, in
general.

Instead, right off the bat the Elisp doc tells users:

  Some functions in Emacs accept only fixnums.  Also, while fixnums can
  always be compared for numeric equality with 'eq', bignums require
  more-heavyweight equality predicates like 'eql'."

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

And even if we tell them something like that we should NOT emphasize
using `eq' ("bignums _require_...").  We should NOT give users the
impression that they should want to avoid the "more-heavyweight"
comparison function `eql'.

We should instead tell users, right away, that they can (and typically
should) use `eql' for comparing any integers, regardless of whether they
happen, on this or that platform/machine, to be fixnums or bignums.

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

Using `eq' is only an optimisation; it's platform/machine-specific; and
it makes users worry about whether the numbers being compared are both
fixnums.  (Sure, they can always test first with `fixnump' or `bignump',
but still...)

And I don't see where the doc tells you how the Lisp reader treats an
integer numeral - when it gives you a fixnum and when it gives you a
bignum.  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)?  I mean, if
you're going to be comparing against a literal value, and the doc slants
you toward using `eq' as it does, you'll at least want to know whether
some numeral ends up as a fixnum or a bignum.  (Sure, you can always
test it...)

(BTW, this doc should probably also mention that the numerical value of
a marker is an integer.  Sure, if they follow the link to node Markers
they'll find that out, but still.)



In GNU Emacs 27.0.60 (build 1, x86_64-w64-mingw32)
 of 2019-12-28
Repository revision: 21c3020fcec0a32122d2680a391864a75393031b
Windowing system distributor `Microsoft Corp.', version 10.0.18362
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install -C 'CFLAGS=-O2 -static -g3''

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

[Eli Zaretskii]

> Date: Mon, 10 Feb 2020 15:55:03 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> 
>   Some functions in Emacs accept only fixnums.  Also, while fixnums can
>   always be compared for numeric equality with 'eq', bignums require
>   more-heavyweight equality predicates like 'eql'."
> 
> That's really the _last_ thing we should tell users, not the first.
> 
> And even if we tell them something like that we should NOT emphasize
> using `eq' ("bignums _require_...").  We should NOT give users the
> impression that they should want to avoid the "more-heavyweight"
> comparison function `eql'.
> 
> We should instead tell users, right away, that they can (and typically
> should) use `eql' for comparing any integers, regardless of whether they
> happen, on this or that platform/machine, to be fixnums or bignums.
> 
> I'm really surprised this doc got inserted as it is.
> 
> Using `eq' is only an optimisation; it's platform/machine-specific; and
> it makes users worry about whether the numbers being compared are both
> fixnums.  (Sure, they can always test first with `fixnump' or `bignump',
> but still...)
> 
> And I don't see where the doc tells you how the Lisp reader treats an
> integer numeral - when it gives you a fixnum and when it gives you a
> bignum.  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)?  I mean, if
> you're going to be comparing against a literal value, and the doc slants
> you toward using `eq' as it does, you'll at least want to know whether
> some numeral ends up as a fixnum or a bignum.  (Sure, you can always
> test it...)

There seems to be a contradiction here: where we do describe the
difference between fixnums and bignums, you argue that we shouldn't,
but then you pick up a place where we don't distinguish between them,
and you argue that we should...

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

[Drew Adams]

> >   Some functions in Emacs accept only fixnums.  Also, while fixnums can
> >   always be compared for numeric equality with 'eq', bignums require
> >   more-heavyweight equality predicates like 'eql'."
> >
> > That's really the _last_ thing we should tell users, not the first.
> >
> > And even if we tell them something like that we should NOT emphasize
> > using `eq' ("bignums _require_...").  We should NOT give users the
> > impression that they should want to avoid the "more-heavyweight"
> > comparison function `eql'.
> >
> > We should instead tell users, right away, that they can (and typically
> > should) use `eql' for comparing any integers, regardless of whether they
> > happen, on this or that platform/machine, to be fixnums or bignums.
> >
> > I'm really surprised this doc got inserted as it is.
> >
> > Using `eq' is only an optimisation; it's platform/machine-specific; and
> > it makes users worry about whether the numbers being compared are both
> > fixnums.  (Sure, they can always test first with `fixnump' or `bignump',
> > but still...)
> >
> > And I don't see where the doc tells you how the Lisp reader treats an
> > integer numeral - when it gives you a fixnum and when it gives you a
> > bignum.  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)?  I mean, if
> > you're going to be comparing against a literal value, and the doc slants
> > you toward using `eq' as it does, you'll at least want to know whether
> > some numeral ends up as a fixnum or a bignum.  (Sure, you can always
> > test it...)
> 
> There seems to be a contradiction here: where we do describe the
> difference between fixnums and bignums, you argue that we shouldn't,
> but then you pick up a place where we don't distinguish between them,
> and you argue that we should...

Maybe read again what I wrote.

I didn't say we should not describe the
difference between the two.  Not at all.

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

[Eli Zaretskii]

> Date: Tue, 11 Feb 2020 10:26:08 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 39557@debbugs.gnu.org
> 
> > There seems to be a contradiction here: where we do describe the
> > difference between fixnums and bignums, you argue that we shouldn't,
> > but then you pick up a place where we don't distinguish between them,
> > and you argue that we should...
> 
> Maybe read again what I wrote.

Maybe read again what I wrote.

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

[Noam Postavsky]

Eli Zaretskii <eliz@gnu.org> writes:

> There seems to be a contradiction here: where we do describe the
> difference between fixnums and bignums, you argue that we shouldn't,
> but then you pick up a place where we don't distinguish between them,
> and you argue that we should...

I think Drew intended the argument that we should distinguish them as a
sarcastic reductio ad absurdum.

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

[Drew Adams]

> > There seems to be a contradiction here: where we do describe the
> > difference between fixnums and bignums, you argue that we shouldn't,
> > but then you pick up a place where we don't distinguish between them,
> > and you argue that we should...
> 
> I think Drew intended the argument that we should distinguish them as a
> sarcastic reductio ad absurdum.

Not at all.  I wonder why you would think that,
especially when I reiterated:

   I didn't say we should not describe the
   difference between the two.  Not at all.

It's appropriate to distinguish them in the doc,
since they are distinguished in reality.  They
have different behavior.

I argued for treatment similar to what the Common
Lisp doc provides.  (And I pointed to that doc.
You might want to take a look.)

The Common Lisp doc guides you to, a priori,
treating them the same in your code that uses
them.  That is, as a general rule, ignore their
difference as much as possible -- think integer.
And that means think (use) `eql'.

If and when you really need to distinguish them
in practice (rare), then do so.  And of course
the doc should tell you how to do that.

I object to the doc about integers starting off
by telling you "bignums require more-heavyweight
predicates like `eql'", and possibly giving the
mistaken impression that you should in general
try to use fixnums and `eq'.  That's the wrong
message to send, IMO, whether explicit or not.

The main message of the doc about integers and
comparison is that you should, in general, use
`eql' - not `eq'.  That message isn't delivered,
and if you think it is then I'll just suggest
that it's lost.

I didn't say that we shouldn't mention that
fixnums can be compared using `eq'.  I said
that's the _last_, not the first, thing we
should tell them about fixnums and bignums.

The fact that fixnums can be compared using
`eq' is _not_ a wonderful feature.  It can
even represent a liability - a risk that users
might compare integers generally using `eq'.

The use case for comparing integers with `eq'
is a corner case.

But this doc puts it front and center, as if
it were important, or a cool trick that real
lispers use: use fixnums as integers because
you can use `eq', which isn't so "heavyweight".

The message should be to compare integers with
`eql' - do NOT use `eq'.

---

We can (but we really need not) add that if,
for some reason, you know that both numbers
are fixnums, then you can use `eq'.  But don't
start with that.

I wouldn't suggest that we even add here that
using `eq' is more performant than `eql'.
Users who know more generally that `eq' is
faster than `eql' will know whether it makes
sense for them to use `eq' in any given case
when both integers are known to be fixnums.

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

[Noam Postavsky]

Drew Adams <drew.adams@oracle.com> writes:

>> > There seems to be a contradiction here: where we do describe the
>> > difference between fixnums and bignums, you argue that we shouldn't,
>> > but then you pick up a place where we don't distinguish between them,
>> > and you argue that we should...
>>
>> I think Drew intended the argument that we should distinguish them as a
>> sarcastic reductio ad absurdum.
>
> Not at all.  I wonder why you would think that,

When you said this:

    I mean, if you're going to be comparing against a literal value, and
    the doc slants you toward using `eq' as it does

since you *don't* want the doc to slant towards `eq', I read that
paragraph as sarcastic.

By the way, this

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

is too easily read as a snide jab (I know, you didn't mean it that way),
so it would be nice if you could leave out that kind of meta-opinion
from future reports.

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

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > I think Drew intended the argument that we should distinguish them as a
  > sarcastic reductio ad absurdum.

I urge everyone to avoid sarcasm on our mailing lists.
It creates a risk of misunderstandings, and gives no benefit.

See https://gnu.org/philosophy/kind-communication.html.

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

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

[Drew Adams]

> >> I think Drew intended the argument that we should
> >> distinguish them as a sarcastic reductio ad absurdum.
> >
> > Not at all.  I wonder why you would think that,
> 
> When you said this:
> 
>     I mean, if you're going to be comparing against a
>     literal value, and the doc slants you toward using
>     `eq' as it does
> 
> since you *don't* want the doc to slant towards `eq',
> I read that paragraph as sarcastic.

The actual quote:

  And I don't see where the doc tells you how the Lisp
  reader treats an integer numeral - when it gives you
  a fixnum and when it gives you a bignum.  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)?
  I mean, if you're going to be comparing against a
  literal value, and the doc slants you toward using
  `eq' as it does, you'll at least want to know whether
  some numeral ends up as a fixnum or a bignum.

There's nothing the least bit sarcastic in any of that.

That point/question is about what happens when a
numeral is read and interpreted by Lisp.  It
suggests that we say something about that case.
To use `eq' with a numeral you need to know when
it's handled as a fixnum.

If you use `eql' then that's not a consideration -
you don't really need to know how the numeral is
handled.  But since the doc currently, in effect,
promotes the use of `eq' somewhat, providing such
info might help.

There's no reductio ad absurdum there, let alone
a sarcastic one.

Putting this differently, if you compare an integer
against an integer numeral then you had better use
`eql', unless you know that both are fixnums, and
for the latter to be true you need to know how
numerals are handled.

I'm guessing the following rule applies also in
the case of interpreting a numeral - but if so
then maybe it would help to say so explicitly:

  if Emacs computes an integer in fixnum range, it
  represents the integer as a fixnum, not a bignum.

It's easy to think that a numeral isn't "computed",
and so to not think that this rule applies to a
numeral.  At least I, as one reader, wondered how
numerals are handled.

> By the way, this
> 
>     I'm really surprised this doc got inserted as it is.
> 
> is too easily read as a snide jab (I know, you
> didn't mean it that way), so it would be nice if
> you could leave out that kind of meta-opinion
> from future reports.

Is that a meta-opinion on your part? ;-)

I think it may be too easy for you to read it
that way because you're perhaps trying to read
my bug reports that way.  Maybe chill a bit?

Actually, I was just expressing my surprise,
as Eli usually shepherds new doc sufficiently
well that such things don't happen.  And I
mean that sincerely, as a compliment.

(Darn, another meta-opinion. (Darn, another
meta-meta-opinion that risks being taken as
sarcasm. (Darn, yet another. (D...))))

As for avoiding sarcasm (even humor) in mail:
Sure.  But a companion rule of etiquette
might be to avoid attributing malevolence
when a simple, constructive reading will do.
The golden rule implies offering the benefit
of the doubt.

The "you" in my bug report was consistently
the user.  The report was technical, not a
rant.  It wasn't I who took this to the
personal/meta level.  How about we turn now
to the technical content - the problem
reported?  Any thoughts on that?

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

[Noam Postavsky]

Drew Adams <drew.adams@oracle.com> writes:

> There's nothing the least bit sarcastic in any of that.
[...]
> avoid attributing malevolence when a simple, constructive reading will
> do.  The golden rule implies offering the benefit of the doubt.

Yeah, I didn't intend to attribute malevolence; you wondered how I read
sarcasm (which, even if it might not be the best technique for
communication, isn't the same as ill-intent) in your message, so I
explained.

> Actually, I was just expressing my surprise,
> as Eli usually shepherds new doc sufficiently
> well that such things don't happen.  And I
> mean that sincerely, as a compliment.

Although I do believe you meant it that way, I still struggle to read
this as a compliment, even with the added explanation.

> to the technical content - the problem
> reported?  Any thoughts on that?

The idea is recommend using eql for comparing integers first, and move
the description of eq and fixnum/bignum distinction to the next
paragraph, right?

And also to document when the reader returns fixnums or bignums.  Though
I guess that might instead be solved by making the rule you cited
stronger to something like:

    Emacs always represents integers in fixnum range as a fixnum, not a
    bignum.

(Assuming that's true, which I believe it is)

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

[Drew Adams]

> > to the technical content - the problem
> > reported?  Any thoughts on that?
> 
> The idea is recommend using eql for comparing integers first, and move
> the description of eq and fixnum/bignum distinction to the next
> paragraph, right?

Almost.  Recommend `eql' generally for integers, even
as, i.e., even _after_, pointing out that integers
are either fixnums or bignums.  IOW, it's a general
recommendation, regardless of the fact that there
are two kinds of integers.

And in fact point out that you CANNOT use `eq', in
general, to compare integers.  That's part of the
point about recommending `eql'.  The recommendation
is in spite of the fact that there are two kinds of
integers - it applies to integers of both kinds, and
`eq' cannot be used with integers of both kinds.

And somewhere after that (whether the next paragraph
or not), get into the fact that you can use `eq' (in
addition to `eql') to compare two fixnums (BOTH must
be known to be fixnums) - IF you think it's important
to point that out.

I think it's important to point out that you can
_distinguish_ a fixnum from a bignum, and how to do
that.

But I can't say whether it's really important, in
this doc, to say that you can compare two fixnums
using `eq'.  A priori, I'd think not.

As I said earlier, AFAIK that's only an optimization,
and anyone who is liable to use/need such optimizing
should already know that `eq' is faster than `eql'.

I don't think that _this_ doc needs to or should
point out that `eql' is "more-heavyweight" than
`eq'.  That's not specific to integer comparison.

To be clear, I have no objection to saying that
you can use `eq' for two fixnums.  I'm just not
aware of why it's important to do that in this doc.

> And also to document when the reader returns fixnums or bignums.  Though
> I guess that might instead be solved by making the rule you cited
> stronger to something like:
> 
>   Emacs always represents integers in fixnum range
>   as a fixnum, not a bignum.
> 
> (Assuming that's true, which I believe it is)

Yes, that would be OK, provided we don't speak of
"computing" the integer, which can be misleading
for a literal (a numeral), or provided we make
clear that that rule applies also to numerals.

Thanks for working on this fix, if you do.

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

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

If nobody was really being sarcastic, that's good news.
(We all misinterpret things sometimes.)

I still urge everyone to avoid sarcasm on our mailing lists.
See https://gnu.org/philosophy/kind-communication.html.

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

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

[Paul Eggert]

[-- 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

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

[Drew Adams]

Thanks for working on this.

> > 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.

Thanks.

> > 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.

Thanks.

> > 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."

Not really the same thing.  Nothing there says that
a marker position is an integer (fixnum or bignum),
and not some other kind of number.

Sure, many readers will know (but not from here)
that buffer positions are integers.  And they can
guess that marker positions are buffer positions,
hence integers...  But it's not hard to tell them
that the numerical value of a marker is an integer.

(This isn't a big deal.  I said "should probably
also mention".  I could have said "maybe".  Just a
suggestion.)

> > 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 see.  Then please say that.

As for the proposed changes -

If we're going to talk about "older" code then
we should specify older than what.  I don't
think there should be any need to talk about
older code or say "should now".  The general
rule's simple: use `eql' - worked before,
works now.

If some code uses `eq', it couldn't possibly
have worked before with two integers big
enough to now be bignums, right?  Any code -
old or new - that uses `eq' to compare
integers needs to know that at least one of
the operands is a fixnum.

We should just say that you can use `eql' to
compare any integers, and add that you can't
use `eq' to compare integers if they're both
bignums.  How complicated is that?

Emphasize `=' and `eql'.  `eq' should just be
a footnote.  That's my suggestion.

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

[Paul Eggert]

On 2/17/20 3:19 PM, Drew Adams wrote:

>>> 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."
> 
> Not really the same thing.  Nothing there says that
> a marker position is an integer (fixnum or bignum),
> and not some other kind of number.

That's clear from context. This section is titled "Integer Basics" and it's all 
about integers.

Personally I'd even trim some text from the above quote, as it's not basic to 
integers. I would rather not make that text longer or trickier.

>>> 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 see.  Then please say that.

I'd rather not. Again, this section is "Integer Basics" and the reference manual 
should not bog itself down various possible ways to use integers in programs 
(there are too many ways).

> If we're going to talk about "older" code then
> we should specify older than what.

I originally wrote "older than Emacs 27" but trimmed it as being nonessential 
before installing the patch. It's not a big deal either way.

> I don't
> think there should be any need to talk about
> older code or say "should now".

This bug report assumed that Emacs is basically like Common Lisp in this area. 
However, Emacs is not there yet (though we've made progress), and it's better if 
the documentation reflects that fact rather than pretending there's no 
difference from Common Lisp.

> Any code -
> old or new - that uses `eq' to compare
> integers needs to know that at least one of
> the operands is a fixnum.

It's sometimes OK to use eq even when both arguments are bignums. It depends on 
the circumstances.

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

[Drew Adams]

> >> 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 see.  Then please say that.
> 
> I'd rather not. Again, this section is "Integer Basics" and the reference
> manual
> should not bog itself down various possible ways to use integers in programs
> (there are too many ways).

Then remove all mention of `eq', if you don't
specify how it behaves with bignums.

> > If we're going to talk about "older" code then
> > we should specify older than what.
> 
> I originally wrote "older than Emacs 27" but trimmed it as being
> nonessential
> before installing the patch. It's not a big deal either way.

If it means nothing to say "older code" then
remove it altogether.  The hand waving just
confuses.

> > I don't
> > think there should be any need to talk about
> > older code or say "should now".
> 
> This bug report assumed that Emacs is basically like Common Lisp in this
> area.

No, it doesn't.  Whatever Emacs Lisp users need
to know about integers is what they should be
told.  If they need to be told something about
`eq' then tell that.

> However, Emacs is not there yet (though we've made progress), and it's
> better if
> the documentation reflects that fact rather than pretending there's no
> difference from Common Lisp.

AFAIK, I didn't say anything that contradicts that.
I'd never suggest that Emacs Lisp doc pretend that
Emacs Lisp is the same as Common Lisp where it's
not.

I mentioned CL because its doc is clear wrt the
use of `eql' for numbers.  If the Emacs doc can't
say the same thing, that's fine; it should say
what it needs to say, to make clear its own
behavior.  It shouldn't waffle or confuse users.

> > Any code -
> > old or new - that uses `eq' to compare
> > integers needs to know that at least one of
> > the operands is a fixnum.
> 
> It's sometimes OK to use eq even when both arguments are bignums. It depends
> on the circumstances.

Either it's important to say how `eq' behaves with
bignums or it's not.  

If it is, then users deserve the straight info.
If it's not, why talk about `eq' at all?  In that
case, why not just tell users to compare integers
using `eql' or `='?

You seem to be trying to have your cake and eat
it too.  You seem to want to talk about `eq' in
the context of integers, but you apparently don't
want to say how it behaves.

I don't see how that helps users.  My suggestion
is to either (1) really say what the deal is with
`eq' wrt integers (but not as the first thing we
say about integers - you've already moved it,
which is good) or (2) say nothing about it, other
than to recommend against using it and for using
`eql'.

Figure out what the real message is for users,
about using `eq' with integers - what they should
be told.  Then communicate it.

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

[Paul Eggert]

On 2/17/20 5:52 PM, Drew Adams wrote:
> You seem to be trying to have your cake and eat
> it too.

I think we're done here.

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

[Lars Ingebrigtsen]

Paul Eggert <eggert@cs.ucla.edu> writes:

> I think we're done here.

I think so, too, so I'm closing this bug report.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no