Add org-cite citation command function
Closed this issue · 26 comments
Just FYI, looks like org-cite (native org citation support) will be merged soon.
https://lists.gnu.org/archive/html/emacs-orgmode/2021-04/msg00790.html
I've implemented it on a branch of bibtex-actions, but it makes more sense here.
I'll wait a bit to merge it/or submit a PR.
Woah, that looks cool. Wasn't aware of this effort. (No time to read mailing lists recently.)
We should definitely update the default citation functions. The current default citation function (ebib-links?) are pretty outdated and I doubt that anyone is seriously using it. I may be wrong though and that's why I hesitated to change it so far. But with a standard org citation format it's a nobrainer.
We should definitely update the default citation functions. The current default citation function (ebib-links?) are pretty outdated and I doubt that anyone is seriously using it. I may be wrong though and that's why I hesitated to change it so far. But with a standard org citation format it's a nobrainer.
Probably the obvious approach is to keep the current one, add the new one and then (probably not until org-cite is merged to master, and released as part of Org 9.5) make that default?
Yes, that's a good plan.
FYI, I just committed an org-cite "follow processor".
As you'll see, it should be trivial to add one for bibtex-completion, which then would bind bibtex-completion-at-point to org-open-at-point.
Relevant discussion: jkitchin/org-ref#885 (comment)
A first baby step: a0d32ab
I decided to follow an approach that relies more on Emacs' text editing capabilities. So there's no UI that prompts users for pre- and suffixes or citation styles. The user can easily add them by hand. Plus we can add a wrapper for oc-bibtex' UI later if we want as a separate citation function.
Other plans:
- Extend
helm-bibtex-with-local-bibliographysuch that it uses the org file's bibliography (if any). - Add a follow processor that opens the entry in helm-bibtex so that users have quick access to helm-actions.
- Similar for ivy-bibtex.
My understanding is that this should give us basic but more or less complete integration with oc-bibtex. Am I missing something?
Open questions:
- Do I need an insert processor? This would override org's insert UI (if I understand correctly) but is that desirable?
- What's the activate-processor doing?
- Do I need an insert processor? This would override org's insert UI (if I understand correctly) but is that desirable?
I think the UX is better, but probably a matter of personal preference.
You can experiment with the one included in oc-basic to get a sense. Would just allow you to replace that UI, partially (as I have), or fully (as John).
- What's the activate-processor doing?
John probably understands better than I, but see the gif of the csl-activate processor I link to above to get a sense.
@tmalsburg - I took a look at ivy-bibtex and helm-bibtex; what you need in both to create insert processors for org-cite is a function in each that opens the browsing interface, but returns a single key string, or a list of keys. I don't see that ATM.
Or, alternately, add a parameter to the entry points to allow them to do that?
Let me know if you have any questions.
Okay, I'm looking at oc-basic.el to figure out what needs to be done:
;;; Register processor
(org-cite-register-processor 'basic
: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)
:cite-styles
'((("author" "a") ("caps" "c"))
(("noauthor" "na") ("bare" "b"))
(("nocite" "n"))
(("note" "ft") ("bare-caps" "bc") ("caps" "c"))
(("numeric" "nb"))
(("text" "t") ("bare-caps" "bc") ("caps" "c"))
(("nil") ("bare" "b") ("bare-caps" "bc") ("caps" "c"))))My initial sense is that we need to do the following:
- helm/ivy-bibtex need to offer an insert processor.
- helm/ivy-bibtex need to offer a follow processor that open the search with the reference pre-selected (to give users quick access to actions).
- The slots for
:activate,:export-citation,:export-bibliographycan be recycled from the basic processor.
Not sure about the :cite-style property. Is that specific to pandoc and/or the latex citation package used? If yes, there won’t be a single default that will make the majority of users happy.
Either way, offering an insert and follow processor should be fairly easy.
One problem: The bibliography configured in helm-bibtex is not necessarily the same as the one references in the org file. I guess we need to extend helm-bibtex-with-local-bibliography to work with local org bibliographies.
How can I activate and use a processor after registering it with org-cite-register-processor? I created a first sketch but it doesn't do anything.
I've created a simple follow-processor that simply echos the key(s) and I registered it via:
(org-cite-register-processor 'helm-bibtex
:follow #'helm-bibtex-org-cite-goto)But nothing happens when I click on a citation.
I'll reply to your other questions in a subsequent comment, or edit this one. But in the meantime ...
One problem: The bibliography configured in helm-bibtex is not necessarily the same as the one references in the org file. I guess we need to extend helm-bibtex-with-local-bibliography to work with local org bibliographies.
I was wondering about that too. Could you add that to bibtex-completions?
How can I activate and use a processor after registering it with org-cite-register-processor? I created a first sketch but it doesn't do anything.
That merely makes that set of processors available.
To use, you do:
(setq org-cite-follow-processor 'helm-bibtex)One problem: The bibliography configured in helm-bibtex is not necessarily the same as the one references in the org file. I guess we need to extend helm-bibtex-with-local-bibliography to work with local org bibliographies.
I was wondering about that too. Could you add that to bibtex-completions?
Yes, we already have bibtex-completion-find-local-bibliography which looks for the local bibliography in LaTeX documents but it can be extended to handle org files as well.
To use, you do:
(setq org-cite-follow-processor 'helm-bibtex)
Still doesn't work. In fact the citation isn't even clickable. (It just looks clickable because it's underlined.)
Unrelated: Is anyone working on making the bibtex parser in oc.el faster? It takes about 100 times longer to parse my bib than parsebib. I see there are provisions in the code for a cache but it doesn't appear to be working, so Emacs freezes for 30s every time I insert a key.
Still doesn't work. In fact the citation isn't even clickable. (It just looks clickable because it's underlined.)
I take it by what you say below, the oc-basic insert processor does work for you?
What happens when you run org-cite-insert outside of a citation?
Unrelated: Is anyone working on making the bibtex parser in oc.el faster?
IDK, but have noticed that.
I take it by what you say below, the oc-basic insert processor does work for you?
I can create new citations with the basic processor and add keys to existing citations, but I can't follow them. After restarting Emacs, the citations are clickable (and I do get the little popup with the paper's title!) but nothing happens when I click. Hm ...
Oh, I'm sorry; not had my morning coffee yet!
You're talking about follow. Have you tried org-open-at-point while on a citation?
I think, though am not sure, to make the citation links clickable such that they run org-open-at-point, they would need to be in an activate processor.
If I'm right, it would be good to have that as a maybe configurable option on different activate processors.
My initial sense is that we need to do the following:
- helm/ivy-bibtex need to offer an insert processor.
Yes.
- helm/ivy-bibtex need to offer a follow processor that open the search with the reference pre-selected (to give users quick access to actions).
As I said on the other thread, I don't think that's necessary; just run the actions directly from point.
That's what I and @jkitchin, at least, are doing.
I think, however, opening the browsing UI could be one option there.
- The slots for
:activate,:export-citation,:export-bibliographycan be recycled from the basic processor.
Correct, or any other processor.
EDIT: but to be clear, the ONLY reason to fill slots if you want/need users to be able to refer to them by name. They have to do this anyway:
(setq org-cite-activate-processor 'foo-bar-processor)So just include what you actually provide code for.
Not sure about the
:cite-styleproperty. Is that specific to pandoc and/or the latex citation package used? If yes, there won’t be a single default that will make the majority of users happy.
You don't need that; it's only for export processors, to expose what they can consume.
See my processor, for example:
I'd actually encourage you to try this, just so you understand how modular all of this is.
(org-cite-register-processor 'oc-bibtex-actions
:insert (org-cite-make-insert-processor
#'helm-bibtex-oc-insert
#'oc-bibtex-actions-select-style)
:follow #'oc-bibtex-actions-follow)... and while you're at it, try @jkitchin's adaptation as well.
This is why I was proposing a separate project like this, given that it could reduce duplication of effort:
https://github.com/bdarcus/oc-blocks
Consider, for example:
- I currently have a style browsing UI in completing-read, as does @jkitchin. You will want one as well. @andras-simonyi and I are strategizing on how to include "live" styles previews in that UI, that work with any export processor.
- @jkitchin has an awesome follow processor, using hydra and/or transient menus at point. I do the same conceptually, but use
embark-actat point currently, though am seriously considering using a transient menu instead emacs-citar/citar#186. But both mostly reuse the same bibtex-completion functions. - @jkitchin is working on very cool activate capabilities, and @andras-simonyi is working on a very interesting alternative (which will probably end up in oc-csl).
So there's a lot of overlap and potential duplication.
But I'm still not sure whether or not that's a great idea; the current situation isn't necessarily a problem.
Edit: On 2 above, I decided against a transcient menu, and focus only on the current embark support. So I have removed that overlap :-)
And no, I don't like the name; was just for illustration.
Insert processors, BTW, probably ought to be specific to individual projects, given they are tied to UI/completion systems.
Either way, offering an insert and follow processor should be fairly easy.
Yes.
You're talking about follow. Have you tried org-open-at-point while on a citation?
Ah, that works. Thanks. But clicking with the mouse doesn't do anything, which is counter-intuitive.
As I said on the other thread, I don't think that's necessary; just run the actions directly from point.
Not sure I understand: If there are multiple keys in the citation, that would execute the action for all of them, no? Firing up a helm-search, would allow users to execute functions on all or on individual entries in that citation. Seem more flexible and also recycles an existing and familiar UI.
So just include what you actually provide code for.
Thanks. I was wondering about that.
You don't need that; it's only for export processors, to expose what they can consume.
I'm relieved to hear :)
But I'm still not sure whether or not that's a great idea.
I have to think about it. It's not immediately clear that this would simplify things sufficiently because (I think) my processor is going to contain some helm/ivy-specific code, so the potential overlap is perhaps not that big? Not sure.
Not sure I understand: If there are multiple keys in the citation, that would execute the action for all of them, no? Firing up a helm-search, would allow users to execute functions on all or on individual entries in that citation. Seem more flexible and also recycles and existing and familiar UI.
Ah, good point.
If point is on a citation-reference, then run directly (for example, open a menu to choose the action); if on the citation prefix, open helm?
John and I were discussing this recently on the other thread.
I have to think about it. It's not immediately clear that this would simplify things sufficiently because (I think) my processor is going to contain some helm/ivy-specific code, so the potential overlap is perhaps not that big? Not sure.
I'm not either; think about it.
You can obviously reuse code freely across our projects. If you find doing so seems like a hassle, and think it might be confusing to users, maybe there's merit?
As I said to John, one of my priorities is also as a maintainer of the doom biblio module; how this will play out in the code and documentation there. It could get confusing if each of us end up creating and maintaining our own slightly different activate and follow processors. Here's my current WIP attempt.
You're talking about follow. Have you tried org-open-at-point while on a citation?
Ah, that works. Thanks. But clicking with the mouse doesn't do anything, which is counter-intuitive.
For me, with the 'basic activate and follow processor, clicking on citation-reference opens the bibtex entry.
For me, with the 'basic activate and follow processor, clicking on citation-reference opens the bibtex entry.
Maybe there's an org variable that governs this behavior? I can't find one ATM.
It's weird, because for me, I can click on links, but not on citations; also using basic activate and follow.
It's weird, because for me, I can click on links, but not on citations.
Same.
You're talking about follow. Have you tried org-open-at-point while on a citation?
Ah, that works. Thanks. But clicking with the mouse doesn't do anything, which is counter-intuitive.
For me, with the 'basic activate and follow processor, clicking on citation-reference opens the bibtex entry.
Are you doing anything in your code so that you get the click access to your hydra?
I want that for my embark/which-key solution, but don't want to write my own activate processor.
I did add mouse-1 to the keymap that is added at activation. The activate processor in org-ref-cite is very easy to customize now.