====== CSL Syntax Summary ======

This page is intended to be a brief description of some of the constructs that can be used when creating CSL definitions.

It also shows how they interact with zotero where appropriate.



===== Preamble =====

At the beginning of the XML markup is the usual header information. This will look something like this
<code xml>
<?xml version="1.0" encoding="UTF-8"?>
<style xmlns="http://purl.org/net/xbiblio/csl" class="in-text" xml:lang="en">
</code>
This can be copied more or less verbatim, the ''class'' is the only part you may want to change. Note that the namespace declaration on the root element binds the elements in the style to that namespace URI.
The class can either be ''note'' or ''in-text''. Use note for citation styles that use numbered citations, and ''in-text'' for those that have author-date like types.


===== Info =====
The next section contains information about the edition of the markup definition. The content model for the CSL metadata is borrowed from Atom. The idea behind this is to include sufficient information that CSL styles can be hosted in distributed style repositories, that users may be able to subscribe to collections of styles in their fields of interest, and that the style files can be updated transparently as needed. 

As with Atom, the ''cs:id'' element is required, and must be a valid, stable, and unique URI. Make sure you choose the ID carefully, as tools will use this to assess the identity of the style. If you cannot give it a good, stable, unique URI that is HTTP resolvable, you can instead use some like a GUID in URN form.

Likewise, tools will also use the date-time value of the ''cs:updated'' element to assess whether the style has changed since last accessed or cached.
<code xml>
<info>
 <title>A new format</title>
 <id>http://www.zotero.org/namespaces/CSL/newformat</id>
 <author>
  <name>My name</name>
  <email>my-address@wherever.com</email>
 </author>
 <updated>2007-10-12 03:33:00+05:00</updated>
 <summary>My great new style format.</summary>
</info>
</code>
This can also include various other attributes, including ''contributor'' and a number of other fields which may be useful. The ''cs:category'' element can be particularly useful for browsing large repositories and for allowing users to subscribe to styles within particular content areas. For this reason, be sure to include them to ensure the infrastructure of CSL styles scales gracefully. 







===== Macros =====
The next section is typically a list of macro definitions. These are sort of like subroutines that can be called later in the description to make similar styles for parts.
**Effective use of macros is a key to making good styles**. Ideally, in fact, the main layout sections for the citation and bibliography should be quite simple, and simply call a series of macros.

An example macro is
<code xml>
<macro name="editor-translator">
  <names variable="editor translator" prefix="(" suffix=")" delimiter=", ">
    <name and="symbol" initialize-with=". " delimiter=", "/>
    <label form="short" prefix=", " text-transform="capitalize" suffix="."/>
  </names>
</macro>
</code>

It is particularly crucial in author-date styles that rely on author names for sorting that one create a macro that can handle a wide variety of cases, including resources that do no include listed authors. Example:
<code xml>
<macro name="author">
  <names variable="author">
    <name name-as-sort-order="all" 
          and="symbol" 
          sort-separator=", " 
          initialize-with=". "
          delimiter=", " 
          delimiter-precedes-last="always"/>
    <label form="short" prefix=" (" suffix=".)" text-transform="capitalize"/>
    <substitute>
      <names variable="editor"/>
      <names variable="translator"/>
      <text macro="title"/>
    </substitute>
  </names>
</macro>
</code>

This example includes the logic that allows the formatter to gracefully adapt to a wide-range of resource types. Likewise, one could create a macro for titles like so:
<code xml>
  <macro name="title">
    <choose>
      <if type="book">
        <text variable="title" text-case="sentence" font-style="italic"/>
      </if>
      <else>
        <text variable="title" text-case="sentence"/>
      </else>
    </choose>
  </macro>
</code>
Note here that CSL reserves three types as generic fallbacks. In this case, for example, "book" is a generic fallback for all resources that have the characteristic that they are essentially self-contained items. So, for example, a music album will use this rule in the absence of any rules specific to its type.

