Scope of this Primer

This document is meant as a first introduction to the Citation Style Language (CSL) and is primarily aimed at those who wish to create or modify CSL styles. Some prior knowledge of XML or HTML will come in handy. If these terms are unfamiliar to you, check out one of the many online introductions to XML, e.g. the one at http://www.w3schools.com/xml/.

What is CSL?

The Citation Style Language (CSL) is an open and free [1] XML based language for writing CSL styles, which describe how citations and bibliographies should be formatted. Citing plays an important role in academic literature: it can be used for attribution (which is important to avoid plagiarism), to give context to your research, and to eliminate the need to repeat previously published results.

Unfortunately, correctly citing is often far from trivial. Style guides like the American Psychological Association (APA) Style, The Chicago Manual of Style or the MLA Style dedicate many pages to citation formatting. To complicate things further, many academic journals use proprietary styles that deviate from these 'generic' citation styles.

The Citation Style Language was designed to make citing easier. When CSL styles are used in combination with CSL compatible reference management software (such as Zotero or Mendeley), citations and bibliographies can be automatically generated according to the style of preference [2]. You can quickly switch between styles (e.g. if a manuscript has to be submitted to a different scientific journal). Finally, terms, date formats, and punctuation rules used for citations and bibliographies can be changed at a whim to follow one of 38 different locales (ranging from Afrikaans to Hebrew to Vietnamese).

[1]	If you use CSL styles, you don't have to worry about getting sued! We promise!

[2]	There are already over a thousand CSL styles available at http://www.zotero.org/styles

Different Classes of Citation Styles

Before we leap into the world of CSL, let's take a look at the different types of citation styles that are in use. Citation styles can be divided in two groups:

1. "in-text" styles: when a work is cited, a citation is added to the sentence. The citation points directly to a corresponding bibliographic entry in the bibliography.

   Various types of "in-text" styles exist. The main types are:

   • "author-date" and "author" styles

     Sentence [3]

     Yeast cells were grown at 25°C in batch cultures on 0.5% methanol for 36 hours (Gidijala et al. 2008) or in carbon-limited chemostat cultures (van der Klei et al. 1991; Zwart et al. 1983). (author-date)

     Yeast cells were grown at 25°C in batch cultures on 0.5% methanol for 36 hours (Gidijala et al.) or in carbon-limited chemostat cultures (van der Klei et al.; Zwart et al.). (author)

     Bibliography

     Gidijala L, Bovenberg RA, Klaassen P, van der Klei IJ, Veenhuis M, et al. (2008) Production of functionally active Penicillium chrysogenum isopenicillin N synthase in the yeast Hansenula polymorpha. BMC Biotechnol 8: 29.

     van der Klei IJ, Harder W, Veenhuis M (1991) Methanol metabolism in a peroxisome-deficient mutant of Hansenula polymorpha: a physiological study. Arch Microbiol 156: 15-23.

     Zwart KB, Veenhuis M, Harder W (1983) Significance of yeast peroxisomes in the metabolism of choline and ethanolamine. Antonie Van Leeuwenhoek 49: 369-385.

   • "numeric" styles

     Sentence

     Yeast cells were grown at 25°C in batch cultures on 0.5% methanol for 36 hours [6] or in carbon-limited chemostat cultures [21, 22].

     Bibliography

     6. Gidijala L, Bovenberg RA, Klaassen P, van der Klei IJ, Veenhuis M, et al. (2008) Production of functionally active Penicillium chrysogenum isopenicillin N synthase in the yeast Hansenula polymorpha. BMC Biotechnol 8: 29.

     21. Zwart KB, Veenhuis M, Harder W (1983) Significance of yeast peroxisomes in the metabolism of choline and ethanolamine. Antonie Van Leeuwenhoek 49: 369-385.

     22. van der Klei IJ, Harder W, Veenhuis M (1991) Methanol metabolism in a peroxisome-deficient mutant of Hansenula polymorpha: a physiological study. Arch Microbiol 156: 15-23.

   • "label" styles

     Sentence

     Yeast cells were grown at 25°C in batch cultures on 0.5% methanol for 36 hours [GBKv2008] or in carbon-limited chemostat cultures [ZwVH1983; vaHV1991].

     Bibliography

     [GBKv2008] Gidijala L, Bovenberg RA, Klaassen P, van der Klei IJ, Veenhuis M, et al. (2008) Production of functionally active Penicillium chrysogenum isopenicillin N synthase in the yeast Hansenula polymorpha. BMC Biotechnol 8: 29.

     [ZwVH1983] Zwart KB, Veenhuis M, Harder W (1983) Significance of yeast peroxisomes in the metabolism of choline and ethanolamine. Antonie Van Leeuwenhoek 49: 369-385.

     [vaHV1991] van der Klei IJ, Harder W, Veenhuis M (1991) Methanol metabolism in a peroxisome-deficient mutant of Hansenula polymorpha: a physiological study. Arch Microbiol 156: 15-23.

   [3]	The illustrating sentence is from Gidijala L, Kiel JAKW, Douma RD, Seifar RM, van Gulik WM, et al. 2009 An Engineered Yeast Efficiently Secreting Penicillin. PLoS ONE 4(12): e8317. doi:10.1371/journal.pone.0008317

