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

[Drew Adams <drew.adams@oracle.com>]

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