Because of the value of macros and the potential to reuse them in different styles and automated software tools, it is recommended that you try to adapt common macro names, such as:
  * title
  * author
  * author-short
  * editor-translator
  * publisher
  * access (for URLs and archival locations)
  * event (for conference, hearings, etc.)
  * issued
  * issued-year
  * pages
  * citation-locator (for cited pages and such)
  * locators (volume and issue, for example)
  * container-prefix (for the "In" and such that often preceded container info)
  * edition (for edition or version info)

===== Citation =====
Now we get to the first of the key parts. The citation construct is the part that appears in-line in the text. This may just be a simple number in some styles, or an (author, date) type of citation.
<code xml>
<citation>
  <option />
  <layout>
    some layout
  </layout>
</citation>
</code>
The options allow you to control various things about the citation, which will be considered later.
The layout is where the actual information is formatted for putting on the page.
The layout directive itself has some optional parameters, the most common being to use prefix and suffix and delimiter. For instance
<code xml>
<layout prefix="(" suffix=")" delimiter=";">
</code>
is common for the author/date format layout.

===== Bibliography =====
This is the second of the key parts, where the bibliography is formatted. It is very similar to the citations section.
<code xml>
<bibliography>
  <option .../>
  <layout>
    ...
  </layout>
</bibliography>
</code>
Again, a set of options to control some of the layout, then the layout itself.

===== Options =====
There are numerous options available. Most apply to both citations and the bibliography, although there are a few that are specific. Here is a summary of them with an example of each.

==== Common options ====
These apply to both bibliography and citation sections.

  * et-al-min - the minimum number of authors for the et-al rules to kick in. 
<code xml><option name="et-al-min" value="6"/></code>
  * et-al-use-first - How many authors to include before the et-al part. 
<code xml><option name="et-al-use-first" value="6"/></code>

==== Citation only options ====
  * et-al-subsequent-min - the minimum authors for et-al in subsequent references. Only applies to citations. 
<code xml><option name="et-al-subsequent-min" value="6"/></code>
  * et-al-subsequent-use-first - the minimum authors for et-al in subsequent references. Only applies to citations. 
<code xml><option name="et-al-subsequent-use-first" value="1"/></code>
  * disambiguate-add-year-suffix a true/false to indicate how to disambiguate two references that are otherwise the same. This adds a suffix to the year, so you'll get 2007a, 2007b etc. 
<code xml><option name="disambiguate-add-year-suffix" value="true"/></code>
  * disambiguate-add-names - add additional names, disregarding the "et-al" setting, to disambiguate the citations. 
<code xml><option name="disambiguate-add-names" value="true"/></code>
  * disambiguate-add-givenname - add a given name to a citation to disambiguate it, so John Doe, 2005 compared to Doe, 2005. 
<code xml><option name="disambiguate-add-givenname" value="true"/></code>
  * collapse - this allows citations to be collapsed into an abbreviated style. The value is one of the following:
    * citation-number - collapses numeric citations from [1, 2, 3] to [1-3]
    * year - collapses multiple references to the same author to just the years. So (Doe 2000, Doe 2001) collapses to (Doe 2000, 2001). 
    * year-suffix - collapses like in the year option, but also collapses (Doe 2000a, Doe 2000b) to (Doe 2000a, b). This is ignored if the disambiguate-add-year-suffix is not in use.

==== Bibliography only options ====

  * hanging-indent - formats the bibliography with a hanging indent.
<code xml><option name="hanging-indent" value="true"/></code>
  * second-field-align - values of true or margin. It is most useful with numbered items and allows the number to be placed in the margin.
<code xml><option name="second-field-align" value="margin"/></code>
  * subsequent-author-substitute - substitutes subsequent recurrences of an author for a given string. Help wanted here!
<code xml><option subsequent-author-substitute="some text"/></code>


