bug#17623: 24.4.50; incorrect example for `apply-partially' in (elisp) `Calling Functions'

[Eli Zaretskii <eliz@gnu.org>]

> From: Michael Heerdegen <michael_heerdegen@web.de>
> Cc: stefan@marxist.se,  17623@debbugs.gnu.org
> Date: Sat, 23 Oct 2021 17:29:09 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > > But Emacs' `1+' accepts one argument.
> >
> > Why does it matter?
> 
> Because the text talks about the number of accepted arguments, right in
> the preceding lines.

The text talks about the variant of 1+ shown in the text, not about
the built-in 1+.

> > Anyway, you are saying that, because the description in the manual
> > doesn't pedantically cover the case of functions that can accept any
> > number of arguments, it is incorrect?  Really??
> 
> Can't you image that some people might have a look at the number of
> accepted arguments of the example -- directly after we talked about the
> number of accepted arguments of the result of an `apply-partially' call
> -- to check if they understood the paragraph correctly?  Is this really
> that far fetched?

No, it isn't far-fetched.  But what problem will those people find?
that infinity - 1 = infinity? isn't that obvious?

> > I'm sorry for this lecture, but it is my impression that you sometimes
> > forget about this when you talk about our documentation -- this is not
> > the first time we argue about similar stuff for similar reasons.
> 
> You don't seem to want to consider that what is a simplification for one
> makes the thing harder to understand for others.

Such simplifications make it harder to understand only for those who
already know what the function does.  They might feel uneasy about the
simplification because they could think it simplifies too much.  Like
I feel whenever I read that analogy about space-time curvature.  But
this text is not written for people who already know, it is written
for those who don't.

> We should aim for a documentation that is good for learning for
> everyone, not only for people who think and learn like you.

Feel free to suggest text which will do that.  The only way I know of
for doing that is to follow a simplified description with a small
print saying something like "This is not entirely accurate; the truth
is that ..." etc.  (That is not what you proposed, and my response was
to what you actually proposed.)  If you think that would be useful, we
could add such a text, if someone submits it.

> Really, I'm a bit irritated about your reactions.

Yes, I've noticed.  It doesn't help.

> Is my way of learning and reading wrong in your eyes?  If I say I
> find that text or detail confusing - is it just that this can't be
> true, and that's it?  Or my mistake?  Or does it not matter?

I hope I answered these questions above.