Miskatonic University Press

In parts 1, 2 and 3 we took a single citation in an Org document, applied citation and bibliography styles to it, and used the basic processor to export it. In this post I’ll look at the four capabilities that the basic processor has. They are described in the manual and also in lisp/oc.el, which says (at time of writing):

This library provides tooling to handle citations in Org, e.g, activate, follow, insert, and export them, respectively called “activate”, “follow”, “insert” and “export” capabilities. Libraries responsible for providing some, or all, of these capabilities are called “citation processors”.

The four capabilities are: activate, follow, insert and export. Citation processors don’t need to have all of them, but the basic processor does.

Activate

The activate capability changes how a citation looks and acts in Org. Here’s our sample file from last time when viewed in plain uncustomized Emacs with emacs -Q basic.org (after hitting y several times to allow file-local variables):

The default Org highlighting makes keyword lines (options, bibliography, cite_export and print_bibliography) red and the heading blue. The basic citation processor’s activate capability makes the citation look different: it’s RoyalBlue3.

(To dig into details like this, put the cursor in the citation somewhere and hit C-u C-x = (that’s what-cursor-position with a prefix argument) and Emacs will show you a remarkable amount of information about that character, including that it has the faces org-cite-key and org-cite. They are what you would customize to change the look.)

Another property is that if you hover the mouse over the citation key (in this case @friends) then you’ll see the bibliographic information. In this screenshot you can’t see my pointer, but it’s on top of @friends, which is why it’s turned green:

If you hover over the rest of the citation object, such as the word cite, nothing will happen. Only the citation key has information to show.

From now on I’ll show it with my Emacs setup (which I’ve honed since 1995 and continue to fiddle with monthly: it’ll be perfect soon). Here’s the same mouseover, again without the mouse pointer visible.

That’s using the solarized dark theme and now the citation object has this colour by default but changes on mouseover.

Here’s some relevant documentation from lisp/oc-basic.el in the source code:

[The] “activate” capability re-uses default fontification, but provides additional features on both correct and wrong keys according to the bibliography defined in the document.

When the mouse is over a known key, it displays the corresponding bibliography entry. Any wrong key, however, is highlighted with `error’ face. Moreover, moving the mouse onto it displays a list of suggested correct keys, and pressing on the faulty key will try to fix it according to those suggestions.

We saw what happens with a correct citation key, but Org can also tell us about broken ones!

Let’s make this a little more interesting by adding a fake item into Basic.bib with a key that’s almost the same as the real one.

@book{friends,
  title = {​{​{LaTeX}​​} and Friends},
  author = {van Dongen, M.R.C.},
  date = {2012},
  location = {Berlin},
  publisher = {Springer},
  doi = {10.1007/978-3-642-23816-1},
  isbn = {978-3-642-23816-1}
}

@book{frionds,
  title = {Frionds},
  author = {F. Rionds}
}

Then in our Org file we misspell the citation key as @frinds. The processor knows this key doesn’t exist in our bibliography so it shows it in a different colour.

If we hover over it, Org offers help: “Suggestions (mouse-1 to substitute): friends frionds”.

Left-clicking on the key pops up this in the minibuffer:

1/2 Did you mean
friends
frionds

Up or down to choose the one you want, hit RET (that is, Return or Enter), and that key is put into the citation object, fixing it. Nice! This is a smart, helpful feature. (The suggestions are made with the string-distance function, which calculates the Levenshtein distance between two strings.)

I looked ahead at the other export processors and they do not have any special activate features, so they will fall back on what’s here. Perhaps people will add more features: might it be possible to see a fully formatted citation in the mouseover, similar to a LaTeX preview fragment? Perhaps users could get at the suggestions with the keyboard and not have to use a mouse?

Follow

With a simple citation the follow capability is straightforward: if the pointer is in a citation object and you hit RET, the window splits, a new buffer opens, and the pointer is placed at the start of that entry in the .bib file. I guess this would be used mostly for editing the metadata when you notice a problem, but if you want to use it to look at the entry a quick C-x 0 gets rid of the new window.

With more complex citations this capability does a little more, so we’ll come back to it.

Insert

The command to insert a citation is org-cite-insert, and the keybinding to remember is C-c C-x @. As Emacs keybindings go this is pretty easy to remember (I admit that’s not saying much): Org mode uses C-c C-x so we’re typing that all the time, and the @ goes with the @ in the citation keys.

Let’s say that Basic.bib still has that faked @frionds entry, and we’re in basic.org.

#+options: title:nil author:nil date:nil toc:nil num:nil

#+bibliography: Basic.bib
#+cite_export: basic numeric numeric

"Most scholarly works have citations and a bibliography or reference
section," wrote a computer scientist [cite:@friends].

* Bibliography

#+print_bibliography:

I start a new paragraph after my one sentence and I hit C-c C-x @. This pops up in my minibuffer:

(1/2) Key (empty input exits):
F. Rionds                       Rionds
van Dongen, M.R.C.        2012   and Friends

It may not look like that in yours. If you’re using plain Emacs you won’t see a list of options but they are there. If you’re using a completion system such as Vertico or Ivy or the built-in fido-mode then you’ll see a list. Org knows the options, and your completion system is handling them.

I could move down a line and the van Dongen entry would be highlighted, and then if I hit RET it would be chosen. Or I can do some filtering: here’s what it looks like if I enter “van”:

If I hit RET the van Dongen entry is chosen and the citation key is added to the list it’s building.

If you’re using plain Emacs, enter “van” and complete it with TAB. You’ll see the bibliographic entry listed, and hit RET to add it.

You can insert more than one citation, but I’m going to deal multiples next so we’ll stop here. In plain Emacs, and some other completion systems, you would hit RET to make the “empty input” that finishes this step. In Vertico and Ivy that won’t work, and you’ll need to hit C-u C-j or (in Vertico) M-RET. (Thanks to two helpful people on the Org mailing list for helping me with this.)

However you do it, when you’ve done it the citation object [cite:@friends] will be inserted into the file. Done!

#+options: title:nil author:nil date:nil toc:nil num:nil

#+bibliography: Basic.bib
#+cite_export: basic numeric numeric

"Most scholarly works have citations and a bibliography or reference
section," wrote a computer scientist [cite:@friends].

[cite:@friends]

* Bibliography

#+print_bibliography:

If you want to delete a citation, giving the insert command a prefix argument (C-u) will do that: if the pointer is on a citation then C-u C-c C-x @ will delete it.

One small last note: Org will let you insert a citation anywhere there is regular text, but not on keyword lines such as options or in source code blocks. You’ll get a “Cannot insert a citation here” error.

Export

Exporting turns the Org file into some other document format, and we’ve been doing that to text or PDF. The export capability is what makes a citation object (perhaps with a style and variant such as [cite/na/b:@friends]) into something human-readable. There’s a lot about this in part 1, but I’ll copy some of that here for completeness.

Showing what’s available in the basic citation processor, here is a table of styles (s), variants (v), how they’re specified, what the citation object looks like in the raw, and what it becomes when exported. The citation exporting happens when the whole document is exported (for example with C-c C-e l o to export to a PDF and then open it)—you don’t have to do anything special to prepare it.

Here’s the table in the LaTeX export, with an extra column specifying the style name.

With the basic processor we can export to text, HTML, LaTeX and OpenDocument. Different processors export to different document types, but they all export to LaTeX and you can always make a PDF.

The next post—the last about the basic processor—will be about complex citations with multiple keys, prefixes and suffixes.