Custom completion categories and Embark keymaps

[minad]

I've seen that citar defines its own completion categories bib-reference, citation-key and oc-citation. First I'd like to make the proposal to prefix the categories with citar- since they are Citar-specific as far as I understood. What is the difference between these categories? It seems you distinguish the categories mostly to provide different keymaps in Embark? This brings me to my second point - does it make sense to keep this distinction, since it goes a bit against the Embark spirit where no difference is made for the keymaps of objects coming from minibuffer or normal buffers. Of course it does not make sense to execute all actions on minibuffer candidates or buffer candidates. However Embark also allows to execute arbitrary actions via M-x on the current candidate, which makes this point less relevant.

[bdarcus]

What is the difference between these categories?

@roshanshariff asked about this recently too.

I will say part of the reason is to do with the bibtex-completion dependency, and the fact that the "insert" commands work differently than does org-cite-insert as it works with the org-cite-make-insert-processor function.

Aside: I am aware I don't currently have any bindings for either of these. But I was intending to.

In org-cite, it makes sense to include org-cite-insert at point, because that command behaves differently depending on context. So if point is after an existing key, for example, it appends a new one. If it's on a key, it replaces. If on the "cite" part, it prompts to edit a style.

But the bibtex-completion latex and markdown insert aren't that smart, so they don't make sense to use at point, and can cause unexpected results.

But ...

If we revised those insert citation functions to behave consistently with org-cite-insert (something @aikrahguzar already started to do with his latex adapter), then not only could we align the keymaps, but it might also make sense to remove citar-insert-keys.

See #383.

Only practical impediment is my current lack of understanding of buffer/point coding.

BTW, citation insertion and embark at point now work with markdown.

First I'd like to make the proposal to prefix the categories with citar- since they are Citar-specific as far as I understood.

Probably.

When I originally named them, I was contemplating possibility of future non-citar commands, but that probably doesn't make sense in retrospect.

[roshanshariff]

@bdarcus here I think the direction this is headed is two embark maps, or possibly even one.

I like the idea of having only one target type, but thinking about it more perhaps there are logically two kinds of targets: citations and references.