2. "note" styles: when a work is cited, a marker is added to the sentence. The marker, which can be a number or a symbol, points to a foot or endnote. In contrast to in-text citations, foot or endnotes typically contain all information required to locate the cited work(s). Optionally, the cited works can also be included in a bibliography. An example of a note style [4]:

   "In the Island of St. Kilda, according to Martin, [*] the men do not acquire beards until the age of thirty or upwards, and even then the beards are very thin. On the Europæo-Asiatic continent, beards prevail until we pass beyond India; though with the natives of Ceylon they are often absent, as was noticed in ancient times by Diodorus. [†]"

   [*]	'Voyage to St. Kilda' (3rd edit. 1753), p. 37.

   [†]	Sir J. E. Tennent, 'Ceylon,' vol. ii. 1859, p. 107.

   [4]	Example taken from Darwin 1882 The descent of man, and selection in relation to sex. London: John Murray. 2d ed., 15th thousand, available online.

It is not uncommon for in-text citations or foot and endnotes to include references to multiple works. In CSL jargon, the entire in-text citation or note is called the "citation". A "citation" that references multiple works contains multiple "cites", with each "cite" referencing a single work. Similarly, the "bibliography" consists of "bibliographic entries", one for each cited work.

XML Declaration

<?xml version="1.0" encoding="UTF-8"?>

The first line of the style is the XML declaration, and tells you that the style is written according to the XML specification (remember that CSL is an XML based language).

Style

<style xmlns="http://purl.org/net/xbiblio/csl" version="1.0" class="in-text">
  ...
</style>

Style is the root element of the CSL style. The attributes on this element specify that a) all the elements in the style are part of the CSL schema (xmlns="http://purl.org/net/xbiblio/csl"), b) that the style is compatible with CSL 1.0 (version="1.0") and c) that the CSL style describe an "in-text" type of citation style (class="in-text").

Info

<info>
  <title>My First Style</title>
  <id>my-first-style</id>
  <updated>2008-10-29T21:01:24+00:00</updated>
</info>

The first child element of the style root element is info. The info element contains information about the style. In this case the child elements of info give the style title, an ID to identify the style and the date and time the style was last updated.

Citation

<citation>
  <sort>
    <key macro="issued"/>
    <key macro="author-short"/>
  </sort>
  <layout prefix="(" suffix=")" delimiter="; ">
    <text macro="author-short"/>
    <text macro="issued" prefix=" "/>
  </layout>
</citation>

Skipping the macro elements for now, we reach the citation element. This element describes how the "in-text" citations should be formatted. The layout element specifies that each citation should be wrapped in parentheses (prefix="(" suffix=")"), and that cites in a citation should be delimited by "; ". Each cite consists of the output of two macros: the "author-short" macro (<text macro="author-short"/>), which renders the author surnames, and the "issued" macro (<text macro="issued"/>), which renders the year of issue. The output of the "issued" macro is preceded by a space (prefix=" "). This layout element could result in "in-text" citations like:

(Doe 1999)

and

(Hayden, Scott, Muffley 1980; Strangelove 1964; Mandrake 1964)

The sort element specifies how cites within a citation should be sorted. In our case, cites are first sorted by the year of issue, and then by the author surnames. This changes the second example citation to:

