upgrade-notes.txt

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
`Citation Style Language 1.0`__
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
?????????????
Upgrade Notes
?????????????

__ `Table of Contents`_

.. class:: fixed

   `citationstyles.org`__

__ http://citationstyles.org/

.. class:: info-version

   2012-06-15

.. class:: contributors

   **Author**
   
   Rintze M. Zelle, PhD
       
   **Contributors**

   | Frank G. Bennett, Jr.
   | Bruce D'Arcus
   
   |CCBYSA|_

.. |CCBYSA| image:: http://i.creativecommons.org/l/by-sa/3.0/80x15.png
.. _CCBYSA: http://creativecommons.org/licenses/by-sa/3.0/

========

.. contents:: Table of Contents

========

Citation Style Language 1.0 - What's New?
=========================================

The release of `Citation Style Language 1.0
<http://citationstyles.org/citation-style-language/schema/>`_ represents a
significant update of the Citation Style Language (CSL), an open XML language to
describe citation styles. This document describes the changes compared to CSL
0.8 (released in March 2009).

**Nota Bene** These notes include many XML examples to demonstrate new CSL
features. Please note that these examples are reduced to a minimum, and often
don't constitute valid CSL styles. In addition, when references are made to the
XML elements of CSL, the CSL namespace ("cs") is always attached as a prefix
(e.g. ``cs:citation`` for the ``citation`` element). However, for CSL styles it
is customary to declare the default CSL namespace on the root ``cs:style``
element (<style xmlns="http://purl.org/net/xbiblio/csl" />), which eliminates
the need to include this namespace for each element.

Project Home(s)
+++++++++++++++

The first change is that `CitationStyles.org
<http://citationstyles.org/>`_ is the new home of the CSL project (the old home
was located at `<http://xbiblio.sourceforge.net/csl/>`_). The new website
will be the central location to find CSL schemas, documentation and styles.

For CSL development the `SourceForge xbiblio mailing list
<http://sourceforge.net/mailarchive/forum.php?forum_name=xbiblio-devel>`_ will
be kept in use. Code hosting has moved around a bit. A switch from
SourceForge.net to `Bitbucket <https://bitbucket.org/bdarcus/>`_ in 2010
has been followed by a move to `GitHub
<https://github.com/citation-style-language/>`_ in 2011.

Documentation
+++++++++++++

Prior to the release of CSL 1.0, CSL documentation was rather scarce. Most of
what was available was hosted on the `Zotero wiki
<http://www.zotero.org/support/>`_. With CSL 1.0, we improved on this situation.
In addition to these upgrade notes, a full specification_ has been made
available. As before, the `schema
<http://citationstyles.org/citation-style-language/schema/>`_ itself is also a
source of information, although reading the schema requires some understanding
of `RELAX NG Compact <http://www.relaxng.org/>`_, the XML schema language
in which the CSL schema is written.

.. _specification: http://citationstyles.org/downloads/specification.html

Schema
++++++

Split Schema
------------

Whereas the CSL 0.8 schema consists of a single file, the CSL 1.0 schema has
been split into the following files:

* csl.rnc - The core of the CSL schema. This file contains most of the schema
  logic and calls the other schema files
* csl-categories.rnc
* csl-terms.rnc
* csl-types.rnc
* csl-variables.rnc

The main advantage of splitting up the schema is that the schema will be easier
to maintain. If you wish to validate styles against the CSL schema, make sure
all the files are located in the same directory, and validate against csl.rnc.

Validation
----------

The CSL 1.0 schema has been extended with two Schematron rules to make sure
styles don't use ``cs:text`` and ``cs:key`` elements that call non-existing
``cs:macro`` elements. Note that not all validators support embedded Schematron
code (e.g. `Jing <http://www.thaiopensource.com/relaxng/jing.html>`_ just
ignores the rules). In addition, the CSL 1.0 schema can now be used to validate
the `locales files`_ (e.g. "locales-en-US.xml"), which contain
localizations of terms, date formats and style options.