Citations (subsuming 'oc-citation) are targets found in buffers. Their actions should probably include: open-all-[files/url/notes/bibentries], insert/edit/delete keys, change citation type, and edit pre/suffix.

References (subsuming 'bib-reference and 'citation-key) are targets appearing either in the document as components of citations, or as completion candidates. Their actions should be open [file/url/note/bibentry] and insert (into citation at point or make new citation otherwise)

The target finder should try to find both in documents, but in formats (text/Markdown) that don't support complex citations, perhaps it only returns "reference" targets? In org/latex, it should return both reference and citation targets, as it does in org-mode now with 'oc-citation and 'citation-key. So if you want to operate on one reference, you can just do it, but then you can use embark-cycle to select the full citation and operate on that instead.

Does that make sense?

[bdarcus]

Does that make sense?

Yes, except "insert" is complicated ATM, and allowing it at-point can yield unexpected results..

[roshanshariff]

Complicated because it needs to do the right thing per major mode? And you mentioned that you were having trouble getting it to call 'org-cite-insert` in Org mode, and in plain text modes it needs some point-manipulation to insert at the right place. I can help with getting these working; that will let us get rid of the Org-specific targets, right?

[bdarcus]

Complicated because it needs to do the right thing per major mode?

Correct: #383.

And you mentioned that you were having trouble getting it to call 'org-cite-insert` in Org mode, and in plain text modes it needs some point-manipulation to insert at the right place. I can help with getting these working; that will let us get rid of the Org-specific targets, right?

By which you mean the org-specific category?

Yes, that's the idea.

FWIW, org-element includes two objects for org-cite:

1. citation
2. citation-reference

[roshanshariff]

After working on implementing the context-aware actions, now I'm leaning towards having only one target type (maybe 'citar-reference?) and therefore only one keymap. As is the case now, the target string can either be a single key or "key1 & key2 & key3" for multi-key citations. We will have two target finders in all modes, similar to what now happens in org-mode: one will return the single key at point, and the other all the keys in the current citation (for modes that support multi-key citations, mostly implemented in #394). So if you're on a particular key, you first get the single key as a target, then the entire citation. If you're on a citation affix but outside any key, you only get the second target type.

Looking at the current set of operations, it seems they should mostly work in all contexts:

Action	Minibuffer	Buffer Key	Buffer Citation
open file/url/note/entry	✔️	✔️	✔️
insert citation at point (context-sensitive)	✔️	✔️	✔️
edit thing at point (style/key)	❌	✔️	✔️
insert bibtex entry/formatted reference/keys	✔️	❌	❌
refresh library	✔️	✔️	✔️

• open file/url/note/entry
  Currently some of these aren't great at dealing with multi-keys (e.g. open entry, feat: completing-read citar-select-ref option #363) but we can probably figure something out. I'm working on a way to unify all the open functions that should also solve this problem (will open a PR soon).
• edit thing at point
  Currently in org-mode this just calls org-cite-insert. If point is not on an existing citation, it will prompt for multiple keys and insert a citation at point (exactly like edit/insert citation at point does). We can adopt the same behaviour for all major modes, making it behave like insert-citation when called from the minibuffer.
• insert bibtex/formatted reference/keys
  These are clearly unwanted if you invoke them when point is inside a citation, but the results are very predictable and not confusing (getting a blob of text at point). Most users will probably undo and carry on.
• refresh library
  This should probably be marked as a repeatable action in Embark, so you can invoke it and then go on to invoke one of other actions (and it should print a message to the echo area so users know it did something).

Any thoughts?

[bdarcus]

Any thoughts?

Not anything specific ATM.

But in general, I think priority should be on the UX.

If simpler (in this context, one embark map) is consistent with a better, more elegant and clear, UX, then that should be the approach.

If OTOH, two is better, then that should be the approach.

If unsure, perhaps start by simplifying to 2, and then can iterate based on feedback?

For org, I do want to be able to edit a citation style and affixes at point, but ATM I don't have a strong opinion on whether or not I have to be able to do with embark-act. I'm just not sure. Am happy to test a version without it.

org-cite-insert itself effectively has two targets, each of them complex: citation (style, affixes, list of references), citation-reference (key, affixes).

[roshanshariff]

I agree with the priority being on the UX. In fact, the reason I proposed this change is that it's confusing to have a mostly-identical but slightly different Embark keymap available depending on whether the current target is a single key or multi-key citation. And from the table above, it seems like all the operations have sensible meanings in all contexts.

For org-mode the "edit-thing-at-point" operation in the table is effectively a pass-through to org-cite-insert. It ignores the target and just does something sensible based on the location of point; that's why I thought it should be available in all contexts. In particular, if you invoke it with point on the style part, it'll offer to change it; or if point is on a particular key it will change that. I don't believe it has any support for editing affixes; it just inserts a new key at the beginning/end of the citation if you're on the prefix/suffix.

My proposal is to continue to have this command be a wrapper around org-cite-insert, but also implement equivalent functionality for other major modes.

[bdarcus]

Just a thought as I'm taking a break ...

It could be that we only have an embark target finder for citation-references?

And maybe add citar-edit-citation to the direct keymap; something like C-e? (edit: though I guess this has it's own issues)

That might simplify things at-point.

But still might be value to have two keymaps, with at-point more focused on "open" actions.

[bdarcus]

On this:

I'm working on a way to unify all the open functions that should also solve this problem (will open a PR soon).

Up to you, but you might open an issue first to discuss the plan?

I've thought about this issue, but never came to a conclusion about the obvious path forward; each that I considered had trade-offs.

Here's an earlier issue:

#229