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

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

[Drew Adams]

The text states incorrectly that the example defines an equivalent of
built-in function `1+', but it does not.  The function defined in the
example is equivalent to this one, which is not equivalent to `1+':

(defun 1+-sum (&rest args)
 "Return one more than the sum of the args."
 (1+ (apply #'+ args)))

This function accepts any number of args, including zero.
`1+' requires a single arg.

As it stands, this example is liable to confuse more than help.

In GNU Emacs 24.4.50.1 (i686-pc-mingw32)
 of 2014-05-25 on ODIEONE
Bzr revision: 117153 tsdh@gnu.org-20140525174054-vzeh4zeg00a1ley8
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/Devel/emacs/snapshot/trunk
 --enable-checking=yes,glyphs 'CFLAGS=-O0 -g3'
 LDFLAGS=-Lc:/Devel/emacs/lib 'CPPFLAGS=-DGC_MCHECK=1
 -Ic:/Devel/emacs/include''

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

[Michael Heerdegen]

Drew Adams <drew.adams@oracle.com> writes:

> The text states incorrectly that the example defines an equivalent of
> built-in function `1+', but it does not.  The function defined in the
> example is equivalent to this one, which is not equivalent to `1+':
> [...]
> As it stands, this example is liable to confuse more than help.

I think you're right.  Drew, how would you reformulate the paragraph so
that it's not confusing?

Or should we try to find a different example?  Maybe something like

  (defalias 'string-empty-p (apply-partially #'string= "")) ?

Michael.

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

[Drew Adams]

> should we try to find a different example?  Maybe something like
> (defalias 'string-empty-p (apply-partially #'string= "")) ?

Yes, we should.  But forget about giving an example that (re)defines
a function that is a built-in or is otherwise predefined.

And again, it is better to have an example that illustrates and
takes advantage of the fact that the function returned accepts any
number of args.

`string=' accepts only two args.  The signature of `string-empty-p'
shows that it accepts any number of arguments, and it says nothing
about their type, but `string-empty-p' raises an error if it is
passed anything other than 2 strings.  Nothing wrong with that, but
it is not so clear as an illustration of `apply-partially'.

And it is better to have an example where the function passed does
not have _only_ an &rest parameter (in which case it could be applied
to just the first argument anyway).  This example uses a function (+)
that accepts any number of args, but its only parameter is an &rest
parameter, so it is not a great way to show `apply-partially':

(defalias '3+ (apply-partially '+ 3)
  "Return 3 plus the sum of the arguments.")

(3+ 2 5 1)
    => 11

That is better than an example that uses a function that accepts
only a fixed number of arguments, but it is not as informative as
examples like these, which accept a first arg that is a string
and other args of any type.

(defun present-list (frmt &rest things)
  "Use format string FRMT to present a list of THINGS."
  (format frmt things))

(defalias 'list-en (apply-partially #'present-list "The list: `%S'")
  "Return a string that presents a list of arguments.")

(defalias 'list-fr (apply-partially #'present-list "La liste : `%S'")
  "Renvoyer une chaine qui presente use liste d'arguments.")

(list-en 1 2 3)
    => "The list: `(1 2 3)'"

(list-fr '(x 42) '(y alpha))
    => "La liste : `((x 42) (y alpha))'"

However, instead of (or in addition to) showing such an example,
we could show the simple equivalence of these two (for all FUN,
ARG1, and ARGS):

(apply (apply-partially FUN ARG1) ARGS) = (apply FUN ARG1 ARGS)

That alone tells users what `apply-partially' is all about.

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

[Michael Heerdegen]

Hi,

BTW, the second sentence here from (info "(elisp) Calling Functions") is
confusing too wrt what it says about arguments.

,----------------------------------------------------------------------
| The act of fixing some of the function’s arguments is
| called "partial application" of the function(1).  The result is a new
| function that accepts the rest of arguments and calls the original
| function with all the arguments combined.
`----------------------------------------------------------------------

IMHO we should be more clearer about arguments, but then we can keep the
1+ example.  I think it would be more important to say that
`apply-partially` is most useful in combination with functionals, as it
is explained later on that info page.  That the result accepts any
number of arguments is more kind of an implementation detail.


Michael.

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

[Eli Zaretskii]

> From: Michael Heerdegen <michael_heerdegen@web.de>
> Date: Sat, 28 Jun 2014 17:53:15 +0200
> Cc: 17623@debbugs.gnu.org
> 
> BTW, the second sentence here from (info "(elisp) Calling Functions") is
> confusing too wrt what it says about arguments.
> 
> ,----------------------------------------------------------------------
> | The act of fixing some of the function’s arguments is
> | called "partial application" of the function(1).  The result is a new
> | function that accepts the rest of arguments and calls the original
> | function with all the arguments combined.
> `----------------------------------------------------------------------
> 
> IMHO we should be more clearer about arguments, but then we can keep the
> 1+ example.  I think it would be more important to say that
> `apply-partially` is most useful in combination with functionals, as it
> is explained later on that info page.  That the result accepts any
> number of arguments is more kind of an implementation detail.

Sorry, I don't understand this critique.  Perhaps if you suggested an
alternative wording, it would become clear what is it that confused
you about the current text.

Thanks.

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

[Michael Heerdegen]

Eli Zaretskii <eliz@gnu.org> writes:

> Sorry, I don't understand this critique.  Perhaps if you suggested an
> alternative wording, it would become clear what is it that confused
> you about the current text.

There's nothing wrong per see in the current text, but it sounds as if
`apply-partially` would somehow analyze the argument list of its first
argument.  But it's semantic is very simple.

Say that

  (apply-partially f arg_1 ... arg_n) 

is equivalent to

  (lambda (&rest args) (apply f arg_1 ... arg_n args))

With that, what we currently have an ok elucidation of that definition.


And I think that the paragraph about `apply-partially` should be merged
into the later text talking about functionals, because the main use case
of `apply-partially` is to construct anonymous functions for usage as
argument to some other function.


Michael.

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

[Eli Zaretskii]

> From: Michael Heerdegen <michael_heerdegen@web.de>
> Cc: 17623@debbugs.gnu.org
> Date: Sat, 28 Jun 2014 19:53:34 +0200
> 
> There's nothing wrong per see in the current text, but it sounds as if
> `apply-partially` would somehow analyze the argument list of its first
> argument.

Where does it say that?  It says the result is a new function that
will call the original with all the arguments combined.  There's
nothing about analysis in that text.

> Say that
> 
>   (apply-partially f arg_1 ... arg_n) 
> 
> is equivalent to
> 
>   (lambda (&rest args) (apply f arg_1 ... arg_n args))

Sorry, I don't see how this is an improvement.

Accidentally, the current text is a bit different from what you cited:

   -- Function: apply-partially func &rest args
       This function returns a new function which, when called, will call
       FUNC with the list of arguments composed from ARGS and additional
       arguments specified at the time of the call.  If FUNC accepts N
       arguments, then a call to `apply-partially' with `M < N' arguments
       will produce a new function of `N - M' arguments.

> And I think that the paragraph about `apply-partially` should be merged
> into the later text talking about functionals, because the main use case
> of `apply-partially` is to construct anonymous functions for usage as
> argument to some other function.

If you mean this:

     It is common for Lisp functions to accept functions as arguments or
  find them in data structures (especially in hook variables and property
  lists) and call them using `funcall' or `apply'.  Functions that accept
  function arguments are often called "functionals".

     Sometimes, when you call a functional, it is useful to supply a no-op
  function as the argument.  Here are two different kinds of no-op
  function:

then it directly follows the part we were talking about.

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

[Michael Heerdegen]

Eli Zaretskii <eliz@gnu.org> writes:

> > Say that
> > 
> >   (apply-partially f arg_1 ... arg_n) 
> > 
> > is equivalent to
> > 
> >   (lambda (&rest args) (apply f arg_1 ... arg_n args))
>
> Sorry, I don't see how this is an improvement.

It's an improvement because it's short and clearer than any text that
just tries to describe it.

> Accidentally, the current text is a bit different from what you cited:

I didn't cite anything, I just said that I don't find it clear, because
I think it can be misunderstood.

> > And I think that the paragraph about `apply-partially` should be merged
> > into the later text talking about functionals, because the main use case
> > of `apply-partially` is to construct anonymous functions for usage as
> > argument to some other function.
>
> If you mean this:
>
>      It is common for Lisp functions to accept functions as arguments or
>   find them in data structures (especially in hook variables and property
>   lists) and call them using `funcall' or `apply'.  Functions that accept
>   function arguments are often called "functionals".
>
>      Sometimes, when you call a functional, it is useful to supply a no-op
>   function as the argument.  Here are two different kinds of no-op
>   function:
>
> then it directly follows the part we were talking about.

I were talking about both parts, and that we should say that
`apply-partially` is, like ignore and identity, as well mainly useful in
combination with functionals.  That's all.

Eli, dunno why, but our discussions don't yield any results most of the
time.  I would like to stop here, ok?

Michael.

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

[Eli Zaretskii]

> From: Michael Heerdegen <michael_heerdegen@web.de>
> Cc: 17623@debbugs.gnu.org
> Date: Sat, 28 Jun 2014 21:37:06 +0200
> 
> Eli, dunno why, but our discussions don't yield any results most of the
> time.  I would like to stop here, ok?

??? Are you sure you didn't confuse me with some other Eli?  Because I
actually googled our discussions, and I see only examples to the
contrary.

In any case, if you want to stop the discussion, just don't reply.  No
need for uncalled-for semi-offensive remarks.

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

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

>> Say that
>>
>>   (apply-partially f arg_1 ... arg_n)
>>
>> is equivalent to
>>
>>   (lambda (&rest args) (apply f arg_1 ... arg_n args))
>
> Sorry, I don't see how this is an improvement.
>
> Accidentally, the current text is a bit different from what you cited:
>
>    -- Function: apply-partially func &rest args
>        This function returns a new function which, when called, will call
>        FUNC with the list of arguments composed from ARGS and additional
>        arguments specified at the time of the call.  If FUNC accepts N
>        arguments, then a call to `apply-partially' with `M < N' arguments
>        will produce a new function of `N - M' arguments.
>
>> And I think that the paragraph about `apply-partially` should be merged
>> into the later text talking about functionals, because the main use case
>> of `apply-partially` is to construct anonymous functions for usage as
>> argument to some other function.
>
> If you mean this:
>
>      It is common for Lisp functions to accept functions as arguments or
>   find them in data structures (especially in hook variables and property
>   lists) and call them using `funcall' or `apply'.  Functions that accept
>   function arguments are often called "functionals".
>
>      Sometimes, when you call a functional, it is useful to supply a no-op
>   function as the argument.  Here are two different kinds of no-op
>   function:
>
> then it directly follows the part we were talking about.

There was a discussion here about how to improve the 'apply-partially'
documentation, but it didn't yield any concrete suggestions for
improvements.  I read the text we have now, and I find it clear with
regards to the questions raised in this thread, so I'm closing this bug
report.

If this conclusion is incorrect and this is still an issue, please reply
to this email (use "Reply to all" in your email client) and we might
reconsider.  We are more likely to reconsider if such a request comes
with a concrete suggestion for how to improve this text, preferably in
the form of a patch.

Thanks.

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

[Michael Heerdegen]

Stefan Kangas <stefan@marxist.se> writes:

> There was a discussion here about how to improve the 'apply-partially'
> documentation, but it didn't yield any concrete suggestions for
> improvements.  I read the text we have now, and I find it clear with
> regards to the questions raised in this thread, so I'm closing this bug
> report.

I disagree.  The paragraph in the manual explains what the arity of the
function returned by `apply-partially' would be.

Directly following is an example suggesting that (apply-partially '+ 1)
is equivalent to #'1+ - which obviously contradicts that preceding
paragraph.

I'm a bit confused that you don't consider this a problem, and also that
you said there were no concrete suggestions.

There were concrete suggestions for improvements.  One was to simply
spell out the function that is constructed.  It is only one line, and
would make the semantics clear.

BTW, whenever I posted an example using `apply-partially', Stefan told
me that it would be more efficient to write out the lambda.  That aspect
could also be covered: when is worth using?

Or delete that paragraph, better to say nothing than to confuse readers.


Michael.

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

[Stefan Kangas]

Michael Heerdegen <michael_heerdegen@web.de> writes:

> I disagree.  The paragraph in the manual explains what the arity of the
> function returned by `apply-partially' would be.
>
> Directly following is an example suggesting that (apply-partially '+ 1)
> is equivalent to #'1+ - which obviously contradicts that preceding
> paragraph.
>
> I'm a bit confused that you don't consider this a problem, and also that
> you said there were no concrete suggestions.

I have re-read the paragraph, and I have to say that IMO it is clear as
is written.  But I understand that you feel that it is not.

> There were concrete suggestions for improvements.  One was to simply
> spell out the function that is constructed.  It is only one line, and
> would make the semantics clear.

Instead of going into all that, can't we just find an example where the
arity doesn't present any problems?  Any ideas for something like that?

How about zerop?

    (defalias 'zerop (apply-partially '= 0)
      "Return t if argument is zero.")

But I guess `=' is also N-ary...

> BTW, whenever I posted an example using `apply-partially', Stefan told
> me that it would be more efficient to write out the lambda.  That aspect
> could also be covered: when is worth using?

That could be useful to add, I agree.

> Or delete that paragraph, better to say nothing than to confuse readers.

I think it should be kept.  Performance is not the only consideration.

    (apply-partially #'fun foo bar baz)

    (lambda (&rest args) (apply #'fun foo bar baz args))

It's obviously a matter of style but I find the former easier to read
than the latter.

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

[Michael Heerdegen]

Stefan Kangas <stefan@marxist.se> writes:

> How about zerop?
>
>     (defalias 'zerop (apply-partially '= 0)
>       "Return t if argument is zero.")
>
> But I guess `=' is also N-ary...

How about

(defalias 'max-positive (apply-partially #'max 0)
  "Return the largest non-negative argument or 0 if all are negative.")

