Shady Characters

Giving credit where it’s due has been an important part of writing for Shady Characters since I started back in 2010. Where I use an image that I don’t own myself, for instance, I try my best to find the owner, obtain their permission and then credit them in the caption for their work. Equally as important, I try to link to or cite all of the sources I use when writing about a given subject. That last part has given me no end of grief, and that’s what I’m going to write about today.

What follows is more than a little bit technical, so if you aren’t interested in the mechanics of how scholarly references work online you might want to find some alternative reading material. Might I suggest Glenn Fleishman’s introduction to his new book,1 London Kerning, in which he gets under the skin of London’s long history of type, typography and printing? It’s a great read.

For the rest of you: here we go!

In the beginning

The Shady Characters website runs on a piece of open source software2 called WordPress.3 WordPress is a content management system, or CMS, that stores and displays text and images and takes care of a host of related organisational tasks into the bargain. Like most other CMSes, WordPress is both bare-bones and open-ended at the same time: out of the box, it can’t do much other than manage a simple, blog-style website, but it can be extended by means of additional software packages, called “plugins”, that are designed to hook into the core WordPress software and provide extra services ranging from footnotes4 to spam filters.5

Given all this, one of the challenges when I first started the site was to find a plugin I could use to insert references into posts in a simple, consistent way. Actually, that’s not quite true. What I wanted was a system that could make use of my existing library of references, managed by a Windows program called Mendeley6, in as few steps as possible. In the end, I settled on the following Heath Robinson scheme:

1. I configured Mendeley to periodically save my library to a BibTeX file on my local drive. (BibTeX7 is a standard, more or less, that describes references in a machine-readable way so that they can be exchanged between computer programs. It isn’t the only such standard and nor, arguably, is it the best, but it is the one that Mendeley supports.)
2. I configured Dropbox,8 a service that synchronises files across multiple computers, to make my BibTeX library available online. (You can view it here).
3. I installed a WordPress plugin called Papercite,9 designed specifically to load and render BibTeX references, and pointed it towards my online library of references.

Dropbox gymnastics aside, it was Benjamin Piwowarski’s Papercite plugin that made the whole thing work. It read the BibTeX file at my Dropbox URL, teased it apart into individual references and, when I asked it to, it turned those references into nicely formatted HTML to be embedded within my blog posts.

So far, so good.

The problem was that Papercite never quite worked as I would have liked it to. Its formatting was a little too rigid, for instance, and it would occasionally refuse to pick up new references in my library. To encounter problems like these isn’t unusual, of course; whether it’s a piece of software or a screwdriver, no tool can ever be the right one for all users all of the time. Fortunately, Benjamin continued to improve Papercite month on month — right up until the middle of 2015, when the previously steady stream of new versions and bug fixes dried up.

Partly because active development on Papercite had come to a halt and partly because I wanted to learn more about PHP, the programming language in which it was written, in November 2015 I took a copy of Papercite and started to iron out its kinks. I modified it so that it would run on Windows, when previously it worked only on Unix-like operating systems; I made the formatting of its references more malleable, so as to fit in better with Shady Characters’ visual appearance; I fixed its handling of special characters (rather a necessity for a site about unusual marks of punctuation); I made it a little faster here and there; I made it more forgiving when it encountered unfamiliar types of reference; and, finally, I upgraded it to work with the most recent version of PHP.

All this and Papercite would still occasionally refuse to work, whether in terms of finding, parsing or rendering references. I have no doubt that some of the problems were due to my own ham-fisted modifications, but other were inherent in the plugin itself. It was time for a change.

Bibcite: a new citation plugin

And so here we are. For the past few months I’ve been working on a new citation plugin for WordPress — one that is inspired by Benjamin’s approach to Papercite, but also one that takes advantage of some of the innovations that have been made in the eight years since I started Shady Characters. It’s called Bibcite and you can find it here, on Github, the software hosting site.

In writing Bibcite I decided to mimic Papercite’s mode of operation as closely as I could. As such, it does much the same set of things:

• It loads a library of BibTeX references from a defined URL
• It stores those references in WordPress’s internal database
• When asked to process a blog post or a page of text, it looks for “shortcodes” — that is, textual tags like [bibcite] and [bibtex] — to decide where to insert references and how to format them. For the most part, Bibcite understands the same set of shortcodes as Papercite and will treat them in the same way.

It’s worth mentioning that none of this is especially big or clever. Bibcite is deliberately constructed to be a mundane piece of software that does predictable things.

The one thing that I have changed is how Bibcite converts computer-friendly BibTeX references into human-readable citations. A BibTeX reference looks something like this:

@misc{Suarez2010,
	author = {Harris, N.},
	booktitle = {The Oxford companion to the book},
	editor = {Suarez, Michael F. and Woudhuysen, H. R.},
	isbn = {9780198606536},
	mendeley-groups = {A Book about Books},
	pages = {807--808},
	publisher = {Oxford University Press},
	title = {{Hypnerotomachia Poliphili}},
	year = {2010}
}

Somewhat mechanical, no? We, as humans, would rather see something like this:

• Harris, N. “Hypnerotomachia Poliphili”. In The Oxford Companion to the Book, edited by Michael F. Suarez and H. R. Woudhuysen, 807-808. Oxford University Press, 2010.

There are already a number of software tools that can perform this conversion. Papercite employs one called OSBiB,10 for example, dating back to 2005, that comes with its own special file format to describe how a BibTeX reference should be converted into a formatted citation. The set of such conversions available to end users like myself has always been relatively limited (I had to modify one of OSBiB’s built-in styles for use here at Shady Characters, for instance), which can be a problem in a world where every academic journal defines its own citation style.

Enter the Citation Style Language (CSL) project.11 This is a huge endeavour that takes in a number of related subject areas:

1. It provides a formal schema for representing machine-readable citations
2. It provides a formal schema for describing conversions from machine-readable reference to human-readable citation
3. It makes available an enormous library of conversions covering the house styles of thousands of different journals
4. It provides software tools for various programming languages (PHP included) that tie all this together

These last two parts are what makes CSL so useful. These days, no sensible software developer starts a program from scratch and, as such, to find a project that has already cracked the hardest problems you would otherwise have faced is incredibly heartening.

In particular, Bibcite could not work without Sebastian Böttger’s citeproc-php12 library, one of the many pieces of software that make CSL available in different programming languages. It also contains the thousands of citation styles defined in CSL’s official repository,13 making them available to plugin users with no further configuration steps. (Notably, the one thing that the CSL project does not help with is converting from hoary old BibTeX references to shiny, modern CSL references, but that too is already taken care of by Benjamin Geißler’s helpful reference converter project.14)

In the end, Bibcite is isn’t so much as a complete software product as the glue between a number of different software libraries, which is exactly what a modern program should be.*

What’s next?

By design, very little should change here at Shady Characters. Posts that contain references will still display them as footnotes in the text and as a bibliography down at the end of each post. Formatting will be a little different, but not significantly. It should be business as usual, more or less, with the exception that you should see fewer error messages referring to Dropbox URLs or other referencing issues. If you come across anything that looks broken or is otherwise unhelpful, please let me know either here in the comments or via the Contact page.

If you’re interested in having a look at the source code behind the plugin or in learning how to use it, Bibcite is now available at Github. For the moment, it’s most suited to experienced WordPress users: the plugin is not yet available via the official WordPress plugin repository and some PHP knowledge is required to build it. It’s still very much a work in progress and I expect it to stay that way for some time.

If you do happen to try out Bibcite, please let me know what you think either in the comments or over at Github, where you can raise an issue or propose changes to the code itself via a pull request.

And that’s it! Thanks for reading and for indulging me in this technical digression. And now, back to your regular programme.

1.

“London Kerning”. Medium.

 ↢

2.

Open Source Initiative. “The Open Source Definition (Annotated)”. Accessed May 20, 2018.

 ↢

3.

WordPress.org. “About”. Accessed May 20, 2018.

 ↢

4.

“Civil Footnotes”. WordPress Plugins.

 ↢

5.

WordPress Plugins. “Akismet Anti-Spam”.

 ↢

6.

“Mendeley.Com”.

 ↢

7.

“BibTeX”.

 ↢

8.

“Dropbox”. Accessed May 29, 2018.

 ↢

9.

“Papercite”. Benjamin Piwowarski’s website. Accessed May 20, 2018.

 ↢

10.

Grimshaw, Mark, Andrea Rossato, Guillaume Gardey, and Christian Boulanger. “OSBiB v3.0”. Bibliophile.

 ↢

11.

D’Arcus, Bruce, Simon Kornblith, Frank G. Bennet Jr., and Rintze M. Zelle. “Citation Style Language”. Accessed May 21, 2018.

 ↢

12.

Böttger, Sebastian. “Citeproc-php”.

 ↢

13.

Citation Style Language. “Styles”.

 ↢

14.

Geißler, Benjamin. “Converter”.

 ↢

*

In addition to the libraries mentioned above, Bibcite is built on Devin Vinson’s WordPress Plugin Boilerplate and uses code from the following projects:

• Apache log4php
• cocur/slugify
• PSR Log
• renanbr/bibtex-parser
• Twig

A big thank-you to all of the respective project owners, contributors and maintainers! ↢