Miskatonic University Press

Silence is so accurate

art quotes

From Silence in the Age of Noise by Erling Kagge, translated by Becky L. Crook (New York: Pantheon, 2017), pp. 26–27:

High-pitched noises can have many modes of expression, but the most powerful scream that I have ever experienced is one that is void of sound: The Scream by Edvard Munch. I fell silent upon looking at it. There passed a communicative silence between the painting and me. Yes, I know that I cannot hop into the painting and be the person who lays a hand on the screamer’s right shoulder, yet I feel just as strongly connected to the experience of the screamer.

The philosopher Denis Diderot believed that one who observes interesting art is like a deaf man watching mute signs on a subject known to him. The formulation is a bit cumbersome, but it’s accurate. You are deaf when you stand there, attempting to interpret what is placed, hung or presented before you. The strange thing is that such a supposition also applies to Marc [sic] Rothko’s far more introspective paintings. His large, rectangular fields of colour in bold, often dark, hues are in a way the opposite of The Scream. They seem to house an enormous battery of energy. “Silence is so accurate,” said Rothko, when he refused to explain his images. Had he been able to simply reply with words, then perhaps he would have written an article instead of making a painting.

Mystery fictional footnotes added

footnotes

Thanks to a wonderful list from Zi-Ling Yan (sent in 2022 but I just got to it) I added twenty authors to the Fictional Footnotes and Indexes list. All did footnotes, and all were mystery and pulp writers from the first half of the twentieth century: John Dickson Carr, Kendell Crossen (who created the crime-fighting Buddhist superhero the Green Lama), Ellery Queen, Dorothy L. Sayers and others.

Also noted: Effron, Malcah. “On the Borders of the Page, on the Borders of Genre: Artificial Paratexts in Golden Age Detective Fiction.” Narrative 18.2 (2010), 199–219. DOI: 10.1353/nar.0.0046.

UPDATED a couple of hours later: added over a dozen more, thanks to another great list.

Raymond Briggs

kady.macdonald.denton literature

The Raymond Briggs episode of Desert Island Discs is wonderful. This quote stood out to me, where Sue Lawley and he are talking about the different kinds of work involved in doing graphic novels:

It’s like making a film: you write the script and then you become the director and decide who comes on from the left, who comes on from the right, and who speaks first and so on.

This reminded me of something my mother, Kady MacDonald Denton, said in a 2007 interview on CBC Radio One after winning the Elizabeth Mrazik-Cleaver Canadian Picture Book Award for Snow.

A picture book is a unique art form. It is the two languages, the visual and the spoken, put together. It’s sort of like a—almost like a frozen theatre in a way. You open the cover of the books, the curtain goes up, the drama ensues.

Basic citations in Org (Part 5)

citations emacs zotero

This 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:

The text sample exported to PDF
The text sample exported to PDF

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:

In the PDF all the formatting works
In the PDF all the formatting 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:

Screenshot of a mouseover
Screenshot of a mouseover

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.

Basic citations in Org (Part 4)

citations emacs zotero

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

Screenshot of basic.org in plain Emacs
Screenshot of basic.org in plain Emacs

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:

Hovering over citation key shows metadata
Hovering over citation key shows metadata

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.

Hovering over citation key shows metadata
Hovering over citation key shows metadata

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.

Incorrect citation key is shown in red
Incorrect citation key is shown in red

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

Mouseover text on bad citation key
Mouseover text on bad citation key

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”:

Filtering to matches on van
Filtering to matches on van

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

The key has been added to a list
The key has been added to a list

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.

s v codes citation result
      [​cite:@friends] (van Dongen, M.R.C., 2012)
  b //b [​cite//b:@friends] van Dongen, M.R.C., 2012
  c //c [​cite//c:@friends] (Van Dongen, M.R.C., 2012)
a   /a [​cite/a:@friends] van Dongen, M.R.C.
a c /a/c [​cite/a/c:@friends] Van Dongen, M.R.C.
ft   /ft [​cite/ft:@friends] ¹
ft b /ft/b [​cite/ft/b:@friends] ²
ft bc /ft/bc [​cite/ft/bc:@friends] ³
ft c /ft/c [​cite/ft/c:@friends]
n   /n [​cite/n:@friends]  
na   /na [​cite/na:@friends] (2012)
na b /na/b [​cite/na/b:@friends] 2012
nb   /nb/ [cite/nb:@friends] (1)
t   /t [​cite/t:@friends] van Dongen, M.R.C. (2012)
t b /t/b [​cite/t/b:@friends] van Dongen, M.R.C. 2012
t bc /t/bc [​cite/t/bc:@friends] Van Dongen, M.R.C. 2012
t c /t/c [​cite/t/c:@friends] Van Dongen, M.R.C. (2012)

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

