Using upgrade.xsl

First, check whether the styles that you wish to update validate against the CSL 0.8.1 schema.

Then use an XSLT processor to update the styles. Available options are the command-line tools Saxon and xsltproc. Alternatively, one of the (more user-friendly) online converters, such as the one offered by www.shell-tools.net can be used. For the latter tool, the instructions are:

1. Paste the contents of upgrade.xsl into the "xslt" text box at http://www.shell-tools.net/index.php?op=xslt
2. Paste the contents of the CSL 0.8 style into the "xml" text box
3. Click the "Submit Query"-button
4. Copy the text from the "output" text box to a suitable text editor (e.g. Notepad on Windows) and save the file with a .csl-extension.

Finally, after the conversion, it is recommended to validate the converted style, this time against the CSL 1.0 schema.

Links

The role of the cs:link element is to store URLs (using the href attribute) while indicating how these URLs are related to the style (using the rel attribute). The use of rel has been slightly modified in CSL 1.0 to increase clarity. First, every cs:link element should carry the rel attribute. Secondly, the available values of rel have changed to:

• "self". The URI of the CSL style itself (only for independent styles). In CSL 0.8 "self" was implicit when ref wasn't used.
• "independent-parent". Renamed from "source", this indicates the URI of the independent parent style (only for dependent styles).
• "template". Can be used to link to the style from which the current style is derived.
• "documentation". Links to documentation, e.g. the style guide. Note that "documentation" has replaced "homepage".

Formats and Fields

The cs:category element has two purposes: to indicate for which field(s) of study a style is relevant (e.g. "biology") and to indicate the format of the style (e.g. "author-date"). In CSL 0.8 the term attribute was used for both cases. With CSL 1.0, term has been replaced with two attributes: citation-format, to indicate the citation format, and field, to indicate the field of study. An example:

<style>
  <info>
    <category citation-format="author-date"/>
    <category field="biology"/>
  </info>
</style>

In CSL 0.8 the possible citation formats were: "author-date", "label", "note", "numeric" and "in-text". In CSL 1.0 "in-text" has been replaced with "author" (a format that only shows author names in in-text citations, like the MLA style).

ISSN and ISSN-L

ISSN-identifiers unambiguously identify journals. While CSL 0.8 allowed only a single ISSN identifier to be included in the style metadata section, CSL 1.0 now supports multiple ISSNs (e.g. the ISSNs of the print and online editions of a journal), as well as the relatively new ISSN-L identifier. For example:

<style>
  <info>
    <issn>1234-1234</issn>
    <issn>4567-4567</issn>
    <issnl>8521-8521</issnl>
  </info>
</style>

Localized Dates

CSL 1.0 introduces support for date localization. This feature is optional: styles can still define dates in the usual non-localized format. To use a localized date, all you need to do is use cs:date with the form attribute set to either text (for dates like 'April 21, 2008') or numeric (e.g. '4/21/08'). As demonstrated in the example below, it is not necessary to specify any cs:date-part elements for localized dates:

<style>
  <bibliography>
    <layout>
      <!-- old-fashioned, unlocalized date -->
      <date variable="accessed">
        <date-part name="year"/>
        <date-part name="month" form="numeric" prefix="-"/>
        <date-part name="day" prefix="-"/>
      </date>
      <!-- default localized date -->
      <date variable="accessed" form="numeric"/>
    </layout>
  </bibliography>
</style>

The format of localized dates (i.e. punctuation and the order of the date-parts) is specified in the "locales-xx-XX.xml". As with terms, localized date formats can be overridden within styles. In addition, localized dates can be customized within a style via two options. First, the date-parts attribute can be added to cs:date to control which date-parts are shown. With the default value of year-month-day the whole date is shown. With year-month and year only the year/month and year date-parts are shown, respectively. The second option is the ability to redefine how one or more cs:date-part element are formatted. Note that the order of cs:date-part elements for a localized date within cs:layout doesn't affect the rendering order of the date-parts (this in contrast with non-localized dates or dates specified within cs:locale, where the order of the cs:date-part elements does control the rendering order). Neither does the presence or absence of cs:date-part elements affect which date-parts are shown (this is controlled via the date-parts attribute described above). Instead, cs:date-part elements allow you to override specific properties of the localized date-parts (e.g. the form attribute of the month-date-part can be set to "short"). Note that changes made in this way affect all locales. An example illustrating the different options:

<style>
  <!-- a modified date format for the English locale -->
  <locale xml:lang="en">
    <date form="text">
      <date-part name="month" suffix=" " form="short"/>
      <date-part name="day" suffix=", "/>
      <date-part name="year"/>
    </date>
  </locale>
  <bibliography>
    <layout>
      <!-- localized date that only shows the year and month -->
      <date form="text" date-parts="year-month"/>
      <!-- localized date in numeric format with leading zeros -->
      <date form="numeric">
        <date-part name="month" form="numeric-leading-zeros"/>
        <date-part name="day" form="numeric-leading-zeros"/>
      </date>
    </layout>
  </bibliography>
</style>

In developing CSL 1.0 it was recognized that robust date localization requires a clear distinction between style-specific and locale-dependent formatting of dates. As a result, some limitations have been placed on the use of cs:date when used for localized dates. First, affixes (prefixes and suffixes) on cs:date are considered style-specific formatting (e.g. parentheses around the date: "(2000)"). It is therefore not allowed to apply affixes to cs:date when this element is used within cs:locale (in both styles and "locales-xx-XX.xml" files). Instead, all locale-specific affixes should be applied to the cs:date-part elements. Conversely, it is not allowed to apply affixes to cs:date-part elements when the parent cs:date calls a localized date. Secondly, cs:date may not carry the delimiter attribute when used in a style to call a localized date. In CSL 1.0 this attribute can be used to specify a delimiter for the date-parts, which is considered locale-specific formatting.

N.B. When creating a localized date format, consider graceful scaling of dates when applying affixes to the cs:date-part elements. As an example, consider the date format "May 1, 2008". By using the following arrangement of affixes, correct dates are obtained for any value of the date-parts attribute:

<date form="text">
  <date-part name="month" suffix=" "/>
  <date-part name="day" suffix=", "/>
  <date-part name="year"/>
</date>

Localized Options

In addition to localized dates and terms, CSL 1.0 now also supports localized options (although for now, there is only one such an option, punctuation-in-quote). The default value of localized options is set for each locale in the "locales-xx-XX.xml" files, but these values can be overridden using the cs:style-options element within cs:locale in a CSL style. An example:

<style>
  <locale xml:lang="en">
    <style-options punctuation-in-quote="true"/>
  </locale>
</style>

Default Locale

To prevent localization of styles (which might be desirable for journal-specific styles) the default-locale attribute can be included on the cs:style element (this attribute already existed in CSL 0.8, but was not supported by Zotero). Its value should be a locale code (e.g. "fr-FR" for French). An example:

<style default-locale="fr-FR"/>

N.B. With CSL 0.8 there was some confusion about the use of default-locale, and some style authors included the xml:lang attribute instead. In CSL 1.0 xml:lang is no longer allowed as an attribute on cs:style.

Citation Collapsing

CSL 1.0 offers finer control of citation collapsing. First, two new options have been introduced, both of which are set as attributes on cs:citation: year-suffix-delimiter, which defines the delimiter for subsequent year suffixes (e.g. the comma in "Doe 2000a,b, Smith 1999"), and after-collapse-delimiter, which defines the delimiter between a group of collapsed citations and the subsequent citation (e.g. the semicolon in "Doe 2000a, b; Smith 1999, Williams 2002"). Both attributes default to the delimiter set on the cs:layout element within cs:citation. Secondly, "year-suffix-ranged" has been added as a possible value of the collapse attribute of cs:citation. If collapse is set this value, citations are collapsed as with "year-suffix", but ranges of year-suffixes are collapsed as well (e.g. "Doe 2000a,b,c,e" would become "Doe 2000a-c,e"). An example of how these attributes are set:

<style>
  <citation collapse="year-suffix-ranged" year-suffix-delimiter="," after-collapse-delimiter=";">
    <layout delimiter=", " />
  </citation>
</style>

Dates

<style>
  <citation>
    <layout>
      <date variable="issued">
        <date-part name="month" suffix=" "/>
        <date-part name="year" range-delimiter="/"/>
      </date>
    </layout>
  </citation>
</style>

<style>
  <citation>
    <layout>
      <date variable="issued">
        <date-part name="month" suffix=" "/>
        <date-part name="year"/>
      </date>
    </layout>
  </citation>
</style>

<style>
  <citation>
    <layout delimiter="; ">
      <choose>
        <if is-uncertain-date="issued">
          <text term="circa" form="short" suffix=" "/>
        </if>
      </choose>
      <date variable="issued">
        <date-part name="year"/>
      </date>
    </layout>
  </citation>
</style>

Names

<names variable="editor translator">
  <name />
  <label form="short" prefix=" (" suffix=")" />
</names>

<names variable="author">
  <name/>
  <et-al font-style="italic" prefix=" "/>
</names>

<names variable="author">
  <name/>
  <et-al term="and others" prefix=" "/>
</names>

<names variable="author">
  <name form="long">
    <name-part name="family" font-variant="capitalize-all"/>
  </name>
</names>

Ordinal Numbers

To allow for localization of ordinal numbers, CSL 1.0 includes the new terms ordinal-01 to ordinal-04. For the en-US locale, these terms have the values "st", "nd", "rd" and "th" (resulting in ordinal numbers of "1st", "2nd", "3rd", "4th", etc.). In addition, support for long ordinals has been introduced with the terms long-ordinal-01 to long-ordinal-10 ("first", "second", ..., "tenth"). Long ordinals can be selected by using cs:number and setting the form attribute to "long-ordinal".

Original Publisher

Sometimes (older) books are republished by a different publisher. To indicate the original publisher, and the location of the original publisher, CSL 1.0 adds two new variables, original-publisher and original-publisher-place. Note that CSL 0.8 already included the name variable original-publisher, which could only be used with cs:names. The variables original-publisher and original-publisher-place in CSL 1.0 are 'normal' variables, and can be used with cs:text.

Pages

CSL 1.0 introduces two new page variables: "page-first" and "number-of-pages". The existing variable "pages" is still used for page ranges (e.g. of journal articles and book chapters). The variable "page-first" holds the first page of the page range. The variable "number-of-pages" is used to indicate the total number of pages of an item (e.g. a book or thesis).

In addition, a new global (non-localized) option, page-range-format, has been added to control the collapsing of page ranges. This attribute, set on cs:style, can have the values "expanded" (e.g. "321-328"), "minimal" ("321-8"), and "chicago" ("321-28", which follows the collapsing rules of the Chicago Manual of Style). When the attribute isn't present, the content of the "page"-variable is shown as is. An example:

<style page-range-format="chicago">
  <bibliography>
    <layout>
      <text variable="page"/>
    </layout>
  </bibliography>
</style>

Pluralization

In CSL 1.0 small changes have been made to the use of plural. As with CSL 0.8, this attribute can be set on cs:text and cs:label. When used on cs:text, plural can still be set to "false" to use the singular form of a term (the default), or to "true" to use the plural form. But when used on cs:label, different values are now available. With "contextual" (the default value), the plurality of the variable determines whether the singular or plural form of the term is used (e.g. "page 43" and "pages 3-5"). With "never" and "always" respectively the singular or plural form of the term is used, regardless of the plurality of the variable. An example:

