org-roam-bibtex
org-roam-bibtex copied to clipboard
org-roam
Add org-cite support
Native org citation support, called the org-cite module, has almost wrapped up, and the feature will be merged to master "any day."
For org-roam, OC introduces citation and citation-reference objects to org-element, and the main oc.el module file includes functions like org-cite-list-keys that will return all citation keys in a document. So indexing these will be trivial.
Beyond that, OC is designed around flexible and modular "capabilities"; currently:
-
activate (fontification, previews, etc.; relevant for
org-roam; seecsl-activate, whose functionality is likely to be integrated into the coreoc-cslprocessor) -
follow (actions tied to
org-open-at-point; this is the one most relevant toorg-roam-bibtex) - insert
- export
One configures these "processors" like so:
(setq org-cite-activate-processor 'basic)
So it will be a highly flexible, modular, system.
Here, for those curious doom users, is my draft PR to add support to its biblio module:
https://github.com/hlissner/doom-emacs/pull/5212
PS - I recently learned that org-ref requires both ivy and helm, which I find really problematic, as I don't use either. I guess you will have a decision to make about its status going forward. I would hope that if you continue to support it, it becomes optional in ORB.
Hi, thank you. I can't promise that I will be able to look at it until the org-cite feature is merged into master, but once it is, ORB will definitely accommodate for it. Moreover, I believe there is very little that needs to be done on the ORB side to support org-cite. So to mimic Org-ref's behaviour, one just has to add an activate processor and point it to orb-edit-note, which as of now can be readily done on the user side - there is no need to change anything within ORB. But surely ORB should take care of it automatically and define such a processor itself.
Now, the question of really supporting org-cite is a question to Org-roam @jethrokuan. Org-roam should be able to recognize org-cite elements and index them as "ref" links. As was discussed on Discourse some time ago, there is not too much work to be done, but that work means changing internals of Org-roam. The question whether to continue to support Org-ref citations is therefore also a question to Org-roam. Also, Org-ref is not a hard dependency of Org-roam. One is not forced to to install it to be able to use Org-roam, but one of course won't be able to elevate Org-ref citations to "ref" links. I believe it would be possible to keep support for both Org-ref and org-cite, and Org-ref is already optional.
Then of course there is little sense for ORB to support org-cite (to define an activate processor) until the real support is introduced into Org-roam.
Yeah, I was wondering how much really needed to be done.
The main oc.el module file includes functions like org-cite-list-keys that will return all citation keys in a document. So indexing will be trivial.
I guess I should have posted this on the main repo tracker.
WDYT @jethrokuan? Feel free to move this if you think better.
So to mimic Org-ref's behaviour, one just has to add an activate processor and point it to orb-edit-note, which as of now can be readily done on the user side.
To be sure, this piece will also be trivial.
But it would actually be a "follow" processor.
I will be adding one that wraps the bibtex-completion stuff, including it's open-notes function, which works with OR/B.
https://github.com/bdarcus/bibtex-actions/pull/156
The basic idea there is those then get bound to org-open-at-point when on a citation, or citation-reference.
PS - I edited the main post with some of this info.
Org-ref is not a hard dependency of Org-roam.
No, but it is in ORB. That's what I was meaning here.
Org-ref is not a hard dependency of Org-roam.
No, but it is in ORB. That's what I was meaning here.
No, ORB doesn't really depend on Org-ref. Well, it's complicated. There is no (require 'org-ref) statement in ORB code (a hard dependency), this is delegated to the user. In Package-Requires header, Org-ref is indeed listed as dependency but this was introduced to automate installation of Org-ref because some users were not aware it was required by Org-roam to enable cite:links "refs". The only Org-ref function that ORB uses, apart from what is necessary to "integrate" Org-ref, is org-ref-format-entry, which is just a formatting function and can easily be replaced.
So what is happening here is that ORB depends on Org-roam being able to recognize Org-ref cite:links as "refs". But Org-roam does not depend explicitly on Org-ref, so ORB is forced to propagate it as a dependency, although conceptually it's not. So rest assured, Org-ref is not and will not be a strict logical dependency for ORB. As soon a Org-roam does not intrinsically depend on Org-ref, ORB will immediately make it absolutely optional.
Just by way of update, @myshevchuk @jethrokuan, org-cite is now in org-mode master.
Looking again at org-cite-list-keys, I realize now it is currently only for the export process.
But that code is super simple:
(defun org-cite-list-keys (info)
(delete-dups
(org-element-map (org-cite-list-citations info) 'citation-reference
(lambda (r) (org-element-property :key r))
info)))
Tentative discussion of plans for oc-focused org-ref 3.0.
https://github.com/jkitchin/org-ref/issues/885#issuecomment-880294348
@bdarcus Thank you! I may not always respond in time but I'm trying to follow the updates regularly. Unfortunately, I'm really very busy now - I have to finish my PhD thesis by the end of August - and will probably have very little time for new ORB features until then. On the other hand, reviewing and merging pull requests should not be that much time consuming, so you are welcome to submit them!
Best of luck with that!
I'd like to hear from @jethrokuan on what he's thinking for org-roam proper. It seems that's the first step?
IUC, it really just means indexing oc citation-references?
Thinking more, with everything rapidly coalescing around org-cite, I'm not sure: are any changes needed in ORB?
Open notes functionality already works with bibtex-actions-org-cite, and that simply wraps bibtex-completion-open-notes.
But on this, one easy change is to remove this dependency. I really don't want that package installed for me, particularly when it, in turn, installs helm AND ivy, and will likely soon be obsolete anyway.
In Package-Requires header, Org-ref is indeed listed as dependency but this was introduced to automate installation of Org-ref because some users were not aware it was required by Org-roam to enable cite:links "refs".
Updated video on org-ref functionality for oc.
https://www.youtube.com/watch?v=3TBYg1MZ6iY
And new repo:
https://github.com/jkitchin/org-ref-cite
He recently added a function to update org-ref cite links to org-cite citations.
Now that OR has OC support, I guess the question is what ORB might add.
So org-ref-cite (whose future is now unclear) has a hydra-based "follow processor", and bibtex-actions an embark-based one.
Each provides access to functions that take one-or-more keys-at-point as input. I expect to some degree the functions could be shared between them, though I haven't yet tried myself.
I have also made my bibtex-action-open-notes function rely on a defcustom for that function, so that a user could swap org-edit-notes etc.
What needs to be updated in ORB is its ability to treat Org-cite citations in ROAM_REFS in the same way it treats Org-ref citations. That is it should be able to recognize Org-cite entries in Org-roam database and determine whether to create a new note or take the user to the existing one.
It should also be able to provide its "note actions" for an Org-cite-powered note as well as create new notes and put Org-cite citations in ROAM_REFS.
It should also provide a function for an Org-cite follow processor to create/open a note.
The above is more of a roadmap for myself. I'll look at it as soon as possible.
@bdarcus what is the workflow of using bibtex-action with orb? How to make note editing go through org-roam templates?
@bdarcus what is the workflow of using bibtex-action with orb? How to make note editing go through org-roam templates?
Discussed in the README, but:
(setq bibtex-actions-file-open-note-function 'orb-bibtex-actions-edit-note)
But the default notes function does work with org-roam. It just doesn't use its template system (uses the internal one).
I've contemplated adding a notes function for org-roam using its template system, but don't have the knowledge or time ATM.
@bdarcus I worked fine with a bothersome issue. Sometimes, when pressing C-; then n, It asks for capturing again. If I just choose a different file, a new note is created. If I used a custom template for the bibliography, a new chunk of text is inserted. Is there is any way to avoid that?
@myshevchuk It happens every time I select the note option from embark-act. I got redirected to the capture templates and after I choose a template, it appends to the created note.
@OAshkar Most probably some configuration issue on your side. I'll need more information to debug it. It is in any case unrelated to Org-cite support, so please either open a new issue or post the question on Discourse
@myshevchuk Thank you. I will check my configs. If I failed to find the problem, I will open an issue with my config.
Orb note actions now recognize Org-ref v3 [[cite: &links]] and Org-cite [cite:@elements] in addition to the old Org-ref v2 plain cite:links. See #220 and #222.
Hello @myshevchuk , I use the org-cite format [cite:@elements] orb-note-action works orb-insert-link works too However, org-open-at-point brings me to an hydra menu (from org-ref, I suppose) and it's not able to perform most of the actions as it says:
Bibtex-completion couldn't find entry with key "@elements".
It would work with the following format cite:elements, however it is not the org-cite format. Maybe I'm doing something wrong. Any idea?
Hi, @sampso.
orb-note-action works orb-insert-link works too
That's it about Org-cite support in ORB.
Maybe I'm doing something wrong. Any idea?
Yes, you're trying to use Org-cite citations with Org-ref. Org-ref does not support Org-cite citations.
However, org-open-at-point brings me to an hydra menu
That's not ORB's task. You can take a look at Citar, which provides a comprehensive support for Org-cite citations, in particular the familiar Org-ref-like behavior. I believe, you also need Embark for this, but please consult Citar's docs for more details.
if you use Org-ref + Helm/Ivy-bibtex + Org-roam, ORB provides integration for that. If you use Org-cite + Citar + Org-roam, ORB provides integration for that too.
Thanks a lot for the follow up. I should then switch to org-cite + citar (I tried before, but I wasn’t able to configure it correctly ; I’ll try again) Also, in my config I have org-ref :disabled (with use package), and I don’t know why it is loaded. I’ll have to check that (I’m wondering if org roam bibtex don’t load it somewhere) Thanks again!
I’m wondering if org roam bibtex don’t load it somewhere
ORB does attempt to load Org-ref when org-roam-bibtex-mode is turned on. But I added this only yesterday. It wouldn't load Org-ref in earlier versions.
FWIW, it's not a problem to use org-ref with org-cite.
But if you use org-cite and citar, ORB itself becomes optional.
it's not a problem to use org-ref with org-cite.
That's true.
But if you use org-cite and citar, ORB itself becomes optional.
That's true also for the case of the Org-ref and Helm/Ivy-bibtex tandem. All these packages, Citar included, primarily target BibTeX bibliography management and citation management in Org files. They also have their own capabilities for note management, which is rather rudimentary compared to Org-roam's though. ORB's main task is to force all these packages to use Org-roam for note management instead of their built-in mechanisms. ORB's main feature is enabling expansion of BibTeX keywords in Org-roam templates and none of the above packages can do that.
All other features of ORB like inserting links/citations or accessing additional actions on a note are secondary convenience features resulting mainly from user requests. They also attempt not to duplicate the existing functionalities of other packages but rather to utilized them. So I'd say it depends on the workflow. For a note-centered workflow, ORB is a natural extension to connect Org-roam with bibliography/citation management packages. For a citation/BibTeX-centered workflow, both ORB and Org-roam become optional, since all these packages have their own note management systems.
ORB's main feature is enabling expansion of BibTeX keywords in Org-roam templates and none of the above packages can do that.
Yes, citar doesn't use org-roam templates. It could, but it's not a priority, in part because, as you say, ORB provides that.
For a citation/BibTeX-centered workflow, both ORB and Org-roam become optional, since all these packages have their own note management systems.
I would separate ORB and org-roam though. I'd say:
- use org-roam if you want backlinks etc that include citations (now including org-cite)
- use ORB if you want to use org-roam's template system