Re: [RFC] The best way to choose an "action" at point: context-menu-mode, transient, which-key or embark?

Re: [RFC] The best way to choose an "action" at point: context-menu-mode, transient, which-key or embark?

[Gabriel Santos]

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

Greetings,

I'll go through the examples found on this e-mail and
suggest the menu command I find best for the proposed
scenarios.

Below is how I think these options could be used.

context-menu-mode
      No particular target, should mostly be used for actions on
      the whole buffer or on a region, or all particular elements
      defined.

      Example: Org -> Headings -> Demote Headings

transient
      Also no particular target, but should be used for commands that
      would require a menu for interaction, such as exporting and capturing.

      Example 1: org-export-*dispatch* -> transient menu
      Example 2: org-capture -> transient menu
      Example 3: org-attach -> transient menu

which-key
      On a target, list actions that could be performed on it.

embark
      Can be used to replace which-key in customization.

      But, despite saying this, I have it configured to use which-key as its menu.

Ihor Radchenko <yantar92@posteo.net> writes:

> I have raised the topic of refactoring Org mode menu systems during
> EmacsConf in <https://emacsconf.org/2024/talks/org-update/>

I saw the talk live, really excited for the future of Org!

> The initial idea was replacing the self-written menu code in Org with
> built-in transient.el.
>
> Later, during OrgMeetup a number of people raised concerns that
> transient may sometimes be an overkill, and that some people may prefer
> alternative UIs. In particular, embark and context-menu-mode were
> mentioned.

Personally, I'd prefer for built-in packages/functionality to be considered first.

The consideration for context-menu for me is particularly intriguing, as there's
a lot of functionality already included in Org's context menu.

> (I am CCing the discussion participants and potentially interested
> maintainers)

Hope to see their responses to this.

I'm just a common user, so my opinions should be taken with a grain of salt.

> In Org mode (although not only in Org mode, looking at the success of
> embark.el), we often have a UI model where users call an "action"
> command (like org-ctrl-c-ctrl-c or org-open-at-point) followed by
> interactive selection among multiple actions.

I don't often use org-ctrl-c-ctrl-c, but now that I've seen the interaction
menu for properties as an example, I'd say the best option for it would be
which-key, as it's a simpler menu.

> For example, org-open-at-point on a heading with multiple links inside
> will raise a section buffer listing all the links - pressing a number
> will open the corresponding link.

I'd consider which-key again for this.

> Another example (see the example patch below), which is a
> work-in-progress patch for Org citation system, is "following" a
> citation. To "follow" citation may mean multiple things including but
> not limited to: (1) going to citation record in the bibliography file;
> (2) following URL; (3) downloading .pdf file for a citation; etc.
>  **The list of "follow" actions may be customized by users**

This is similar to the functions available in the following package:

<https://github.com/emacs-citar/citar>

It also allows for opening the bibliography, links, notes, and files
connected to the citation.

I use it with embark:

<https://github.com/emacs-citar/citar/blob/main/citar-embark.el>

> The general UI flow in these scenarios will be:
>
> 1. User calls "action" with cursor at certain syntax element
> 2. Action menu is displayed, showing the available actions/targets (dynamically built)
> 3. User selects the action/target

I'm not sure what the best option would be for displaying targets, but which-key
should be able to cover most cases that would require "simpler" menus for actions.

I'd also add in that it could be considered over transient if its dynamically built.
I tend to associate transient with "static" options.

> This UI flow can be implemented using context menus, which-key popups,
> transient menus, and also using embark (where the way menu is displayed
> can be customized).
>
> All the 4 approaches represent different UI models with various
> strengths and weaknesses:
>
> - transient has a very flexible layout builder where the menu items can
>   be arranged granularly, but intercepts the main loop disrupting
>   certain keyboard-based workflows
> - which-key does not stand on the way and integrates well into Emacs'
>   key binding model, but provides little flexibility for menu layout

It has options for setting the pop-up type and position. Could this help with
flexibility?

> - embark stays in the middle between which-key and transient, making use
>   of transient keymaps and allowing a custom menu renderer
> - context-menu-mode provides mouse experience
>
> I am wondering if we can work out some universal API to plug the
> described action->menu->selection model into the UI that user prefers.

I'd say that this is the best options out of all of them, but, as you said:

> "I am wondering if we can work out [...]"

This would require considerable work.

> Tentatively, I am thinking about the following:
>
> For a given Emacs "prefix" command (e.g. org-open-at-point), we define a
> set of customizations:
>
> 1. List of possible actions: ((name1 . action1 props) (name2 . action2 ...) ...)
>    PROPS is a plist defining extra properties like key-binding, display
>    string, maybe something else to be used in the future.
> 2. Menu interface to use (transient, context-menu, embark, which-key)
> 3. Layout settings for the specific interfaces. For example, transient
>    layout definition.
>
> WDYT?
>
> Best,
> Ihor