.. _locales files: https://github.com/citation-style-language/locales

Styles
++++++

Updating CSL 0.8 Styles
-----------------------

CSL 1.0 is backward incompatible with CSL 0.8, which means that CSL 0.8 styles
don't work with CSL 1.0 processors. Fortunately, it is possible to
(automatically) update CSL 0.8 styles to the CSL 1.0 format using the
`upgrade.xsl
<https://github.com/citation-style-language/utilities/raw/master/update.xsl>`_
XSLT stylesheet. This conversion has been performed for all the styles in the
`Zotero Style Repository <http://www.zotero.org/styles>`_. However, if
you use (custom) CSL styles that aren't included in this style repository, you
might need to do this yourself.

Using upgrade.xsl
~~~~~~~~~~~~~~~~~

First, check whether the styles that you wish to update validate against the
`CSL 0.8.1 schema
<http://citationstyles.org/citation-style-language/schema/>`_.

Then use an XSLT processor to update the styles. Available options are the
command-line tools `Saxon <http://saxon.sourceforge.net/>`_ and
`xsltproc <http://xmlsoft.org/XSLT/xsltproc2.html>`_. Alternatively, one of the
(more user-friendly) online converters, such as the one offered by
`www.shell-tools.net <http://www.shell-tools.net/index.php?op=xslt>`_ can be
used. For the latter tool, the instructions are:

1. Paste the contents of `upgrade.xsl
   <https://github.com/citation-style-language/utilities/raw/master/update.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`_.

.. _CSL 1.0 schema: http://citationstyles.org/citation-style-language/schema/

Version Number
--------------

Starting with CSL 1.0, styles (and locales files) must indicate the CSL version
with which they are compatible. All CSL 1.0 styles should include the
``version`` attribute with the value "1.0" on the cs:style element, e.g.:

.. sourcecode:: xml

    <style version="1.0" class="in-text"/>

For "locale-xx-XX.xml" files this attribute should be set on the root
``cs:locale`` element.

Options as Attributes
---------------------

In CSL 0.8, citation- and bibliography-specific style options were set with
``cs:option`` elements. In CSL 1.0 this element is no longer used. Instead,
options are set using attributes. CSL 1.0 includes global options, which affect
the output of both the ``citation`` and ``bibliography`` sections, and which are
set as attributes on the ``cs:style`` element. Options that are
citation-specific are now set on the ``cs:citation`` element, while
bibliography-specific options are set on the ``cs:bibliography`` element.

Style Metadata
--------------

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:

.. sourcecode:: xml

    <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
<http://www.issn.org/2-22637-What-is-an-ISSN-L.php>`_ identifier. For example:

.. sourcecode:: xml

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

Localization
------------

The "locales-xx-XX.xml" files (with "xx-XX" indicating the locale, e.g. "en-US"
for "English - United States") that are part of CSL previously had only the role
of supplying localized terms. With CSL 1.0, these locale files also contain
localized style options and localized date formats. Because of this, some
changes have been made to the XML format of these files: ``cs:locale`` has
replaced ``terms`` as the root element, the ``xml:lang`` and ``xmlns``
attributes are now applied to the ``cs:locales`` element, and several new
elements have been introduced for the localization of dates and options
(``cs:date``, ``cs:date-part`` and ``cs:style-options``).

As before, it is possible to use the ``cs:locale`` element in styles to override
any content of the "locales-xx-XX.xml" files. The ``cs:locale`` element can be
used with or without the ``xml:lang`` attribute. If ``xml:lang`` is not set, the
contents of the ``cs:locale`` element will be used for all locales. If
``xml:lang`` is set to a locale code, the content of the ``cs:locale`` element
will override the content of the specified locale. N.B. a ``cs:locale`` element
with the ``xml:lang`` attribute takes priority over a ``cs:locale`` element
without the attribute. For example,

