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

[Gabriel Santos]

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*