===== Variables =====
These are the variables that can be used in the layout. They can also be tested in the ''<if>'' syntax, and displayed with the ''<text variable="title">'' syntax. They map to various things in the zotero entries. Some of them are available in both short and long form.
  * title - maps to the **Title** field in the long form, and the **Short Title** in the short form.
  * container-title - maps to **Publication**.
  * collection-title - Maps to **Series**.
  * original-title - no mapping.
  * publisher - maps to **Publisher**.
  * publisher-place - maps to **Place**.
  * event - no mapping
  * event-place - no mapping
  * page - maps to **Pages**.
  * locator - maps to the location in the cite dialog.
  * version - no mapping?
  * volume - maps to **Volume**.
  * number-of-volumes - maps to **# of Volumes**.
  * issue - maps to **Issue**.
  * medium - no mapping.
  * status - no mapping.
  * edition - maps to **Edition**.
  * genre - maps to **Type**.
  * note - no mapping.
  * annote - no mapping.
  * abstract - maps to abstract (may be broken though).
  * keyword - no mapping.
  * number - no mapping.
  * archive - maps to **Repository**.
  * archive_location - maps to **Loc. in Archive**.
  * archive-place - no mapping.
  * URL - maps to **URL**.
  * DOI - maps to **DOI**.
  * ISBN - no mapping (that I can find).
  * citation-number - maps to the number of the citation.
  * citation-label - no mapping.

===== Authors =====
These are the types of author that can be used in the layout. They can be displayed with the ''<names>'' syntax. They map to various things in the zotero entries. Some of them are available in both short and long form.

  * author - maps to the **Author** field.
  * editor - maps to the **Editor**.
  * translator - maps to the **Translator**.
  * publisher - no mapping.
  * original-author - no mapping.
  * original-publisher - no mapping.
  * recipient - no mapping
  * interviewer - no mapping
  * series-editor - no mapping
  * composer - no mapping

Author markup is done using the ''<names>'' and ''<name>'' directives.
The names wraps the whole thing, and the name how to format an individual.
The names also allows a <substitute> block to fill in with other syntax.
For the <name> block, there are a number of options that can be specified, besides the generic formatting:
  * form - long or short.
  * and - set to either //symbol// to use & or //text// to use the word "and" to combine authors.
  * delimiter - set to something like "," to separate names.
  * delimiter-precedes-last - //always// uses the delimiter even for the last author, //never// doesn't.
  * name-as-sort-order - //first// sorts by the first author, //all// doesn't.
  * sort-separator - some text to separate the first and last names.
  * initialize-with - the text to follow each initial and a directive to use initials.

e.g.,
<code xml>
<names variable="author">
 <name form="short" and="symbol" delimiter=", " initialize-with=". "/>
</names>
</code>
The <substitute> comes into play if the named author variable is missing. It allows other things to be substituted. For instance
<code xml>
<names variable="author">
 <name name-as-sort-order="all" and="symbol" sort-separator=", " initialize-with=". "
    delimiter=", " delimiter-precedes-last="always"/>
 <label form="short" prefix=" (" suffix=".)" text-transform="capitalize"/>
 <substitute>
   <names variable="editor"/>
   <names variable="translator"/>
   <text macro="title"/>
 </substitute>
</names>
</code>
would fill in with the editor, translator or the title in that order.
===== Dates =====
There are various date fields that can be used. These are typically displayed with the ''<date>'' markup.

  * issued - maps to the **Date**.
  * event - no mapping
  * accessed  - maps to **Accessed**.
  * container - no mapping.

Dates are processed with the ''<date>'' and ''<date-part>'' markup.
The ''<date>'' part is a wrapper around the block, and specifies the date you are working with. This usually encapsulates a sequence of ''<date-part>'' directives. The date as a whole can have the usual formatting directives.
The <date-part> lets you format individual parts of the date. The parameters, apart from the usual formatting constructs, are
  * month - which can also have the form attributes
    * short (e.g. Jan)
    * long (e.g. January)
    * numeric (e.g. 1)
    * numeric-leading-zeros (e.g. 01)
  * day - which can also have the form attributes
    * numeric (e.g. 1)
    * numeric-leading-zeros (e.g. 01)
    * ordinal (e.g. 1st)
  * year - which can be with form short or long. (e.g. 05 or 2005)
  * other - other bits of the date (time maybe) also in short/long form.