LaTeX export of table of examples
LaTeX export of table of examples

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.

Basic citations in Org (Part 3)

citations emacs

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:

Numeric bibliography, numeric citations
Numeric bibliography, numeric citations

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:

Numeric bibliography, noauthor citations
Numeric bibliography, noauthor citations

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

Author-date bibliography, nocite citations
Author-date bibliography, nocite citations

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.

Nice-Looking Printed LibraryThing Catalogue updated

alc code4lib libraries nlpltc

Nice-Looking Printed LibraryThing Catalogue (on GitHub at nlpltc) has had a bit of work and now the README is up to date and make test will do something. You can use nlpltc to take an export of your LibraryThing catalogue and make a nice-looking PDF, possibly like this:

Sample of a catalogue
Sample of a catalogue

The idea for it began at the Access hackfest in 2010 and I wrote more about it in 2011. I mentioned the library of the Arts and Letters Club of Toronto, where I volunteer as the librarian, and some potential plans for converting from the idiosyncratic classification system to Dewey:

One way to fix this would be to reclassify everything with the Dewey Decimal Classification. How would I get the Dewey numbers? One easy way would be to use LibraryThing to manage our collection. When one enters a book into LT, it often knows the Dewey number already, or it can find it. The numbers it doesn’t know I could look up in the Toronto Public Library’s catalogue. They have an excellent collection for Toronto-related things. I could add the Dewey number to the LibraryThing record for my own use and for everyone else’s.

A few years later I did just that, and it turned out very well. I plan to write it up.

I’ve been using nlpltc to generate nice-looking printed catalogues and it’s turned out very well. The code is messy, the templating is ugly because it embeds Ruby inside LaTeX, I’m told it fails on some Unicode characters (I will fix this), and I don’t follow any proper established software development methodology, but it works and it’s fun to hack on. Not many hackfest projects are in use thirteen years later!

If you try it out, let me know. I never did email Tim Spalding about getting it into LibraryThing, but I will now. Who knows? It’d be great to press a button and LibraryThing generates a nice-looking PDF.

Basic citations in Org (Part 2)

citations emacs

Numeric style in citation but not bibliography

In Part 1 we took a citation in its simplest form, using the default basic citation processor, then ran through all its possible styles and variants, and made a bibliography to go with it. It all worked—the in-text citation or footnote led to the right entry in the bibliography—except for the numeric style. That generated a number, but there was no number in the bibliography to match. We’ll start here by recreating the problem.

As before, we’ll use this Basic.bib file:

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

Set the file basic.org to this, where the /nb in the citation object means the numeric style will be used.

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

#+bibliography: Basic.bib

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

* Bibliography

#+print_bibliography:

Exporting that to a PDF (C-c C-e l p) gives this:

Citation number does not match bibliography
Citation number does not match bibliography

The citation is “(1)” but there’s no matching numbered entry in the bibliography. How do we fix that? With the cite_export keyword.

cite_export

In basic.org we already have two keywords: bibliography (to specify where to look for bibliographic metadata) and print_bibliography (to tell Org to print the bibliography). Now we introduce the third: cite_export.

cite_export specifies three things: citation processor, bibliography style and citation style. The format is:

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

If any of them is left out, the relevant default is used. If you don’t set cite_export, defaults are used for all three. If you specify one thing, it has to be a valid citation processor, and then the default bibliography and citation styles are used. If you specify two, they have to be a valid citation processor and a valid bibliography style, and then the default citation style is used.

