-
Notifications
You must be signed in to change notification settings - Fork 0
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?
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 [#]_. 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).
.. [#] 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:
|csl-infrastructure|
.. |csl-infrastructure| image:: https://github.com/rmzelle/writing/raw/master/csl-infrastructure.png
First, the reference manager needs a CSL processor to process the CSL style and item metadata [#]_. 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).
.. [#] Zotero and Mendeley both use the open source JavaScript
citeproc-js <https://bitbucket.org/fbennett/citeproc-js/wiki/Home>_ 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
<?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 "<" 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.
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.