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

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?

[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? (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.

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>