Re: When is a function an interactive function? [was Re: Is function 'org-insert-property-drawer' usable?]

[Jean Louis <bugs@gnu.support>]

* Alain.Cochard@unistra.fr <Alain.Cochard@unistra.fr> [2023-01-06 02:16]: :ATTACH:
:PROPERTIES:
:ID:       51b2af8b-b2b1-45a7-ab74-1d8e7d8fce7e
:END:
> so I was trying to understand if there is a way to deduce whether or
> not a particular function is a command.  Based on several examples
> such as
> 
>    ‘M-<RIGHT>’ (‘org-do-demote’)

Function is considered command when it has declaration (interactive)

See: (info "(elisp) Defining Commands")

22.2 Defining Commands
======================

The special form ‘interactive’ turns a Lisp function into a command.
The ‘interactive’ form must be located at top-level in the function
body, usually as the first form in the body; this applies to both lambda
expressions (*note Lambda Expressions::) and ‘defun’ forms (*note
Defining Functions::).  This form does nothing during the actual
execution of the function; its presence serves as a flag, telling the
Emacs command loop that the function can be called interactively.  The
argument of the ‘interactive’ form specifies how the arguments for an
interactive call should be read.

Please note
-----------

The word "interactive" is used in context of Emacs Lisp, and not in
the context of English language.

In the context of the English language any Emacs Lisp function may be
interactive, even if it is not a command.

And to note is that only commands, which are functions with
(interactive) declaration, may be bound to keys.

> I conjectured that, when an interactive function does correspond to a
> command,

Function with (interactive) declaraion IS a command.

But in English language ordinary context in computing, a function may
be interactive but not a command, because it does not have
(interactive) declaration.

> it is just mentioned between parentheses, right after its
> corresponding key combination.  I tried to check this in an as much
> systematic way as I could and investigated 330 such instances (based
> on the manual of version 9.5).

> - that even if a function is _not_ mentioned in that conventional
>   form, it be explicitly stated in the manual that it is
>   non-interactive (just as was recently proposed for
>   'org-insert-property-drawer' by Ihor+Bastien).

When programmer wish to find out if function is interactive, one can
use C-h f function-name-here to see if it is interactive, or one may
jump to it's definition:

(find-function 'org-insert-property-drawer) and see if there is
declaration to be command, 

or to use the test like this:

(commandp 'org-insert-property-drawer) ➜ nil

IMHO, mentioning for each function if it is interactive or
non-interactive in Emacs manual is waste.

And programmers shall observe that commands should appear only in
corresponding modes:

If MODES is present, it should be a list of mode names (symbols) that
this command is applicable for.  The main effect of this is that
‘M-x TAB’ (by default) won’t list this command if the current buffer’s
mode doesn’t match the list.  That is, if either the major mode isn’t
derived from them, or (when it’s a minor mode) the mode isn’t in effect.

> (interactive &optional ARG-DESCRIPTOR &rest MODES)

> If MODES is present, it should be a list of mode names (symbols) that
> this command is applicable for.  The main effect of this is that
> ‘M-x TAB’ (by default) won’t list this command if the current buffer’s
> mode doesn’t match the list.  That is, if either the major mode isn’t
> derived from them, or (when it’s a minor mode) the mode isn’t in
> effect.

And sharp programmers should make sure that their functions that may
be invoked interactively in other modes, recognize what is going on
and don't disturb user's work or data.

> For example, with the cursor on 'org-capture-finalize' in the manual,
> 'C-h f <RET>' gives nothing right away; 'C-h f org-capture<TAB>' does
> not offer 'org-capture-finalize' as a completion; 'C-h f
> org-capture-fin<TAB>' does complete and says that
> 'org-capture-finalize' is interactive; and then it becomes possible to
> use it with 'M-x'.
> 
> Similarly, as far I as can see, 'M-x org-attach-attach' fails right
> away, but works after having been used once with the standard (menu)
> way.

Good inspection!

I find it not right that I can even invoke `M-x og-attach-attach' in
this mail mode.

And I find it out of control that directory was created in ~/data
without asking me or telling me, by using `org-attach'.

We have too many expectations.

> I can understand why it is like that, but still find it disconcerting.
> If it is to stay this way, perhaps things could be made more explicit
> in the manual.

Thanks for observation.

> List (of non interactive functions that might be thought interactive
> to the ignorant):
> 
> - ‘C-u C-u <TAB>’ (‘org-set-startup-visibility’)

Any function without (interactive) declaration may be made a "command"
by adding declaration by using `lambda' like this:

(lambda () (interactive) (org-set-startup-visibility))

and that `lambda' may be bound to key.

> - ‘C-c C-e’ (‘org-export’) 
> 
>   Shouldn't this one be 'org-export-dispatch'?

Right.

> - ‘C-c '’ (‘org-edit~sbpecial’) 
> 
>   This must be a typo, right?

Good observation.

> - ‘C-c C-e o o’ (‘org-export-to-odt’) 
> 
>   Shouldn't it be 'org-odt-export-to-odt'?

That is right.


-- 
Jean

Take action in Free Software Foundation campaigns:
https://www.fsf.org/campaigns

In support of Richard M. Stallman
https://stallmansupport.org/