<number variable="edition" form="ordinal"/>
<text term="edition" plural="false"/>
<group>
  <label variable="page" plural="always"/>
  <text variable="page"/>
</group>

N.B. The plural attribute was one of the few cases where the implementation in Zotero did not follow the CSL 0.8 schema.

Quotes

CSL 1.0 introduces new terms for inner ("open-inner-quote" and "close-inner-quote", e.g. ‘ and ’) and outer quotes ("open-quote" and "close-quote", e.g. “ and ”). Together with the new punctuation-in-quote-option (see Punctuation around Quotes), quotes applied with the quotes attribute are now fully localized.

<text value="Voyage of 'The Beagle'"/>

<text prefix="Speak, " value="'friend'"  suffix=", and enter" quotes="true"/>

Rich Text Markup within Fields

Although not part of the CSL 1.0 specification, the new citeproc-js CSL processor used by Zotero supports an exciting new feature: the ability to use rich text markup within item fields. This markup is applied with a small set of HTML(-like) tags:

• <b> - bold
• <i> - italics
• <sc> - small-caps
• <sub> - subscript
• <sup> - superscript

E.g. if a Zotero item has the title "Ca²⁺ levels in <i>Homo sapiens</i>", this will render as "Ca²⁺levels in Homo sapiens". Rich text markup can also be used with the value attribute of cs:text, but here special XML characters ("<", ">") have to be escaped, e.g.:

<text value="&lt;b&gt;some bold text&lt;/b&gt;"/>

In contrast, markup used with the prefix and suffix attributes is not recognized. Finally, note that bold and italics markup are subject to flipflopping.

second-field-align

The second-field-align attribute can be used to align any subsequent lines of a bibliography entry with the beginning of the second field. In CSL 0.8 the value of this attribute could be set to "true" or "margin" to place the first field respectively in the margin, or flush against it. In CSL 1.0 "true" has been renamed to "flush".

Stripping Periods

A new attribute, strip-periods, can now be set on cs:date-part (only for name="month"), cs:label and cs:text. The attribute is inactive when set to "false" (the default value), but if set to "true", any periods are stripped from the variable contents. strip-periods replaces the include-period attribute that was part of CSL 0.8.

strip-periods is especially useful for journal abbreviations. There are plans to improve support for journal abbreviations in future versions of CSL (e.g. by using lookup lists to find the correct journal abbreviation given a certain journal title), but for now it is recommended that users include periods for journal abbreviations in their (Zotero) libraries. With the help of strip-periods, styles can then either use the journal abbrevation as is, or use a version without periods. An example:

<text variable="container-title" form="short" strip-periods="true"/>

would output "Appl Environ Microbiol" if the journal abbreviation for the Zotero item is "Appl. Environ. Microbiol.".

Year Suffix

Year-suffixes are included automatically when the disambiguate-add-year-suffix attribute on cs:citation is set to "true". However, some styles desire special markup of year-suffixes, such as italics (e.g. "2000a, b"). For this CSL 1.0 introduces the year-suffix variable, which can be used to explicitly specify the location and formatting of year-suffixes. An example:

<style>
  <citation>
    <layout delimiter=", ">
      <date variable="issued">
        <date-part name="year"/>
      </date>
      <text variable="year-suffix" font-style="italic"/>
    </layout>
  </citation>
</style>

Layout Control with the Display Attribute

CSL 0.8 included a display attribute, with possible values of "block" or "inline-block", intended to provide some control over the layout of bibliography entries. However, it remained unimplemented by any known processor, and was not used in any known styles. In CSL 1.0, the display attribute has been refined and extended: it is now restricted to rendering-element children of cs:layout under cs:bibliography, and has possible values of "block", "left-margin", "right-inline", and "indent".

By leveraging the styling features of the target rendering platform (HTML, a word processor, a document processing system), the enhancements to display permit the implementation of sophisticated formatting effects, such as publication listings headed by the name of each author. See the CSL 1.0 Specification for further details on the use of this attribute.