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

[Eli Zaretskii]

> From: Michael Heerdegen <michael_heerdegen@web.de>
> Cc: stefan@marxist.se,  17623-done@debbugs.gnu.org
> Date: Sat, 23 Oct 2021 14:44:39 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > In what sense is that a contradiction?  (+ 1 10) is equivalent to (1+ 10),
> > so we have N = 2 arguments in the original function and M = 1 = N - 1 in
> > the new one.
> 
> No, N is described as the number of arguments the function accepts, not
> as the number of arguments in someone's example.  So
> 
>  N = infinity, and  M = N - 1 = infinity.
> 
> But Emacs' `1+' accepts one argument.

Why does it matter?  The example shows a function created by
apply-partially, it doesn't say the result is exactly bug-for-bug
compatible with the existing primitive.  Suppose we would enhance the
built-in 1+ to accept any number of arguments: would you then retract
your objections? why?

> 1 /= infinity.  Different functions.

Actually, I think the issue here is that infinity - 1 = infinity.

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

This manual is not an academic paper, where everything must be
pedantically rigorous.  It is a manual that teaches a language.  When
you teach, you sometimes use simplifications to explain a complex
subject, and simplifications are always less than 100% accurate.  But
that doesn't make simplifications useless or invalid.  Like the
well-known analogy that explains gravitation-induced curvature of the
space-time by describing a heavy marble ball placed on a rubber sheet
(which is preposterously incorrect, if one takes the analogy apart),
simplifications help people to form a mental model of what really
happens that is instrumental and thus useful, even if it isn't
rigorously correct.  So simplifications are a useful didactic
instrument, and we shouldn't be afraid of using them when they do the
job.

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.

If it will help remove your objections, we could note in parentheses
that functions which accept any number of arguments will still accept
any number of arguments after apply-partially.  Would that be good
enough for you?  If not, why not?

> It is a detail, but given that the preceding paragraph explains the
> arity, and then we give an example that doesn't preserve arity, it's a
> detail with the potential of confusion.

That paragraph doesn't explain the arity.  It doesn't mention that
word even once.  It explains apply-partially, not arity.

> > I cannot disagree more.  That one line doesn't make anything clear, it
> > just shows the implementation.
> 
> It does for me.  We can't have both?

No, because showing the implementation muddies the waters and will
confuse at least some readers.  So it's a net loss for a manual that
needs to explain and teach.  And the implementation can be easily seen
anyway, it's just one keypress away.

> > I object to deleting that.  That text certainly helps me, so it cannot
> > be useless, let alone harmful.
> 
> Why again was saying something like "note that unlike the built-in
> function this version accepts any number of arguments" rejected?

It wasn't, because it wasn't suggested anywhere I could see in the
discussion.  I've no objections to adding this as a footnote, FWIW.