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

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

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.