last Friday I finally committed last necessary changes to make Org Roam BibTeX (ORB) fully compatible with Org Roam v2. These changes live in the org-roam-v2 branch and are also tagged as v0.6.0-pre.
There have been a few significant changes. For example, there is no such thing as orb-templates anymore - one is supposed to use org-roam-capture-templates. The documentation has been updated but there may be inconsistencies, therefore also cross-check the respective docstrings (these may also be inconsistent though), or ask here.
There is a minor glitch where a newly created note will not be recognized as existent, so that calling edit notes, e.g. from helm-bibtex or ivy-bibtex, will offer to run the capture again. This will be fixed soon. If you really need to work with the new version rather than just try it, it’s possible to update the notes cache by evaluating (orb-make-notes-cache). There may also be other bugs. Otherwise all the familiar functionality, e.i. editing notes from Helm-bibtex, Ivy-bibtex or Org-ref citation links, template expansion, orb-note-actions, orb-insert, orb-pdf-scrapper, should be fully usable.
The new version will be properly checked and released and the development org-roam-v2 branch will be merged into master as soon as the Org Roam v2 is released.
Every time I visit an existing literature file, org-roam-bibtex jumps to the last known positions and makes a break line. For example.
I have this file and I will put the cursor anywhere, for example in the ID property.
:PROPERTIES:
:ID: <CURSOR HERE> 20210419T055156
:ROAM_REFS: cite:ZahariadesToDo2016
:END:
#+TITLE: ZahariadesToDo2016: To-Do List Formula: A Stress-Free Guide To Creating To-Do Lists That Work!
I close the file and go to another file (for example a daily note) and type or search cite:ZahariadesToDo2016. Click there, a popup opens and I select “Add notes”.
Here the capture template offers me to create a new reference note about the same cite (I think this is a bug).
I press r (my key for references), and I jump correctly to the right file but with this format:
:PROPERTIES:
:ID:
20210419T055156
:ROAM_REFS: cite:ZahariadesToDo2016 cite:ZahariadesToDo2016
:END:
#+TITLE: ZahariadesToDo2016: To-Do List Formula: A Stress-Free Guide To Creating To-Do Lists That Work!
There is a break line just before the last cursor position.
This is not necessary if org-roam-bibtex-mode is on. The reason why it is not turned on automatically is here:
:hook (org-roam-mode . org-roam-bibtex-mode)
In Org-roam v2, org-roam-mode is no longer a minor mode as in v1. It’s a major mode of the Org-roam buffer with backlinks. The best Doom way to have org-roam-bibtex-mode turned on automatically is something like this:
(after! org-roam
(org-roam-bibtex-mode))
Also, the specialized function orb-org-ref-edit-note should be used with org-ref-notes-function instead of orb-edit-note. The former correctly sets Org-ref’s internal org-ref-bibliography-files and ensures ORB will also work in BibTeX files. But again, this is unnecessary if you have org-roam-bibtex-mode on.
Since you didn’t have a call to org-roam-bibtex-mode, which is an autoloaded function, the package org-roam-bibtex was not loaded, and therefore the config section with (require 'org-ref) was not executed.
This happens because ORB relies on its own fast internal cache to check whether a note exists. This cache is not updated automatically - I’m still figuring out the best way to do this. To update the cache, one needs to run (orb-make-notes-cache). I hope to fix this soon.
I also noticed that when capture is run for an existing note and :if-new is set to (file+head), then the existing note gets messed up. Either Org-roam or Org-capture are to blame here because ORB does not run capture itself and does not actually modify note files. ORB’s task is either to open an existing note, or to prepare Org-roam for capturing a new note. So a situation where capture is run for an existing note should not arise in the first place. But again, this behaviour will be fixed as written above. Until then, one needs to run (orb-make-notes-cache) manually each time after creating, deleting or renaming a note. If you really need ORB v0.6 for your work then you should figure out a way to call this function every time Org-roam database is updated.
@bruce, this is rather a question of how Org-cite will affect Org-ref and more generally workflows that rely on the Org-Roam - ORB - Org-ref - Bibtex-completion chain. I haven’t had a chance of trying Org-cite yet, just had a quick look on its code. It seems there might be conflicts between the two packages and I’m not sure whether both could be used simultaneously. ORB does not depend on Org-ref or cite:links. The only thing it has to do with them is to set Org-ref’s org-ref-notes-function to point to orb-org-ref-edit-note so that when following a cite:link and choosing Edit notes from the pop-up menu will do the Org-roam find-or-capture stuff. So if Org-ref and Org-cite are not compatible, this workflow will be affected. One could still use Bibtex-completion through one of its interfaces to achieve the same. Template expansion will not be impacted.
In fact, this is more of a question to Org-roam, because it hiddenly depends on Org-ref in a few places to recognize cite:links and treat them as “ref” links. However, that should be easy to fix.
Org-cite is a framework. It’s clearly stated in its documentation. It provides a native API to handle following and exporting cite:links, making them first-class Org citizens. Other packages are supposed to use this API to provide some user-level functionality. As such, it’s not a competitor to Org-ref. Org-ref will just have to use Org-cite as a backend. This will significantly simplify Org-ref’s code and make it more robust. With my limited knowledge of Org-ref’s codebase, I’d say the transition would be pretty straightforward, but at the same time quite labour intensive.
FWIW, while John Kitchin has expressed interest in rewriting org-ref to target org-cite, he has said it will probably take awhile (I think mostly because of lack of time).
But clearly oc is the future.
Org-cite is a framework. It’s clearly stated in its documentation. It provides a native API to handle following and exporting cite:links , making them first-class Org citizens.
Right. But the syntax and model of these citations is different than what org-ref uses. So I guess ideally org-roam could treat them the same, at least for the transition period.
When org-cite drops, I’m willing to put the time to figure out the inter-operation that we could have with it. As @mshevchuk, I’ve only had a rudimentary look at the code, but I trust our ability to grok the code fairly rapidly, considering our experience with other parts of the org-mode eco-system.
The problem with maintaining inter-operability between two systems is that it requires an extensive amount of work to keep everything from sliding apart. Following this rationale, we decided to not maintain a legacy version of v1 because it’s not only going to spread us thin, but it’s also going to limit our imagination to the intersection of the two paradigms.
So, in short: I’m willing to work on org-cite integration as I had for org-ref integration with @mshevchuk, but the goal will always be to strive towards what’s most native (org-cite in theorg-cite vs. org-ref discussion) and what requires the least amount of maintenance. Depending on the feature discrepancy ratio between org-ref and org-cite, I’d either be willing to keep both or to migrate what functions we may to org-cite.
The syntax is still that of a regular Org link: either a plain link cite:link or a bracketed link [[cite:link][description]]. The semantics of different parts does’t matter in this case. Org-roam is not going to process any links. It just figures it’s a cite link an updates the database table with ref backlinks accordingly.
I just checked Org-roam for stuff related to Org-ref. It looks like Org-roam now uses a more general approach of matching against org-plain-link-re to determine whether a ref is a link. So as soon as Org-cite registers its links with Org parser, e.g. updates the regexps such as org-link-plain-re, there will be no difference. And it’s definitely going to do that. Previously, Org-roam was using org-ref-cite-types to match the cite:links. Now, it does not seem to use this variable anywhere anymore, so actually it looks like Org-roam has already made a seamless transition to Org-cite that also works with Org-ref, @jethro? There is also an Org-ref-specific workaround, which deals with a bug in Org-ref, but it’s not related to parsing cite:links.
I was just meaning that a citation in org-cite is not using that mechanism;
[cite/text:see @doe, p23]
Definitely.
I don’t use org-ref personally, and am pretty psyched about org-cite.
FWIW, it looks to be this will be merged for org 9.5. I have no idea when that is planned for release though, and how that will relate to an org-roam v2 release timeline.
Oh, I didn’t realize it was so drastically different. In any case, if it’s registered as a proper Org link, Org-roam will not have any troubles. Although the two styles are indeed incompatible, I don’t see why Org-roam couldn’t support them both. It all boils down to recognizing these patterns as links and putting them into the ref table.
This warning is triggered when cite:links are not registered with Org-mode. It can only happen when Org-ref is not loaded. Could you try M-x load-library → org-ref and check whether the error still persists?
For anyone that wants to dig into the details, the code is extremely well-documented (at least in the docstrings), and currently lives on the wip-cite-new branch.
