Re: Proposal: 'executable' org-capture-templates

[Max Nikulin <manikulin@gmail.com>]

On 01/07/2022 06:30, Arthur Miller wrote:
> Max Nikulin writes:
>>
>> (load (expand-file-name "org-multimenu"))
>> (org-menu-multiinstance-stateful
>>   `((("1" "one" 1)
>>      ("2" "two" 2)))
>>   :state (format-time-string "%T")
>>   :text "Some heading"
>>   :buffer-name "*Test menu*"
>>   :handler (lambda (entry state)
>> 	    (org-select-quit) ; it does not kill the buffer
>> 	    (message "handler %S %S" entry state)))
> 
> I might be missunderstanding you now, but from this example it seems to me that
> you see menu entries as something that aims for the menu itself, while state is
> some user data?

I am feeling myself confused now. It seems you have got the idea mostly 
right, but I suspect some resistance though.

For org-capture there are menu entries data in `org-capture-templates' 
that is the same set of rules (how to expand templates where to store 
result) for all instances of menu. I do not see any point to make each 
entry an executable closure.

State specific to each menu instance consists from the following parts:
- requested action (prefix argument: goto target location, insert at point)
- data required to expand template when it is selected, namely 
`org-overriding-default-time', `org-capture-initial' and maybe something 
else.

Template properties and capture data are quite orthogonal and for me it 
is rather natural to keep them independently. I would prefer to have 
support of state at low level, but it can be added on the top of basic 
functions through a closure. In a different use case, when menu is just 
a collection of independent actions, there is no point in the state 
shared by all entries of the menu instance.

>> However I would expect that menu handler is not aware if menu is implemented
>> using buffers. From my point of view handler should not have buffer argument.
> 
> I understand, and I agree it is not very beautiful design :). The problem is when
> client code provides its own handler. In the beginning I used a flag,
> org-select-transient, to signal the menu should go away, but that wasn't very
> clean either.

There are two types of actionable menu entries:
1. Ones that modify the state associated with menu instance without real 
action. Currently they are e.g. toggles like body only or complete 
document with headers for the export dispatcher. Menu should be retained 
when such action is called.
2. Entries that call real action. In the case of export dispatcher or 
`org-capture' menu buffer should be destroyed before a new one to 
display export result or expanded template is created or selected.

So generally it is not possible to determine in advance if menu should 
be "closed" before calling its handler. It is too late to close menu 
when the handler returns some value. I considered a predicate function 
that accepts menu entry data and the state and returns decision if menu 
should be retained. Looking into your implementation I realized that 
`org-select-quit' is almost ready to be a better solution. If the 
handler just changes the state then it does not call the quit function. 
Actions must invoke `org-select-quit' to notify menu implementation that 
the instance may (or must) be destroyed. The only problem is currently 
with multi-instance menu. Buffer is not destroyed by this function. 
Despite it is possible to kill the buffer since it is passed as an 
argument, I would prefer to delegate this action to `org-select-quit', 
so menu caller becomes completely unaware if menu implementation uses 
buffers or something else.

There are may be a convenience keyword argument that adds call of 
`org-select-quit' before invoking a handler. It should be handy for 
simple menu with no options that can be changed before calling an action.

> The buffer text is just dead text;

It is unfortunate, I hope, you will reconsider it.

>>                                 E.g. "C-c C-e" ox dispatcher has some options and
>> user should see current values.
> 
> Can that be implemented as a submenu (group node as in org-capture-templates)?

I suppose, it is necessary to provide some visual feedback, so it is 
obvious to user that some options is changed (e.g. "C-b" for "C-c C-e" 
export). It may be a kind of always visible status line, however in some 
cases it is better to display option value close to its menu entry.

In a minimal variant there may be a function to set status line and menu 
keeps a pair of markers, so text between them are erased and new status 
is inserted when the function is called.

In the beginning I was afraid that menu instance state may become a 
serious problem with implementation you proposed. Actually it appeared 
to be a matter of convenience. Entry-dependent behavior (if menu should 
be kept or closed) would benefit from some polishing. Presenting to the 
user changes in menu state in response to their actions should be 
addressed somehow.