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