Introduction to Editing CSL
Table of Contents
This is an introduction to the Citation Style Language (CSL) and the technologies it uses (e.g., XML), and a tutorial for creating and modifying CSL styles and locale files. This guide does not discuss all the features of CSL. For that, you can consult the (more technical) CSL 1.0 specification, which we will reference throughout this guide.
While citing resources (books, journal articles, etc.) is an integral part of scholarly communication, formatting references often consumes much time and effort. Many journals and publishers require use of their own custom citation style format, and citation style guides are often either very elaborate or too concise and lacking in details.
Luckily, computer software can ease this burden. Reference management software not only helps with keeping track of scholarly resources, but can also help by automatically generate citations and bibliographies in different styles [1]. But to know how to format references, such reference managers need descriptions of each style in a computer-readable format. In this guide we focus on one of these formats, the open source Citation Style Language (CSL).
| [1] | Reference managers store the individual details of each resource separately (e.g. the item's title, issue date, authors, etc.). Together, these details make up the item metadata. Formatted references are generated by piecing together the different parts of metadata. |
In addition to item metadata (the details of the cited resources) and CSL styles (describing the different citation formats), there are a few more parts that make up the CSL infrastructure, shown below:
First, the reference manager needs a CSL processor to process the CSL style and item metadata [2]. Secondly, CSL styles are accompanied by a collection of CSL locale files, which are used to render the references in the desired locale (with a single CSL style, you can generate references in a range of languages). Finally, if the citations and bibliographies are rendered via a word processor plugin, the item metadata is supplemented by details on how the items are cited in the manuscript (e.g. the order in which the items are cited, and which items are cited together in a single citation).
| [2] | Zotero and Mendeley both use the open source JavaScript citeproc-js CSL processor. |
For those new to XML (or HTML), this section gives a short overview of what you need to know about XML in order to edit CSL styles and locale files.
Let's take a look at the following piece of CSL XML:
<?xml version="1.0" encoding="utf-8"?>
<style xmlns="http://purl.org/net/xbiblio/csl" class="in-text" version="1.0">
<info>
<title>Academic Medicine</title>
<id>http://www.zotero.org/styles/academic-medicine</id>
<link href="http://www.zotero.org/styles/vancouver" rel="independent-parent"/>
<category citation-format="numeric"/>
<category field="medicine"/>
<updated>2011-10-10T23:31:02+00:00</updated>
</info>
</style>There are several concepts and terms you need to be familiar with. These are:
-
XML Declaration. The first line of any style or locale file should always
be the XML declaration. It most cases, this will be
<?xml version="1.0" encoding="utf-8"?>. This line designates the document as XML, and specifies the XML version ("1.0") and character encoding ("utf-8") used. -
Elements and Hierarchy. The basic building blocks of XML documents are
elements, which are hierarchically structured. Each XML document contains a
single root element (for CSL styles this is
<style/>). If an element contains other elements, the parent element is split into a start tag (<style>) and an end tag (</style>). In our example, the<style/>element has one child element,<info/>. This element has several children of its own, which are grandchildren of the grandparent<style/>element. Element tags are always wrapped in less-than ("<") and greater-than (">") characters (e.g.<style>). For an empty-element tag, ">" is preceded by a forward-slash (e.g.<category/>), while for end tags "<" is followed by a forward-slash (e.g.</style>). Indentation (with spaces or tabs) helps showing the hierarchical levels. -
Attributes and Element Content. There are two ways to add additional
information to elements. First, XML elements can carry one or more attributes
(the order of attributes on an element is arbitrary). Every attribute needs a
value. For example, the style element carries a
versionattribute, set to value of "1.0", indicating that the style is CSL 1.0. Secondly, elements can store non-element content between start and end tags, e.g. the content of the<id/>element is "http://www.zotero.org/styles/academic-medicine". -
Escaping. Some characters have to be substituted when used for purposes
other than for defining the XML structure (e.g. when used in attribute values
or non-element content), or, in the case of the ampersand ("&"), for
substitution itself. Escape sequences are "<" for "<", ">" for ">",
"&" for "&", "'" for ', and """ for ". For example, the link
"http://domain.com/?tag=a&id=4" should be escaped as
<link href="http://domain.com/?tag=a&id=4"/>. - Well-formedness and Schema Validity. Unlike HTML, XML does not allow for any markup errors. Any error, like forgetting an end tag, having more than one root element, or incorrect escaping will break the XML document and prevent it from being processed. XML documents that follow the XML specification and are error-free are "well-formed". For well-formed styles and locale files there is a second level of testing, involving the CSL schema. This schema describes which elements and attributes are allowed and how they must be used. When a style or locale file is tested against the schema rules (this is called "validation") and passes, the file is valid CSL. Only well-formed and valid CSL files can be expected to work properly.
CSL styles and locales can be edited with any plain text editor. However, editors with XML support can make editing easier with features like automatic indenting, tag closing, and real-time testing for well-formedness and schema validation. Suitable editors include Notepad++ for Windows, TextWrangler for MacOS X, and the cross-platform <oXygen/> XML Editor (commercial), GNU Emacs (in nXML mode) and jEdit (with its XML plugin). The latter is described in more detail below.
Instead of validating directly in the text editor, you can also use a dedicated XML validator. See Validation for more information.
The Zotero reference manager comes with two CSL tools. After installing the Zotero Firefox add-on, you can access the Zotero Preview pane by entering "chrome://zotero/content/tools/cslpreview.xul" in the Firefox address bar. The Preview pane generates citations and bibliographies for all installed CSL styles, using the items selected in your local Zotero library. The Zotero Reference Test pane, accessible via "chrome://zotero/content/tools/csledit.xul", allows you to edit a style with instant previewing, again using items from your Zotero library.