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

classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

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

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



Reply | Threaded
Open this post in threaded view
|

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.



Reply | Threaded
Open this post in threaded view
|

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

Lars Ingebrigtsen
Paul Eggert <[hidden email]> writes:

> I think we're done here.

I think so, too, so I'm closing this bug report.

--
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no