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

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

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

> 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'm really surprised this doc got inserted as it is.

I'm not surprised at all. The doc was an improvement over its predecessor, we're 
all busy doing other things, and the issues raised in this bug report are low 
priority.

If you're still dissatisfied with the manual, I suggest proposing specific 
wording changes so that future fixes in this area can be accomplished more 
efficiently.