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>

Org-cite: Replace basic follow-processor with transient menu?

[Tor-björn Claesson]

Hello!

I recently switched from org-ref to org-cite, and would like to thank
eveyone who has worked on citation handling in org-mode!
Your work is of incredible value to my research productivity!

Since I use org-roam-ref, I initially went with citar and installed
vertico, marginalia and embark, but this felt a bit invasive,
so I went back to the built in basic processors,
which fill all my needs except for the follow-processor.

To improve following, I made a transient which offers options other than
opening the bibliography entry. This works really well, and can easily
be extended by adding new suffixes.

In order to make the basic follow processor more useful, would you be
interested in replacing it with a transient menu?

As an example, I attach my transient, including examples on extensions.
It would obviously need some work on wording and thought as to what
commands should be made available by default. Also I am not used to
elisp, and the code can probably be improved!

I hope that this example demonstrates how more useful and extensible
the basic citation follower would be in form of a transient menu,
and would be happy to work this into something fit for inclusion
in org-mode, in case you would be interested.

Best regards,
Tor-björn Claesson

(transient-define-prefix tbc/follow-reference (datum &optional _)
  "How should we follow references?"
  [["Open"
    ("b" "bibliography entry"
     (lambda ()
       (interactive)
       (org-cite-basic-goto
        (car  (oref (transient-prefix-object) scope))
        (cadr (oref (transient-prefix-object) scope)))))]
   ["Copy"
    ("c" "citation key"
     (lambda ()
       (interactive)
       (kill-new
        (org-element-property :key (car (oref (transient-prefix-object) scope))))))]]
  (interactive)
  (transient-setup 'tbc/follow-reference nil nil :scope (list 
                                                         datum
                                                         _)))
(org-cite-register-processor 'tbc
  :follow #'tbc/follow-reference)
(setq org-cite-follow-processor 'tbc)

(transient-append-suffix 'tbc/follow-reference "b"
  '("p" "pdf"
    (lambda ()
      (interactive)
      (find-file-other-window
       (concat
        tbc/projektet ; path to my research files
        "Referensartiklar/"
        (org-element-property :key (car (oref (transient-prefix-object) scope)))
        ".pdf")))))

(transient-append-suffix 'tbc/follow-reference "p"
  '("n" "note"
    (lambda ()
      (interactive)
      (orb-edit-note
       (org-element-property
        :key (car  (oref (transient-prefix-object) scope)))))))

;; Adapted from org-ref
(transient-append-suffix 'tbc/follow-reference "c"
  '("d" "DOI"
     (lambda ()
       (interactive)
       (kill-new 
        (save-excursion 
          (with-temp-buffer
            (mapc #'insert-file-contents org-cite-global-bibliography)
            (bibtex-set-dialect (parsebib-find-bibtex-dialect) t)
            (bibtex-search-entry (org-element-property :key (car (oref (transient-prefix-object) scope))))
            (setq doi (bibtex-autokey-get-field "doi"))
            (replace-regexp-in-string "^http://dx.doi.org/" "" doi)))))))

Re: Org-cite: Replace basic follow-processor with transient menu?

[Tor-björn Claesson]

Ihor Radchenko <yantar92@posteo.net> writes:
> Rather than going into recursive replacements, simply let-bind
> !citation, !prefix, and anything else we may want to provide around the
> lambda/function call.

Clever! I had to put the let inside the lambda for it to work.

(defun org-cite-basic-follow--parse-suffix-specification (specification)
  (pcase specification
    (`(,key ,desc (lambda . ,fn-args) . ,other)
     (list key desc `(lambda ,@fn-args) ,other))
    (`(,key ,desc (,fn . ,fn-args) . ,other)
     `(,key ,desc
            (lambda ()
              (interactive)
              (let ((!citation (car (transient-scope)))
                    (!prefix (cadr (transient-scope)))
                    (!citation-key (org-element-property :key (car (transient-scope)))))
                (,fn ,@fn-args)))
            ,other))
    (other other)))

Does it make sense to keep matching the lambda separately? This just
keeps getting better=)

Thanks and cheers!
Tor-björn

Re: Org-cite: Replace basic follow-processor with transient menu?

[Ihor Radchenko]

Tor-björn Claesson <tclaesson@gmail.com> writes:

> Clever! I had to put the let inside the lambda for it to work.

You probably do not have to once you use lexical binding (that is - not
C-x C-e ad-hoc, but put things into actual byte-compiled file)

But let inside the lambda body is perfectly fine.

> (defun org-cite-basic-follow--parse-suffix-specification (specification)
>   (pcase specification
>     (`(,key ,desc (lambda . ,fn-args) . ,other)
>      (list key desc `(lambda ,@fn-args) ,other))
>     (`(,key ,desc (,fn . ,fn-args) . ,other)
>      `(,key ,desc
>             (lambda ()
>               (interactive)
>               (let ((!citation (car (transient-scope)))
>                     (!prefix (cadr (transient-scope)))
>                     (!citation-key (org-element-property :key (car (transient-scope)))))
>                 (,fn ,@fn-args)))
>             ,other))
>     (other other)))
>
> Does it make sense to keep matching the lambda separately? This just
> keeps getting better=)

AFIU, you need to match against lambda simply to avoid the next clause
matching it. If so, you can change the clause to match all ,fn, except
lambda like the following:

`(,key
  ,desc
  (,(and fn (guard (not (eq fn 'lambda))))
   . ,fn-args)
  . ,other)

This is getting ugly though.
An alternative would be simply

(defun org-cite-basic-follow--parse-suffix-specification (specification)
  (pcase specification
    ((and val `(,key ,desc (,fn . ,fn-args) . ,other))
     (if (eq fn 'lambda) val
       `(,key ,desc
              (lambda ()
		(interactive)
		(let ((!citation (car (transient-scope)))
                      (!prefix (cadr (transient-scope)))
                      (!citation-key (org-element-property :key (car (transient-scope)))))
                  (,fn ,@fn-args)))
              ,@other)))
    (other other)))

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
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: Org-cite: Replace basic follow-processor with transient menu?

[Tor-björn Claesson]

Ihor Radchenko <yantar92@posteo.net> writes:
> AFIU, you need to match against lambda simply to avoid the next clause
> matching it.

Exactly.

> If so, you can change the clause to match all ,fn, except
> lambda like the following:
>
> `(,key
>   ,desc
>   (,(and fn (guard (not (eq fn 'lambda))))
>    . ,fn-args)
>   . ,other)
>
> This is getting ugly though.
> An alternative would be simply
>
> (defun org-cite-basic-follow--parse-suffix-specification (specification)
>   (pcase specification
>     ((and val `(,key ,desc (,fn . ,fn-args) . ,other))
>      (if (eq fn 'lambda) val
>        `(,key ,desc
>               (lambda ()
> 		(interactive)
> 		(let ((!citation (car (transient-scope)))
>                       (!prefix (cadr (transient-scope)))
>                       (!citation-key (org-element-property :key (car (transient-scope)))))
>                   (,fn ,@fn-args)))
>               ,@other)))
>     (other other)))

I feel that the guard option does the right thing by directly fixing
the pattern matching - but what approach do you prefer?

Is this starting to be a good time for me to produce a patch?

Cheers,
Tor-björn

Re: Org-cite: Replace basic follow-processor with transient menu?

[Ihor Radchenko]

Tor-björn Claesson <tclaesson@gmail.com> writes:

> I feel that the guard option does the right thing by directly fixing
> the pattern matching - but what approach do you prefer?

I provided the guard example just for your reference.
The preference for actual code is more readable code.
IMHO, my second variant with (and val ...) is more readable.

> Is this starting to be a good time for me to produce a patch?

Yes. Thanks in advance!

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
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: Org-cite: Replace basic follow-processor with transient menu?

[Tor-björn Claesson]

Ihor Radchenko <yantar92@posteo.net> writes:

> Tor-björn Claesson <tclaesson@gmail.com> writes:
>
>> I feel that the guard option does the right thing by directly fixing
>> the pattern matching - but what approach do you prefer?
>
> I provided the guard example just for your reference.
> The preference for actual code is more readable code.
> IMHO, my second variant with (and val ...) is more readable.
>

A, thanks, I will use that then!

>> Is this starting to be a good time for me to produce a patch?
>
> Yes. Thanks in advance!

Would it make sense to add two functions for getting the doi and url
from a citation? That would be generally useful, and simplify the
transient menu specification.

Also, is this change big enough that I should apply for copyright
assignment?

Cheers,
Tor-björn

Re: Org-cite: Replace basic follow-processor with transient menu?

[Ihor Radchenko]

Tor-björn Claesson <tclaesson@gmail.com> writes:

>>> Is this starting to be a good time for me to produce a patch?
>>
>> Yes. Thanks in advance!
>
> Would it make sense to add two functions for getting the doi and url
> from a citation? That would be generally useful, and simplify the
> transient menu specification.

Do you mean opening citation URL derived from URL/DOI fields in browser?

> Also, is this change big enough that I should apply for copyright
> assignment?

FSF threshold for "tiny" changes is 15 lines of code.
I doubt that you can fit the changes within 15 lines, so yes, you do
need copyright assignment. See
https://orgmode.org/worg/org-contribute.html#copyright

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
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: Org-cite: Replace basic follow-processor with transient menu?

[Tor-björn Claesson]

Den lör 9 nov. 2024 kl 16:07 skrev Ihor Radchenko <yantar92@posteo.net>:
> > Would it make sense to add two functions for getting the doi and url
> > from a citation? That would be generally useful, and simplify the
> > transient menu specification.
>
> Do you mean opening citation URL derived from URL/DOI fields in browser?

No, that I think belongs in the transient suffix. Rather I meant a
function to get the
DOI from a citation. I thought about this, and would like to only
include the open
bibliography entry in the patch, and look into other options later.
Would this be ok?

>
> FSF threshold for "tiny" changes is 15 lines of code.
> I doubt that you can fit the changes within 15 lines, so yes, you do
> need copyright assignment. See
> https://orgmode.org/worg/org-contribute.html#copyright

Ok, thanks!

Cheers
Tor-björn

Re: Org-cite: Replace basic follow-processor with transient menu?

[Ihor Radchenko]

Tor-björn Claesson <tclaesson@gmail.com> writes:

> ... I thought about this, and would like to only
> include the open
> bibliography entry in the patch, and look into other options later.
> Would this be ok?

Yup.

Re: Org-cite: Replace basic follow-processor with transient menu?

[Tor-björn Claesson]

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

Here is my first attempt.
I have read the commit guidelines, but it is very possible that I have
misunderstood or just missed something, so I'm grateful for any
feedback!

Cheers,
Tor-björn

Den sön 10 nov. 2024 kl 18:40 skrev Ihor Radchenko <yantar92@posteo.net>:
>
> Tor-björn Claesson <tclaesson@gmail.com> writes:
>
> > ... I thought about this, and would like to only
> > include the open
> > bibliography entry in the patch, and look into other options later.
> > Would this be ok?
>
> Yup.

[-- Attachment #2: 0001-lisp-oc-basic.el-Transient-menu-for-following-citati.patch --]
[-- Type: text/x-patch, Size: 7625 bytes --]

From c8731ecd5db2beecc434a65448a7302212aab95a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tor-bj=C3=B6rn=20Claesson?= <tclaesson@gmail.com>
>
Date: Mon, 11 Nov 2024 11:46:32 +0200
Subject: [PATCH] lisp/oc-basic.el: Transient menu for following citations

* lisp/oc-basic.el (require 'transient): Pull in transient.
(org-cite-basic-follow-ask): New customization option. should
`org-cite-basic-follow' should prompt the user for an action?
(org-cite-basic-follow-actions): New customization option, that
specifies the contents of the transient menu.
(org-cite-basic-follow): New function.  Displays a menu asking how to
follow a citation if called with a negative prefix, or
`org-cite-basic-follow-ask' is non-nil. Otherwise, it retains the
default behaviour of opening the bibliography entry.
(org-cite-basic-follow--parse-suffix-specification,
org-cite-basic-follow--setup): Helper functions for
`org-cite-basic-follow'.
(org-cite-register-processor 'basic): Update the basic citation
processor to follow citations using `org-cite-basic-follow'.

* etc/ORG_NEWS (Menu for choosing how to follow citations): Describe
the new feature
(New option ~org-cite-basic-follow-ask~): Describe this new
customization option.
(New option ~org-cite-basic-follow-actions~): Describe this new
customization option, which specifies the layaout of the
`org-cite-basic-follow' transient menu.

This change was co-authored with much support from Ihor Radchenko and
Jonas Bernoulli, thanks!
---
 etc/ORG-NEWS     | 22 +++++++++++++
 lisp/oc-basic.el | 84 ++++++++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 103 insertions(+), 3 deletions(-)

diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index de4f11b25..cf87e11bf 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -114,6 +114,17 @@ The keybindings in the repeat-maps can be changed by customizing
 
 See the new [[info:org#Repeating commands]["Repeating commands"]] section in Org mode manual.
 
+*** Menu for choosing how to follow citations
+If invoked with a prefix of C-- C-u, following citations with
+the org-cite-basic citation backend will no present a transient menu,
+offering choices for how to follow citations.
+
+The contents of this menu can be customized in
+~org-cite-basic-follow-actions~.
+
+In order to always show this menu, set ~org-cite-basic-follow-ask~
+to non-nil.
+
 ** New and changed options
 
 # Chanes deadling with changing default values of customizations,
@@ -158,6 +169,17 @@ English.  The default value is ~t~ as the CSL standard assumes that
 English titles are specified in sentence-case but the bibtex
 bibliography format requires them to be written in title-case.
 
+*** New option ~org-cite-basic-follow-ask~
+When this option is non-nil, following a citation with the basic citation
+backend will present a transient menu with choices for how to follow the
+citation.
+If nil, following a citation will open its bibliography entry.
+
+*** New option ~org-cite-basic-follow-actions~
+This option specifies the options presented by ~org-cite-basic-follow~
+if it is invoked with a C-- C-u prefix or ~org-cite-basic-follow-ask~
+is non-nil.
+
 ** New functions and changes in function arguments
 
 # This also includes changes in function behavior from Elisp perspective.
diff --git a/lisp/oc-basic.el b/lisp/oc-basic.el
index e207a1997..8add329b7 100644
--- a/lisp/oc-basic.el
+++ b/lisp/oc-basic.el
@@ -74,6 +74,7 @@
 (require 'map)
 (require 'oc)
 (require 'seq)
+(require 'transient)
 
 (declare-function org-open-at-point "org" (&optional arg))
 (declare-function org-open-file "org" (path &optional in-emacs line search))
@@ -140,6 +141,36 @@
   :type 'face
   :safe #'facep)
 
+(defcustom org-cite-basic-follow-ask nil
+  "Should `org-cite-basic' ask how to follow citations?
+
+When this option is nil, `org-cite-basic-follow' opens the bibliography entry.
+Otherwise, `org-cite-basic-follow' will display a transient menu prompting the 
+user for an action. The contents of this menu can be customized in 
+`org-cite-basic-follow-actions'."
+  :group 'org-cite
+  :package-version '(Org . "9.8")
+  :type 'boolean)
+
+(defcustom org-cite-basic-follow-actions
+  '[["Open"
+     ("b" "bibliography entry" (org-cite-basic-goto !citation !prefix))]]
+  "Actions in the `org-cite-basic-follow' transient menu.
+
+This option uses the same syntax as `transient-define-prefix', see Info node
+`(transient)Binding Suffix and Infix Commands'. In addition, it is possible 
+to specify a function call for the COMMAND part, where !citation, 
+!prefix, and !citation-key can be used to access those values. 
+
+If COMMAND is a lambda form, it can access the citation and prefix like this:
+
+  (lambda (citation prefix)
+     (interactive (transient-scope))
+     ...)"
+  :group 'org-cite
+  :package-version '(Org . "9.8")
+  :type 'sexp)
+
 \f
 ;;; Internal variables
 (defvar org-cite-basic--bibliography-cache nil
@@ -832,6 +863,53 @@ present in the citation."
        (bibtex-set-dialect)
        (bibtex-search-entry key)))))
 
+(transient-define-prefix org-cite-basic-follow (citation &optional prefix)
+  "Follow citation.
+
+This transient is invoked through `org-open-at-point'. 
+When `org-open-at-point' is invoked with a negative prefix,
+or `org-cite-basic-follow-ask' is non-nil, it will present
+a transient menu prompting the user for an action. Otherwise,
+it will open the bibliography entry for the citation at point.
+
+Suffixes can not be added to this transient menu using the ordinary
+`transient-append-suffix' or `transient-insert-suffix', instead, the
+contents of the menu are defined in the variable
+`org-cite-basic-follow-actions'."
+  [:class transient-columns
+          :setup-children org-cite-basic-follow--setup
+          :pad-keys t]
+  (interactive)
+  (if (or org-cite-basic-follow-ask
+          (equal prefix '(-4)))
+      (transient-setup 'org-cite-basic-follow nil nil
+                       :scope (list citation prefix))
+    (org-cite-basic-goto citation prefix)))
+
+(defun org-cite-basic-follow--parse-suffix-specification (specification)
+  (pcase specification
+    ((and val `(,key ,desc (,fn . ,fn-args) . ,other))
+     (if (eq fn 'lambda) val
+       `(,key ,desc
+              (lambda ()
+		(interactive)
+		(let ((!citation (car (transient-scope)))
+                      (!prefix (cadr (transient-scope)))
+                      (!citation-key
+                       (org-element-property :key (car (transient-scope)))))
+                  (,fn ,@fn-args)))
+              ,@other)))
+    (other other)))
+
+(defun org-cite-basic-follow--setup (_)
+  (transient-parse-suffixes
+   'org-cite-basic-follow
+   (cl-map 'vector
+           (lambda (group)
+             (cl-map 'vector #'org-cite-basic-follow--parse-suffix-specification
+                     group))
+           org-cite-basic-follow-actions)))
+
 \f
 ;;; "Insert" capability
 (defun org-cite-basic--complete-style (_)
@@ -920,9 +998,9 @@ Raise an error when no bibliography is set in the buffer."
   :activate #'org-cite-basic-activate
   :export-citation #'org-cite-basic-export-citation
   :export-bibliography #'org-cite-basic-export-bibliography
-  :follow #'org-cite-basic-goto
-  :insert (org-cite-make-insert-processor #'org-cite-basic--complete-key
-                                          #'org-cite-basic--complete-style)
+  :follow #'org-cite-basic-follow
+  :insert  (org-cite-make-insert-processor #'org-cite-basic--complete-key
+                                           #'org-cite-basic--complete-style)
   :cite-styles
   '((("author" "a") ("caps" "c"))
     (("noauthor" "na") ("bare" "b"))
-- 
2.45.2

Re: Org-cite: Replace basic follow-processor with transient menu?

[Ihor Radchenko]

Tor-björn Claesson <tclaesson@gmail.com> writes:

> Here is my first attempt.
> I have read the commit guidelines, but it is very possible that I have
> misunderstood or just missed something, so I'm grateful for any
> feedback!

Thanks for the patch!

See my comments below.

> * lisp/oc-basic.el (require 'transient): Pull in transient.

Technically, we still support Emacs 27, which does not have
transient. But accounting for this would be a pain and Emacs 30 is
probably going to be released some time around the beginning of the next
year. So, let's not worry about this and accept that Org 9.8-pre (next
release) no longer supports Emacs 27.

If you are a user of Emacs 27 + Org main branch, and have strong
objections, please chime in.

> +*** Menu for choosing how to follow citations
> +If invoked with a prefix of C-- C-u, following citations with
> +the org-cite-basic citation backend will no present a transient menu,
> +offering choices for how to follow citations.

I imagine C-- C-u more as a toggle - if `org-cite-basic-follow-ask' is
t, it disables the menu; enables otherwise.

> +(defcustom org-cite-basic-follow-ask nil
> +  "Should `org-cite-basic' ask how to follow citations?
> +
> +When this option is nil, `org-cite-basic-follow' opens the bibliography entry.
> +Otherwise, `org-cite-basic-follow' will display a transient menu prompting the 
> +user for an action. The contents of this menu can be customized in 
> +`org-cite-basic-follow-actions'."

Note: our convention is to use double space between sentences.
There are also typos, but that's a minor thing I can fix myself before
merging.

> +(defcustom org-cite-basic-follow-actions
> +  '[["Open"
> +     ("b" "bibliography entry" (org-cite-basic-goto !citation !prefix))]]
> +  "Actions in the `org-cite-basic-follow' transient menu.
> +
> +This option uses the same syntax as `transient-define-prefix', see Info node
> +`(transient)Binding Suffix and Infix Commands'. In addition, it is possible 
> +to specify a function call for the COMMAND part, where !citation, 
> +!prefix, and !citation-key can be used to access those values. 
> +
> +If COMMAND is a lambda form, it can access the citation and prefix like this:
> +
> +  (lambda (citation prefix)
> +     (interactive (transient-scope))
> +     ...)"

Could we make !prefix, and !citation work in lambdas? We should be able
to.

> +(transient-define-prefix org-cite-basic-follow (citation &optional prefix)
> +  "Follow citation.
> +
> +This transient is invoked through `org-open-at-point'. 
> +When `org-open-at-point' is invoked

It should not matter for this command where it is called from.
You can simply drop references to `org-open-at-point'

We can even make the prefix work as a standalone command. Simply using
interactive spec.

(interactive
   (list (let ((obj (org-element-context)))
           (pcase (org-element-type obj)
             ((or citation citation-reference) obj)
             (_ (user-error "No citation at point"))))))

> ... with a negative prefix, +or `org-cite-basic-follow-ask' is
> non-nil, it will present +a transient menu prompting the user for an
> action. Otherwise, +it will open the bibliography entry for the
> citation at point.

> +Suffixes can not be added to this transient menu using the ordinary
> +`transient-append-suffix' or `transient-insert-suffix', instead, the
> +contents of the menu are defined in the variable
> +`org-cite-basic-follow-actions'."

Suffixes can be added. Try

(transient-append-suffix 'org-cite-basic-follow nil
  '[["Other" ("t" "test" (lambda () (interactive) (message "Hello!")))]])

> +(defun org-cite-basic-follow--parse-suffix-specification (specification)
> +  (pcase specification

Please, add the docstring.

> +    ((and val `(,key ,desc (,fn . ,fn-args) . ,other))
> +     (if (eq fn 'lambda) val
> +       `(,key ,desc
> +              (lambda ()
> +		(interactive)
> +		(let ((!citation (car (transient-scope)))
> +                      (!prefix (cadr (transient-scope)))
> +                      (!citation-key
> +                       (org-element-property :key (car (transient-scope)))))

`org-open-at-point' may be called with point at citation rather than
citation reference. Citation object does not have :key property.

I think that we should drop !citation-key spec and instead specify that
the command may be called with citation or citation-reference object in !citation.

> +(defun org-cite-basic-follow--setup (_)
> +  (transient-parse-suffixes

Docstring here as well.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
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: Org-cite: Replace basic follow-processor with transient menu?

[Tor-björn Claesson]

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

Ihor Radchenko <yantar92@posteo.net> writes:
> See my comments below.
Thanks for taking the time to look at this!

>> +*** Menu for choosing how to follow citations
>> +If invoked with a prefix of C-- C-u, following citations with
>> +the org-cite-basic citation backend will no present a transient menu,
>> +offering choices for how to follow citations.
>
> I imagine C-- C-u more as a toggle - if `org-cite-basic-follow-ask' is
> t, it disables the menu; enables otherwise.
That is more useful, thanks!

>
>> +(defcustom org-cite-basic-follow-ask nil
>> +  "Should `org-cite-basic' ask how to follow citations?
>> +
>> +When this option is nil, `org-cite-basic-follow' opens the bibliography entry.
>> +Otherwise, `org-cite-basic-follow' will display a transient menu prompting the 
>> +user for an action. The contents of this menu can be customized in 
>> +`org-cite-basic-follow-actions'."
>
> Note: our convention is to use double space between sentences.
> There are also typos, but that's a minor thing I can fix myself before
> merging.

Ah, bummer. I have fixed (at least some) of those typos.

>> +(defcustom org-cite-basic-follow-actions
>> +  '[["Open"
>> +     ("b" "bibliography entry" (org-cite-basic-goto !citation !prefix))]]
>> +  "Actions in the `org-cite-basic-follow' transient menu.
>> +
>> +This option uses the same syntax as `transient-define-prefix', see Info node
>> +`(transient)Binding Suffix and Infix Commands'. In addition, it is possible 
>> +to specify a function call for the COMMAND part, where !citation, 
>> +!prefix, and !citation-key can be used to access those values. 
>> +
>> +If COMMAND is a lambda form, it can access the citation and prefix like this:
>> +
>> +  (lambda (citation prefix)
>> +     (interactive (transient-scope))
>> +     ...)"
>
> Could we make !prefix, and !citation work in lambdas? We should be able
> to.

Sure! It took me some trial and error to get the list splicing right but
now it works in lambdas to. I added another helper to do let binding.

>> +(transient-define-prefix org-cite-basic-follow (citation &optional prefix)
>> +  "Follow citation.
>> +
>> +This transient is invoked through `org-open-at-point'. 
>> +When `org-open-at-point' is invoked
>
> It should not matter for this command where it is called from.
> You can simply drop references to `org-open-at-point'
>
> We can even make the prefix work as a standalone command. Simply using
> interactive spec.
>
> (interactive
>    (list (let ((obj (org-element-context)))
>            (pcase (org-element-type obj)
>              ((or citation citation-reference) obj)
>              (_ (user-error "No citation at point"))))))

I was not able to get this to work.

>> ... with a negative prefix, +or `org-cite-basic-follow-ask' is
>> non-nil, it will present +a transient menu prompting the user for an
>> action. Otherwise, +it will open the bibliography entry for the
>> citation at point.
>
>> +Suffixes can not be added to this transient menu using the ordinary
>> +`transient-append-suffix' or `transient-insert-suffix', instead, the
>> +contents of the menu are defined in the variable
>> +`org-cite-basic-follow-actions'."
>
> Suffixes can be added. Try
>
> (transient-append-suffix 'org-cite-basic-follow nil
>   '[["Other" ("t" "test" (lambda () (interactive) (message "Hello!")))]])

Ah, I didn't know you could nil the position.

>> +(defun org-cite-basic-follow--parse-suffix-specification (specification)
>> +  (pcase specification
>
> Please, add the docstring.
>

Ok.

>> +    ((and val `(,key ,desc (,fn . ,fn-args) . ,other))
>> +     (if (eq fn 'lambda) val
>> +       `(,key ,desc
>> +              (lambda ()
>> +		(interactive)
>> +		(let ((!citation (car (transient-scope)))
>> +                      (!prefix (cadr (transient-scope)))
>> +                      (!citation-key
>> +                       (org-element-property :key (car (transient-scope)))))
>
> `org-open-at-point' may be called with point at citation rather than
> citation reference. Citation object does not have :key property.
>
> I think that we should drop !citation-key spec and instead specify that
> the command may be called with citation or citation-reference object in !citation.

`org-cite-basic-goto' handles this by prompting the user for a key, if
it is called with a citation object. I adopted this approach. (I find the
!citation-key useful for a lot of things I like to do to citations, and
would like to keep it.)

>> +(defun org-cite-basic-follow--setup (_)
>> +  (transient-parse-suffixes
>
> Docstring here as well.

Ok.

Version 2 of the patch is attached.

Cheers,
Tor-björn


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: transient-follower-version2 --]
[-- Type: text/x-diff, Size: 8075 bytes --]

From e91fff9f6c03e2c766dee410f46382398f883997 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tor-bj=C3=B6rn=20Claesson?= <tclaesson@gmail.com>
Date: Tue, 12 Nov 2024 11:09:16 +0200
Subject: [PATCH] lisp/oc-basic.el: Transient menu for following citations

* lisp/oc-basic.el (require 'transient): Pull in transient.
(org-cite-basic-follow-ask): New customization option. should
`org-cite-basic-follow' prompt the user for an action?
(org-cite-basic-follow-actions): New customization option, that
specifies the contents of the transient menu.
(org-cite-basic-follow): New function.  Displays a menu asking how to
follow a citation if `org-cite-basic-follow-ask' is
non-nil. Otherwise, it retains the default behaviour of opening the
bibliography entry. This can be inversed with a negative prefix argument.
(org-cite-basic-follow--parse-suffix-specification,
org-cite-basic-follow--wrap-function, and
org-cite-basic-follow--setup): Helper functions for
`org-cite-basic-follow'.
(org-cite-register-processor 'basic): Update the basic citation
processor to follow citations using `org-cite-basic-follow'.

* etc/ORG_NEWS (Menu for choosing how to follow citations): Describe
the new feature
(New option ~org-cite-basic-follow-ask~): Describe this new
customization option.
(New option ~org-cite-basic-follow-actions~): Describe this new
customization option, which specifies the layout of the
`org-cite-basic-follow' transient menu.

This change was co-authored with much support from Ihor Radchenko and
Jonas Bernoulli, thanks!
---
 etc/ORG-NEWS     | 22 +++++++++++
 lisp/oc-basic.el | 95 +++++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 116 insertions(+), 1 deletion(-)

diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index de4f11b25..b859b0ada 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -114,6 +114,15 @@ The keybindings in the repeat-maps can be changed by customizing
 
 See the new [[info:org#Repeating commands]["Repeating commands"]] section in Org mode manual.
 
+*** Menu for choosing how to follow citations
+
+Following citations with the org-cite-basic citation backend can now present a
+transient menu. To show this menu, set ~org-cite-basic-follow-ask~ to non-nil. 
+This behaviour can be reversed with a negativ prefix.
+
+The contents of this menu can be customized in
+~org-cite-basic-follow-actions~.
+
 ** New and changed options
 
 # Chanes deadling with changing default values of customizations,
@@ -158,6 +167,19 @@ English.  The default value is ~t~ as the CSL standard assumes that
 English titles are specified in sentence-case but the bibtex
 bibliography format requires them to be written in title-case.
 
+*** New option ~org-cite-basic-follow-ask~
+
+When this option is non-nil, following a citation with the basic citation
+backend will present a transient menu with choices for how to follow the
+citation.
+If nil, following a citation will open its bibliography entry.
+
+This behaviour can be reversed with a negative prefix argument.
+
+*** New option ~org-cite-basic-follow-actions~
+
+This option specifies the options presented by ~org-cite-basic-follow~.
+
 ** New functions and changes in function arguments
 
 # This also includes changes in function behavior from Elisp perspective.
diff --git a/lisp/oc-basic.el b/lisp/oc-basic.el
index e207a1997..c3fc3f34d 100644
--- a/lisp/oc-basic.el
+++ b/lisp/oc-basic.el
@@ -74,6 +74,7 @@
 (require 'map)
 (require 'oc)
 (require 'seq)
+(require 'transient)
 
 (declare-function org-open-at-point "org" (&optional arg))
 (declare-function org-open-file "org" (path &optional in-emacs line search))
@@ -140,6 +141,30 @@
   :type 'face
   :safe #'facep)
 
+(defcustom org-cite-basic-follow-ask nil
+  "Should `org-cite-basic' ask how to follow citations?
+
+When this option is nil, `org-cite-basic-follow' opens the bibliography entry. 
+Otherwise, `org-cite-basic-follow' will display a transient menu prompting the 
+user for an action.  The contents of this menu can be customized in 
+`org-cite-basic-follow-actions'."
+  :group 'org-cite
+  :package-version '(Org . "9.8")
+  :type 'boolean)
+
+(defcustom org-cite-basic-follow-actions
+  '[["Open"
+     ("b" "bibliography entry" (org-cite-basic-goto !citation !prefix))]]
+  "Actions in the `org-cite-basic-follow' transient menu.
+
+This option uses the same syntax as `transient-define-prefix', see Info node
+`(transient)Binding Suffix and Infix Commands'.  In addition, it is possible 
+to specify a function call for the COMMAND part, where !citation, 
+!prefix, and !citation-key can be used to access those values."
+  :group 'org-cite
+  :package-version '(Org . "9.8")
+  :type 'sexp)
+
 \f
 ;;; Internal variables
 (defvar org-cite-basic--bibliography-cache nil
@@ -832,6 +857,74 @@ present in the citation."
        (bibtex-set-dialect)
        (bibtex-search-entry key)))))
 
+(transient-define-prefix org-cite-basic-follow (citation &optional prefix)
+  "Follow citation.
+
+If `org-cite-basic-follow-ask' is non-nil, this transient will present
+a menu prompting the user for an action. 
+Otherwise, it will open the bibliography entry for the citation at point.  
+This behaviour is inverted when the transient is called with a negative prefix
+argument.
+
+The contents of the menu are defined in the variable
+`org-cite-basic-follow-actions'."
+  [:class transient-columns
+          :setup-children org-cite-basic-follow--setup
+          :pad-keys t]
+  (interactive)
+  (if (xor org-cite-basic-follow-ask
+           (equal prefix '(-4)))
+      (transient-setup 'org-cite-basic-follow nil nil
+                       :scope (list citation prefix))
+    (org-cite-basic-goto citation prefix)))
+
+(defun org-cite-basic-follow--wrap-function (fn-args &optional fn)
+  "Provide !citation, !prefix, and !citation-key symbols."
+  (append 
+   `(let ((!citation (car (transient-scope)))
+          (!prefix (cadr (transient-scope)))
+          (!citation-key
+           (if (org-element-type-p (car (transient-scope)) 'citation-reference)
+               (org-element-property :key (car (transient-scope)))
+             (pcase (org-cite-get-references (car (transient-scope)) t)
+               (`(,key) key)
+               (keys
+                (or (completing-read "Select citation key: " keys nil t)
+                    (user-error "Aborted"))))))))
+   (if fn
+       `((,fn ,@fn-args))
+     fn-args)))
+
+(defun org-cite-basic-follow--parse-suffix-specification (specification)
+  "Handle special syntax for `org-cite-basic-follow-actions'."
+  (pcase specification
+    (`(,key ,desc (lambda ,args . ,fn-args) . ,other)
+     `(,key ,desc
+            (lambda ,args
+              ,(unless (and (listp (car fn-args))
+                            (equal (caar fn-args)
+                                   'interactive))
+                 '(interactive))
+              ,(org-cite-basic-follow--wrap-function fn-args))
+            ,@other))
+    (`(,key ,desc (,fn . ,fn-args) . ,other)
+     `(,key ,desc
+            (lambda ()
+	      (interactive)
+	      ,(org-cite-basic-follow--wrap-function fn-args fn))
+            ,@other))
+    (other other)))
+
+(defun org-cite-basic-follow--setup (_)
+  "Update `org-cite-basic-follow' when `org-cite-basic-follow-actions' changes."
+  (transient-parse-suffixes
+   'org-cite-basic-follow
+   (cl-map 'vector
+           (lambda (group)
+             (cl-map 'vector #'org-cite-basic-follow--parse-suffix-specification
+                     group))
+           org-cite-basic-follow-actions)))
+
 \f
 ;;; "Insert" capability
 (defun org-cite-basic--complete-style (_)
@@ -920,7 +1013,7 @@ Raise an error when no bibliography is set in the buffer."
   :activate #'org-cite-basic-activate
   :export-citation #'org-cite-basic-export-citation
   :export-bibliography #'org-cite-basic-export-bibliography
-  :follow #'org-cite-basic-goto
+  :follow #'org-cite-basic-follow
   :insert (org-cite-make-insert-processor #'org-cite-basic--complete-key
                                           #'org-cite-basic--complete-style)
   :cite-styles
-- 
2.46.0

Re: Org-cite: Replace basic follow-processor with transient menu?

[Ihor Radchenko]

Tor-björn Claesson <tclaesson@gmail.com> writes:

>> Could we make !prefix, and !citation work in lambdas? We should be able
>> to.
>
> Sure! It took me some trial and error to get the list splicing right but
> now it works in lambdas to. I added another helper to do let binding.

I think that a simple

(let ((!prefix ...) ...)
 (lambda ...))

will work.

But you should test without C-x C-e. Need to reload the whole library.

>> We can even make the prefix work as a standalone command. Simply using
>> interactive spec.
>>
>> (interactive
>>    (list (let ((obj (org-element-context)))
>>            (pcase (org-element-type obj)
>>              ((or citation citation-reference) obj)
>>              (_ (user-error "No citation at point"))))))
>
> I was not able to get this to work.

Just replace the interactive spec with my version and then
M-x org-cite-basic-follow with point on citation in Org document.

>> `org-open-at-point' may be called with point at citation rather than
>> citation reference. Citation object does not have :key property.
>>
>> I think that we should drop !citation-key spec and instead specify that
>> the command may be called with citation or citation-reference object in !citation.
>
> `org-cite-basic-goto' handles this by prompting the user for a key, if
> it is called with a citation object. I adopted this approach. (I find the
> !citation-key useful for a lot of things I like to do to citations, and
> would like to keep it.)

I am not sure if it is a good idea.
Commands in org-cite-basic-follow-actions may or may not need it, while
your code will _aways_ prompt user about citation key; even when the
citation key is never used.

If you realy, really want it, we can go into `cl-symbol-macrolet' and
lazy evaluation, but will be tricky (especially arranging for
(setq !citation-key ...) to work.

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

Fwd: Org-cite: Replace basic follow-processor with transient menu?

[Tor-björn Claesson]

[-- Attachment #1.1: Type: text/plain, Size: 1513 bytes --]

Ihor Radchenko <yantar92@posteo.net> writes:
> Tor-björn Claesson <tclaesson@gmail.com> writes:
>
>> Den tis 12 nov. 2024 kl 20:02 skrev Ihor Radchenko <yantar92@posteo.net>:
>>>
>>> I am not sure if it is a good idea.
>>> Commands in org-cite-basic-follow-actions may or may not need it, while
>>> your code will _aways_ prompt user about citation key; even when the
>>> citation key is never used.
>>>
>>> If you realy, really want it, we can go into `cl-symbol-macrolet' and
>>> lazy evaluation, but will be tricky (especially arranging for
>>> (setq !citation-key ...) to work.
>>>
>>
>> Wouldn't my beginner approach with recursive replacement fix this
problem?
>
> Nope. Mindlessly replacing instances of !citation-key with value may
> break the code. Consider, for example,
>
> (lambda ()
>   (let ((citation! (concat citation! "-foo"))) ...))
>
> There will be more complex cases as well.
>
> `cl-symbol-macrolet' it trying to handle what you tried with recursive
> replacement, but more carefully. But even `cl-symbol-macrolet' fails in
> certain edge cases.

Ah, then it has to go. Here comes a fixed patch. The code is much
simpler like this, but i kept the let under the lambda because for some
reason it did not work for me. Also, the interactive clause in the
transient,
while working, upset make test, but this could be fixed by requiring
org-element and quoting citation and citation-reference.

Thanks for taking the time to explain!

Cheers,
Tor-björn

[-- Attachment #1.2: Type: text/html, Size: 2088 bytes --]

[-- Attachment #2: 0001-lisp-oc-basic.el-Transient-menu-for-following-v3.patch --]
[-- Type: application/x-patch, Size: 7955 bytes --]

Re: Fwd: Org-cite: Replace basic follow-processor with transient menu?

[Ihor Radchenko]

Tor-björn Claesson <tclaesson@gmail.com> writes:

> Ah, then it has to go. Here comes a fixed patch. ...

Thanks.
See my comments below.

> +*** Menu for choosing how to follow citations

Maybe "New transient menu when following citations"

> +Following citations with the org-cite-basic citation backend can now present a
> +transient menu. To show this menu, set ~org-cite-basic-follow-ask~ to non-nil. 
> +This behaviour can be reversed with a negativ prefix.

"-4" prefix. Not negative.

> +This behaviour can be reversed with a negative prefix argument.

Same. "-4".

> +(defcustom org-cite-basic-follow-actions
> +  '[["Open"
> +     ("b" "bibliography entry" (org-cite-basic-goto !citation !prefix))]]
> +  "Actions in the `org-cite-basic-follow' transient menu.
> +
> +This option uses the same syntax as `transient-define-prefix', see Info node
> +`(transient)Binding Suffix and Infix Commands'.  In addition, it is possible 
> +to specify a function call for the COMMAND part, where !citation and 
> +!prefix can be used to access those values."
> +  :group 'org-cite
> +  :package-version '(Org . "9.8")
> +  :type 'sexp)

1. Ideally, we want at least one more menu entry here. Otherwise, the
   menu is not very useful.
2. It would be nice to provide some examples on using !citation and
   !prefix in the docstring. Also, lambdas.
3. We need to explain what !citation and !prefix refer to.

> +(transient-define-prefix org-cite-basic-follow (citation-object &optional prefix)
> ...
> +This behaviour is inverted when the transient is called with a negative prefix
> +argument.

-4 prefix

> +(defun org-cite-basic-follow--parse-suffix-specification (specification)
> +  "Handle special syntax for `org-cite-basic-follow-actions'."
> +  (pcase specification
> +    (`(,key ,desc (lambda ,args . ,fn-args) . ,other)
> +     `(,key ,desc
> +            (lambda ,args
> +              ,(unless (and (listp (car fn-args))
> +                            (equal (caar fn-args)
> +                                   'interactive))
> +                 '(interactive))
> +              (let ((!citation (car (transient-scope)))
> +                    (!prefix (cadr (transient-scope))))

This can be improved a bit.
Rather than storing transient scope as (list citation prefix), we can
use plist: (list :citation citation :prefix prefix). Then, we can do
(let ((!citation (plist-get (transient-scope) :citation))
      (!prefix (plist-get (transient-scope) :prefix))) ...)

It will be more readable.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
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: Fwd: Org-cite: Replace basic follow-processor with transient menu?

[Tor-björn Claesson]

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

Thank you for taking the time to look at this!

Ihor Radchenko <yantar92@posteo.net> writes:
>> +(defcustom org-cite-basic-follow-actions
>> +  '[["Open"
>> +     ("b" "bibliography entry" (org-cite-basic-goto !citation !prefix))]]
>> +  "Actions in the `org-cite-basic-follow' transient menu.
>> +
>> +This option uses the same syntax as `transient-define-prefix', see Info node
>> +`(transient)Binding Suffix and Infix Commands'.  In addition, it is possible 
>> +to specify a function call for the COMMAND part, where !citation and 
>> +!prefix can be used to access those values."
>> +  :group 'org-cite
>> +  :package-version '(Org . "9.8")
>> +  :type 'sexp)
>
> 1. Ideally, we want at least one more menu entry here. Otherwise, the
>    menu is not very useful.
> 2. It would be nice to provide some examples on using !citation and
>    !prefix in the docstring. Also, lambdas.
> 3. We need to explain what !citation and !prefix refer to.

1. The infrastructure is very useful in itself, but I have added an
option to add the DOI to the kill ring, it seems innocent enough. I had
first thought that I would like to, as a next step, add a helper
function to try really hard to get a citation key from a citation, but
lets go with this.

2 and 3. I tried to describe this in the new version of the patch.

>> +(defun org-cite-basic-follow--parse-suffix-specification (specification)
>> +  "Handle special syntax for `org-cite-basic-follow-actions'."
>> +  (pcase specification
>> +    (`(,key ,desc (lambda ,args . ,fn-args) . ,other)
>> +     `(,key ,desc
>> +            (lambda ,args
>> +              ,(unless (and (listp (car fn-args))
>> +                            (equal (caar fn-args)
>> +                                   'interactive))
>> +                 '(interactive))
>> +              (let ((!citation (car (transient-scope)))
>> +                    (!prefix (cadr (transient-scope))))
>
> This can be improved a bit.
> Rather than storing transient scope as (list citation prefix), we can
> use plist: (list :citation citation :prefix prefix). Then, we can do
> (let ((!citation (plist-get (transient-scope) :citation))
>       (!prefix (plist-get (transient-scope) :prefix))) ...)
>
> It will be more readable.
Neat! Thanks!

Please find attached version 4 of the patch.

Cheers,
Tor-björn


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: oc-basic transient follower version 4 --]
[-- Type: text/x-diff, Size: 8452 bytes --]

From c66af1e878f90e7b2cd89a613fc72da177cc6529 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tor-bj=C3=B6rn=20Claesson?= <torb@barbar.claesson.fi>
Date: Tue, 12 Nov 2024 11:09:16 +0200
Subject: [PATCH] lisp/oc-basic.el: Transient menu for following citations

* lisp/oc-basic.el (require 'transient): Pull in transient.
(require 'org-element): Pull in org-element.
(org-cite-basic-follow-ask): New customization option. should
`org-cite-basic-follow' prompt the user for an action?
(org-cite-basic-follow-actions): New customization option, that
specifies the contents of the transient menu.
(org-cite-basic-follow): New function.  Displays a menu asking how to
follow a citation if `org-cite-basic-follow-ask' is
non-nil. Otherwise, it retains the default behaviour of opening the
bibliography entry. This can be inversed with a negative prefix argument.
(org-cite-basic-follow--parse-suffix-specification and
org-cite-basic-follow--setup): Helper functions for
`org-cite-basic-follow'.
(org-cite-register-processor 'basic): Update the basic citation
processor to follow citations using `org-cite-basic-follow'.

* etc/ORG_NEWS (Menu for choosing how to follow citations): Describe
the new feature
(New option ~org-cite-basic-follow-ask~): Describe this new
customization option.
(New option ~org-cite-basic-follow-actions~): Describe this new
customization option, which specifies the layout of the
`org-cite-basic-follow' transient menu.

This change was co-authored with much support from Ihor Radchenko and
Jonas Bernoulli, thanks!
---
 etc/ORG-NEWS     |  22 +++++++++++
 lisp/oc-basic.el | 100 ++++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 121 insertions(+), 1 deletion(-)

diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index de4f11b25..bacc38be2 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -114,6 +114,15 @@ The keybindings in the repeat-maps can be changed by customizing
 
 See the new [[info:org#Repeating commands]["Repeating commands"]] section in Org mode manual.
 
+*** New transient menu when following citations
+
+Following citations with the org-cite-basic citation backend can now present a
+transient menu. To show this menu, set ~org-cite-basic-follow-ask~ to non-nil. 
+This behaviour can be reversed with a -4 prefix.
+
+The contents of this menu can be customized in
+~org-cite-basic-follow-actions~.
+
 ** New and changed options
 
 # Chanes deadling with changing default values of customizations,
@@ -158,6 +167,19 @@ English.  The default value is ~t~ as the CSL standard assumes that
 English titles are specified in sentence-case but the bibtex
 bibliography format requires them to be written in title-case.
 
+*** New option ~org-cite-basic-follow-ask~
+
+When this option is non-nil, following a citation with the basic citation
+backend will present a transient menu with choices for how to follow the
+citation.
+If nil, following a citation will open its bibliography entry.
+
+This behaviour can be reversed with a -4 prefix argument.
+
+*** New option ~org-cite-basic-follow-actions~
+
+This option specifies the options presented by ~org-cite-basic-follow~.
+
 ** New functions and changes in function arguments
 
 # This also includes changes in function behavior from Elisp perspective.
diff --git a/lisp/oc-basic.el b/lisp/oc-basic.el
index e207a1997..c42f95489 100644
--- a/lisp/oc-basic.el
+++ b/lisp/oc-basic.el
@@ -74,6 +74,8 @@
 (require 'map)
 (require 'oc)
 (require 'seq)
+(require 'transient)
+(require 'org-element)
 
 (declare-function org-open-at-point "org" (&optional arg))
 (declare-function org-open-file "org" (path &optional in-emacs line search))
@@ -140,6 +142,43 @@
   :type 'face
   :safe #'facep)
 
+(defcustom org-cite-basic-follow-ask nil
+  "Should `org-cite-basic' ask how to follow citations?
+
+When this option is nil, `org-cite-basic-follow' opens the bibliography entry. 
+Otherwise, `org-cite-basic-follow' will display a transient menu prompting the 
+user for an action.  The contents of this menu can be customized in 
+`org-cite-basic-follow-actions'."
+  :group 'org-cite
+  :package-version '(Org . "9.8")
+  :type 'boolean)
+
+(defcustom org-cite-basic-follow-actions
+  '[["Open"
+     ("b" "bibliography entry" (org-cite-basic-goto !citation !prefix))]
+    ["Copy"
+     ("d" "DOI"
+      (kill-new
+       (save-excursion
+         (with-temp-buffer
+           (mapc #'insert-file-contents org-cite-global-bibliography)
+           (bibtex-set-dialect (parsebib-find-bibtex-dialect) t)
+           (bibtex-search-entry (org-element-property :key !citation))
+           (setq doi (bibtex-autokey-get-field "doi"))
+           (replace-regexp-in-string "^http://dx.doi.org/" "" doi)))))]]
+  "Actions in the `org-cite-basic-follow' transient menu.
+
+This option uses the same syntax as `transient-define-prefix', see Info node
+`(transient)Binding Suffix and Infix Commands'.  In addition, it is possible 
+to specify a function call for the COMMAND part, where !citation (the citation
+object to be followed) and !prefix (any prefix argument to the follower) can be
+used to access those values. For example:
+(org-cite-basic-goto !citation !prefix) or
+(lambda () (message (org-element-property :key !citation)))"
+  :group 'org-cite
+  :package-version '(Org . "9.8")
+  :type 'sexp)
+
 \f
 ;;; Internal variables
 (defvar org-cite-basic--bibliography-cache nil
@@ -832,6 +871,65 @@ present in the citation."
        (bibtex-set-dialect)
        (bibtex-search-entry key)))))
 
+(transient-define-prefix org-cite-basic-follow (citation-object &optional prefix)
+  "Follow citation.
+
+If `org-cite-basic-follow-ask' is non-nil, this transient will present
+a menu prompting the user for an action. 
+Otherwise, it will open the bibliography entry for the citation at point.  
+This behaviour is inverted when the transient is called with a -4 prefix
+argument.
+
+The contents of the menu are defined in the variable
+`org-cite-basic-follow-actions'."
+  [:class transient-columns
+          :setup-children org-cite-basic-follow--setup
+          :pad-keys t]
+  (interactive
+    (list (let ((obj (org-element-context)))
+           (pcase (org-element-type obj)
+             ((or 'citation 'citation-reference) obj)
+             (_ (user-error "No citation at point"))))))
+  (if (xor org-cite-basic-follow-ask
+           (equal prefix '(-4)))
+      (transient-setup 'org-cite-basic-follow nil nil
+                       :scope (list :citation citation-object :prefix prefix))
+    (org-cite-basic-goto citation-object prefix)))
+
+(defun org-cite-basic-follow--parse-suffix-specification (specification)
+  "Handle special syntax for `org-cite-basic-follow-actions'."
+  (pcase specification
+    (`(,key ,desc (lambda ,args . ,fn-args) . ,other)
+     `(,key ,desc
+            (lambda ,args
+              ,(unless (and (listp (car fn-args))
+                            (equal (caar fn-args)
+                                   'interactive))
+                 '(interactive))
+              (let ((!citation (plist-get (transient-scope) :citation))
+                    (!prefix (plist-get (transient-scope) :prefix)))
+                ,@fn-args))
+            ,@other))
+    (`(,key ,desc (,fn . ,fn-args) . ,other)
+     `(,key ,desc
+            (lambda ()
+	      (interactive)
+              (let ((!citation (plist-get (transient-scope) :citation))
+                    (!prefix (plist-get (transient-scope) :prefix)))
+	        (,fn ,@fn-args)))
+            ,@other))
+    (other other)))
+
+(defun org-cite-basic-follow--setup (_)
+  "Update `org-cite-basic-follow' when `org-cite-basic-follow-actions' changes."
+  (transient-parse-suffixes
+   'org-cite-basic-follow
+   (cl-map 'vector
+           (lambda (group)
+             (cl-map 'vector #'org-cite-basic-follow--parse-suffix-specification
+                     group))
+           org-cite-basic-follow-actions)))
+
 \f
 ;;; "Insert" capability
 (defun org-cite-basic--complete-style (_)
@@ -920,7 +1018,7 @@ Raise an error when no bibliography is set in the buffer."
   :activate #'org-cite-basic-activate
   :export-citation #'org-cite-basic-export-citation
   :export-bibliography #'org-cite-basic-export-bibliography
-  :follow #'org-cite-basic-goto
+  :follow #'org-cite-basic-follow
   :insert (org-cite-make-insert-processor #'org-cite-basic--complete-key
                                           #'org-cite-basic--complete-style)
   :cite-styles
-- 
2.46.0

Re: Fwd: Org-cite: Replace basic follow-processor with transient menu?

[Ihor Radchenko]

Tor-björn Claesson <tclaesson@gmail.com> writes:

>> 1. Ideally, we want at least one more menu entry here. Otherwise, the
>>    menu is not very useful.
> ...
> 1. The infrastructure is very useful in itself, but I have added an
> option to add the DOI to the kill ring, it seems innocent enough. I had
> first thought that I would like to, as a next step, add a helper
> function to try really hard to get a citation key from a citation, but
> lets go with this.

Thanks!

> +(defcustom org-cite-basic-follow-actions
> +  '[["Open"
> +     ("b" "bibliography entry" (org-cite-basic-goto !citation !prefix))]
> +    ["Copy"
> +     ("d" "DOI"
> +      (kill-new
> +       (save-excursion
> +         (with-temp-buffer
> +           (mapc #'insert-file-contents org-cite-global-bibliography)
> +           (bibtex-set-dialect (parsebib-find-bibtex-dialect) t)
> +           (bibtex-search-entry (org-element-property :key !citation))
> +           (setq doi (bibtex-autokey-get-field "doi"))
> +           (replace-regexp-in-string "^http://dx.doi.org/" "" doi)))))]]
> +  "Actions in the `org-cite-basic-follow' transient menu.

Two comments here:
1. It should not be a lambda. Better have a function or even command
2. The logic is not right. You should better follow
   `org-cite-basic--key-completion-table':
   `org-cite-basic--parse-bibliography', `org-cite-basic--get-entry',
   and `org-cite-basic--get-field'.

-- 
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: Fwd: Org-cite: Replace basic follow-processor with transient menu?

[Tor-björn Claesson]

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

> Two comments here:
> 1. It should not be a lambda. Better have a function or even command
> 2. The logic is not right. You should better follow
>    `org-cite-basic--key-completion-table':
>    `org-cite-basic--parse-bibliography', `org-cite-basic--get-entry',
>    and `org-cite-basic--get-field'.

And this time with a patch, apologies.

/Tor-björn


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: Patch version 5 --]
[-- Type: text/x-diff, Size: 9808 bytes --]

From 7e9e0c64fbda2dcb67d8c8421d1c9923ca93e8b4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tor-bj=C3=B6rn=20Claesson?= <torb@barbar.claesson.fi>
Date: Tue, 12 Nov 2024 11:09:16 +0200
Subject: [PATCH] lisp/oc-basic.el: Transient menu for following citations

* lisp/oc-basic.el (require 'transient): Pull in transient.
(require 'org-element): Pull in org-element.
(org-cite-basic-follow-ask): New customization option. should
`org-cite-basic-follow' prompt the user for an action?
(org-cite-basic-follow-actions): New customization option, that
specifies the contents of the transient menu.
(org-cite-basic--get-key): New function. Get citation key from
citation or citation reference.
(org-cite-basic-follow): New function.  Displays a menu asking how to
follow a citation if `org-cite-basic-follow-ask' is
non-nil. Otherwise, it retains the default behaviour of opening the
bibliography entry. This can be inversed with a negative prefix argument.
(org-cite-basic-follow--parse-suffix-specification and
org-cite-basic-follow--setup): Helper functions for
`org-cite-basic-follow'.
(org-cite-register-processor 'basic): Update the basic citation
processor to follow citations using `org-cite-basic-follow'.

* etc/ORG_NEWS (Menu for choosing how to follow citations): Describe
the new feature
(New option ~org-cite-basic-follow-ask~): Describe this new
customization option.
(New option ~org-cite-basic-follow-actions~): Describe this new
customization option, which specifies the layout of the
`org-cite-basic-follow' transient menu.

This change was co-authored with much support from Ihor Radchenko and
Jonas Bernoulli, thanks!
---
 etc/ORG-NEWS     |  22 +++++++++
 lisp/oc-basic.el | 115 +++++++++++++++++++++++++++++++++++++++++++----
 2 files changed, 128 insertions(+), 9 deletions(-)

diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index de4f11b25..bacc38be2 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -114,6 +114,15 @@ The keybindings in the repeat-maps can be changed by customizing
 
 See the new [[info:org#Repeating commands]["Repeating commands"]] section in Org mode manual.
 
+*** New transient menu when following citations
+
+Following citations with the org-cite-basic citation backend can now present a
+transient menu. To show this menu, set ~org-cite-basic-follow-ask~ to non-nil. 
+This behaviour can be reversed with a -4 prefix.
+
+The contents of this menu can be customized in
+~org-cite-basic-follow-actions~.
+
 ** New and changed options
 
 # Chanes deadling with changing default values of customizations,
@@ -158,6 +167,19 @@ English.  The default value is ~t~ as the CSL standard assumes that
 English titles are specified in sentence-case but the bibtex
 bibliography format requires them to be written in title-case.
 
+*** New option ~org-cite-basic-follow-ask~
+
+When this option is non-nil, following a citation with the basic citation
+backend will present a transient menu with choices for how to follow the
+citation.
+If nil, following a citation will open its bibliography entry.
+
+This behaviour can be reversed with a -4 prefix argument.
+
+*** New option ~org-cite-basic-follow-actions~
+
+This option specifies the options presented by ~org-cite-basic-follow~.
+
 ** New functions and changes in function arguments
 
 # This also includes changes in function behavior from Elisp perspective.
diff --git a/lisp/oc-basic.el b/lisp/oc-basic.el
index e207a1997..fc55d3a32 100644
--- a/lisp/oc-basic.el
+++ b/lisp/oc-basic.el
@@ -74,6 +74,8 @@
 (require 'map)
 (require 'oc)
 (require 'seq)
+(require 'transient)
+(require 'org-element)
 
 (declare-function org-open-at-point "org" (&optional arg))
 (declare-function org-open-file "org" (path &optional in-emacs line search))
@@ -140,6 +142,39 @@
   :type 'face
   :safe #'facep)
 
+(defcustom org-cite-basic-follow-ask nil
+  "Should `org-cite-basic' ask how to follow citations?
+
+When this option is nil, `org-cite-basic-follow' opens the bibliography entry. 
+Otherwise, `org-cite-basic-follow' will display a transient menu prompting the 
+user for an action.  The contents of this menu can be customized in 
+`org-cite-basic-follow-actions'."
+  :group 'org-cite
+  :package-version '(Org . "9.8")
+  :type 'boolean)
+
+(defcustom org-cite-basic-follow-actions
+  '[["Open"
+     ("b" "bibliography entry" (org-cite-basic-goto !citation !prefix))]
+    ["Copy"
+     ("d" "DOI"
+      (kill-new
+       (org-cite-basic--get-field
+        'doi
+        (org-cite-basic--get-key !citation))))]]
+  "Actions in the `org-cite-basic-follow' transient menu.
+
+This option uses the same syntax as `transient-define-prefix', see Info node
+`(transient)Binding Suffix and Infix Commands'.  In addition, it is possible 
+to specify a function call for the COMMAND part, where !citation (the citation
+object to be followed) and !prefix (any prefix argument to the follower) can be
+used to access those values. For example:
+(org-cite-basic-goto !citation !prefix) or
+(lambda () (message (org-element-property :key !citation)))"
+  :group 'org-cite
+  :package-version '(Org . "9.8")
+  :type 'sexp)
+
 \f
 ;;; Internal variables
 (defvar org-cite-basic--bibliography-cache nil
@@ -326,6 +361,16 @@ INFO is the export state, as a property list."
                 (map-keys entries))
               (org-cite-basic--parse-bibliography)))
 
+(defun org-cite-basic--get-key (citation-or-citation-reference)
+  "Return citation key for CITATION."
+  (if (org-element-type-p citation-or-citation-reference 'citation-reference)
+      (org-element-property :key citation-or-citation-reference)
+    (pcase (org-cite-get-references citation-or-citation-reference t)
+      (`(,key) key)
+      (keys
+       (or (completing-read "Select citation key: " keys nil t)
+           (user-error "Aborted"))))))
+
 (defun org-cite-basic--get-entry (key &optional info)
   "Return BibTeX entry for KEY, as an association list.
 When non-nil, INFO is the export state, as a property list."
@@ -805,14 +850,7 @@ export state, as a property list."
 When DATUM is a citation reference, open bibliography entry referencing
 the citation key.  Otherwise, select which key to follow among all keys
 present in the citation."
-  (let* ((key
-          (if (org-element-type-p datum 'citation-reference)
-              (org-element-property :key datum)
-            (pcase (org-cite-get-references datum t)
-              (`(,key) key)
-              (keys
-               (or (completing-read "Select citation key: " keys nil t)
-                   (user-error "Aborted"))))))
+  (let* ((key (org-cite-basic--get-key datum))
          (file
           (pcase (seq-find (pcase-lambda (`(,_ . ,entries))
                              (gethash key entries))
@@ -832,6 +870,65 @@ present in the citation."
        (bibtex-set-dialect)
        (bibtex-search-entry key)))))
 
+(transient-define-prefix org-cite-basic-follow (citation-object &optional prefix)
+  "Follow citation.
+
+If `org-cite-basic-follow-ask' is non-nil, this transient will present
+a menu prompting the user for an action. 
+Otherwise, it will open the bibliography entry for the citation at point.  
+This behaviour is inverted when the transient is called with a -4 prefix
+argument.
+
+The contents of the menu are defined in the variable
+`org-cite-basic-follow-actions'."
+  [:class transient-columns
+          :setup-children org-cite-basic-follow--setup
+          :pad-keys t]
+  (interactive
+    (list (let ((obj (org-element-context)))
+           (pcase (org-element-type obj)
+             ((or 'citation 'citation-reference) obj)
+             (_ (user-error "No citation at point"))))))
+  (if (xor org-cite-basic-follow-ask
+           (equal prefix '(-4)))
+      (transient-setup 'org-cite-basic-follow nil nil
+                       :scope (list :citation citation-object :prefix prefix))
+    (org-cite-basic-goto citation-object prefix)))
+
+(defun org-cite-basic-follow--parse-suffix-specification (specification)
+  "Handle special syntax for `org-cite-basic-follow-actions'."
+  (pcase specification
+    (`(,key ,desc (lambda ,args . ,fn-args) . ,other)
+     `(,key ,desc
+            (lambda ,args
+              ,(unless (and (listp (car fn-args))
+                            (equal (caar fn-args)
+                                   'interactive))
+                 '(interactive))
+              (let ((!citation (plist-get (transient-scope) :citation))
+                    (!prefix (plist-get (transient-scope) :prefix)))
+                ,@fn-args))
+            ,@other))
+    (`(,key ,desc (,fn . ,fn-args) . ,other)
+     `(,key ,desc
+            (lambda ()
+	      (interactive)
+              (let ((!citation (plist-get (transient-scope) :citation))
+                    (!prefix (plist-get (transient-scope) :prefix)))
+	        (,fn ,@fn-args)))
+            ,@other))
+    (other other)))
+
+(defun org-cite-basic-follow--setup (_)
+  "Update `org-cite-basic-follow' when `org-cite-basic-follow-actions' changes."
+  (transient-parse-suffixes
+   'org-cite-basic-follow
+   (cl-map 'vector
+           (lambda (group)
+             (cl-map 'vector #'org-cite-basic-follow--parse-suffix-specification
+                     group))
+           org-cite-basic-follow-actions)))
+
 \f
 ;;; "Insert" capability
 (defun org-cite-basic--complete-style (_)
@@ -920,7 +1017,7 @@ Raise an error when no bibliography is set in the buffer."
   :activate #'org-cite-basic-activate
   :export-citation #'org-cite-basic-export-citation
   :export-bibliography #'org-cite-basic-export-bibliography
-  :follow #'org-cite-basic-goto
+  :follow #'org-cite-basic-follow
   :insert (org-cite-make-insert-processor #'org-cite-basic--complete-key
                                           #'org-cite-basic--complete-style)
   :cite-styles
-- 
2.46.0

[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]

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.

Dear all,

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

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

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.

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.

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**

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

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
- 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.

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

Tor-björn Claesson <tclaesson@gmail.com> writes:

> From 7e9e0c64fbda2dcb67d8c8421d1c9923ca93e8b4 Mon Sep 17 00:00:00 2001
> From: =?UTF-8?q?Tor-bj=C3=B6rn=20Claesson?= <torb@barbar.claesson.fi>
> Date: Tue, 12 Nov 2024 11:09:16 +0200
> Subject: [PATCH] lisp/oc-basic.el: Transient menu for following citations
>
> * lisp/oc-basic.el (require 'transient): Pull in transient.
> (require 'org-element): Pull in org-element.
> (org-cite-basic-follow-ask): New customization option. should
> `org-cite-basic-follow' prompt the user for an action?
> (org-cite-basic-follow-actions): New customization option, that
> specifies the contents of the transient menu.
> (org-cite-basic--get-key): New function. Get citation key from
> citation or citation reference.
> (org-cite-basic-follow): New function.  Displays a menu asking how to
> follow a citation if `org-cite-basic-follow-ask' is
> non-nil. Otherwise, it retains the default behaviour of opening the
> bibliography entry. This can be inversed with a negative prefix argument.
> (org-cite-basic-follow--parse-suffix-specification and
> org-cite-basic-follow--setup): Helper functions for
> `org-cite-basic-follow'.
> (org-cite-register-processor 'basic): Update the basic citation
> processor to follow citations using `org-cite-basic-follow'.
>
> * etc/ORG_NEWS (Menu for choosing how to follow citations): Describe
> the new feature
> (New option ~org-cite-basic-follow-ask~): Describe this new
> customization option.
> (New option ~org-cite-basic-follow-actions~): Describe this new
> customization option, which specifies the layout of the
> `org-cite-basic-follow' transient menu.
>
> This change was co-authored with much support from Ihor Radchenko and
> Jonas Bernoulli, thanks!
> ---
>  etc/ORG-NEWS     |  22 +++++++++
>  lisp/oc-basic.el | 115 +++++++++++++++++++++++++++++++++++++++++++----
>  2 files changed, 128 insertions(+), 9 deletions(-)
>
> diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
> index de4f11b25..bacc38be2 100644
> --- a/etc/ORG-NEWS
> +++ b/etc/ORG-NEWS
> @@ -114,6 +114,15 @@ The keybindings in the repeat-maps can be changed by customizing
>  
>  See the new [[info:org#Repeating commands]["Repeating commands"]] section in Org mode manual.
>  
> +*** New transient menu when following citations
> +
> +Following citations with the org-cite-basic citation backend can now present a
> +transient menu. To show this menu, set ~org-cite-basic-follow-ask~ to non-nil. 
> +This behaviour can be reversed with a -4 prefix.
> +
> +The contents of this menu can be customized in
> +~org-cite-basic-follow-actions~.
> +
>  ** New and changed options
>  
>  # Chanes deadling with changing default values of customizations,
> @@ -158,6 +167,19 @@ English.  The default value is ~t~ as the CSL standard assumes that
>  English titles are specified in sentence-case but the bibtex
>  bibliography format requires them to be written in title-case.
>  
> +*** New option ~org-cite-basic-follow-ask~
> +
> +When this option is non-nil, following a citation with the basic citation
> +backend will present a transient menu with choices for how to follow the
> +citation.
> +If nil, following a citation will open its bibliography entry.
> +
> +This behaviour can be reversed with a -4 prefix argument.
> +
> +*** New option ~org-cite-basic-follow-actions~
> +
> +This option specifies the options presented by ~org-cite-basic-follow~.
> +
>  ** New functions and changes in function arguments
>  
>  # This also includes changes in function behavior from Elisp perspective.
> diff --git a/lisp/oc-basic.el b/lisp/oc-basic.el
> index e207a1997..fc55d3a32 100644
> --- a/lisp/oc-basic.el
> +++ b/lisp/oc-basic.el
> @@ -74,6 +74,8 @@
>  (require 'map)
>  (require 'oc)
>  (require 'seq)
> +(require 'transient)
> +(require 'org-element)
>  
>  (declare-function org-open-at-point "org" (&optional arg))
>  (declare-function org-open-file "org" (path &optional in-emacs line search))
> @@ -140,6 +142,39 @@
>    :type 'face
>    :safe #'facep)
>  
> +(defcustom org-cite-basic-follow-ask nil
> +  "Should `org-cite-basic' ask how to follow citations?
> +
> +When this option is nil, `org-cite-basic-follow' opens the bibliography entry. 
> +Otherwise, `org-cite-basic-follow' will display a transient menu prompting the 
> +user for an action.  The contents of this menu can be customized in 
> +`org-cite-basic-follow-actions'."
> +  :group 'org-cite
> +  :package-version '(Org . "9.8")
> +  :type 'boolean)
> +
> +(defcustom org-cite-basic-follow-actions
> +  '[["Open"
> +     ("b" "bibliography entry" (org-cite-basic-goto !citation !prefix))]
> +    ["Copy"
> +     ("d" "DOI"
> +      (kill-new
> +       (org-cite-basic--get-field
> +        'doi
> +        (org-cite-basic--get-key !citation))))]]
> +  "Actions in the `org-cite-basic-follow' transient menu.
> +
> +This option uses the same syntax as `transient-define-prefix', see Info node
> +`(transient)Binding Suffix and Infix Commands'.  In addition, it is possible 
> +to specify a function call for the COMMAND part, where !citation (the citation
> +object to be followed) and !prefix (any prefix argument to the follower) can be
> +used to access those values. For example:
> +(org-cite-basic-goto !citation !prefix) or
> +(lambda () (message (org-element-property :key !citation)))"
> +  :group 'org-cite
> +  :package-version '(Org . "9.8")
> +  :type 'sexp)
> +
>  \f
>  ;;; Internal variables
>  (defvar org-cite-basic--bibliography-cache nil
> @@ -326,6 +361,16 @@ INFO is the export state, as a property list."
>                  (map-keys entries))
>                (org-cite-basic--parse-bibliography)))
>  
> +(defun org-cite-basic--get-key (citation-or-citation-reference)
> +  "Return citation key for CITATION."
> +  (if (org-element-type-p citation-or-citation-reference 'citation-reference)
> +      (org-element-property :key citation-or-citation-reference)
> +    (pcase (org-cite-get-references citation-or-citation-reference t)
> +      (`(,key) key)
> +      (keys
> +       (or (completing-read "Select citation key: " keys nil t)
> +           (user-error "Aborted"))))))
> +
>  (defun org-cite-basic--get-entry (key &optional info)
>    "Return BibTeX entry for KEY, as an association list.
>  When non-nil, INFO is the export state, as a property list."
> @@ -805,14 +850,7 @@ export state, as a property list."
>  When DATUM is a citation reference, open bibliography entry referencing
>  the citation key.  Otherwise, select which key to follow among all keys
>  present in the citation."
> -  (let* ((key
> -          (if (org-element-type-p datum 'citation-reference)
> -              (org-element-property :key datum)
> -            (pcase (org-cite-get-references datum t)
> -              (`(,key) key)
> -              (keys
> -               (or (completing-read "Select citation key: " keys nil t)
> -                   (user-error "Aborted"))))))
> +  (let* ((key (org-cite-basic--get-key datum))
>           (file
>            (pcase (seq-find (pcase-lambda (`(,_ . ,entries))
>                               (gethash key entries))
> @@ -832,6 +870,65 @@ present in the citation."
>         (bibtex-set-dialect)
>         (bibtex-search-entry key)))))
>  
> +(transient-define-prefix org-cite-basic-follow (citation-object &optional prefix)
> +  "Follow citation.
> +
> +If `org-cite-basic-follow-ask' is non-nil, this transient will present
> +a menu prompting the user for an action. 
> +Otherwise, it will open the bibliography entry for the citation at point.  
> +This behaviour is inverted when the transient is called with a -4 prefix
> +argument.
> +
> +The contents of the menu are defined in the variable
> +`org-cite-basic-follow-actions'."
> +  [:class transient-columns
> +          :setup-children org-cite-basic-follow--setup
> +          :pad-keys t]
> +  (interactive
> +    (list (let ((obj (org-element-context)))
> +           (pcase (org-element-type obj)
> +             ((or 'citation 'citation-reference) obj)
> +             (_ (user-error "No citation at point"))))))
> +  (if (xor org-cite-basic-follow-ask
> +           (equal prefix '(-4)))
> +      (transient-setup 'org-cite-basic-follow nil nil
> +                       :scope (list :citation citation-object :prefix prefix))
> +    (org-cite-basic-goto citation-object prefix)))
> +
> +(defun org-cite-basic-follow--parse-suffix-specification (specification)
> +  "Handle special syntax for `org-cite-basic-follow-actions'."
> +  (pcase specification
> +    (`(,key ,desc (lambda ,args . ,fn-args) . ,other)
> +     `(,key ,desc
> +            (lambda ,args
> +              ,(unless (and (listp (car fn-args))
> +                            (equal (caar fn-args)
> +                                   'interactive))
> +                 '(interactive))
> +              (let ((!citation (plist-get (transient-scope) :citation))
> +                    (!prefix (plist-get (transient-scope) :prefix)))
> +                ,@fn-args))
> +            ,@other))
> +    (`(,key ,desc (,fn . ,fn-args) . ,other)
> +     `(,key ,desc
> +            (lambda ()
> +	      (interactive)
> +              (let ((!citation (plist-get (transient-scope) :citation))
> +                    (!prefix (plist-get (transient-scope) :prefix)))
> +	        (,fn ,@fn-args)))
> +            ,@other))
> +    (other other)))
> +
> +(defun org-cite-basic-follow--setup (_)
> +  "Update `org-cite-basic-follow' when `org-cite-basic-follow-actions' changes."
> +  (transient-parse-suffixes
> +   'org-cite-basic-follow
> +   (cl-map 'vector
> +           (lambda (group)
> +             (cl-map 'vector #'org-cite-basic-follow--parse-suffix-specification
> +                     group))
> +           org-cite-basic-follow-actions)))
> +
>  \f
>  ;;; "Insert" capability
>  (defun org-cite-basic--complete-style (_)
> @@ -920,7 +1017,7 @@ Raise an error when no bibliography is set in the buffer."
>    :activate #'org-cite-basic-activate
>    :export-citation #'org-cite-basic-export-citation
>    :export-bibliography #'org-cite-basic-export-bibliography
> -  :follow #'org-cite-basic-goto
> +  :follow #'org-cite-basic-follow
>    :insert (org-cite-make-insert-processor #'org-cite-basic--complete-key
>                                            #'org-cite-basic--complete-style)
>    :cite-styles
> -- 
> 2.46.0
>

-- 
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? (was: Fwd: Org-cite: Replace basic follow-processor with transient menu?)

[Panayotis Manganaris]

Hello. I'm very much an elisp amateur, but one of my main motives for
learning has been to make use of emacs' many beautiful UI systems.

Therefore, I'll provide my comments from a designer perspective and
avoid implementation detail.

Ihor Radchenko <yantar92@posteo.net> writes:

> TL;DR: We are in the process of designing a more unified selection
> interface for Org mode

Thanks to Tor-björn, Jonas, Ihor, and everyone else for this work. I've
learned much by following this thread.

> a number of people raised concerns that transient may sometimes be an
> overkill

I agree with others that transient is overkill for most of the menus in
org-mode. A counter argument, going by the patches exchanged here, might
be that transient menus are a clean and scalable approach.

I've not tried the in-dev transient follow processor, but I imagine it
is similar to the old org-ref (John Kitchin) hydra menu. I used org-ref
for years, and enjoyed how its menu united many features, including
- a system analogous to org-cite follow processors for navigating to sources/notes
- a system akin to reftex-mode for org
- a system for downloading new references and making new bibliography entries

With this level of complexity, a transient menu seems like the modern
weapon of choice for a similar feature set. Only, wait, I stopped using
org-ref.

Long story short, I concluded that treating org-mode like a nexus for
these intertwined features was, at least, encouraging my bad habit of
treating org-mode as an "everything app."

I have since delegated the task of populating my personal library to a
dedicated reference manager. I started using latex-mode and reftex to
write papers, thus gaining more typesetting control and making version
management much easier. I still use org to take notes, but now enjoy a
much more stable and focused configuration.

I tell this story as an (anecdotal) case study for how a powerful menu
can be less productive in the long run. Org-ref's hydra menu is not to
blame for my bad decisions but, at least in-part, I used it (and even
extended it) because a greater man put it there.

Scalable design is an invitation to scale. Perhaps the wise know better.
Anyway, the simple tasks of navigating from a citation link to a copy of
the original document, its URL, or an associated note is achievable with
a completing-read (helm, counsel, vertico, etc.) interface.

Transient is overkill.

> This UI flow can be implemented using context menus [...] embark

I like org's context menus, but I like embark better. I do think it
would be very generous of org to delegate its own contextual actions to
embark if so configured.

I'll elaborate:

As is, I like to run org-babel code block functions through embark, I
only wish there were more of them to run. I find this to be far superior
in every way to binding equivalent key chords for the mode.

Also, for me, embark-bindings and embark-prefix-help-command have
completely replaced which-key for discovering key bindings on-the-fly.

> 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 support this idea in principle.

> 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.

I would focus on associating just enough metadata with functions to
enable using them with embark. I really have no idea what the best way
to do this is. This seems to be the biggest missing piece.

Maybe in the short term we just crowd-source some embark configuration
on WORG.

Menus should of course be useful without embark. If the goal here is to
deprecate many of org's ad-hoc interfaces, I think the natural default
replacement for most is completing-read. I may be completely wrong.

> 2. Menu interface to use (transient, context-menu, embark, which-key)

It seems like Tor-björn and Ihor have already laid the groundwork for
using transient in this way. So, I'll just say bravo. Regardless of my
opinion on transient overuse, it looks like great work.

On the other hand, e.g. if the org export dispatch menu isn't transient,
it should be. Seems obvious to me.

> 3. Layout settings for the specific interfaces. For example, transient
>    layout definition.

It is important to avoid making more org-mode-specific UI abstractions.
Whatever the solution, it is important that the UI implementations
tapped to take over help share the maintenance burden.

In this way, I reckon most interface customization can be done in hooks.

> WDYT?

Ideally org-mode uses established APIs rather than making another.

Thanks for reading, and thanks for the chance to contribute.

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]

Panayotis Manganaris <panos.manganaris@gmail.com> writes:

> Menus should of course be useful without embark. If the goal here is to
> deprecate many of org's ad-hoc interfaces, I think the natural default
> replacement for most is completing-read. I may be completely wrong.

For the existing interfaces, we are not going to change things in
incompatible ways. The idea is to keep the existing menus working as
similarly as possible compared to the current ad-hoc menus.
So, no, we are not going to replace things with completing-read.
Not by default.

But what I hope to see is a way for users to customize the UI to their
preference. Without touching the defaults.

> On the other hand, e.g. if the org export dispatch menu isn't transient,
> it should be. Seems obvious to me.

Yes. That's where we will have to use transient.
This discussion mostly concerns simpler cases when user needs to choose
from a list.

-- 
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? (was: Fwd: Org-cite: Replace basic follow-processor with transient menu?)

[Samuel Wales]

a couple of quick and somewhat obvious comments.  i use VERY large
fonts with a maximized gui emacs [vt / maximized urxvt  when needed],
still resulting in, throughout emacs, often, a smaller number of
screen lines or columns than content, even with my usual one window
per frame.  most org menus respect this and can be scrolled or
tweaked.  just wanted compatibility to be in the specs.  especially,
to make sure no functionality is unreachable, but also where possible
to modify column numbers / fill to look ok.  i am slowly trying
transient in gptel and still getting used to it.

next, i use org-mouse and think it's wonderful.  generally, when using
a computer, i use mouse-only or kb-only, but not the combination.
mouseability was mentioned, but just wanted, where possible, the
ability to do most things using only mouse in addition to only kb.
and, where possible, org-mouse compatibility or replacement, whichever
is deemed best.

On Sat, Dec 14, 2024 at 3:08 AM Ihor Radchenko <yantar92@posteo.net> wrote:
>
> Panayotis Manganaris <panos.manganaris@gmail.com> writes:
>
> > Menus should of course be useful without embark. If the goal here is to
> > deprecate many of org's ad-hoc interfaces, I think the natural default
> > replacement for most is completing-read. I may be completely wrong.
>
> For the existing interfaces, we are not going to change things in
> incompatible ways. The idea is to keep the existing menus working as
> similarly as possible compared to the current ad-hoc menus.
> So, no, we are not going to replace things with completing-read.
> Not by default.
>
> But what I hope to see is a way for users to customize the UI to their
> preference. Without touching the defaults.
>
> > On the other hand, e.g. if the org export dispatch menu isn't transient,
> > it should be. Seems obvious to me.
>
> Yes. That's where we will have to use transient.
> This discussion mostly concerns simpler cases when user needs to choose
> from a list.
>
> --
> 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>
>


-- 
The Kafka Pandemic

A blog about science, health, human rights, and misopathy:
https://thekafkapandemic.blogspot.com

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]

Samuel Wales <samologist@gmail.com> writes:

> a couple of quick and somewhat obvious comments.  i use VERY large
> fonts with a maximized gui emacs [vt / maximized urxvt  when needed],
> still resulting in, throughout emacs, often, a smaller number of
> screen lines or columns than content, even with my usual one window
> per frame.  most org menus respect this and can be scrolled or
> tweaked.  just wanted compatibility to be in the specs.  especially,
> to make sure no functionality is unreachable, but also where possible
> to modify column numbers / fill to look ok.  i am slowly trying
> transient in gptel and still getting used to it.

Thanks for the important input!
Does transient look fine on your screen? If yes, we should not have a
problem.

-- 
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? (was: Fwd: Org-cite: Replace basic follow-processor with transient menu?)

[Samuel Wales]

thanks for interest.

the transient menu i am trying uses more character columns and
lines than window (c-u m-x gptel-send).  transient's solution
does not work well for me.

1) wrapping
   - 3 text columns.  rightmost text column (header: "Response
     to") has lines that wrap at rhs (not word) to lhs (not
     beginning of that text column), putting lines between items
     in first text column.
   - (for clarity: by rhs and lhs, i mean where text goes, at
     smallest usable font, maximized gui frame, no wm
     decoration, one window in frame, 2 fringes)
   - BEST SOLUTION FOR ME: wrap at word boundaries, /within each
     text column/, as is done when one exports org tables to
     html
2) vertical scrolling
   - BEST SOLUTION FOR ME: SPC DEL, as is done in org export
     menu
     - in transient, SPC and DEL make echo area say ? for help.
       ? makes the message go away but nothing else changes.
       another ?  brings up the help for function gptel-send.
       i'd want scrolling.
     - transient is vertically scrollable using up down arrows
       and c-v m-v, but those are harder on rsi and harder to
       locate on my kb than SPC DEL
   - i did not notice that there are lines below window.  if
     there isn't an indicator, BEST LOCATION FOR ME: left fringe
     in cases where fringe exists.
3) transient does not allow changing font size with
   text-scale-increase/decrease (but a smaller font would not be
   legible)


- transient:
    - Archive: gnu
    - Version: 0.8.1
    - dependency issue before explicitly installing this version.

- emacs    29.4
- org    9.7.16
- gptel    ~/.emacs.d/elpa/gptel-0.9.6.0.20241115.83706


some current org menus, although REALLY GOOD, have possibly
regressed in recent years.  in any case, for example, export is
scrollable; todo kw is not, so i cannot access some todo kw.

i put a lot of effort into this response, hope it makes sense.


On Mon, Dec 16, 2024 at 10:52 AM Ihor Radchenko <yantar92@posteo.net> wrote:
>
> Samuel Wales <samologist@gmail.com> writes:
>
> > a couple of quick and somewhat obvious comments.  i use VERY large
> > fonts with a maximized gui emacs [vt / maximized urxvt  when needed],
> > still resulting in, throughout emacs, often, a smaller number of
> > screen lines or columns than content, even with my usual one window
> > per frame.  most org menus respect this and can be scrolled or
> > tweaked.  just wanted compatibility to be in the specs.  especially,
> > to make sure no functionality is unreachable, but also where possible
> > to modify column numbers / fill to look ok.  i am slowly trying
> > transient in gptel and still getting used to it.
>
> Thanks for the important input!
> Does transient look fine on your screen? If yes, we should not have a
> problem.
>
> --
> 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>



--
The Kafka Pandemic

A blog about science, health, human rights, and misopathy:
https://thekafkapandemic.blogspot.com

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

[Samuel Wales]

thanks for interest.

the transient menu i am trying uses more character columns and
lines than window (c-u m-x gptel-send).  transient's solution
does not work well for me.

1) wrapping
   - 3 text columns.  rightmost text column (header: "Response
     to") has lines that wrap at rhs (not word) to lhs (not
     beginning of that text column), putting lines between items
     in first text column.
   - (for clarity: by rhs and lhs, i mean where text goes, at
     smallest usable font, maximized gui frame, no wm
     decoration, one window in frame, 2 fringes)
   - BEST SOLUTION FOR ME: wrap at word boundaries, /within each
     text column/, as is done when one exports org tables to
     html
2) vertical scrolling
   - BEST SOLUTION FOR ME: SPC DEL, as is done in org export
     menu
     - in transient, SPC and DEL make echo area say ? for help.
       ? makes the message go away but nothing else changes.
       another ?  brings up the help for function gptel-send.
       i'd want scrolling.
     - transient is vertically scrollable using up down arrows
       and c-v m-v, but those are harder on rsi and harder to
       locate on my kb than SPC DEL
   - i did not notice that there are lines below window.  if
     there isn't an indicator, BEST LOCATION FOR ME: left fringe
     in cases where fringe exists.
3) transient does not allow changing font size with
   text-scale-increase/decrease (but a smaller font would not be
   legible)


- transient:
    - Archive: gnu
    - Version: 0.8.1
    - dependency issue before explicitly installing this version.

- emacs    29.4
- org    9.7.16
- gptel    ~/.emacs.d/elpa/gptel-0.9.6.0.
20241115.83706


some current org menus, although REALLY GOOD, have possibly
regressed in recent years.  in any case, for example, export is
scrollable; todo kw is not, so i cannot access some todo kw.

i put a lot of effort into this response, hope it makes sense.


[p.s.  attempting re-send as reply to all as my first response went to
ihor only.  i hope this is not too jarring as a top post and sent to
all recipients.  idk which recipients are included 1] because others
included them easrlier in the thread/conversation vs. 2] because they
are not on the emacs devel list or the org list an want copies.]

[p.p.s. this webmail ui drives me nuts and some solecisms are due to
it being inaccessible [e.g. no compose button showing, not clear how
to change subject header.]

> On Mon, Dec 16, 2024 at 10:52 AM Ihor Radchenko <yantar92@posteo.net> wrote:
> >
> > Samuel Wales <samologist@gmail.com> writes:
> >
> > > a couple of quick and somewhat obvious comments.  i use VERY large
> > > fonts with a maximized gui emacs [vt / maximized urxvt  when needed],
> > > still resulting in, throughout emacs, often, a smaller number of
> > > screen lines or columns than content, even with my usual one window
> > > per frame.  most org menus respect this and can be scrolled or
> > > tweaked.  just wanted compatibility to be in the specs.  especially,
> > > to make sure no functionality is unreachable, but also where possible
> > > to modify column numbers / fill to look ok.  i am slowly trying
> > > transient in gptel and still getting used to it.
> >
> > Thanks for the important input!
> > Does transient look fine on your screen? If yes, we should not have a
> > problem.
> >
> > --
> > 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>
>
>
>
> --
> The Kafka Pandemic
>
> A blog about science, health, human rights, and misopathy:
> https://thekafkapandemic.blogspot.com



-- 
The Kafka Pandemic

A blog about science, health, human rights, and misopathy:
https://thekafkapandemic.blogspot.com

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

[Jonas Bernoulli]

Hello!


Samuel Wales <samologist@gmail.com> writes:

> thanks for interest.

I've worked with other users with impaired vision to improve their
experience with Transient before and tend to prioritize that work.

That being said, the end-of-year crunch is upon us, so I likely won't
find the time to do anything beyond what I have already done today.

You should update Transient to the development version.  I found two
regressions affecting the features described below and fixed them this
morning.  These fixes will make it into the next release, scheduled for
very early 2025.

> the transient menu i am trying uses more character columns and
> lines than window (c-u m-x gptel-send).

I didn't notice that you effectively said "too small in both
dimensions", so the first advice below, might not be as useful as I
initially though.  Or it might, let's see.

> transient's solution does not work well for me.
>
> 1) wrapping
>    - 3 text columns.

You can tell Transient to only ever use a single column, and
additionally you can always display the menu in a new window on the
right instead of at the bottom.

(setq transient-force-single-column t)
(setq transient-display-buffer-action
      '(display-buffer-in-side-window
        (side . right)
        (dedicated . t)
        (inhibit-same-window . t)))

>                       rightmost text column (header: "Response
>      to") has lines that wrap at rhs (not word) to lhs (not
>      beginning of that text column), putting lines between items
>      in first text column.
>    - (for clarity: by rhs and lhs, i mean where text goes, at
>      smallest usable font, maximized gui frame, no wm
>      decoration, one window in frame, 2 fringes)
>    - BEST SOLUTION FOR ME: wrap at word boundaries, /within each
>      text column/, as is done when one exports org tables to
>      html
> 2) vertical scrolling
>    - BEST SOLUTION FOR ME: SPC DEL, as is done in org export
>      menu
>      - in transient, SPC and DEL make echo area say ? for help.
>        ? makes the message go away but nothing else changes.
>        another ?  brings up the help for function gptel-send.
>        i'd want scrolling.
>      - transient is vertically scrollable using up down arrows
>        and c-v m-v, but those are harder on rsi and harder to
>        locate on my kb than SPC DEL

You can add your preferred bindings like so:

  (keymap-set transient-map "SPC" #'transient-scroll-up)
  (keymap-set transient-map "DEL" #'transient-scroll-down)

Some Transient menus to *not* prevent commands from other keymaps to
be invoked while the menu is active.  If you bind "SPC" in all menus
as shown above, then that will shadow the regular binding, making it
hard to insert a space.

[However, I'll have to deeply think about the bindings used for commands
available in all transient menus in general soon, but this is not the
time and place.]

[I'll likely also have to support horizontal scrolling eventually.]

>    - i did not notice that there are lines below window.  if
>      there isn't an indicator, BEST LOCATION FOR ME: left fringe
>      in cases where fringe exists.

This enters "I'll look into that next year" territory.

The color of that line actually indicates whether a menu allows
"outside" commands to be invoked while the menu is active.

Most users don't notice this piece of information, myself included.
You can hide it, if you wish, using:

  (setq transient-mode-line-format nil)

> 3) transient does not allow changing font size with
>    text-scale-increase/decrease (but a smaller font would not be
>    legible)

To permanently use a different font size in transient menus use:

  (defun transient-i-shrunk-the-glyphs ()
    (text-scale-set -1)) ; or 1 to grow

  (add-hook 'transient-setup-buffer-hook #'transient-i-shrunk-the-glyphs)

To allow changing the size on demand, use something like:

  (defun transient-text-scale-increase (inc)
    (interactive "p")
    (with-current-buffer transient--buffer
      (text-scale-increase inc)))

  (defun transient-text-scale-decrease (dec)
    (interactive "p")
    (with-current-buffer transient--buffer
      (text-scale-decrease dec)))

  (keymap-set transient-map "C-x +" #'transient-text-scale-increase)
  (keymap-set transient-map "C-x -" #'transient-text-scale-decrease)
  (keymap-set transient-predicate-map "<transient-text-scale-increase>"
              #'transient--do-call)
  (keymap-set transient-predicate-map "<transient-text-scale-decrease>"
              #'transient--do-call)

You could also remember the size between menu invocations:

  (defvar transient-text-scale-amount 0)

  (transient-define-suffix transient-text-scale-increase (inc)
    :transient t
    (interactive "p")
    (with-current-buffer transient--buffer
      (text-scale-increase inc)
      (setq transient-text-scale-amount text-scale-mode-amount)))

  (transient-define-suffix transient-text-scale-decrease (inc)
    :transient t
    (interactive "p")
    (with-current-buffer transient--buffer
      (text-scale-decrease dec)
      (setq transient-text-scale-amount text-scale-mode-amount)))

  (keymap-set transient-map "C-x +" #'transient-text-scale-increase)
  (keymap-set transient-map "C-x -" #'transient-text-scale-decrease)

  (defun transient-restore-text-scale ()
    (unless (local-variable-p 'text-scale-mode-amount)
      (text-scale-set transient-text-scale-amount)))

I might make a refinement of one of these variants available by default,
but that will require some more though, which I don't have the time for
until next year.

     Cheers,
     Jonas


> - transient:
>     - Archive: gnu
>     - Version: 0.8.1
>     - dependency issue before explicitly installing this version.
>
> - emacs    29.4
> - org    9.7.16
> - gptel    ~/.emacs.d/elpa/gptel-0.9.6.0.20241115.83706
>
>
> some current org menus, although REALLY GOOD, have possibly
> regressed in recent years.  in any case, for example, export is
> scrollable; todo kw is not, so i cannot access some todo kw.
>
> i put a lot of effort into this response, hope it makes sense.
>
>
> On Mon, Dec 16, 2024 at 10:52 AM Ihor Radchenko <yantar92@posteo.net> wrote:
>>
>> Samuel Wales <samologist@gmail.com> writes:
>>
>> > a couple of quick and somewhat obvious comments.  i use VERY large
>> > fonts with a maximized gui emacs [vt / maximized urxvt  when needed],
>> > still resulting in, throughout emacs, often, a smaller number of
>> > screen lines or columns than content, even with my usual one window
>> > per frame.  most org menus respect this and can be scrolled or
>> > tweaked.  just wanted compatibility to be in the specs.  especially,
>> > to make sure no functionality is unreachable, but also where possible
>> > to modify column numbers / fill to look ok.  i am slowly trying
>> > transient in gptel and still getting used to it.
>>
>> Thanks for the important input!
>> Does transient look fine on your screen? If yes, we should not have a
>> problem.
>>
>> --
>> 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>
>
>
>
> --
> The Kafka Pandemic
>
> A blog about science, health, human rights, and misopathy:
> https://thekafkapandemic.blogspot.com