Context-sensitive insertion and edit commands

[roshanshariff]

This is a continuation of #394.

• Context-aware insert-citation
  • Org mode
  • Latex (already implemented)
  • Markdown
• Context-aware insert/edit function
  • Org mode (calls org-cite-insert)
  • Latex (calls citar-latex-insert-citation)
  • Markdown (calls citar-markdown-insert-citation)
• Target finders for keys and citations
  • Org mode
  • Latex
  • Markdown (based on Use thing-at-point for citar-markdown-key-at-point #395)
• Remove Org-specific Embark target (Custom completion categories and Embark keymaps #381)
• Update documentation

Partly implements #383: in Markdown, citar-insert-citation will now add new keys after the current citation key, or at the beginning of the citation if point is just after [.

Fixes #278, fixes #393: citar-insert-citation now does something useful in Org mode, either inserting a new org-cite citation or adding new keys to an existing citation at point. The new keys are added at the beginning of the citation if point is before the first key, or after the current key otherwise.

Relevant to #203: there are now two target finders, one for individual keys and the other for full citations. Both target types have the same keymap, offering the usual open actions. Running embark-act once will select and highlight the single key at point, and then running embark-cycle (or pressing the key bound to embark-act again) will select and highlight the entire citation. Depending on which target is active, the open commands will either act on a single key or all the keys in the citation.

Relevant to #190: the new citar-insert-edit action now runs the insert-edit major mode function, which is currently a thin wrapper around org-cite-insert in Org mode. TBD whether this behaviour should be changed.

Fixes #387.

[bdarcus]

Nice work @roshanshariff!

I just added a few minor line comments/questions, and suggestions which are mostly about docstring formatting.

EDIT: I committed the suggestions and merged. You can followup on the questions.

PS - Perhaps worth mentioning:

I've gone back-and-forth about whether it's the right approach for citation insertion and editing, but the solid at-point functionality might provide a foundation on which to add capf functionality in the future if it makes sense.

[roshanshariff]

The insert-edit functions for Markdown and Latex are pretty much the minimum viable implementations, and they don't let you change the citation macro or delete/replace keys. The next step is to make them more useful: either

1. try to imitate the logic of org-cite-make-insert-processor, or
2. design what we think the correct insert-edit behaviour should be and use it everywhere.

If we choose (2), we can also use it in Org mode; insert processors don't have to be made using org-cite-make-insert-processor. Either way, we should have a coherent story for all the editing uses cases (ref. #385).

[bdarcus]

insert processors don't have to be made using org-cite-make-insert-processor.

Correct. I asked the developer to add that because didn't want to figure out to do all that coding myself :-)

Also possible, and likely better: if we find some good tweaks for org-cite-make-insert-processor, contribute them to org. I've started to submit small patches along those lines.