Or something like

(apply-partially #'seq-concatenate 'vector)

or

(defalias 'user-file-name-concat
  (apply-partially #'file-name-concat (expand-file-name "~/")))

?

Michael.

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

[Eli Zaretskii]

> From: Michael Heerdegen <michael_heerdegen@web.de>
> Cc: Eli Zaretskii <eliz@gnu.org>,  17623-done@debbugs.gnu.org
> Date: Sat, 23 Oct 2021 11:44:21 +0200
> 
> I disagree.  The paragraph in the manual explains what the arity of the
> function returned by `apply-partially' would be.
> 
> Directly following is an example suggesting that (apply-partially '+ 1)
> is equivalent to #'1+ - which obviously contradicts that preceding
> paragraph.

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.

> I'm a bit confused that you don't consider this a problem, and also that
> you said there were no concrete suggestions.

That suggestion doesn't make the documentation more clear, IMNSHO,
unless the reader already knows about apply-partially and generally
has a lot of background knowledge about Lisp and Emacs Lisp.  Why are
you saying the suggestion is not being considered, whereas in reality
it was considered (and rejected)?

> There were concrete suggestions for improvements.  One was to simply
> spell out the function that is constructed.  It is only one line, and
> would make the semantics clear.

I cannot disagree more.  That one line doesn't make anything clear, it
just shows the implementation.

> BTW, whenever I posted an example using `apply-partially', Stefan told
> me that it would be more efficient to write out the lambda.  That aspect
> could also be covered: when is worth using?

Concrete proposals for expanding the documentation of apply-partially
(read: patches) will be most welcome, of course.

> Or delete that paragraph, better to say nothing than to confuse readers.

I object to deleting that.  That text certainly helps me, so it cannot
be useless, let alone harmful.

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

[Michael Heerdegen]

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. 1 /= infinity.  Different
functions.

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.

> > I'm a bit confused that you don't consider this a problem, and also that
> > you said there were no concrete suggestions.

> Why are you saying the suggestion is not being considered, whereas in
> reality it was considered (and rejected)?

I responded to "there were no suggestions" without reading everything of
the thread.  I had the impression that the bug had been closed in a
rush.  Maybe I was wrong.  Stefan's explanation was confusing to me.

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

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


Michael.

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.

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

[Michael Heerdegen]

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

Yes, because then it would be a correct replacement.

> > 1 /= infinity.  Different functions.
>
> Actually, I think the issue here is that infinity - 1 = infinity.

In this context this is correct.  What issue?

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

> 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.  We should aim for a
documentation that is good for learning for everyone, not only for
people who think and learn like you.

Really, I'm a bit irritated about your reactions.  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?

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

That "N".  It is called the arity of that function.  Also M-N.

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

Then please do that.


Michael.

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

[Stefan Kangas]

Michael Heerdegen <michael_heerdegen@web.de> writes:

>> 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.
>
> Then please do that.

Now done on emacs-28 (commit ef37a86cac).  I also fixed the
documentation bug you spotted where we used < instead of <=.

Thanks.

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

[Michael Heerdegen]

Stefan Kangas <stefan@marxist.se> writes:

> Now done on emacs-28 (commit ef37a86cac).  I also fixed the
> documentation bug you spotted where we used < instead of <=.

Thanks.

When reading again, I wondered if we should convert that whole manual
page to use function quoting.  E.g.

  (apply-partially '+ 1) ~> (apply-partially #'+ 1)

The same problem exists for a few other pages.  Should I make a separate
report about this?

TIA,
Michael.

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

[Stefan Kangas]

Michael Heerdegen <michael_heerdegen@web.de> writes:

> When reading again, I wondered if we should convert that whole manual
> page to use function quoting.  E.g.
>
>   (apply-partially '+ 1) ~> (apply-partially #'+ 1)
>
> The same problem exists for a few other pages.  Should I make a separate
> report about this?

I don't have a strong opinion either way.

I think what could be better documented are the benefits of quoting with
function (or #').  AFAICT, it is not really explained on (info "(elisp)
Anonymous Functions"), it is more hinted at.

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

[Michael Heerdegen]

Stefan Kangas <stefan@marxist.se> writes:

> I think what could be better documented are the benefits of quoting
> with function (or #').  AFAICT, it is not really explained on
> (info "(elisp) Anonymous Functions"), it is more hinted at.

Yes, it could say that one should always use this for quoting functions.

That page also doesn't tell that lambda the macro is self-funquoting -
without this information the part about lambda expressions is a bit
confusing.


Michael.

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

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > I think what could be better documented are the benefits of quoting with
  > function (or #').  AFAICT, it is not really explained on (info "(elisp)
  > Anonymous Functions"), it is more hinted at.

I don't know of any benefit to using #', or any reason to use it.
If there is one, I'd like to know about it.

In the absence of a reason, I think we may as well keep Lisp simple
by quoting function names with singlequote.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

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

[Michael Heerdegen]

Richard Stallman <rms@gnu.org> writes:

> I don't know of any benefit to using #', or any reason to use it.
> If there is one, I'd like to know about it.

For named functions, the byte-compiler will warn if that function is not
defined or might not be known at run time.  Very helpful to detect typos
or dependency problems.  But that only works if you use this style
consequently.

Michael.

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

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

[Stefan Kangas]

Michael Heerdegen <michael_heerdegen@web.de> writes:

> Why again was saying something like "note that unlike the built-in
> function this version accepts any number of arguments" rejected?

Would this resolve any remaining confusion in this paragraph?  If so,
adding this sounds like a reasonable outcome.  It is a true statement,
and I don't think it risks confusing things further.

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

[Michael Heerdegen]

Stefan Kangas <stefan@marxist.se> writes:

> Michael Heerdegen <michael_heerdegen@web.de> writes:
>
> > Why again was saying something like "note that unlike the built-in
> > function this version accepts any number of arguments" rejected?
>
> Would this resolve any remaining confusion in this paragraph?

Yes.

I would also replace "M<N" with "M<=N"; there are useful cases with M=N,
e.g.

#+begin_src emacs-lisp
(defalias 'make-minibufferless-frame
  (apply-partially #'make-frame '((minibuffer . nil))))
;; (make-minibufferless-frame) => [a new frame without a minibuffer]
#+end_src


Michael.

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

[Eli Zaretskii]

> From: Michael Heerdegen <michael_heerdegen@web.de>
> Cc: Eli Zaretskii <eliz@gnu.org>,  17623-done@debbugs.gnu.org
> Date: Sat, 23 Oct 2021 17:38:21 +0200
> 
> I would also replace "M<N" with "M<=N"; there are useful cases with M=N,
> e.g.

I don't object, but please note that the text didn't say M=N is not a
possibility.  It says _IF_ M<N, _THEN_ ..., so this doesn't say that M
cannot be equal to N, and understanding it as if it did say that is
IMO jumping to wrong conclusions.

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

[Drew Adams]

>      It is common for Lisp functions to accept functions as arguments or
>   find them in data structures (especially in hook variables and property
>   lists) and call them using `funcall' or `apply'.  Functions that accept
>   function arguments are often called "functionals".
>      Sometimes, when you call a functional, ...

No, they are not "often" called functionals.  They are far more commonly
called "higher-order functions", especially in the context of programming.
FWIW, I suggest you replace "functional" with that more recognizable term.

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

[Stefan Monnier]

> There's nothing wrong per see in the current text, but it sounds as if
> `apply-partially` would somehow analyze the argument list of its first
> argument.  But it's semantic is very simple.

> Say that

>   (apply-partially f arg_1 ... arg_n) 

> is equivalent to

>   (lambda (&rest args) (apply f arg_1 ... arg_n args))

This equivalence is not true either.  E.g.

    (prog1 (apply-partially #'message format)
      (setq format "hello"))

BTW, `apply-partially' is mostly a crutch to have "simple closures" in
a dynamically scoped setting.  In code that uses lexical-binding, it's
generally better to use a straight closure.


        Stefan