Skip to content

Introduction to Editing CSL

Jump to bottom Edit New page
rmzelle edited this page Dec 5, 2011 · 4 revisions

Introduction to Editing CSL

.. contents:: Table of Contents

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.

.. _CSL 1.0 specification: http://citationstyles.org/downloads/specification.html

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, like the Citation Style Language (CSL).

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 <https://bitbucket.org/fbennett/citeproc-js/wiki/Home>_ 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|

.. |csl-infrastructure| image:: https://github.com/rmzelle/writing/raw/master/csl-infrastructure.png

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
    <?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++ <http://notepad-plus-plus.org/>_ for Windows, TextWrangler <http://www.barebones.com/products/textwrangler/>_ for MacOS X, and the cross-platform <oXygen/> XML Editor <http://www.oxygenxml.com/>_ (commercial), GNU Emacs <http://www.gnu.org/software/emacs/>_ (in nXML mode <http://www.thaiopensource.com/nxml-mode/>) and jEdit <http://www.jedit.org/> (with its XML plugin <jEdit>_).

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 <http://www.zotero.org>_ reference manager comes with two CSL tools. After installing the Zotero Firefox add-on, you can access the Zotero Preview pane <http://www.zotero.org/support/dev/citation_styles/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 <http://www.zotero.org/support/dev/citation_styles/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