Commands, term "closure" and online help

Commands, term "closure" and online help

[T.V Raman]

Describe function now calls "commands" "closure" as in:

emacspeak is a closure in emacspeak.el.

For the average user, term "closure" is likely intimidating, could we
perhaps call it "Command"? While doing that, it might also be useful to
distinguish non-interactive functions by calling them "functions".


-- 

Re: Commands, term "closure" and online help

[Eli Zaretskii]

> From: "T.V Raman" <raman@google.com>
> Date: Mon, 15 Apr 2024 07:51:38 -0700
> 
> Describe function now calls "commands" "closure" as in:
> 
> emacspeak is a closure in emacspeak.el.

Not here, it doesn't:

  query-replace is an interactive compiled-function in ‘replace.el’.

Re: Commands, term "closure" and online help

[Eli Zaretskii]

> Date: Mon, 15 Apr 2024 17:56:35 +0300
> From: Eli Zaretskii <eliz@gnu.org>
> Cc: emacs-devel@gnu.org
> 
> > From: "T.V Raman" <raman@google.com>
> > Date: Mon, 15 Apr 2024 07:51:38 -0700
> > 
> > Describe function now calls "commands" "closure" as in:
> > 
> > emacspeak is a closure in emacspeak.el.
> 
> Not here, it doesn't:
> 
>   query-replace is an interactive compiled-function in ‘replace.el’.

However, in a native-compilation build I get this, for example:

  find-file is an interactive subr-native-elisp in ‘files.el’.

Can we replace "subr-native-elisp" with something more human-readable,
please?

Re: Commands, term "closure" and online help

[T.V Raman]

I dont have native compile turned on.

I slightly mispoke earlier, non-interactive functions appear to be
described as closure, not sure if that is always the case.
string-lessp is called a  primitive-function, which is actually
useful.
string-trim is called a compiled function.

emacspeak is called a compiled function, however if you eval the
function with C-x C-e while developing it gets called  a compiled
closure.

All in all quite  confusing 

Eli Zaretskii writes:
 > > Date: Mon, 15 Apr 2024 17:56:35 +0300
 > > From: Eli Zaretskii <eliz@gnu.org>
 > > Cc: emacs-devel@gnu.org
 > > 
 > > > From: "T.V Raman" <raman@google.com>
 > > > Date: Mon, 15 Apr 2024 07:51:38 -0700
 > > > 
 > > > Describe function now calls "commands" "closure" as in:
 > > > 
 > > > emacspeak is a closure in emacspeak.el.
 > > 
 > > Not here, it doesn't:
 > > 
 > >   query-replace is an interactive compiled-function in ‘replace.el’.
 > 
 > However, in a native-compilation build I get this, for example:
 > 
 >   find-file is an interactive subr-native-elisp in ‘files.el’.
 > 
 > Can we replace "subr-native-elisp" with something more human-readable,
 > please?

-- 

Re: Commands, term "closure" and online help

[Eli Zaretskii]

> From: "T.V Raman" <raman@google.com>
> Date: Mon, 15 Apr 2024 08:49:10 -0700
> Cc: monnier@iro.umontreal.ca,
>     raman@google.com,
>     emacs-devel@gnu.org
> 
> I dont have native compile turned on.
> 
> I slightly mispoke earlier, non-interactive functions appear to be
> described as closure, not sure if that is always the case.

I don't see that, either, at least not with a random function I tried:

  file-truename is a compiled-function in ‘files.el’.

This is in a build without native compilation.

> emacspeak is called a compiled function, however if you eval the
> function with C-x C-e while developing it gets called  a compiled
> closure.

Ah, now you are talking!  Indeed, functions defined with C-x C-e are
described as closures.  What would you like to see instead?
interpreted-function, perhaps?

Re: Commands, term "closure" and online help

[Joel Reicher]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: "T.V Raman" <raman@google.com>
>> Date: Mon, 15 Apr 2024 08:49:10 -0700
>> Cc: monnier@iro.umontreal.ca, 
>>     raman@google.com, emacs-devel@gnu.org
>>
>> emacspeak is called a compiled function, however if you eval 
>> the function with C-x C-e while developing it gets called  a 
>> compiled closure.
>
> Ah, now you are talking!  Indeed, functions defined with C-x C-e 
> are described as closures.  What would you like to see instead? 
> interpreted-function, perhaps?

Perhaps "dynamically ..." rather than "interpreted"? That word is 
used in the part of the elisp manual that describes defun 
also. Something like "dynamically generated function" or 
"dynamically defined function"?

Regards,

        - Joel

Re: Commands, term "closure" and online help

[Michael Heerdegen via Emacs development discussions.]

Joel Reicher <joel.reicher@gmail.com> writes:

> > Ah, now you are talking!  Indeed, functions defined with C-x C-e are
> > described as closures.  What would you like to see instead?
> > interpreted-function, perhaps?

> Perhaps "dynamically ..." rather than "interpreted"? That word is used
> in the part of the elisp manual that describes defun also. Something
> like "dynamically generated function" or "dynamically defined
> function"?

