From: Jean Louis <bugs@gnu.support>
To: Alain.Cochard@unistra.fr
Cc: emacs-orgmode@gnu.org
Subject: Re: When is a function an interactive function? [was Re: Is function 'org-insert-property-drawer' usable?]
Date: Sat, 7 Jan 2023 23:33:09 +0300 [thread overview]
Message-ID: <Y7nXBbfaxHkMpYrz@protected.localdomain> (raw)
In-Reply-To: <25527.22953.318527.300303@gargle.gargle.HOWL>
* 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/
next prev parent reply other threads:[~2023-01-07 20:34 UTC|newest]
Thread overview: 12+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-12-31 16:24 Is function 'org-insert-property-drawer' usable? Alain.Cochard
2022-12-31 16:36 ` Ruijie Yu via General discussions about Org-mode.
2023-01-01 13:23 ` Ihor Radchenko
2023-01-01 16:43 ` Alain.Cochard
2023-01-04 11:53 ` Max Nikulin
2023-01-05 9:41 ` Ihor Radchenko
2023-01-05 10:15 ` Bastien Guerry
2023-01-06 13:32 ` Ihor Radchenko
2023-01-05 23:13 ` When is a function an interactive function? [was Re: Is function 'org-insert-property-drawer' usable?] Alain.Cochard
2023-01-06 4:45 ` Max Nikulin
2023-01-07 20:33 ` Jean Louis [this message]
2023-02-03 11:23 ` Ihor Radchenko
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.orgmode.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=Y7nXBbfaxHkMpYrz@protected.localdomain \
--to=bugs@gnu.support \
--cc=Alain.Cochard@unistra.fr \
--cc=emacs-orgmode@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).