Scope of this Primer

This primer is meant as a first introduction to the Citation Style Language (CSL), and is primarily aimed towards those wishing to create or modify CSL styles. Some knowledge about the structure of XML or HTML will come in handy. If you are completely unfamiliar with either markup language, check out one of the many online introductions to XML, e.g. W3Schools' XML Tutorial.

What is CSL?

The Citation Style Language (CSL) is an open and free 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.

However, correctly citing sources is often far from trivial: the more popular styles (e.g. American Psychological Association (APA), Chicago Manual of Style or Modern Language Association (MLA)) have extensive formatting requirements, whereas many academic journals use custom in-house styles.

The Citation Style Language makes citing easier. With CSL styles and CSL-compatible reference management software (such as Zotero or Mendeley), you can automatically generate citations and bibliographies according to your style of preference [1]. You can also easily switch styles, e.g. when you decide to submit your manuscript to a different journal. Finally, CSL offers advanced localization support: with a single CSL style, you can format citations and bibliographies in any of several dozen different languages, using localized terms, date formats, and punctuation.

[1]	Over 1500 CSL styles are 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 main groups:

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

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

   • "author-date" and "author" styles

     Sentence (author-date)

     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). [2]

     Sentence (author)

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

     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.

   [2]	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, a number or 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). Some "note" styles include a bibliography listing the cited works. An example of a note style:

   "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. [†]" [3]

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

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

   [3]	Example taken from Darwin 1882 The descent of man, and selection in relation to sex. London: John Murray. 2nd ed., 15th thousand, http://darwin-online.org.uk/content/frameset?itemID=F955&viewtype=image&pageseq=1.

In-text citations or foot and endnotes can reference 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" contains a "bibliographic entry" 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 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 is of the "in-text" type (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 shows of the output of two macros: "author-short" (<text macro="author-short"/>), which renders the author surnames, and "issued" (<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 produce in-text citations like:

(Doe 1999)

and

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

The sort element specifies how cites within a citation are sorted. In our case, cites are first sorted by the year of issue, and then by the author surnames. This changes the example citation above 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 the formatting of bibliographic entries, and functions very similar to the citation element. 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. The four text elements are wrapped in a group element, and the output of the different elements is separated by a space. Then, preceded by ", ", the journal volume and the pages of the article are rendered. Each bibliographic entry ends with a period. 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? The main purpose of macros is 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, styles are 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. Here we will use the online validator Validator.nu:

1. Select the style you want to validate. When using "Address" option, provide the URL to the style and check the "Be lax about HTTP Content-Type" check-box. With "File Upload", select the style file on your computer. With "Text Field", paste the style code into the text box and select the "XML; don't load external entities" option for the "Parser" drop-down menu.
2. Paste 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. Click the "Validate" button.

When we perform these steps, we get an error:

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

From line 50, column 7; to line 50, column 40

up>↩ <text variable="doi" prefix=", "/>↩ <

Oops! It seems that "doi" is an invalid variable name. After checking the CSL 1.0 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.