Aren't "dynamically defined functions" bytecode functions when running
compiled code?  So this would not be a better term.

AFAIU we want to tell that these functions will, when funcalled, be
handled by the interpreter - thus, are interpreted functions in that
sense.


Michael.

Re: Commands, term "closure" and online help

[Joel Reicher]

Michael Heerdegen via "Emacs development discussions." 
<emacs-devel@gnu.org> writes:

> Joel Reicher <joel.reicher@gmail.com> writes:
>
>>> Ah, now you are talking!  Indeed, functions defined with C-x 
>>> C-e are described as closures.  What would you like to see 
>>> instead?  interpreted-function, perhaps?
>
>> Perhaps "dynamically ..." rather than "interpreted"? That word 
>> is used in the part of the elisp manual that describes defun 
>> also. Something like "dynamically generated function" or 
>> "dynamically defined function"?
>
> Aren't "dynamically defined functions" bytecode functions when 
> running compiled code?  So this would not be a better term.

Which bit of the documentation are you thinking of? I can't find 
that phrase with reference to bytecode.

> AFAIU we want to tell that these functions will, when funcalled, 
> be handled by the interpreter - thus, are interpreted functions 
> in that sense.

My understanding is that the closure is constructed the moment the 
defun (et al) is done, regardless of whether the function is ever 
called.

I'm not familiar with the implementation details but it looks to 
me from a trivial test this happens unconditionally; even when the 
function being defined does not capture anything from its 
enclosing scope...

(defun blah ())

C-x C-e and then C-h f blah to see what I mean. (Maybe this gets 
optimised later?)

That's one of the reasons I think it might be helpful to refer to 
this simply as a function that is "dynamically created", or some 
variation on that.

Regards,

        - Joel

Re: Commands, term "closure" and online help

[Michael Heerdegen via Emacs development discussions.]

Joel Reicher <joel.reicher@gmail.com> writes:

> > Aren't "dynamically defined functions" bytecode functions when
> > running compiled code?  So this would not be a better term.
>
> Which bit of the documentation are you thinking of? I can't find that
> phrase with reference to bytecode.

We are talking about the generated documentation in *Help*, right?  I've
just been using my own words.

>
> > AFAIU we want to tell that these functions will, when funcalled, be
> > handled by the interpreter - thus, are interpreted functions in that
> > sense.
>
> My understanding is that the closure is constructed the moment the
> defun (et al) is done, regardless of whether the function is ever
> called.
>
> I'm not familiar with the implementation details but it looks to me
> from a trivial test this happens unconditionally; even when the
> function being defined does not capture anything from its enclosing
> scope...
>
> (defun blah ())
>
> C-x C-e and then C-h f blah to see what I mean. (Maybe this gets
> optimised later?)
>
> That's one of the reasons I think it might be helpful to refer to this
> simply as a function that is "dynamically created", or some variation
> on that.

I know what you want to say.  But technically, the only difference to
named functions and commands is that these are just unnamed.

But: Note that the wording used in the generated help pages has changed
since the start of this thread: we are currently saying (at least in
master) "interactive interpreted-function" or "interactive
byte-code-function".  Can you live with that?


Michael.

Re: Commands, term "closure" and online help

[Joel Reicher]

Michael Heerdegen via "Emacs development discussions." 
<emacs-devel@gnu.org> writes:

> Joel Reicher <joel.reicher@gmail.com> writes:
>
>>> Aren't "dynamically defined functions" bytecode functions when 
>>> running compiled code?  So this would not be a better term.
>>
>> Which bit of the documentation are you thinking of? I can't 
>> find that phrase with reference to bytecode.
>
> We are talking about the generated documentation in *Help*, 
> right?  I've just been using my own words.

In my question above I was referring to the Info documentation. I 
think it's helpful for the generated and static documentation to 
use consistent terminology.

> But: Note that the wording used in the generated help pages has 
> changed since the start of this thread: we are currently saying 
> (at least in master) "interactive interpreted-function" or 
> "interactive byte-code-function".  Can you live with that?

Oh I see! Just had a poke around in the repo; I didn't realise the 
elisp respresentations themselves had changed, and I thought this 
was still just a documentation matter.

I can't really offer an opinion until I understand the way the new 
types are being used, but I think the OP's main concern was that 
the term "closure" be avoided because it's a little opaque to some 
people unfamiliar with language implementation.

Thanks and regards,

       - Joel

Re: Commands, term "closure" and online help

[Michael Heerdegen]

Joel Reicher <joel.reicher@gmail.com> writes:

> I can't really offer an opinion until I understand the way the new
> types are being used

Actually, nothing changed wrt. usage.  Interpreted functions are only
not lists anymore but opaque objects, so their representation doesn't
invite to abuses.  That's more or less all.

> but I think the OP's main concern was that the term "closure" be
> avoided because it's a little opaque to some people unfamiliar with
> language implementation.

I agree it had been an irritating terminology.

Michael.