.. sourcecode:: xml

    <style>
      <locale>
        <terms>
          <term name="et-al">et alii</term>
        </terms>
      </locale>
      <locale xml:lang="en">
        <style-options punctuation-in-quote="true" />
        <terms>
          <term name="et-al">and others</term>
        </terms>
        <date form="text">
          <date-part name="month" suffix=" " form="short"/>
          <date-part name="day" suffix=", "/>
          <date-part name="year"/>
        </date>
      </locale>
    </style>

with regard to the "et-al" term, this will result in the use of "and others" for
the English locales, and of "et alii" for all other locales.

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:

.. sourcecode:: xml

    <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:

.. sourcecode:: xml

    <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:

.. sourcecode:: xml

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

====================  =============
``date-parts`` value  date
====================  =============
"year-month-day"      "May 1, 2008"
"year-month"          "May 2008"
"year"                "2008"
====================  =============

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:

.. sourcecode:: xml

    <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:

.. sourcecode:: xml

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

Formatting
----------

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:

.. sourcecode:: xml

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

Dates
~~~~~

AD and BC
^^^^^^^^^

CSL 1.0 includes two new terms, ``ad`` and ``bc`` (Anno Domini and Before
Christ). These terms are automatically appended to years: ``bc`` is added to
negative years (e.g. 2500BC), while ``ad`` is added to positive years of less
than four digits (79AD).

Date Ranges
^^^^^^^^^^^

CSL 1.0 adds support for date ranges. By default, date ranges are delimited by
an en-dash (e.g. May–July 2008). Custom delimiters can be set on the
``cs:date-part`` elements with the new ``range-delimiter`` attribute. The
attribute value set on the largest date-part ("day", "month" or "year") that
differs between the two dates of the date range will then be used instead of the
en-dash. For example,

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

would result in "May–July 2008" and "May 2008/June 2009".

Seasons
^^^^^^^

CSL 1.0 includes four new season terms, ``season-01`` to ``season-04``
(respectively Spring, Summer, Autumn and Winter). If a date includes a season
instead of a month, the season term will substituted the month date-part. E.g.,

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

would result in "May 2008" and "Winter 2009".

Uncertain Dates
^^^^^^^^^^^^^^^

Two new features of CSL 1.0 allow for special formatting of uncertain dates.
First, CSL 1.0 introduces the ``is-uncertain-date`` conditional. This
conditional tests "true" when a date is flagged as uncertain. The second addition
is the new "circa" term. For example,

.. sourcecode:: xml

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

would result in "2005" (certain date) and "ca. 2003" (uncertain date).

Names
~~~~~

delimiter-precedes-last
^^^^^^^^^^^^^^^^^^^^^^^

The ``delimiter-precedes-last`` attribute on ``cs:names`` controls the use of
the name delimiter between the last and next-to-last name in name lists. In CSL
0.8, this attribute could be set to either ``always`` or ``never``. To include
the delimiter for lists of three or more names ("Doe, Smith, and Williams") and
to exclude it for lists of only two names ("Doe and Smith"), you would have to
leave out the attribute. Now, in CSL 1.0, it is also possible to explicitly set
the last behavior by using the value "contextual".

Editorial Director
^^^^^^^^^^^^^^^^^^

CSL 1.0 includes a new name variable, ``editorial-director``. This addition is
mostly specific to French, where the "Directeur de la publication" role is
common.

Editor/Translator Name Collapsing
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If a ``cs:names`` element has its ``name`` attribute set to "editor translator"
(or "translator editor"), CSL 1.0 collapses both name lists when their contents
is identical. If a label is specified, and collapsing occurs, the newly added
``editortranslator`` term is used. For example,

.. sourcecode:: xml

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

could result in "John Doe (ed. & trans.)".

Et al.
^^^^^^

A new element, ``cs:et-al``, can now be included within ``cs:names``. This adds
two important features. First, formatting can now be set independently for the
``et-al`` term. For example,

.. sourcecode:: xml

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

