Add org-cite support

[bdarcus]

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; see csl-activate, whose functionality is likely to be integrated into the core oc-csl processor)
• follow (actions tied to org-open-at-point; this is the one most relevant to org-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:

doomemacs/doomemacs#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.

[myshevchuk]

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.

[bdarcus]

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.

emacs-citar/citar#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.

[bdarcus]

Org-ref is not a hard dependency of Org-roam.

No, but it is in ORB. That's what I was meaning here.

[myshevchuk]

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.

[bdarcus]

Just by way of update, @myshevchuk @jethrokuan, org-cite is now in org-mode master.

[bdarcus]

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)))

[bdarcus]

Tentative discussion of plans for oc-focused org-ref 3.0.

jkitchin/org-ref#885 (comment)

[myshevchuk]

@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!

[bdarcus]

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".

[bdarcus]

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.

[bdarcus]

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.

[myshevchuk]

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.

[OmarAshkar]

@bdarcus what is the workflow of using bibtex-action with orb? How to make note editing go through org-roam templates?