Miskatonic University Press

Thirty years

vagaries

I wrote this on 13 March 1994:

I’ve been working on some hypertext, with HTML, and chatting on the IRC a fair bit.

That was on Internex Online, the famous io.org. As K.K. Campbell wrote in “Party’s Over: How Internex Online Fell Afoul of the New Internet” in Eye Weekly on 9 November 1995, when IO was collapsing:

IO was the place to be in Toronto cyberspace. The digital generation flocked to it and lit up its modem lights all day and all night. It was the mother ship that launched thousands of netters and dozens of Internet service providers (ISPs).

The next month I noted I was getting three and a half hours a day of free access for working on the hypertext help system, which was built with the text browser Lynx.

The access was with a 2400 bps modem. My current download speed, tested through a VPN on the other side of the country, is 17,500 times faster, which means that averaged out the speed has gone up well over 50,000% annually. I pay about $90 per month (it should be less, but TekSavvy gets hosed by the big telcos), but I get unlimited access all day, and I don’t have to work on the help pages.

I drifted away from IRC but I’m still working with hypertext.

On another note, looking back at some old IO files I saw I’d posted this to the Usenet group sci.logic in October 1994, with the subject “Productivity of Turing machines.” I’d learned about Busy Beaver machines.

I’m doing a metalogic course, and we just finished doing Turing machines. We did the “Busy Beaver” machines - the nth BB being the machine of n states that produces more 1’s on the tape given input of only blanks than any other machine of n states. (Then we went on to prove there is no machine that, given input n, figures out the productivity of the BB of size n.)

We figured out that the productivity of the BB of size 1 was 1. The prof mentioned some work had been done to figure out productivities of bigger BB’s - the 7th is in the thousands, I think he said.

Does anybody know any more about this? Any references I could check? I searched on the Web, but couldn’t find anything. Any further information would be appreciated - I find Turing machines very interesting.

Herb Enderton (a math prof at UCLA) replied:

Yes. Start with the review of Brady in The Journal of Symbolic Logic, vol. 56 (1991), page 1091. That gives the known scores for the Busy Beaver game, and references to other papers on the subject. It’s a fun topic.

Incidentally, I am told by people who have translated works on recursion theory from English into other languages that the phrase “busy beaver” gave them a lot of trouble!

Enderton was the reviews editor of The Journal of Symbolic Logic, so he had overseen this review three years earlier.

And Peter Suber (then a philosophy professor at Earlham College) replied:

A BB of size 5 already has a productivity in the thousands. In 1984, George Uhing constructed a BB(5) with a productivity of 1,915. Of course, we can’t prove that this is the most productive BB(5). But Uhing says he conducted a brute force search of all the 64,403,380,965,376 possible BB(5)’s to find his. (Source: Ivars Peterson, The Mathematical Tourist, W.H. Freeman, 1988, pp. 197-99.)

(Suber used underscores before and after the title. Markdown turns that into italics: plain text from 1994 formats nicely thirty years later!)

I had no idea who either was. They both gave generous and informative answers to a stranger. It may still be September 1993 (who am I to complain? I’d only got in a few months early) but that helpful spirit is still out there, though it’s a lot harder to find.

Canadaland testimonial

podcasts

Some of the Canadaland podcasts have testimonials from supporters at the start. The host will say Canadaland is supported by So-and-So and Someone Else and list a few names, and end with “and also by Maria,” and then there’s audio from Maria saying why she supports the shows and what she likes and perhaps what she doesn’t like (usually a fond gripe about owner and publisher Jesse Brown).

A few weeks ago I was asked to do one, and they used it for Short Cuts #969: Mulroney, One of Canada’s Most Divisive Prime Ministers.

As I say in it, I never miss an episode of Commons or Wag the Doug. It was a treat to be asked.

Two stamps, of Brian Mulroney and Michael Wilson, captioned Hi! I tax books.
Two stamps, of Brian Mulroney and Michael Wilson, captioned Hi! I tax books.

Molly White, Become a Wikipedian in 30 Minutes

wikipedia

Become a Wikipedian in 30 Minutes, by Molly White, is a really good video:

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.

List of all blog posts