results in "Doe *et al.*". Secondly, it is now possible to use two different
``et-al`` terms within a single style (e.g. one for in-text citations and one
for the bibliography). The desired term, "et-al" (the default) or "and others",
is set with the ``name`` attribute on the ``cs:et-al`` element. For example,

.. sourcecode:: xml

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

would yield "Doe and others" (note that both terms are localized).

Formatting Name Parts
^^^^^^^^^^^^^^^^^^^^^

CSL 1.0 introduces the ability to separately format given and family names.
Formatting is specified via the new ``cs:name-part`` element, a child of
``cs:name``. The ``name`` attribute of this element should be set to either
"family" or "given". Note that the order of ``name-part`` elements does not
affect the order in which the name parts are shown. An example, resulting in
names like "John SMITH":

.. sourcecode:: xml

    <names variable="author">
      <name form="long">
        <name-part name="family" text-case="uppercase"/>
      </name>
    </names>

Inheritable Name Options
^^^^^^^^^^^^^^^^^^^^^^^^

In CSL 0.8, any attribute used for name formatting had to be included for each
occurrence of the ``cs:names`` element, even if names were identically formatted
for all these elements. To reduce the need for duplication, CSL 1.0 introduces
inheritable options: the attributes ``and``, ``delimiter-precedes-last``,
``initialize-with``, ``name-as-sort-order`` and ``sort-separator`` can now also
be set on ``cs:style``, ``cs:citation`` and ``cs:bibliography``. The attributes
``form`` and ``delimiter`` have been made available as ``name-form`` and
``name-delimiter``, respectively, as the original attribute names have different
uses when set on ``cs:style``, ``cs:citation`` and ``cs:bibliography``.
Similarly, the ``names-delimiter`` attribute has been introduced as a companion
of the ``delimiter`` attribute on ``cs:names``.

When a name attribute is set on ``cs:style``, ``cs:citation`` or
``cs:bibliography``, its value is used for all ``cs:names`` elements within the
element carrying the attribute. However, when an element lower in the hierarchy
carries the same attribute with a different value, this value will override the
value(s) specified higher in the hierarchy.

In addition to these changes, CSL 1.0 also includes more fine-grained control
for et-al settings. The attributes ``et-al-min``, ``et-al-use-first``,
``et-al-subsequent-min``, ``et-al-subsequent-use-first`` now behave like any
other ``cs:name`` attribute, and thus can be set on ``cs:style``,
``cs:citation``, ``cs:bibliography`` and ``cs:name``.

Hyphenation of Compound Given Names
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

A new attribute, ``initialize-with-hyphen``, can be set on ``cs:style`` to
control hyphenation of compound given names (e.g. "Jean-Luc Picard"). When set
to "true" (the default), a hyphen is added when the given name is initialized
("J.-L. Picard"). With "false" the hyphen is left out ("J.L. Picard").

Name Particles
^^^^^^^^^^^^^^

Many Western names consist not only of a given and a family name, but also of
one or more name particles. To control how these particles are handled, CSL 1.0
introduces a new option, ``demote-non-dropping-particle``, which can be set as
an attribute on ``cs:style``. To understand how this option works, it is
important to recognize that not all particles are equal: name particles can be
either kept or dropped when only the surname is shown (from now on we will refer
to these two types as non-dropping-particle and dropping-particle,
respectively). A single name can contain particles of both types (in this case
the non-dropping-particle always comes after the dropping-particle). For
example, the French name "Gérard de la Martinière" can be deconstructed into:

============ =====================
"Gérard"     given name
"de"         dropping-particle
"la"         non-dropping-particle
"Martinière" family name
============ =====================

