Skip to content

Introduction to Editing CSL

Jump to bottom Edit New page
rmzelle edited this page Dec 14, 2011 · 12 revisions

Introduction to Editing CSL

Preface

This is an introduction to the Citation Style Language (CSL) and a tutorial for editing CSL styles. A more comprehensive (but also more technical) overview of CSL is available in the form of the CSL 1.0 specification.

What is CSL?

Citations are crucial in scholarly communication, but manually formatting references is a laborious task. The burden is increased by the diversity of citation styles, as journals and publishers often use their own citation style format. Luckily, reference management programs like Zotero can be used to automatically generate citations and bibliographies. To format references in the desired style, these programs need descriptions of each style in a computer-readable format. The open XML-based Citation Style Language (CSL) is such a format.

CSL Infrastructure

A reference manager that uses CSL to format references needs:

  • CSL styles, describing the different citation styles
  • item metadata, the bibliographic details of the cited resources (e.g., a cited book's title, authors, etc.).
  • a CSL processor, to process the CSL style. Zotero and Mendeley both use the open source JavaScript citeproc-js CSL processor.
  • CSL locale files. CSL supports automatic localization of styles. A single CSL style can be used to format references in any language. The locale files provide default localization data (e.g., translations of common terms like "in" and "and", date formats, and grammar preferences) for a selection of languages.
  • citing details. Many reference managers have word processor plugins so that citations and bibliographies can be easily inserted in manuscripts. In this case, 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, which items are cited together in a single citation, etc.).

csl-infrastructure

XML Basics

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 version attribute, 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 "&lt;" for "<", "&gt;" for ">", "&amp;" for "&", "&apos;" for ', and "&quot;" for ". For example, the link "http://domain.com/?tag=a&id=4" should be escaped as <link href="http://domain.com/?tag=a&amp;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.

Tools for Editing

Text/XML editors

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

XML Validators

Instead of validating directly in the text editor, you can also use a dedicated XML validator. See Validation for more information.

Zotero's Reference Test and Preview panes

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. Users of Zotero Standalone can access these tools through the Zotero preferences panel.

Add a custom footer
Add a custom sidebar
Clone this wiki locally