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.