Is function 'org-insert-property-drawer' usable?

Is function 'org-insert-property-drawer' usable?

[Alain.Cochard]

The manual says:

   You can interactively insert a drawer at point by calling
   ‘org-insert-drawer’, which is bound to ‘C-c C-x d’. [...]  With a
   prefix argument, this command calls ‘org-insert-property-drawer’,
   which creates a ‘PROPERTIES’ drawer right below the current
   headline.

For me,

   C-u C-c C-x d

does insert a 'PROPERTIES' drawer, but

   M-x org-insert-property-drawer

does not.  In fact 'M-x org-insert-p<TAB>' offers no completion.  I
generally use this kind of information to use my own key bindings, but
here I cannot (don't know how).

-- 
EOST (École et Observatoire des Sciences de la Terre) 
ITE (Institut Terre & Environnement) | alain.cochard@unistra.fr
5 rue René Descartes   [bureau 110]  | Phone: +33 (0)3 68 85 50 44 
F-67084 Strasbourg Cedex, France     | [ slot available for rent ]

Re: Is function 'org-insert-property-drawer' usable?

[Ruijie Yu via General discussions about Org-mode.]

Alain.Cochard@unistra.fr writes:

> The manual says:
>
>    You can interactively insert a drawer at point by calling
>    ‘org-insert-drawer’, which is bound to ‘C-c C-x d’. [...]  With a
>    prefix argument, this command calls ‘org-insert-property-drawer’,
>    which creates a ‘PROPERTIES’ drawer right below the current
>    headline.
>
> For me,
>
>    C-u C-c C-x d
>
> does insert a 'PROPERTIES' drawer, but
>
>    M-x org-insert-property-drawer
>
> does not.  In fact 'M-x org-insert-p<TAB>' offers no completion.  I
> generally use this kind of information to use my own key bindings, but
> here I cannot (don't know how).

According to the source code of `org-insert-drawer', I think the manual
is saying that when ARG is non-nil, the function simply calls
`org-insert-property-drawer'.  However, `org-insert-property-drawer' is
not declared interactive, so you wouldn't be able to M-x it.  You could,
however, still run it via elisp:

      M-: (org-insert-property-drawer) RET

Best,


RY

Re: Is function 'org-insert-property-drawer' usable?

[Ihor Radchenko]

[-- Attachment #1: Type: text/plain, Size: 445 bytes --]

Ruijie Yu via "General discussions about Org-mode."
<emacs-orgmode@gnu.org> writes:

> According to the source code of `org-insert-drawer', I think the manual
> is saying that when ARG is non-nil, the function simply calls
> `org-insert-property-drawer'.  However, `org-insert-property-drawer' is
> not declared interactive, so you wouldn't be able to M-x it.

I guess we can just make it into a command. I see no downsides.

See the attached.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-org-insert-property-drawer-Make-into-a-command.patch --]
[-- Type: text/x-patch, Size: 1121 bytes --]

From a32e4791ee3b0f12d8b9ce006c2ec4cede3829eb Mon Sep 17 00:00:00 2001
Message-Id: <a32e4791ee3b0f12d8b9ce006c2ec4cede3829eb.1672579366.git.yantar92@posteo.net>
From: Ihor Radchenko <yantar92@posteo.net>
Date: Sun, 1 Jan 2023 16:21:32 +0300
Subject: [PATCH] org-insert-property-drawer: Make into a command

* lisp/org.el (org-insert-property-drawer): Make interactive.  This
function is mentioned in the manual and may be used by users.

Reported-by: Alain.Cochard@unistra.fr
Link: https://orgmode.org/list/25520.25134.831330.318368@gargle.gargle.HOWL
---
 lisp/org.el | 1 +
 1 file changed, 1 insertion(+)

diff --git a/lisp/org.el b/lisp/org.el
index db32ec562..6cb326ca0 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -13062,6 +13062,7 @@ (defun org-insert-property-drawer ()
   "Insert a property drawer into the current entry.
 Do nothing if the drawer already exists.  The newly created
 drawer is immediately hidden."
+  (interactive)
   (org-with-wide-buffer
    ;; Set point to the position where the drawer should be inserted.
    (if (or (not (featurep 'org-inlinetask)) (org-inlinetask-in-task-p))
-- 
2.38.1


[-- Attachment #3: Type: text/plain, Size: 224 bytes --]


-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: Is function 'org-insert-property-drawer' usable?

[Alain.Cochard]

Ihor Radchenko writes on Sun  1 Jan 2023 13:23:

 > I guess we can just make it into a command.

For me, that would be ideal.  Otherwise, I think it would help a bit
to change the manual from

   ... this command calls ‘org-insert-property-drawer’ ...

to

   ... this command calls the non interactive
   ‘org-insert-property-drawer’ command ...

With this, I would not have asked the question in the first place, and
might have been able to rebind the command without RY's input
(thanks).




-- 
EOST (École et Observatoire des Sciences de la Terre) 
ITE (Institut Terre & Environnement) | alain.cochard@unistra.fr
5 rue René Descartes   [bureau 110]  | Phone: +33 (0)3 68 85 50 44 
F-67084 Strasbourg Cedex, France     | [ slot available for rent ]

Re: Is function 'org-insert-property-drawer' usable?

[Max Nikulin]

On 31/12/2022 23:24, Alain.Cochard@unistra.fr wrote:
> For me,
> 
>    C-u C-c C-x d
> 
> does insert a 'PROPERTIES' drawer, but
> 
>    M-x org-insert-property-drawer
> 
> does not.

I suppose, the idea is to invoke it like

     C-u M-x org-insert-drawer

On 01/01/2023 20:23, Ihor Radchenko wrote:
> Ruijie Yu via writes:
> 
>> According to the source code of `org-insert-drawer', I think the manual
>> is saying that when ARG is non-nil, the function simply calls
>> `org-insert-property-drawer'.  However, `org-insert-property-drawer' is
>> not declared interactive, so you wouldn't be able to M-x it.
> 
> I guess we can just make it into a command. I see no downsides.

At least it was an intentional change:

commit 471ddbd14e2bb3e7689cdca5e6a461e54b8be9d8
Author: Bastien Guerry
Date:   Thu Jan 26 09:18:10 2012 +0100

     Improve `org-insert-drawer' and related documentation.

     * org.el (org-insert-property-drawer): Not an interactive
     command anymore.
     (org-insert-drawer): With a prefix argument, insert a property
     drawer.  Check for headline within the region before inserting
     the drawer.  Don't include special drawers in the completion
     table.
     (org-mode-map): New keybinding `C-c C-x d' for
     `org-insert-drawer'.

     * org.texi (Drawers): How to insert/complete drawers.

     Thanks to Nicolas Goaziou for the discussion and the patch.

Re: Is function 'org-insert-property-drawer' usable?

[Ihor Radchenko]

[-- Attachment #1: Type: text/plain, Size: 596 bytes --]

Max Nikulin <manikulin@gmail.com> writes:

>> I guess we can just make it into a command. I see no downsides.
>
> At least it was an intentional change:
>
> commit 471ddbd14e2bb3e7689cdca5e6a461e54b8be9d8
> Author: Bastien Guerry
> Date:   Thu Jan 26 09:18:10 2012 +0100
>
>      Improve `org-insert-drawer' and related documentation.

Thanks for checking!
I still don't understand why it was turned into a function since I
cannot find the relevant discussion.

Bastien?

If not making `org-insert-property-drawer' a command back, we can amend
the manual, as suggested.

See the attached patch.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-org-manual.org-Clarify-that-org-insert-property-draw.patch --]
[-- Type: text/x-patch, Size: 1779 bytes --]

From 3b930ccaf4f53d203cbbe84001d4d861cbcbb262 Mon Sep 17 00:00:00 2001
Message-Id: <3b930ccaf4f53d203cbbe84001d4d861cbcbb262.1672911565.git.yantar92@posteo.net>
From: Ihor Radchenko <yantar92@posteo.net>
Date: Thu, 5 Jan 2023 12:38:26 +0300
Subject: [PATCH] org-manual.org: Clarify that `org-insert-property-drawer' is
 not a command

* doc/org-manual.org (Drawers): Emphasize that
`org-insert-property-drawer' is not interactive command, but a
function.

Reported-by: Alain.Cochard@unistra.fr
Link: https://orgmode.org/list/tp3pbi$dk$1@ciao.gmane.io
---
 doc/org-manual.org | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index f3b77ebad..4466af8e4 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -1253,11 +1253,12 @@ ** Drawers
 #+findex: org-insert-drawer
 You can interactively insert a drawer at point by calling
 ~org-insert-drawer~, which is bound to {{{kbd(C-c C-x d)}}}.  With an
-active region, this command puts the region inside the drawer.  With
-a prefix argument, this command calls ~org-insert-property-drawer~,
-which creates a =PROPERTIES= drawer right below the current headline.
-Org mode uses this special drawer for storing properties (see
-[[*Properties and Columns]]).  You cannot use it for anything else.
+active region, this command puts the region inside the drawer.  With a
+prefix argument, this command calls non-interactive function
+~org-insert-property-drawer~, which creates a =PROPERTIES= drawer
+right below the current headline.  Org mode uses this special drawer
+for storing properties (see [[*Properties and Columns]]).  You cannot use
+it for anything else.
 
 Completion over drawer keywords is also possible using
 {{{kbd(M-TAB)}}}[fn:6].
-- 
2.38.1


[-- Attachment #3: Type: text/plain, Size: 224 bytes --]


-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: Is function 'org-insert-property-drawer' usable?

[Bastien Guerry]

Hi,

Ihor Radchenko <yantar92@posteo.net> writes:

> I still don't understand why it was turned into a function since I
> cannot find the relevant discussion.

C-u C-c C-x d will call org-insert-property-drawer - I don't think 
this function needs to be a command with its own keybinding.

The discussion is here:

https://list.orgmode.org/87vcnzeo8d.fsf@gmail.com/

> If not making `org-insert-property-drawer' a command back, we can amend
> the manual, as suggested.

Yes, I think amending the manual is good enough!

Thanks,

-- 
 Bastien

Re: Is function 'org-insert-property-drawer' usable?

[Ihor Radchenko]

Bastien Guerry <bzg@gnu.org> writes:

>> If not making `org-insert-property-drawer' a command back, we can amend
>> the manual, as suggested.
>
> Yes, I think amending the manual is good enough!

Applied, onto bugfix.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=28a966484

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

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

[Alain.Cochard]

Max Nikulin writes on Wed  4 Jan 2023 18:53:

 > I suppose, the idea is to invoke it like
 > 
 >      C-u M-x org-insert-drawer

Yes, I got it.  

Let me enlarge the scope (hence the new title). The manual says, in
1.5 Typesetting Conventions Used in this Manual (Key bindings and
commands):

   In the manual we will, wherever possible, give the function that is
   internally called by the generic command.

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’)

I conjectured that, when an interactive function does correspond to a
command, 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).

I concluded that, out of the 330, at most 9 of them are counter
examples (and I think even less; see list below).

9 is a very small proportion, which leads me to say that, in my
opinion, it would be nice:

- that this conjecture be transformed into a theorem (i.e., that
  exceptions be removed),

- that this convention be mentioned in the aforementioned section
  1.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).

(And if that convention is not to be adopted, then all the more reason
to duly mention exceptions to the quasi-rule.)

Regards

PS: as an aside note: during my quest, I met the following unsettling
(to me) cases, of functions that are not interactive "right away", but
appear (to me) to become interactive after "something" has been loaded
(please forgive the informal wording: I don't know the proper
terminology).  They are the 'org-capture-*' and the 'org-attach-*'
functions.

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.

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.

---

List (of non interactive functions that might be thought interactive
to the ignorant):

- ‘C-u C-u <TAB>’ (‘org-set-startup-visibility’)

- ‘S-<RIGHT>’ (‘org-clocktable-try-shift’)

- ‘C-0 C-c C-w’ or ‘C-u C-u C-u C-c C-w’ (‘org-refile-cache-clear’)

- ‘M-<UP>’ (‘org-table-fedit-scroll-up’) 

  It feels strange to me that 'org-table-fedit-scroll-down' be an
  interactive function but not the 'scroll-up' version; in fact: 'C-h
  f org-table-fedit-scroll-up' -> (No matches)

- ‘S-<RIGHT>’ (‘org-property-next-allowed-values’) 

  Shouldn't it be 'org-property-next-allowed-value'?

- ‘U’ (‘org-agenda-bulk-remove-all-marks’) 

  Shouldn't it be 'org-agenda-bulk-unmark-all'?

- ‘C-c C-e’ (‘org-export’) 

  Shouldn't this one be 'org-export-dispatch'?

- ‘C-c '’ (‘org-edit~special’) 

  This must be a typo, right?

- ‘C-c C-e o o’ (‘org-export-to-odt’) 

  Shouldn't it be 'org-odt-export-to-odt'?

-- 
EOST (École et Observatoire des Sciences de la Terre) 
ITE (Institut Terre & Environnement) | alain.cochard@unistra.fr
5 rue René Descartes   [bureau 110]  | Phone: +33 (0)3 68 85 50 44 
F-67084 Strasbourg Cedex, France     | [ slot available for rent ]

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

[Max Nikulin]

On 06/01/2023 06:13, Alain.Cochard wrote:
> 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'.

To improve loading speed, Org starts with minimal set of packages, other 
should be loaded on demand. See `org-modules'.

For C-h f (`describe-function') behavior see
https://debbugs.gnu.org/cgi/bugreport.cgi?bug=60085
"`help-enable-autoload' is not fully obeyed"

As to `org-capture-finalize', while being interactive, it is of little 
use before capture is started and so org-capture is loaded. That is why 
it is not marked for autoload and unavailable for M-x. In future it 
might be restricted to a specific "capture" mode.

Perhaps there is a way to generate TAGS file for Org files an to 
instruct Emacs to lookup collected symbols there.

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

[Jean Louis]

* 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/

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

[Ihor Radchenko]

Alain.Cochard@unistra.fr writes:

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

This is Emacs bug.
https://debbugs.gnu.org/cgi/bugreport.cgi?bug=60085

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

I guess we can make this function autoloaded.
Are there are any other function that you often try to call via M-x and
miss?

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

What about doing something like

- ‘C-u C-u <TAB>’ (‘org-cycle’ ⟶ ‘org-set-startup-visibility’)

There is no reason to make some of the listed functions interactive -
they are not designed to be interactive.

> - ‘S-<RIGHT>’ (‘org-property-next-allowed-values’) 
>
>   Shouldn't it be 'org-property-next-allowed-value'?
>
> - ‘U’ (‘org-agenda-bulk-remove-all-marks’) 
>
>   Shouldn't it be 'org-agenda-bulk-unmark-all'?
>
> - ‘C-c C-e’ (‘org-export’) 
>
>   Shouldn't this one be 'org-export-dispatch'?
>
> - ‘C-c '’ (‘org-edit~special’) 
>
>   This must be a typo, right?
>
> - ‘C-c C-e o o’ (‘org-export-to-odt’) 
>
>   Shouldn't it be 'org-odt-export-to-odt'?

Fixed, on bugfix. Thanks!
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=f33d24108

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>