Miskatonic University PressThis follows parts 1, 2 and 3 and 4 and brings me to the end of my look at the basic citation processor in Org. Next I’m going to look at the CSL processor, which uses the Citation Style Language. That will take a bit of work, but I’ll be back. Beyond that I can see some of the path to comparing Zotero to everything Emacs can do, which is the ultimate goal of all this.
Here I draw on Nicolas Goaziou’s (Not so) Short note about citations in Org (an email to the Org mailing list in April 2021—some things changed before citations launched, but this was part of the big final push that made all this marvellous stuff happen) and Timothy’s This Month in Org from July 2021, plus looking at the source code.
Some things I missed
Before I get into that, I missed some things in the last post, about the insert capability. If the point is in an existing citation object and right on the “style part” (as the code says) and you run the insert command (C-c C-x @) , then Org will offer to update it.
Let’s say the cursor is sitting between “i” and “t” in “cite” here (or on the “i” if your cursor display is a box) and you run C-c C-x @:
"Most scholarly works have citations and a bibliography or reference
section," wrote a computer scientist [cite:@friends].
This menu appears in the minibuffer (in my minibuffer, yours may look different):
(1/7) Style ("" for default):
numeric
nil
note
text
author
nocite
noauthor
Nice! If you want to change the style on a citation, this makes it easy. If you select, for example, author then it will be added as a style to the citation:
"Most scholarly works have citations and a bibliography or reference
section," wrote a computer scientist [cite/author:@friends].
Furthermore, we know we can use C-c C-x @ to add a citation object anywhere in the text of a document, but if we also use the Emacs prefix argument (that is, we run C-u C-c C-x @) then not only will it ask which reference to add, it will ask which style to use on that citation! Also nice!
Here’s something else I missed: I didn’t know we could use full names for styles and variants. I thought we had to use codes (such as a for author). These are equivalent:
[cite/a/c:@friends]
[cite/author/caps:@friends]
I’ve never seen this used, and didn’t realize it from looking at the source code. Now I know!
Prefixes and suffixes
Now back to me figuring out, as best I can, how things work. Up to now I’ve been looking only at simple citations like [cite:@friends]. But citations may need to be more complicated, and Org can handle that.
First of all, there are prefixes and suffixes (which are types of affix). A citation can have either, neither or both. For a citation with a single reference, they work like this:
[@cite/style/variant: prefix @key suffix]
We could have just a prefix:
"Most scholarly works have citations and a bibliography or reference
section," wrote a computer scientist [cite/noauthor: in @friends].
This exports to:
"Most scholarly works have citations and a bibliography or reference
section," wrote a computer scientist (in 2012).
We could have just a suffix:
"Most scholarly works have citations and a bibliography or reference
section," [cite/author: @friends wrote].
This exports to:
"Most scholarly works have citations and a bibliography or reference
section," van Dongen, M.R.C. wrote.
Of course, this is the same as we could have got with this, where the suffix is moved outside the citation object:
"Most scholarly works have citations and a bibliography or reference
section," [cite/author: @friends] wrote.
In simple examples like these, depending on the citation style, different arrangements can export to the same text. Still, this is good for seeing how all the pieces fit together.
We could have a prefix and a suffix:
"Most scholarly works have citations and a bibliography or reference
section," [cite/author: as @friends wrote].
This exports to:
"Most scholarly works have citations and a bibliography or reference
section," as van Dongen, M.R.C. wrote.
Multiple citations
Set aside the affixes for now and let’s cite two different works. We’ll add Robert Hauptman’s Documentation to Basic.bib:
@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 = {9783642238161}
}
@book{documentation,
title = {Documentation: A History and Critique of Attribution,
Commentary, Glosses, Marginalia, Notes, Bibliographies,
Works-Cited Lists, and Citation Indexing and Analysis},
author = {Hauptman, Robert},
date = {2008},
location = {Jefferson NC},
publisher = {McFarland},
isbn = {9780786433339}
}
Let’s edit basic.org to this:
#+options: title:nil author:nil date:nil toc:nil num:nil ^:nil
#+bibliography: Basic.bib
#+cite_export: basic
Citations and bibliographies are important in many forms of
writing [cite:@friends; @documentation].
* Bibliography
#+print_bibliography:Wait, I think I want Hauptman first, because he’s earlier alphabetically and chronologically. I put the point in the first citation key, hit M-t (transpose-words) and they swap places and the semi-colon is left after the first citation key. Thank you, Emacs!
About the semi-colon: when there is more than one citation, there should be no whitespace between a semi-colon and the citation it follows. Citation objects don’t seem to care about whitespace elsewhere, but if you have something like @friends ; then that space may creep in somewhere you don’t want it.
Back to our document:
#+options: title:nil author:nil date:nil toc:nil num:nil ^:nil
#+bibliography: Basic.bib
#+cite_export: basic
Citations and bibliographies are important in many forms of
writing [cite:@documentation; @friends].
* Bibliography
#+print_bibliography:Exported to PDF, we get:
Global prefixes and suffixes
Citations can have prefixes and suffixes, and we can have more than one citation key in a citation object. We put these together, for example like this, where the first citation has a prefix and suffix, and the second has a suffix:
Citations and bibliographies are important in many forms of
writing [cite: see @documentation for history; @friends for an implementation].
That exports to:
Citations and bibliographies are important in many forms of writing (see
Hauptman, Robert, 2008 for history, van Dongen, M.R.C., 2012 for an
implementation).
But there are two more pieces: the global prefix and suffix. Org citations have this general form:
[@cite/style/variant: global-prefix; prefix @key1 suffix; prefix @key2 suffix; ...; global-suffix]
That may not fit in your browser window, so let’s break it down:
[@cite/style/variant:
global-prefix;
prefix @key1 suffix;
prefix @key2 suffix;
...;
global-suffix
]
That’s the full general form. All that is necessary is [cite:@key]. Everything else is optional.
Now, you may wonder, why have global prefixes and suffixes? What is the difference between the global prefix and the first reference prefix? They both go before the first reference and there is no punctuation between them, so you could put words in either place and the result is the same when exported. I haven’t found discussion about this in the mailing list archives, and I don’t know how the LaTeX systems handle things, but I can think of two-and-a-half reasons (and would be glad to hear more):
- each citation reference is discrete and has the form
prefix @key suffix, and when there are several in one complex citation object, the prefix and suffix of any given reference should refer only to it, not to others; - more advanced citation processors may do smart formatting based on affixes; and
- perhaps something about punctuation or that sort of thing.
[Updated later: András Simonyi points out that some citation formats may reorder citations on export, for example because multiple works by an author must be ordered by date.]
Some examples
You can get a surprising amount of formatting inside a citation. Take this:
Citations and bibliographies are important in many forms of
writing [cite: see @documentation for history /inter alia/ but
*no* mathematics; and @friends for an implementation plus
mathematics such as \(x^2 + 2 x + 1\) and \(\aleph_{0}\)].
Exported to LaTeX, it all works:
[Updated later: Ihor Radchenko noted I had a Unicode caret (ˆ) instead of a regular one (^), which was breaking the formula.]
The citation style (and variant) affect the entire citation object. If you want to show just the author for one but author-date for another, that would need to be two citations. Here the author style applies to both citations:
Citations and bibliographies are important in many forms of writing,
as noted in works by [cite/a: @documentation; and @friends].
That becomes (with a duplicated period at the end, because nothing fancy is happening):
Citations and bibliographies are important in many forms of writing, as
noted in works by Hauptman, Robert, and van Dongen, M.R.C..
Timothy’s introduction mentions locators, which let you specify a part of a work, such as a page or chapter. The basic processor doesn’t support them but you can use suffixes:
Citations and bibliographies are important in many forms of writing
[cite: see; @documentation chapters 7 and 9; and @friends p. 19].
This exports to:
Citations and bibliographies are important in many forms of writing
(see Hauptman, Robert, 2008 chapters 7 and 9, and van Dongen, M.R.C., 2012
p. 19).
Activate
The first of the four capabilities any processor can have is activate, to handle fontification and mouseovers and such. Nothing changes about the general appearance of complex citations. Hovering over a citation key will show you its bibliographic information, but hovering over anything else does nothing. In this screenshot my pointer (which can’t be seen) is on top of @documentation, which is made to look different:
Follow
The follow capability acts generously, and hitting RET anywhere in a reference (on a citation key or its prefix or suffix) will take you to its entry in the bibliography. In this, hitting RET on “chapters” opens up the @documentation entry:
[cite: see; @documentation chapters 7 and 9; and @friends p. 19]
Hitting RET on the “cite” or the global prefix (or suffix, were there one) pops up a menu:
1/2 Select citation key:
@friends
@documentation
(I can’t see why they’re in that order … I swapped the entries in Basic.bib so @documentation was first and they still showed with @friends first.)
Insert
With complex citations the insert capability has more to do when the point is in a citation object because there are more places for the new reference to go. Here’s what oc.el says in the code:
On a citation reference:
- on the prefix or right before the "@" character, insert a new reference before the current one,
- on the suffix, insert it after the reference,
- otherwise, update the cite key, preserving both affixes.
When ARG is non-nil, remove the reference, possibly removing the whole citation if it contains a single reference.
On a citation object:
- on the style part, offer to update it,
- on the global prefix, add a new reference before the first one,
- on the global suffix, add a new reference after the last one.
Again take this citation object:
[cite: see; @documentation chapters 7 and 9; and @friends p. 19]
Putting the point anywhere in “see; “ (the global prefix and before the @) then hitting C-c C-x @ and choosing a citation will insert it before @documentation. Being on top of @documentation and inserting will replace @documentation with the new key. Being in “ chapters 7 and 9” and inserting will add the new key right after this reference. Being in “ and “ and inserting puts the new reference before the @friends one, so between the two that there are. If there was a global suffix, inserting while the point is on it would place the citation before it, which makes sense, because the global suffix always has to come last.
All of this works in a do-what-I-mean way. Nothing can ever be inserted before the global prefix or after the global suffix, so inserting when you’re in either does the right thing. If you’re at the start of a citation and insert, it goes before. If you’re at the end of one, it goes after. If you’re on top of a citation key and insert, the key is replaced.
When the point is inside a complex citation object, using the Emacs prefix argument (hitting C-u C-c C-x @) turns insert into delete. If the point is anywhere in a reference, that reference will be deleted. If the point is on the “cite” or the global prefix or suffix, the entire citation object will be deleted.
Export
We’ve seen the export capability all through the above examples, and I can’t think of anything new to add here.
Finally, many thanks to everyone who got Org citations working, in particular Nicolas Goaziou, Bruce D’Arcus, John Kitchin and András Simonyi (@simka@emacs.ch), and to Ihor Radchenko (@yantar92@emacs.ch) for his continued maintenance and bug-fixing. This is a powerful system and it was a lot of labour to implement it. And this is just one part of everything Org does! And Org is just one part of Emacs. And then there’s the whole world of Emacs users.