Clarify distinction between actions on keys vs on citations (lists of keys)

[bdarcus]

I really need feedback from people playing with org-cite, as this question not only relates to fixing the bug in #199, but has far-reaching implications.

Right now, at-point functionality supports both a single reference, and a list of references; actually, all the action commands do.

In practical terms, that means if point is on a multi-key org-cite citation (within "cite" for example), and you run org-open-at-point, we pass a list of keys to the action.

But is this wise? Consider two options:

1. current behavior; the keys of all include references are passed to the commands (as happens now in the minibuffer, BTW)
2. you are first prompted which key to run the action on, before seeing the above menu of actions

Other org-cite implementations do 2; see, for example, org-ref-cite-follow.

If we change to 2, it would involve removing, for example, this:

https://github.com/bdarcus/bibtex-actions/blob/4c6aa3612da91e9de27687bb2a7aeb4999ca84f5/bibtex-actions.el#L435-L436

Either way, this function should be moved to oc-bibtex-actions.

I can see arguments for both approaches, though lean towards changing to 2, because it simplifies this code, and also aligns it with org-ref-cite-follow.

But I can also see arguments for, maybe even prefer, a third option: it working as a list for some commands, and not for others.

Here's my thoughts on this path, which also may clarify the pros and cons of different approaches more generally.

Let's consider three cases:

1. MUST allow a list
2. Probably SHOULD allow a list
3. Probably SHOULD NOT allow a list

Here's what it's in the at-point keymap for embark:

• org-cite-insert: 1 (because these processors are context-aware, and present different UIs depending on where point is)
• bibtex-actions-open: 2
• bibtex-actions-open-entry: 3 (because usually the entries are in the same file)
• bibtex-actions-open-link: 2
• bibtex-actions-open-notes: 2 (this is complicated though, since notes can be single-file, or multi)
• bibtex-actions-open-pdf: 2

Note: I plan to look into adding other actions from org-ref-cite soon, so would be good to clarify this now.

See also #161.

WDYT @oatmealm @ilupin @titaniumbones @mclearc @salutis

Originally posted by @bdarcus in #199 (comment)

[bdarcus]

Here's the commit that implements 1 above.

da414df

[rudolf-adamkovic]

I wonder, when will org-cite come to Emacs' master branch?

[bdarcus]

It's already there ;-)

https://blog.tecosaur.com/tmio/2021-07-31-citations.html

[mclearc]

I haven't any really strong feelings about this, since my workflow doesn't really depend on it. I would think there is some benefit to changing to 2, since (i) simplification of code is almost always a net good, and (ii) acting more like org-ref-cite is also a plus, since if Kitchin is already doing this, the principle of least surprise would encourage some alignment here.

EDIT: one further thought is that you could make this customizable, though that would not allow you to simplify the code...

[rudolf-adamkovic]

@bdarcus

It's already there ;-)

https://blog.tecosaur.com/tmio/2021-07-31-citations.html

BRB, git pull && make && make install 😄

[rudolf-adamkovic]

@bdarcus

I pulled latest master and recompiled Emacs, but I cannot see org-cite anywhere:

• describe-package finds no org-cite
• describe-variable finds no org-cite-global-bibliography
• (require 'oc) fails with "no such file"

Is there anything special I need to do?

P.S. I have been wanting to try org-cite for a long time.

[bdarcus]

Oh, I'm sorry; I misread your earlier post.

It's in org master; not yet Emacs. I don't know how often org is updated in Emacs actually.

FWIW, Doom already has it. It uses straight for package installation, and uses the straight org mirror.

https://systemcrafters.cc/advanced-package-management/using-straight-el/

[bdarcus]

I haven't any really strong feelings about this, since my workflow doesn't really depend on it. I would think there is some benefit to changing to 2, since (i) simplification of code is almost always a net good, and (ii) acting more like org-ref-cite is also a plus, since if Kitchin is already doing this, the principle of least surprise would encourage some alignment here.

EDIT: one further thought is that you could make this customizable, though that would not allow you to simplify the code...

A few wrinkles:

1. I don't thiknk John is sure of the best approach either. org-ref 3.0? jkitchin/org-ref#885 (comment)
2. I think, per your last point, it could be that each option is just complex in different ways. Like, the way John does it now, leads to problems with affix handling, because it doesn't distinguish key-affixes and global.

Maybe in the end we need two target-finders for embark; one for citations, and the other for keys.

[bdarcus]

Someone also encountered a bug that may be related to this.

If in an org document, on "cite" and you invoke embark-act and choose c, it will insert the key there, when it shouldn't.

We might need two OC target finders, with a different keymap for each.

[titaniumbones]

I'm following with interest but as a large majority of my citations have only one key I am not encountering this issue much in my everyday practice and am not sure what's right.