On this described state (list of actions), which-key would be the
best option according to my definition.

But, on the current state of org-open-at-point (shows more targets),
as I commented previously, there's no menu that I associate with:

"Act on target, display a list of other targets."

Maybe context-menu would be the closest one, but I wouldn't consider
which-key or embark, these are more related to functions.

Regards,

--
*Gabriel Santos*

Re: [RFC] The best way to choose an "action" at point: context-menu-mode, transient, which-key or embark?

[Suhail Singh]

Ihor Radchenko <yantar92@posteo.net> writes:

> Tentatively, I am thinking about the following:
>
> For a given Emacs "prefix" command (e.g. org-open-at-point), we define a
> set of customizations:
>
> 1. List of possible actions: ((name1 . action1 props) (name2 . action2 ...) ...)
>    PROPS is a plist defining extra properties like key-binding, display
>    string, maybe something else to be used in the future.
> 2. Menu interface to use (transient, context-menu, embark, which-key)
> 3. Layout settings for the specific interfaces. For example, transient
>    layout definition.
>
> WDYT?

By "display string" do you mean a description of the action?  Or would
that be additional?

Hopefully, the description of each action will be a first-class member
of the "List of possible actions".  Or is the intent that the
description be taken from the form representing an action (e.g. a defun,
a lambda etc).

-- 
Suhail

Re: [RFC] The best way to choose an "action" at point: context-menu-mode, transient, which-key or embark? (was: Fwd: Org-cite: Replace basic follow-processor with transient menu?)

[Psionic K]

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

> intercepts the main loop
This is optional, per transient menu (prefix) and the commands within it.
A common technique, used by magit and others, is to have entry point
commands in the regular keymap so that many commands can be started without
traversing several menus.  If you want normal un-shadowed bindings active
at the same time, the prefix has a slot called `transient-non-suffix' that
is similar to the `:suppress' option in keymaps or setting a `t'
`undefined' binding in a keymap.  However the results of mixing self-insert
and modal or modal and another modal are generally bad.

The biggest drawbacks of transient are well known in Github issues:
- Which-key discovery of Transient keymaps
- Transient binding generation based on keymaps
- Normalizing how to obtain arguments when being called independently as an
interactive command versus being called as a Transient suffix

In the short term, to punch the first two problems in the face, override
the `:setup-children' method.  If you know what keymap you are borrowing
bindings from, you can synchronize it at display time.

Regarding the normalization with interactive, if you are not using
transient infixes and instead lean on the :info class and dynamic
:descriptions, you can display state and store it using normal buffer-local
and defvar techniques, providing visual feedback for what might be hidden
states after the user gets more familiar.  The commands work with or
without a prefix currently active.  In this usage model, you only use
Transient for its flow control, display, and layout.  I find the infix
system to be somewhat of a distraction if you are not actually building a
CLI wrapper, but you can definitely make suffixes and descriptions "smart"
by reading a scope from the prefix and making custom infixes that also
obtain more state when displayed.  A custom infix for storing org elements
or objects could certainly be a thing.

I think deeper user customization is an area that is weak with transient,
but only because the user actually needs to have a vision for how they want
to build up stateful commands.  If you're just doing prefix maps, transient
and hydra are equivalent concepts.  Transient becomes differentiated when
you consider commands that build up state for other commands.  Executing
slightly modified command sentences in rapid succession is not something
the user customizes casually.  Complex commands only make sense when the
context they depend on is populated, which naturally decides the menu flow.

> I am wondering if we can work out some universal API to plug the
> described action->menu->selection model into the UI that user prefers.
>
> Tentatively, I am thinking about the following:
>
> For a given Emacs "prefix" command (e.g. org-open-at-point), we define a
> set of customizations:
>
> 1. List of possible actions: ((name1 . action1 props) (name2 . action2
...) ...)
>    PROPS is a plist defining extra properties like key-binding, display
>    string, maybe something else to be used in the future.
> 2. Menu interface to use (transient, context-menu, embark, which-key)
> 3. Layout settings for the specific interfaces. For example, transient
>    layout definition.

Well, I'm sure you know that transient has more decisions encoded in the
layout than the other options.  If the data going in is a least common
denominator, you need supplementary data elsewhere to achieve a good result.