When only the surname is shown, only the non-dropping-particle is kept: "La
Martinière". However, when names are inverted (with the family name preceding
the given name), styles often differ in name particle handling. First, the
non-dropping-particle can be either prepended to the family name (e.g. "de
Koning, W.") or appended (after initials or given names, e.g. "Koning, W. de").
Note that the dropping-particle is always appended in inverted names. Secondly,
if the non-dropping-particle is prepended to the family name, names can be
sorted in two ways: the non-dropping-particle can remain part of the family name
(as part of the primary sort key; example A), or it may be separated from the
family name and become (part of) a secondary sort key, joining the
dropping-particle, if available (example B). The different sort orders are
illustrated below:

**Sort order A: non-dropping-particle not demoted**

-  primary sort key: "la Martinière"
-  secondary sort key: "de"
-  tertiary sort key: "Gérard"

**Sort order B: non-dropping-particle demoted**

-  primary sort key: "Martinière"
-  secondary sort key: "de la"
-  tertiary sort key: "Gérard"

The ``demote-non-dropping-particle`` attribute can be set to the following
values:

- "never": the non-dropping-particle is treated as part of the family name,
  whereas the dropping-particle is appended (e.g. "de Koning, W.", "la
  Martinière, Gérard de"). The non-dropping-particle is part of the primary sort
  key (example A, e.g. "de Koning, W." appears under "D").
- "sort-only": as "never", with the exception that non-dropping-particle is
  demoted to a secondary sort key (see example B, e.g. "de Koning, W." appears
  under "K").
- "display-and-sort" (default): the dropping and non-dropping-particle are
  appended to the rest of the name (e.g. "Koning, W. de" and "Martinière, Gérard
  de la"). When names are sorted, both particles are part of the secondary sort
  key (see example B, e.g. "Koning, W. de" appears under "K").

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:

.. sourcecode:: xml

    <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:

.. sourcecode:: xml

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

Quote Substitution
^^^^^^^^^^^^^^^^^^

If a field (e.g. a variable) contains a matching set of quotation marks (", ',
or the quotation marks defined by the ``open-inner-quote`` and
``close-inner-quote`` terms), then these quotation marks are replaced by those
defined by the ``open-quote`` and ``close-quote`` terms. For example:

.. sourcecode:: xml

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

will render as: Voyage of “The Beagle”

Flipflopping
^^^^^^^^^^^^

Flipflopping occurs when a field (e.g. a variable) contains a matching set of
quotation marks (", ', or the quotation marks defined by the ``open-quote``,
``close-quote``, ``open-inner-quote`` and ``close-inner-quote`` terms), or when
it contains markup for italics or boldfacing (see `Rich Text Markup within
Fields`_). For example:

.. sourcecode:: xml

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

will render as “Speak ‘friend’, and enter”. Quotes flipflop between inner
(``open-inner-quote`` and ``close-inner-quote``) and outer (``open-quote`` and
``close-quote``) quotes. Italics flipflop between italics and the normal
font-style, and boldface between bold and the normal font-weight.

Punctuation around Quotes
^^^^^^^^^^^^^^^^^^^^^^^^^

The localized option ``punctuation-in-quote`` is used to specify whether
punctuation (commas and periods) should appear within ("true", e.g. for American
English) or outside quotation marks that have been applied by the style ("false"
(default value), e.g. for British English). As such, it can toggle the style
output between

    Douglas Adams, "The Hitchhiker's Guide to the Galaxy," 1979.

and

    Douglas Adams, "The Hitchhiker's Guide to the Galaxy", 1979.

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<sup>2+</sup> levels in <i>Homo
sapiens</i>", this will render as "Ca\ :sup:`2+`\ 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.:

.. sourcecode:: xml

    <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`_.

.. _citeproc-js: http://bitbucket.org/fbennett/citeproc-js/

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:

.. sourcecode:: xml

    <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. "``2000``\ *a*, *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:

.. sourcecode:: xml

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

Disambiguation
--------------

The disambiguation algorithm specified in CSL 0.8 followed the Chicago Manual of
Style. CSL 1.0 supports additional disambiguation methods through the addition
of a new ``givenname-disambiguation-rule`` attribute, which can be used in
combination with the existing ``disambiguate-add-names`` and
``disambiguate-add-givenname`` attributes.

The ``givenname-disambiguate-rule`` option accepts values of "all-names",
"all-names-with-initials", "primary-name", "primary-name-with-initials", and
"by-cite". The first value specifies the Chicago Manual of Style method, which
assures that all names included in citations uniquely identify the relevant
author. The second does the same, but will not expand initialized names. The
third and fourth values specify analogous methods, but here the transformation
of names is limited to the first-listed name. The last option transforms names
only as necessary to uniquely identify references listed in the bibliography. A
more detailed discussion of the disambiguation options can be found in the CSL
1.0 Specification.

Sorting
-------

CSL 1.0 includes several new features to allow for more complex reference
sorting. The first change is that the ``form`` attribute on ``cs:name`` can now
be set to "count". With this value, the enclosing ``cs:names`` returns the
number of names in the name variable instead of the names themselves. When used
for a sort key, this makes it possible to sort according to the number of
authors (or any other kind of contributor). An example:

.. sourcecode:: xml

    <style>
      <macro name="author">
        <names variable="author">
          <name form="count"/>
        </names>
      </macro>
      <bibliography>
        <sort>
          <key macro="author"/>
        </sort>
        <layout/>
      </bibliography>
    </style>

The second change consists of two new attributes for the ``cs:key`` element,
``names-min`` and ``names-use-first``. These attributes, when set, override the
values of ``et-al-min`` and ``et-al-min-first``, respectively. The following
example shows how with these attributes a bibliography can be sorted
alphabetically, while only taking the first author into account:

.. sourcecode:: xml

    <style>
      <macro name="author">
        <names variable="author">
          <name/>
        </names>
      </macro>
      <bibliography>
        <sort>
          <key macro="author" names-min="1" names-use-first="1"/>
        </sort>
        <layout/>
      </bibliography>
    </style>

Back-References in Note Styles
------------------------------

CSL 1.0 adds two features related to back-referencing in note styles. First, the
`position` conditional supports a new value, "near-note". It tests true when an
item has been previously cited, and the distance between the current and most
recent use (measured in number of footnotes or endnotes) does not exceed the
value of the new `near-note-distance` attribute. This attribute, which has a
default value of 5, may be set on `cs:citation`. An example:

.. sourcecode:: xml

    <style class="note">
      <citation near-note-distance="3">
        <layout>
          <choose>
            <if position="near-note">
              ...
            </if>
            <else>
              ...
            </else>
          </choose>
        </layout>
      </citation>
    </style>

N.B. The value of "near-note" is *always* false for references that are not in a
footnote/endnote.

The second feature is the new `first-reference-note-number` variable. When an
item has been previously cited, this variable holds the number of the first note
to cite the item.

Variables
---------

CSL 1.0 introduces a number of new variables:

* "event-date". Replaces "event" date variable.
* "first-reference-note-number". See `Back-References in Note Styles`_
* "jurisdiction". The geographic unit for which a resource (such as legislation)
  is relevant.
* "number-of-pages". See `Pages`_.
* "page-first". See `Pages`_.
* "year-suffix". See `Year Suffix`_.

Terms
-----

CSL 1.0 also introduces a number of new terms:

* "ad" and "bc". See `AD and BC`_.
* "author". This term can be applied as a label to author names. For most
  styles, this term will consist of an empty string ("").
* "by".
* "editortranslator". See `Editor/Translator Name Collapsing`_.
* "ordinal-01`` to "ordinal-04" and "ordinal-01" to "ordinal-10". See
  `Ordinal Numbers`_.
* "original-publisher" and "original-publisher-place". See `Original Publisher`_.
* "reference". This term replace the "references" term from CSL 0.8.
* "season-01" to "season-04". These terms map to respectively spring,
  summer, fall and winter. See `Seasons`_.

.. [1]
   A hat tip to user `komrade <http://www.zotero.org/komrade>`_ of
   the Zotero forums, whose review of the major style guides led to
   this array of rule-sets.