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 ]