What I fear is a system like org-speed-keys which relies on an override of
`org-self-insert' and is yet another orthogonal system.  I much prefer the
Lispy style of integration, which uses a keymap.  Using keymaps, even if
they are not active, to generate transient key bindings via :setup-children
is the best way to have certain integration with other Emacs tools.

How people can collaborate with me on general questions of design is to
open issues on the Transient Showcase.  Either I can point to an existing
example or make a new one.  I've been giving some thought to how to
demonstrate an idea more generally of composing multiple commands and
manipulating the composition to dispatch complex commands in rapid
succession with minor differences.  I personally have my own org speed keys
solution that I've been developing for yet another more complex package I
call Afterburner.  These projects can become stuck in design hell when I
don't have the prodding from other problem analysis, so please, bother me.

https://github.com/positron-solutions/transient-showcase

[-- Attachment #2: Type: text/html, Size: 4850 bytes --]

Re: [RFC] The best way to choose an "action" at point: context-menu-mode, transient, which-key or embark? (was: Fwd: Org-cite: Replace basic follow-processor with transient menu?)

[Ihor Radchenko]

Psionic K <psionik@positron.solutions> writes:

>> intercepts the main loop

> This is optional, per transient menu (prefix) and the commands within it.
> A common technique, used by magit and others, is to have entry point
> commands in the regular keymap so that many commands can be started without
> traversing several menus.  If you want normal un-shadowed bindings active
> at the same time, the prefix has a slot called `transient-non-suffix' that
> is similar to the `:suppress' option in keymaps or setting a `t'
> `undefined' binding in a keymap.  However the results of mixing self-insert
> and modal or modal and another modal are generally bad.

Thanks for the info!
So, we can have something like

:transient-non-suffix 'leave

and then pressing something that is not bound to a suffix or infix will
run the parent keymap command, automatically leaving transient state.

> - Normalizing how to obtain arguments when being called independently as an
> interactive command versus being called as a Transient suffix

I think it is addressed in the example patch I shared. There, we pass
around the original function arguments via macro expansion (!arg-name)

  ["Open" ("b" "bibliography entry" (org-cite-basic-goto !citation !prefix))]

> In the short term, to punch the first two problems in the face, override
> the `:setup-children' method.  If you know what keymap you are borrowing
> bindings from, you can synchronize it at display time.

This is also partially solved. We do use :setup-children, although the
initial implementation simply reads user customization into menu layout.

I believe that we can read a keymap in similar way and generate
transient layout automatically.