(If you have an empty #+cite_export: line, the export generates a PDF with no citations or bibliography, and org-lint reports an error: “Missing export processor name.”)

In our above example, because we didn’t specify cite_export we were using the default citation processor, which is basic. However, we could specify it by name:

#+cite_export: basic

If we put that in basic.org and export to PDF we will get the same as before.

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

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

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

* Bibliography

#+print_bibliography:

That Org file exports to this PDF.

Basic processor, same as before
Basic processor, same as before

Indeed, same as before.

Bibliography styles

Defining only the citation processor and nothing more means the default bibliography and citation styles are used. What if we don’t want the default bibliography style? What is available? There are three options, listed in lisp/oc-basic.el:

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

Let’s start by working through these bibliography styles. First, author-year, which is the default. This will be the same again: before we were defaulting to the default option, now we’re specifying in cite_export that we want to use it.

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

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

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

* Bibliography

#+print_bibliography:

This exports to:

Basic processor, author-year bibliography, same as before
Basic processor, author-year bibliography, same as before

Again, same as before. Next, change cite_export to specify the numeric style.

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

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

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

* Bibliography

#+print_bibliography:

This exports to:

Basic processor, numeric bibliography
Basic processor, numeric bibliography

Aha! They match! The numeric citation style (specified in the citation object by nb) goes with the numeric bibliography style. That makes sense. We have solved the problem!

But let’s keep going and change cite_export one last time to use the plain bibliography style.

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

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

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

* Bibliography

#+print_bibliography:

This exports to:

Basic processor, plain bibliography
Basic processor, plain bibliography

The plain bibliography style is plain indeed. It’s sort of like author-year but without formatting and just the family name of the author.

That covers the three options for bibliography style we can set in cite_export. Next, setting a citation style and how the two sets of options fit together.

Specifying dates

unix

Managing times across time zones is difficult. The Software Freedom Conservancy recently ran four events that were scheduled to accommodate people all around world, and they announced them in an ingenious way I’d never seen before:

Please, join us on our BigBlueButton instance at any (or all!) of these four datetimes:

$ date -d ‘Dec 21 15:00 UTC’ # best accommodates European afternoon: 16:00 CET

$ date -d ‘Dec 22 03:00 UTC’ # best accommodates Australian east coast afternoon: 14:00 AEDT on Dec 23rd

$ date -d ‘Dec 28 00:00 UTC’ # best accommodates US/Pacific afternoon & US/Eastern evening: 16:00 PST on Dec 27th

$ date -d ‘Dec 29 21:00 UTC’ # best accommodates US/Eastern afternoon: 16:00 EST

As long as the reader knows about the command line—and almost all Conservancy supporters would—it’s easy to copy and paste a date command and see what the time is locally.

See also a post from two years ago about converting across time zones.

Basic citations in Org (Part 1)

citations emacs zotero

I did some sessions at work showing what Zotero can do, and my preparations got me caught up on the improvements in version 6 almost two years ago, which I’d read about but not tried. It’s fantastic. A group at Rice University did a great twenty-minute video that covers it all: Reading, Annotating, Note-taking, and Drafting/Outlining with Zotero 6.

The Zotero project did incredible work on this upgrade. Zotero already was the best research management tool and general purpose citation manager around, and now you can use it for PDF annotations, note-taking and draft-writing, and then easily move all that into your word processor, carrying all your citations along. I’ve always recommended it and now have even more reasons to do so (with still more when version 7 comes out).

But I don’t use it that way myself. Notes I take digitally I do in Org mode in Emacs, and if I want to mark up a PDF I print it and use a (mechanical) pencil. I use Zotero mostly as a research management tool, collecting citations and PDFs and web snapshots; lately I’m starting to use it to help with Wikipedia editing (see Wikipedia’s Citing sources with Zotero and Zotero’s Zotero and Wikipedia/Wikidata).

Seeing everything Zotero can do now made me wonder: Can I do that in Emacs with Org? Zotero users can go all in and make it their main research tool. That has a lot to offer. But I don’t want to write in Zotero, because I write in Org. Where should I draw the line between Zotero and Emacs?

That sent me looking into various Emacs packages and tools. It got complicated. This is a big subject. I decided to start with a core feature of any such system: citations. I’m a librarian. Citations I understand.

Citations in Org

A citation system in Org was released in summer 2021 after years of discussion and a lot of intense work. It builds on some great existing work and is itself an extremely impressive achievement. Handling citations is hard and now Org can do it.

But I’d never tried it, not once. And I’m a librarian! I decided I was going to learn it. I enjoy formatting citations and bibliographies by hand—indeed I enjoy everything about The Chicago Manual of Style—but now is the time to figure out how Org does them. The Org manual pages on citations are still rather sparse, and I thought this would be a path to me adding some documentation to improve them. That’s my plan.

When the citation system came out, the best documentation on it was in July 2021’s This Month in Org by the mononymic Timothy. I think this is still the main thing people refer to when they want to know how the system works. Timothy’s piece is very thorough, and it was a huge contribution to helping people understand how the new features worked. I found his example citation unclear, however, because the author is “org, mode and Syntax, Citation and List, Mailing and Effort, Time.” There is so much going on there it made it hard for me to see how things worked.

The citation processors

Citations in Org are meant to be exported to other document formats such as LaTeX (for PDFs), OpenDocument or HTML. As we’ll see, that’s where a sort of formula specifying a citation is turned into something readable. There are five citation processors available to do this exporting: basic and csl, which export to several different formats, and bibtex, biblatex and natbib, which only go to LaTeX.

I decided to start by working through a simple example with the basic processor, which is the only one requiring no dependencies or anything from outside. It turned out there were some bugs with it, which were fixed by Org maintainer Ihor Radchenko (for example this commit). Clearly some tests are needed for citations—but perhaps no one had tried using the basic system in these past two-and-a-half years? Yet another reason to try them out and write them up.

Here is the first part of my look into the basic citation system in Org.

Disclaimer

This is at the end of the commentary section at the top of oc-basic.el, the file with the code that controls the basic processor.

;; Disclaimer: this citation processor is meant to be a proof of concept, and
;; possibly a fall-back mechanism when nothing else is available.  It is too
;; limited for any serious use case.

This is true, but it’s still a great place to start.

Example book and .bib

First, we need something to cite. I’m going to use LaTeX and Friends by M.R.C. van Dongen (Berlin: Springer, 2012). I chose this for three reasons: first, it’s about LaTeX, which will be part of all this; second, the author’s surname begins with a lower-case letter, which will help with examples; and third, it’s a good book. Check out this fifteen-minute video about it.

Next, we’re going to put that book’s metadata into a .bib file, which is a bibliography database format used by BibTeX and BibLaTeX, which we will skip now but come back to later. I’ll also come back to the excellent Better BibTeX Zotero extension, which is going to be important for all this, and can generate these files magically. For now, we’ll just make a file called Basic.bib that has this in it:

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

This says we have a book which will be identified with the key “friends”. We know the title, author (in Surname, Forename order), date of publication, place of publication as “location,” the name of the publisher, the digital object identifier and the International Standard Book Number. Different citation styles will use or ignore this information in their own ways.

”{​{LaTeX}​}” is in curly braces so its unusual capitalization will be preserved. “Bib(La)TeX case protection rules are incredibly convoluted” as the Better BibTeX FAQ says.

Example Org file

Now we’re ready to work on an Org file. Let’s make basic.org. We’ll use some settings to keep exports clean and simple: no title, author, date or table of contents, and don’t number sections.

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

#+bibliography: Basic.bib

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

That [cite:@friends] is an Org “citation object” in its simplest form. It means: cite the work identified with the key “friends”. Where to look for the metadata about this work? In the Basic.bib bibliography file, as specified with #+bibliography: basic.bib.

Exporting to text

Since we’re keeping things simple, we’ll start by exporting to plain text (C-c C-e t A), which gives:

"Most scholarly works have citations and a bibliography or reference
section," wrote a computer scientist (van Dongen, M.R.C., 2012).

It works!

What citation style is “(van Dongen, M.R.C., 2012)” using? It’s Org’s default basic author-year style. We’ll come back to that later.

When we have citations, we need a bibliography. We add that with one line (#+print_bibliography:), and give it a heading to make it look nicer:

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

#+bibliography: Basic.bib

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

* Bibliography

#+print_bibliography:

Then we export again:

"Most scholarly works have citations and a bibliography or reference
section," wrote a computer scientist (van Dongen, M.R.C., 2012).

Bibliography
============

  van Dongen, M.R.C. (2012). /{​{LaTeX}​} and Friends/, Springer.

That looks a bit strange. We see the braces because of a bug in Emacs where something else should be tidying up the BibTeX formatting but doesn’t. This shows in text, HTML and ODT exports. We also see /slashes/ on either end of the title, but that is just the text way of indicating italics. The basic processor is so basic that’s all it can do.

This isn’t showing Org and its citations in the best light, so I’ll switch to exporting to LaTeX and making PDFs, which look much nicer.

Exporting to LaTeX

Let’s export basic.org to LaTeX and generate a PDF, with C-c C-e l p (this assumes a working LaTeX system is installed, of course).

LaTeX export example
LaTeX export example

Phew! That looks a lot better.

Styles and variants

I said [cite:@friends] is the simplest form of citation. There are several “styles” that can be added to it, and most styles have variants. (The word “style” is being unfortunately overloaded given the context of “citation styles” meaning The Chicago Manual of Style and such, but that’s the way it is.) The styles make the citations look different, sometimes very much so. The variants control if the citation is wrapped in brackets and if the first letter is capitalized. [cite:@friends] is in fact using the default style with no variant.

These are the available styles and their variants (as listed in lisp/oc-basic.el in the source code):

style code variants intention
(default)   bare, caps  
author a caps show only author(s)
note ft bare, bare-caps, caps footnotes
nocite n   put in bibliography
noauthor na bare date only
numeric nb   use numbers
text t bare, bare-caps, caps plain text

The variants use codes b (bare; no brackets), bc (bare-caps) or c (caps; first letter of the name is capitalized). Styles and variants are specified using slashes after cite in the citation. For example, the author style uses a, so to use it the default way you would specify [cite/a:@friends], or to use the caps variant, [cite/a/c:@friends]. To use the default style with caps variant, use [cite//c:@friends] with no style code given.

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.

s v codes citation result
      [​cite:@friends] (van Dongen, M.R.C., 2012)
  b //b [​cite//b:@friends] van Dongen, M.R.C., 2012
  c //c [​cite//c:@friends] (Van Dongen, M.R.C., 2012)
a   /a [​cite/a:@friends] van Dongen, M.R.C.
a c /a/c [​cite/a/c:@friends] Van Dongen, M.R.C.
ft   /ft [​cite/ft:@friends] ¹
ft b /ft/b [​cite/ft/b:@friends] ²
ft bc /ft/bc [​cite/ft/bc:@friends] ³
ft c /ft/c [​cite/ft/c:@friends]
n   /n [​cite/n:@friends]  
na   /na [​cite/na:@friends] (2012)
na b /na/b [​cite/na/b:@friends] 2012
nb   /nb/ [cite/nb:@friends] (1)
t   /t [​cite/t:@friends] van Dongen, M.R.C. (2012)
t b /t/b [​cite/t/b:@friends] van Dongen, M.R.C. 2012
t bc /t/bc [​cite/t/bc:@friends] Van Dongen, M.R.C. 2012
t c /t/c [​cite/t/c:@friends] Van Dongen, M.R.C. (2012)

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

LaTeX export of table of examples
LaTeX export of table of examples

Notice that the bare (b) variants don’t have brackets, and the caps (c) variants turn “van Dongen” into “Van Dongen.” Bare-caps (bc) does both.

You can see the nocite (n) style is unusual because it produces nothing. Its use is to force the entry into the bibliography even though the work is not cited; this need arises now and then.

The numeric (nb) style is different because it’s pointing directly to the bibliography. We’ll get to that next.

I recognize these as more or less common citation forms—shown in a simple way—except for some of those text (t) variants. Maybe I’ll figure them out later. It’s good the basic citation processor is complete and offers all variants, because it helps show what’s going on. As the disclaimer said, it’s a proof of concept.

The footnotes look like this. These variants in order are default, bare, bare-caps and caps.

¹ van Dongen, M.R.C. (2012)

² van Dongen, M.R.C. 2012

³ Van Dongen, M.R.C. 2012

⁴ Van Dongen, M.R.C. (2012)

Bibliographies and cite_export

The bibliography generated after that export looks the same as before:

Very simple bibliography
Very simple bibliography

That works for all the citations but one: the numeric style, where the citation was “(1).” For that we need a matching number in the bibliography. This will give the bones of the Vancouver system, which is common in the physical sciences.

To make that appear we need to use the third part of the citation system, the cite_export keyword, which we’ve left out so far. By not specifying it we were using all the defaults. The default citation processor is basic, which we wanted. To have a numbered bibliography matching the numbered citations we’ll need to get away from other defaults and make some customizations, which I’ll cover next.

List of all blog posts