For example:
<code xml>
<date variable="issued" suffix=";">
   <date-part name="year" suffix=" "/>
   <date-part name="month" form="short" suffix=" "/>
   <date-part name="day"/>
</date>
</code>

Although a delimiter can be specified in the date part, it is used to separate multiple dates and not to separate parts of the date. Therefore prefix and suffix are important in the date-part.

===== Text =====
The <text> directive is the way to include text in the output from a variety of sources. For example:

<code xml>
<text variable="title" prefix=" Title: " form="short"/>
</code>

The first parameter can be one of:
  * variable - include the contents of a variable.
  * macro - output the results of evaluating a macro.
  * term - output a specific term which is subject to localisation
  * value - output a given bit of verbatim text.
Other parameters you can include are
  * form - either short or long, only makes sense with certain variables (otherwise defaults to long).
  * include-period - true/false term that adds a '.' if parameter is of type "term" and the term used is an abbreviation, not a long form or symbol
You can also include any of the Formatting directives.

===== Formatting =====
The following are formatting parameters and apply to many of the markup directives.

  * prefix - some text to insert before the main output.
  * suffix - some text to place after the main output
  * font-family - which font family to use.
  * font-style - one of //italic//, //normal// or //oblique//.
  * font-variant - one from //normal// or //small-caps//.
  * font-weight - one of //normal//, //bold// or //light//.
  * text-decoration - one from //none// or //underline//.
  * text-case - a way to modify the capitalisation of the text, one of //lowercase//, //uppercase//, //capitalize-first//, //capitalize-all//, //title//, //sentence//.
  * vertical-align - one of //baseline//, //sup//, //sub//.
  * display - if set to //block// makes this a block of separate text.
  * quotes - true/false to include quotes around it.
For instance
<code xml>
<text variable="edition" prefix=" " suffix=" ed. "/>
<text term="retrieved" text-transform="capitalize" suffix=" "/>
</code>

===== Labels =====
Labels are used to add common text that may be dependant on the item. An example is
the label for pages, which can be p. or pp. depending on if its a single page.
For instance
<code xml>
<group prefix=" (" suffix=")">
  <label variable="page" form="short" suffix=". "/>
  <text variable="page"/>
</group>
</code>
''locator'' is the other variable commonly used.
The usual formatting, short/long forms and an option to include a trailing '.'.
Labels can also be applied without a variable inside a &lt;names&gt; element. In this case, the label is the role label (e.g., "edited by")

===== Groups =====
The group construct allows you to group together elements with a format applied to the whole group.
<code xml>
<group delimiter=": ">
 <text variable="publisher-place"/>
 <text variable="publisher"/>
</group>
</code>
The group is ignored if it contains no variables that exist in the document, even if it contains locale terms. A group can also represent semantic document components, as in:
<code xml>
<group class="container" prefix=". ">
</code>

====== Conditionals ======

Conditional information is tested with the ''<if>'' construct, which must be embedded in a ''<choose>'' block. There is an ''<else-if>'' and an ''<else>'' to allow multi-way choices.
It is common in bibliographies to do different arrangements based on the type, as in 
<code xml>
<choose>
  <if type="book">
    ...
  </if>
  <else-if type="chapter">
    ...
  </else-if>
  <else>
    ...
  </else>
</choose>
</code>
Things that can be tested are type's as above, variables (which includes authors and dates). Also are a few meta variables which include
  * ''position'' which can be tested against ''first'', ''subsequent'', ''ibid'', ''ibid-with-locator'' which do ermmm FIXME
  * ''disambiguate'' which can be tested against true/false. This allows two citations to see if they are the same still.
  * ''locator'' which can be compared against locator types such as ''page'', ''chapter'', ''verse'' etc.
  * ''match'' - this allows and/or/not like behaviour by setting against ''all''/''any''/''none''. This is required if you test multiple types or variables too.
Multiple variables can be tested as in
<code xml>
<if type="chapter book" match="any">
</code>