> What I fear is a system like org-speed-keys which relies on an override of
> `org-self-insert' and is yet another orthogonal system.  I much prefer the
> Lispy style of integration, which uses a keymap.  Using keymaps, even if
> they are not active, to generate transient key bindings via :setup-children
> is the best way to have certain integration with other Emacs tools.

May you please elaborate?

-- 
Ihor Radchenko // yantar92,
Org mode maintainer,
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: [RFC] The best way to choose an "action" at point: context-menu-mode, transient, which-key or embark?

[Ihor Radchenko]

Gabriel Santos <gabrielsantosdesouza@disroot.org> writes:

> context-menu-mode
>       No particular target, should mostly be used for actions on
>       the whole buffer or on a region, or all particular elements
>       defined.
>
>       Example: Org -> Headings -> Demote Headings
> ...
> Personally, I'd prefer for built-in packages/functionality to be considered first.

We will definitely try to support built-ins first and foremost.
I mentioned embark as an example of alternative UI.
Also, embark might be a candidate for upstreaming.

> The consideration for context-menu for me is particularly intriguing, as there's
> a lot of functionality already included in Org's context menu.

This is not right. I think you are confusing ordinary menu bar and
context menu. Context menu is "right click" menu that will display
different items depending on where you click. Org mode currently does
not have context-menu-mode integration (we should fix this deficiency)

> I don't often use org-ctrl-c-ctrl-c, but now that I've seen the interaction
> menu for properties as an example, I'd say the best option for it would be
> which-key, as it's a simpler menu.

My conclusion so far is that there is no "best" for every user. We
should ideally support user-customized menu UI. The main question is how
to do it.

>> This UI flow can be implemented using context menus, which-key popups,
>> transient menus, and also using embark (where the way menu is displayed
>> can be customized).
>>
>> All the 4 approaches represent different UI models with various
>> strengths and weaknesses:
> ...
> It has options for setting the pop-up type and position. Could this help with
> flexibility?

May you elaborate what "it" refers to?

-- 
Ihor Radchenko // yantar92,
Org mode maintainer,
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: [RFC] The best way to choose an "action" at point: context-menu-mode, transient, which-key or embark?

[Ihor Radchenko]

Suhail Singh <suhailsingh247@gmail.com> writes:

>> For a given Emacs "prefix" command (e.g. org-open-at-point), we define a
>> set of customizations:
>>
>> 1. List of possible actions: ((name1 . action1 props) (name2 . action2 ...) ...)
>>    PROPS is a plist defining extra properties like key-binding, display
>>    string, maybe something else to be used in the future.
>> 2. Menu interface to use (transient, context-menu, embark, which-key)
>> 3. Layout settings for the specific interfaces. For example, transient
>>    layout definition.
>
> By "display string" do you mean a description of the action?  Or would
> that be additional?

I mean some way to define how the action should be displayed in the
menu. It may be a full string or just a description to be appended to
the action name, or something else.

> Hopefully, the description of each action will be a first-class member
> of the "List of possible actions".  Or is the intent that the
> description be taken from the form representing an action (e.g. a defun,
> a lambda etc).

Using a docstring sounds like a good idea. But it is a bit early to
decide these details. I'd like to discuss the more general design first.

-- 
Ihor Radchenko // yantar92,
Org mode maintainer,
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: [RFC] The best way to choose an "action" at point: context-menu-mode, transient, which-key or embark?

[Philip Kaludercic]

Can I please be removed from the CCs in this thread?

Ihor Radchenko <yantar92@posteo.net> writes:

> Psionic K <psionik@positron.solutions> writes:
>
>>> intercepts the main loop
>
>> This is optional, per transient menu (prefix) and the commands within it.
>> A common technique, used by magit and others, is to have entry point
>> commands in the regular keymap so that many commands can be started without
>> traversing several menus.  If you want normal un-shadowed bindings active
>> at the same time, the prefix has a slot called `transient-non-suffix' that
>> is similar to the `:suppress' option in keymaps or setting a `t'
>> `undefined' binding in a keymap.  However the results of mixing self-insert
>> and modal or modal and another modal are generally bad.
>
> Thanks for the info!
> So, we can have something like
>
> :transient-non-suffix 'leave
>
> and then pressing something that is not bound to a suffix or infix will
> run the parent keymap command, automatically leaving transient state.
>
>> - Normalizing how to obtain arguments when being called independently as an
>> interactive command versus being called as a Transient suffix
>
> I think it is addressed in the example patch I shared. There, we pass
> around the original function arguments via macro expansion (!arg-name)
>
>   ["Open" ("b" "bibliography entry" (org-cite-basic-goto !citation !prefix))]
>
>> In the short term, to punch the first two problems in the face, override
>> the `:setup-children' method.  If you know what keymap you are borrowing
>> bindings from, you can synchronize it at display time.
>
> This is also partially solved. We do use :setup-children, although the
> initial implementation simply reads user customization into menu layout.
>
> I believe that we can read a keymap in similar way and generate
> transient layout automatically.
>
>> What I fear is a system like org-speed-keys which relies on an override of
>> `org-self-insert' and is yet another orthogonal system.  I much prefer the
>> Lispy style of integration, which uses a keymap.  Using keymaps, even if
>> they are not active, to generate transient key bindings via :setup-children
>> is the best way to have certain integration with other Emacs tools.
>
> May you please elaborate?

Re: [RFC] The best way to choose an "action" at point: context-menu-mode, transient, which-key or embark?

[indieterminacy]

Hello Ihor,

On 2024-12-13 19:41, Ihor Radchenko wrote:
> TL;DR: We are in the process of designing a more unified selection
> interface for Org mode and want to see if there is some way to unify
> context-menu-mode, transient, which-key and embark together. The idea 
> is
> to (1) avoid too many customizations; (2) allow users to decide how to
> choose between multiple options - by mouse, keyboard, and using
> customizable UIs.
> ...

I would consider an `actions -> menu` functionality to be something 
which should be a distinct tool,
albeit heavily configured to suit Orgmode functionality.
I think its great how Transient was able to emerge from Magit's 
activities and its clearly providing opportunities for scaling the 
utility.

If I may widen the topic a little, your RFC could be an opportunity to 
examine the overlaps between Orgmode and Hyperbole.

For instance, the use of implicit buttons could be examined:
https://www.gnu.org/software/hyperbole/man/hyperbole.html#Implicit-Buttons

I reckon what you are proposing (greater fluency and flow for menus 
dependent on context) could benefit Hyperbole's functionality too (the 
action utility for that environment seems more focused on one action 
rather than prompting a selection of actions).

Ive CC'd Robert Weiner (who leads Hyperbole), incase that is of use.

Kind regards,


Jonathan McHugh

Re: [RFC] The best way to choose an "action" at point: context-menu-mode, transient, which-key or embark?

[Gabriel Santos]

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

>> The consideration for context-menu for me is particularly intriguing, as there's
>> a lot of functionality already included in Org's context menu.
>
> This is not right. I think you are confusing ordinary menu bar and
> context menu. Context menu is "right click" menu that will display
> different items depending on where you click. Org mode currently does
> not have context-menu-mode integration (we should fix this deficiency)

Maybe it's some third-party package I'm using, but right-cliking on an Org
buffer gives me a lot of options:

<https://0x0.st/XF1y.png>

>> I don't often use org-ctrl-c-ctrl-c, but now that I've seen the interaction
>> menu for properties as an example, I'd say the best option for it would be
>> which-key, as it's a simpler menu.
>
> My conclusion so far is that there is no "best" for every user. We
> should ideally support user-customized menu UI. The main question is how
> to do it.

I also agree with this conclusion. Hope others can contribute with
suggestions of how to go about it.

>>> This UI flow can be implemented using context menus, which-key popups,
>>> transient menus, and also using embark (where the way menu is displayed
>>> can be customized).
>>>
>>> All the 4 approaches represent different UI models with various
>>> strengths and weaknesses:
>> ...
>> It has options for setting the pop-up type and position. Could this help with
>> flexibility?
>
> May you elaborate what "it" refers to?

Sorry, seems I forgot to clarify. "It" in this context was referring to which-key.

It has the following variables for altering (window) display:

- which-key-popup-type
- which-key-side-window-location

Re: [RFC] The best way to choose an "action" at point: context-menu-mode, transient, which-key or embark?

[Ihor Radchenko]

Gabriel Santos <gabrielsantosdesouza@disroot.org> writes:

> Maybe it's some third-party package I'm using, but right-cliking on an Org
> buffer gives me a lot of options:
>
> <https://0x0.st/XF1y.png>

This is simply a copy of the top-level menu. You would see the same if
you enable the menu bar. No "context" is considered in this case.

-- 
Ihor Radchenko // yantar92,
Org mode maintainer,
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: [RFC] The best way to choose an "action" at point: context-menu-mode, transient, which-key or embark?

[Suhail Singh]

Ihor Radchenko <yantar92@posteo.net> writes:

>> Hopefully, the description of each action will be a first-class member
>> of the "List of possible actions".  Or is the intent that the
>> description be taken from the form representing an action (e.g. a defun,
>> a lambda etc).
>
> Using a docstring sounds like a good idea. But it is a bit early to
> decide these details. I'd like to discuss the more general design first.

I agree that it may be premature to think about implementation details
of how docstrings are stored etc.  However, I would like to ensure that
any discussion of the design of ways-to-choose-an-action-at-point
include self-documentation and self-discovery in the desiderata.

Perhaps this goes without saying, in which case please ignore this
message.  However, it's too important to be left to chance.

-- 
Suhail

Re: [RFC] The best way to choose an "action" at point: context-menu-mode, transient, which-key or embark?

[Juri Linkov]

> 1. List of possible actions: ((name1 . action1 props) (name2 . action2 ...) ...)
>    PROPS is a plist defining extra properties like key-binding, display
>    string, maybe something else to be used in the future.
> 2. Menu interface to use (transient, context-menu, embark, which-key)

This looks like the best design.  Any part of the org buffer could have
text properties with a list of its available actions.  Such a property
could be similar to 'context-menu-functions' handled by 'context-menu-map'.
But since it will be a plain generic list, it could be transformed to any
menu interface such as transient, context-menu, etc.

To transform it to context-menu, org-mode should provide a function
like 'context-menu-minor' that will create a corresponding menu
that will be added as a submenu of the default context menu.

Such integration with existing menus would be better than the current
implementation of context menus in org-mouse-context-menu that completely
replaces the context menu with its own.

Re: [RFC] The best way to choose an "action" at point: context-menu-mode, transient, which-key or embark? (was: Fwd: Org-cite: Replace basic follow-processor with transient menu?)

[Karthik Chikmagalur]

> Regarding the normalization with interactive, if you are not using
> transient infixes and instead lean on the :info class and dynamic
> :descriptions, you can display state and store it using normal buffer-local
> and defvar techniques, providing visual feedback for what might be hidden
> states after the user gets more familiar.  The commands work with or
> without a prefix currently active.  In this usage model, you only use
> Transient for its flow control, display, and layout.  I find the infix
> system to be somewhat of a distraction if you are not actually building a
> CLI wrapper, but you can definitely make suffixes and descriptions "smart"
> by reading a scope from the prefix and making custom infixes that also
> obtain more state when displayed.  A custom infix for storing org elements
> or objects could certainly be a thing.

Do you have an example of using buffer-local variables to store
transient state?  Directing me to an appropriate section of the
showcase should be plenty.

Karthik

Re: [RFC] The best way to choose an "action" at point: context-menu-mode, transient, which-key or embark? (was: Fwd: Org-cite: Replace basic follow-processor with transient menu?)

[Karthik Chikmagalur]

>> intercepts the main loop
> This is optional, per transient menu (prefix) and the commands within it.
> A common technique, used by magit and others, is to have entry point
> commands in the regular keymap so that many commands can be started without
> traversing several menus.  If you want normal un-shadowed bindings active
> at the same time, the prefix has a slot called `transient-non-suffix' that
> is similar to the `:suppress' option in keymaps or setting a `t'
> `undefined' binding in a keymap.  However the results of mixing self-insert
> and modal or modal and another modal are generally bad.

From the manual page describing the `transient-non-suffix' slot:

> If the value is ‘t’, then non-suffixes can be invoked, when it is
> ‘nil’ (the default) then they cannot be invoked.
>
> The only other recommended value is ‘leave’.  If that is used, then
> non-suffixes can be invoked, but if one is invoked, then that exits the
> transient.

This is one of my issues with Transient -- here it is reimplementing the
idea of a regular transient keymap (the kind you can use with
`set-transient-map') but increasing the cognitive load of applying this
behavior.

I understand that Transient needs to implement behaviors not provided by
Elisp (like infixes), but fashioning whole-cloth replacements for
behaviors that are provided -- like the KEEP-PRED behavior of
`set-transient-map' -- makes writing Transients a very high effort
activity.

Karthik

Re: [RFC] The best way to choose an "action" at point: context-menu-mode, transient, which-key or embark? (was: Fwd: Org-cite: Replace basic follow-processor with transient menu?)

[Psionic K]

> Do you have an example of using buffer-local variables to store
> transient state?  Directing me to an appropriate section of the
> showcase should be plenty.

It's less magic than it sounds.  I basically bypassed the infix system
when making transients for Master of Ceremonies.
https://github.com/positron-solutions/moc

`moc-dispatch` is a kind of utility dashboard for screen casting.
Besides controls, it displays various states you might not see in the
minibuffer or elsewhere.  I used dynamic :description functions rather
than infixes to display these states.  It is much simpler to bring
Elisp states into the interface this way.  There's no need and there
can be no meaning of persisting the current state of Emacs.

> like the KEEP-PRED behavior of `set-transient-map'

There's more.  Calling (or declining to call) `setup-prefix' manually
in an interactive form or using the stack manipulation commands can
switch between menus and pure interactive flows.  It's possible to
construct flows that are more program-driven than simple KEEP-PRED or
repeat maps.  Obviously we can hack them both since they are functions
that can manipulate the downstream flow.  Transient's pre-commands are
a bit complex to understand when hacking in behavior but are related
to its menu stack, something transient maps don't need to express.

Instead of talking about Transient's second system behaviors, we can
identify and fix the worst ones.  Jonas is aware of them and generally
in favor of normalizing how transient meshes with interactive, as long
as it doesn't break magit and all the other dependents.

> > org-speed-keys
> May you please elaborate?

I discovered org speed keys because I was making my own speed-key
system and came across the shadowed bindings.  The bindings are always
shadowed, even when speed keys are off.  Unlike Lispy, where I
customize the shadowing using keymaps, org speed keys has
`org-speed-commands'.  From a discoverability standpoint, it breaks
some things.  The commands are opaque.  All I see is `org-self-insert'
whereas my own bindings have unique command names on every key,
another thing I copied from Lispy.  Even if they have DWIM or
situational behavior, it is easier to identify all behavior when
starting from an entry point that doesn't implement details of other
commands.

Re: [RFC] The best way to choose an "action" at point: context-menu-mode, transient, which-key or embark?

[Ihor Radchenko]

Juri Linkov <juri@linkov.net> writes:

>> 1. List of possible actions: ((name1 . action1 props) (name2 . action2 ...) ...)
>>    PROPS is a plist defining extra properties like key-binding, display
>>    string, maybe something else to be used in the future.
>> 2. Menu interface to use (transient, context-menu, embark, which-key)
>
> This looks like the best design.  Any part of the org buffer could have
> text properties with a list of its available actions.  Such a property
> could be similar to 'context-menu-functions' handled by 'context-menu-map'.
> But since it will be a plain generic list, it could be transformed to any
> menu interface such as transient, context-menu, etc.

I am a bit lost.
Maybe I did not describe the use cases I had in mind well.

What I have in mind is a menu UI for various commands:
1. org-open-at-point (one set of actions)
2. org-ctrl-c-ctrl-c (another set of action)
3. some other command
4. ...

Then, "actions" will be various options a given command can do.

In such scenario, the usefulness of text properties is elusive to me.
I'd rather link the menu items to a command, not to place in buffer.

> To transform it to context-menu, org-mode should provide a function
> like 'context-menu-minor' that will create a corresponding menu
> that will be added as a submenu of the default context menu.
>
> Such integration with existing menus would be better than the current
> implementation of context menus in org-mouse-context-menu that completely
> replaces the context menu with its own.

What do you mean by "default context menu"?

-- 
Ihor Radchenko // yantar92,
Org mode maintainer,
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>

org-speed-keys design (was: [RFC] The best way to choose an "action" at point: context-menu-mode, transient, which-key or embark? (was: Fwd: Org-cite: Replace basic follow-processor with transient menu?))

[Ihor Radchenko]

Psionic K <psionik@positron.solutions> writes:

>> > org-speed-keys
>> May you please elaborate?
>
> I discovered org speed keys because I was making my own speed-key
> system and came across the shadowed bindings.  The bindings are always
> shadowed, even when speed keys are off.  Unlike Lispy, where I
> customize the shadowing using keymaps, org speed keys has
> `org-speed-commands'.  From a discoverability standpoint, it breaks
> some things.  The commands are opaque.  All I see is `org-self-insert'
> whereas my own bindings have unique command names on every key,
> another thing I copied from Lispy.  Even if they have DWIM or
> situational behavior, it is easier to identify all behavior when
> starting from an entry point that doesn't implement details of other
> commands.

May you please provide more information about the more natural
implementation of context-dependent bindings?

-- 
Ihor Radchenko // yantar92,
Org mode maintainer,
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: [RFC] The best way to choose an "action" at point: context-menu-mode, transient, which-key or embark?

[Kierin Bell]

Hi Ihor,

Ihor Radchenko <yantar92@posteo.net> writes:

> TL;DR: We are in the process of designing a more unified selection
> interface for Org mode and want to see if there is some way to unify
> context-menu-mode, transient, which-key and embark together. The idea
> is to (1) avoid too many customizations; (2) allow users to decide how
> to choose between multiple options - by mouse, keyboard, and using
> customizable UIs.

I think that the built-in Emacs thingatpt.el should not be overlooked
here.

Instead of implementing an entire system specific to Org, imagine a
generic action-at-point interface that works on "things" from
thingatpt.el. For the various targets, Org could add new "providers" to
`thing-at-point-provider-alist', `forward-thing-provider-alist', and
`bounds-of-thing-at-point-provider-alist'. [ Org actually does already
register its own 'url' provider for links. ]

Then, Org could implement a number of action selection interfaces that
act on the various classes of "thing". An exemplary package would be
Philip Kaludercic's great =do-at-point= package, which provides a simple
action selection menu for the thing-at-point using
`read-multiple-choice', which I find elegant and intuitive.[1]

I have gone as far as implementing a 'heading' provider for Org and
`outline-mode' (for use with =do-at-point.el=). I don't see any reason
why Org couldn't define a 'citation' provider, a 'source-block'
provider, etc.

The only downside that I have found with adding lots of thingatpt.el
providers is that it can be difficult to write providers efficient
enough for `forward-thing' in particular
(`forward-thing-provider-alist').

I may also be misunderstanding the proposed interface. For example,
instead of a generic interface for acting on a single thing at point,
maybe you are describing more of an interface for associating commands
with multiple potential targets that must be located (e.g., in a
subtree), which are then each associated with actions.

Even if that's the case, there is a good case for implementing
thingatpt.el providers for the targets, so that users could bring our
own action-at-point packages/interfaces. [ I would be willing to help
write some of those providers. ] And if thingatpt.el isn't generalized
or fast enough, then there is a case for creating a new, more flexible
/de facto/ library like this for Emacs.


[1] https://codeberg.org/pkal/do-at-point

Thanks,
Kierin

Re: [RFC] The best way to choose an "action" at point: context-menu-mode, transient, which-key or embark?

[Juri Linkov]

>>> 1. List of possible actions: ((name1 . action1 props) (name2 . action2 ...) ...)
>>>    PROPS is a plist defining extra properties like key-binding, display
>>>    string, maybe something else to be used in the future.
>>> 2. Menu interface to use (transient, context-menu, embark, which-key)
>>
>> This looks like the best design.  Any part of the org buffer could have
>> text properties with a list of its available actions.  Such a property
>> could be similar to 'context-menu-functions' handled by 'context-menu-map'.
>> But since it will be a plain generic list, it could be transformed to any
>> menu interface such as transient, context-menu, etc.
>
> I am a bit lost.
> Maybe I did not describe the use cases I had in mind well.
>
> What I have in mind is a menu UI for various commands:
> 1. org-open-at-point (one set of actions)
> 2. org-ctrl-c-ctrl-c (another set of action)
> 3. some other command
> 4. ...
>
> Then, "actions" will be various options a given command can do.
>
> In such scenario, the usefulness of text properties is elusive to me.
> I'd rather link the menu items to a command, not to place in buffer.

Indeed, in this case text properties are not needed.
Then you can use something like the buffer-local variable with the
same name 'context-menu-functions' (handled in 'context-menu-map').
The main point is that these functions return a menu.

But instead of a menu, an org function could return
a more high-level data structure like
((name1 . action1 props) (name2 . action2 ...) ...)

IOW, this means adding an abstraction layer on top of the existing
user interfaces such as transient and context-menu.

>> To transform it to context-menu, org-mode should provide a function
>> like 'context-menu-minor' that will create a corresponding menu
>> that will be added as a submenu of the default context menu.
>>
>> Such integration with existing menus would be better than the current
>> implementation of context menus in org-mouse-context-menu that completely
>> replaces the context menu with its own.
>
> What do you mean by "default context menu"?

The default context menu is the menu constructed from many different
context-menu functions.  Some of them add Undo/Redo entries,
some add Select/Copy/Paste, some add Global submenus, etc.

I meant to keep all these existing menu items, and also append
the submenu items returned by Org-mode.

Re: [RFC] The best way to choose an "action" at point: context-menu-mode, transient, which-key or embark?

[Ihor Radchenko]

Juri Linkov <juri@linkov.net> writes:

> Then you can use something like the buffer-local variable with the
> same name 'context-menu-functions' (handled in 'context-menu-map').
> The main point is that these functions return a menu.
>
> But instead of a menu, an org function could return
> a more high-level data structure like
> ((name1 . action1 props) (name2 . action2 ...) ...)
>
> IOW, this means adding an abstraction layer on top of the existing
> user interfaces such as transient and context-menu.

Yeah. I am not 100% sure if adding an abstraction layer is a great idea.
Another idea I was considering is similar to what you propose: have some
kind of hook like `context-menu-functions', but accepting an extra
argument - menu type (context menu, transient, which-key, etc.). Then, it
should produce appropriate menu spec.

However, this will require Elisp to customize things. Also not ideal.

-- 
Ihor Radchenko // yantar92,
Org mode maintainer,
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: [RFC] The best way to choose an "action" at point: context-menu-mode, transient, which-key or embark?

[Ihor Radchenko]

Kierin Bell <fernseed@fernseed.me> writes:

> I think that the built-in Emacs thingatpt.el should not be overlooked
> here.
>
> Instead of implementing an entire system specific to Org, imagine a
> generic action-at-point interface that works on "things" from
> thingatpt.el. For the various targets, Org could add new "providers" to
> `thing-at-point-provider-alist', `forward-thing-provider-alist', and
> `bounds-of-thing-at-point-provider-alist'. [ Org actually does already
> register its own 'url' provider for links. ]

This is actually not what I had in mind in this thread. I was only
hoping to get input about customizing menu interface in a way that menu
UI can be chosen by user.

As for `thing-at-point', it is not enough for Org's needs.
Let me show you an example of one of the Org "action" commands.

org-ctrl-c-ctrl-c does the following:

1. If performs specific actions depending on Org syntax element at point
2. It performs alternative action in Org edit buffers where
   org-finish-function is defined.
3. It performs different things depending on context around thing at
   point. For example, first paragraph inside a list will trigger a
   different action compared to just a paragraph.

While (1) can be easily ported to thing-at-point, (2) is much harder,
and (3) will involve creating artificial "things" just for the purposes
of specific Org command.

> Then, Org could implement a number of action selection interfaces that
> act on the various classes of "thing". An exemplary package would be
> Philip Kaludercic's great =do-at-point= package, which provides a simple
> action selection menu for the thing-at-point using
> `read-multiple-choice', which I find elegant and intuitive.[1]

I'd like Org _not to implement interfaces_. Instead, I want to reuse the
existing interfaces - transient, menus, which-key, etc. My main question
is whether we can do such thing cleanly.

> I may also be misunderstanding the proposed interface. For example,
> instead of a generic interface for acting on a single thing at point,
> maybe you are describing more of an interface for associating commands
> with multiple potential targets that must be located (e.g., in a
> subtree), which are then each associated with actions.

Yup, something more like this.

> Even if that's the case, there is a good case for implementing
> thingatpt.el providers for the targets, so that users could bring our
> own action-at-point packages/interfaces. [ I would be willing to help
> write some of those providers. ] And if thingatpt.el isn't generalized
> or fast enough, then there is a case for creating a new, more flexible
> /de facto/ library like this for Emacs.

Better interoperability with thingatpt.el will be certainly welcome.
I even coined this idea in the context of tree-sitter in the past.

-- 
Ihor Radchenko // yantar92,
Org mode maintainer,
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>