Miskatonic University Press

My look at citations in Org continues on from Part 1 and Part 2, and here I finish going through the document-level settings.

Keywords and options

We can make document-level settings with three keywords:

• bibliography, to specify where to look for bibliographic metadata (this has no options);
• print_bibliography, to tell Org to print the bibliography, if we want one (this has no options in the basic citation processor but does in some others); and
• cite_export, which we’ll look at here.

cite_export specifies three things, and is used like so:

#+cite_export: citation-processor bibliography-style citation-style

The first option sets which citation processor (or export processor) to use. There are five available in Org:

• basic, the default, which exports to text, HTML, LaTeX and OpenDocument;
• csl, which uses the Citation Style Language, and also exports to text, HTML, LaTeX and OpenDocument; and
• bibtex, biblatex and natbib, which all export only to LaTeX.

We’re using the basic processor here. It’s very simple and useful for figuring out how all this works.

The next choice is about bibliography style. The options here depend on the citation processor. With the basic processor, there are just three:

• author-date (the default)
• numeric
• plain

In the last post we saw how we can set the processor and bibliography style with cite_export, for example:

#+cite_export: basic numeric

Lastly there is citation style, the options for which also depend on the citation processor. With the basic processor there are seven possible styles. (Most have variants that control whether they’re wrapped in brackets and if the first letter of the author name is capitalized.) They are:

• the unnamed default (used if nothing else is specified)
• author
• note
• nocite
• noauthor
• numeric
• text

There’s a table of them all in Part 1. (Look at lisp/oc-basic.el in the source code if you want to see how this is all made to happen.)

Setting a document-level citation style in cite_export

In the first post we saw how we can override the default citation style by adding a style (and possibly variant) to citation objects, for example [cite/a:@friends] (author style) or [cite/a/c:@friends] (author style, with caps variant). This is good for changing one citation at a time. To change them through the whole document, we can specify a new citation style in cite_export and rely on it. (In fact we’re setting a new default, but I’m trying not to use the word “default” in two different ways here. We’re already using “style” two different ways.)

Let’s do some examples. We’ll use the same Basic.bib as before:

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

We’ll revise our sample basic.org file to this, with an unadorned citation object ([cite:@friends]) and all the options in cite_export. Here we say we want a numeric bibliography with numeric citations:

#+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:

Exporting to PDF produces this pleasing match of citation and bibliography, where the reference “(1)” leads to the right source in the bibliography:

The citation object is unadorned but exports in the numeric style because of the document-level setting.

Settings need to work together

It’s possible to put together combinations that don’t make sense. For example, we could use the numeric bibliography style and noauthor citation style. The Org file is the same as above, but with this line changed:

#+cite_export: basic numeric noauthor

Exporting gives this PDF:

That’s not helpful. Similarly, using the author-year bibliography style and the nocite citation style is silly. Change the cite_export line to this:

#+cite_export: basic author-year nocite

Exporting gives this PDF (notice the tiny space before the full stop, because [cite:@friends] becomes nothing but the space before it is still there).

We need to make sure the citation and bibliography settings work together properly. If you’re using Microsoft Word and pulling in citation information from Zotero then you couldn’t mess things up like this. I think BibLaTeX is aware of context and can sometimes produce different output when needed (we may get to this later). With this basic system it’s up to you. Fair enough.

Overriding the document-level citation style

What if we set a new citation style for the document in cite_export but then want to use something different for one citation? This is always possible. In fact, this is just what we saw in Part 1. By not setting a citation style in cite_export the unnamed default was used, and we overrode it in all the examples. If a different citation style is named, we can override it just the same. We always have the freedom to use whatever citation style we want in any citation object.

There’s one situation where this gets tricky: overriding a named citation style to use the unnamed default. Let’s say we have cite_export set so:

#+cite_export: basic author-year author

Now using an unadorned citation object such as [cite:@friends] will just give the author. To use the noauthor style, for example, we would say [cite/na:@friends]. But what if we want to get the original default? It has no style code like na, so it seems like there’s no way to specify it. As I learned from Ihor Radchenko on the Org mailing list, we can get it with nil.

Here’s an example with the author citation style defined for the whole document, then overridden twice. The first citation object gets a nil style code to give the unnamed default we’ve seen before, the second inherits the document-level setting but uses the caps variant (because it’s at the start of the sentence, and I know I need to force that), and the third overrides to give only the date.

#+bibliography: Basic.bib
#+cite_export: basic author-year author

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

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

* Bibliography

#+print_bibliography:

This exports to:

In fact, using anything that isn’t a recognized style code will fall through to the default. The same is true of the variants. And it’s also true of the bibliography and citation style settings in cite_export!

This will export with all the default settings, and org-lint doesn’t complain either:

#+bibliography: Basic.bib
#+cite_export: basic alice wonderland

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

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

But don’t rely on any of that. Use proper names for things, and nil when you want to use that unnamed default citation style.

Next we’ll look at the four capabilities the basic processor has.