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