(Mandrake 1964; Strangelove 1964; Hayden, Scott, Muffley 1980)

Bibliography

<bibliography>
  <sort>
    <key macro="author"/>
    <key macro="issued"/>
  </sort>
  <layout suffix=".">
    <group delimiter=" ">
      <text macro="author"/>
      <text macro="issued" prefix="(" suffix=")"/>
      <text variable="title" suffix="."/>
      <text variable="container-title" font-style="italic"/>
    </group>
    <group prefix=", ">
      <text variable="volume" suffix=":"/>
      <text variable="page"/>
    </group>
  </layout>
</bibliography>

The bibliography element describes how bibliographic entries should be formatted, and functions very similar to the citation element. In the bibliography, more information is provided for the cited works. The "author" macro shows the given and surnames of the authors. The next three text elements output respectively the year of issue, the article title and, in italics, the title of the journal. They are wrapped in a group element, which specifies that the output of the different text elements should be delimited by single spaces. Then, preceded by ", ", the journal volume and the pages of the article are rendered. The sort element at the beginning of the bibliography element specifies that bibliographic entries should first be sorted by the author names, and then by the year of issue. This code could results in bibliographic entries like:

Hayden, S., Scott, G. C., Muffley, M. (1980) How to Stop Worrying and Love the Bomb. Nuclear Journal, 15:548-553.

Mandrake, L. (1964) Improving the Management of Recall Codes. Journal of International Strategics, 8:2790-795.

Strangelove (1964) Nuclear War and How to Prevent It. War Games, 2:23-25.

Macros

<macro name="author-short">
  <names variable="author">
    <name form="short"/>
  </names>
</macro>
<macro name="author">
  <names variable="author">
    <name name-as-sort-order="all" initialize-with=". "/>
  </names>
</macro>
<macro name="issued">
  <date variable="issued">
    <date-part name="year"/>
  </date>
</macro>

So what exactly happens in these macros? Macros are a device to reuse formatting instructions. E.g. in our style, the "author-short" macro is used both for rendering (<text macro="author-short"/>) and for sorting (<key macro="author-short"/>). By using macros, the styles is made more compact and easier to maintain. The three macros have the following output:

• the "author-short" macro lists a names element, which renders all the names stored in the "author" variable. The name child element of names specifies that each name should be shown in its "short" form, i.e. only the surname should be shown).
• the "author" macro is very similar to the "author-short" macro. However, here the author names are shown in their default "long" form, i.e. with both the given and surname. All names are inverted (name-as-sort-order="all"), with the surname preceding the given name (e.g. "Doe, John"). Given names are initialized (initialize-with=". "), with initials being separated by ". " (e.g. "Doe, J. R.")
• the "issued" macro lists a date element, which renders the date stored in the "issued" variable. As only a date-part child element is included for "year", only the year of issue is shown.

Validation

After making changes to a CSL style, it is always a good idea to check whether the style still validates. Correct processing of CSL styles requires that CSL styles are both written in correct XML and conform to the CSL schema. Both these checks can be performed with an XML validator. In this case, we will use the online validator at http://validator.nu/:

1. Select the style. Select the "Text Field" option in the first dropdown menu, and paste the modified style into the text box.
2. Paste the html link to the CSL schema into the "Schemas" text field. For CSL 1.0: http://bitbucket.org/bdarcus/csl-schema/raw/855dcc00cba7/csl.rnc
3. In the "Parser" drop-down menu, select "XML; don't load external entities"
4. Check the option "Be lax about HTTP Content-Type".
5. Click the "Validate" button.

When we perform these steps, we get a few harmless warnings, but also an error:

Error: Bad value doi for attribute variable on element text from namespace http://purl.org/net/xbiblio/csl.

From line 49, column 6; to line 49, column 39

oup>↩ <text variable="doi" prefix=" "/>↩ <

Oops! It seems that "doi" is an invalid variable name. After checking the CSL specification, we discover that the variable name should be capitalized ("DOI"). When we make this correction (<text variable="DOI" prefix=" "/>), and run the validation again, we get the message:

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

As you see, validation is a powerful tool to help you find and eliminate typing errors and other mistakes in CSL styles.