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

[Paul Eggert <eggert@cs.ucla.edu>]

On 2/17/20 3:19 PM, Drew Adams wrote:

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

That's clear from context. This section is titled "Integer Basics" and it's all 
about integers.

Personally I'd even trim some text from the above quote, as it's not basic to 
integers. I would rather not make that text longer or trickier.

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

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

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

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

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