Introduction to Editing CSL

Introduction to Editing CSL

Table of Contents

• Preface
• What is CSL?
  • CSL Infrastructure
• XML Basics
• Tools for Editing
  • Text/XML editors
    • jEdit
  • XML Validators
    • Validating with Validator.nu
  • Zotero's Preview and Reference Test panes

Preface

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.

What is CSL?

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.

CSL Infrastructure

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.

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. The latter is described in more detail below.

jEdit

|link| jEdit is an open source cross-platform Java-based text editor, which can be turned into a powerful XML editor by installing the "XML" plugin. Follow these instructions to set up jEdit for editing CSL styles and locales:

1. Install jEdit
2. Run jEdit, and open the Plugin Manager ("Plugins" > "Plugin Manager..."). Go to the "Install" tab, select the "XML" plugin and click the "Install" button (this will also install the "SideKick" plugin). The plugin will add an "XML" menu entry in the "Plugins" menu.
3. CSL XML files should preferably be indented with 2 spaces per level. Indentation settings can be set via "Utilities" > "Global Options..." under jEdit/Editing. Set "Tab width" and "Indent width" to "2", and check the "Soft (emulated with spaces) tabs" checkbox. You can now automatically (re)indent your XML file via "Plugins" > "XML" > "Indent XML".
4. To enable real-time validation against the CSL schema, |link| download (and unzip) the CSL 1.0 schema. Select the schema in jEdit ("Plugins" > "XML" > "Set Schema...", click the "Browse..." button, and select the "csl.rnc" file). Check the "Parse on Keystroke" option found under "Plugins" > "SideKick" to enable real-time validation.

XML Validators

Instead of validating directly in the text editor, you can also use a dedicated XML validator. Validators that support the Relax NG Compact format of the CSL schema include the command-line tools |link| Jing and |link| RNV, and the online Jing-powered |link| Validator.nu.

Validating with Validator.nu

To use the online XML validator |link| Validator.nu:

1. Select the style you want to validate. When using "Address" option, provide the URL to the style. With "File Upload", select the style file on your computer. With "Text Field", paste the style code into the text box.

2. Enter the URL to the CSL 1.0 schema into the "Schemas" text field: https://github.com/citation-style-language/schema/raw/v1.0/csl.rnc

3. Check the "Be lax about HTTP Content-Type" check-box and select the "XML; don't load external entities" option in the "Parser" drop-down menu.

4. Click the "Validate" button. While you can generally ignore warnings, you should pay attention to errors. If your style is well-formed and conforms to the CSL schema, you will get the message:

   The document validates according to the specified schema(s) and to

   additional constraints checked by the validator.

Zotero's Preview and Reference Test panes

The |link| Zotero reference manager comes with two tools for editing CSL styles. 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 the library of the Zotero add-on. The Zotero Reference Test pane, accessible via "chrome://zotero/content/tools/csledit.xul", allows you to edit a style with instant previewing, again using the items selected in your Zotero library.