Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
dev:csl_syntax_summary [2011/04/03 14:27] – rmzelle | dev:csl_syntax_summary [2017/11/12 19:53] (current) – external edit 127.0.0.1 | ||
---|---|---|---|
Line 1: | Line 1: | ||
- | ====== CSL 0.8.1 Syntax Overview ====== | + | < |
+ | in the process of updating the documentation for | ||
+ | <a href=" | ||
+ | may be outdated in the meantime. Thanks for your understanding.</ | ||
- | This page describes the syntax of version 0.8.1 of the [[http:// | ||
- | Pointers on how CSL styles can be created, modified, validated, shared and installed in Zotero can be found [[creating_citation_styles|here]], | + | See [[dev/citation_styles/CSL 0.8.1 Syntax]]. |
- | + | ||
- | ====== CSL Style Structure ====== | + | |
- | All CSL styles share the same basic structure: only five different XML elements can be nested directly in the '' | + | |
- | + | ||
- | * '' | + | |
- | * '' | + | |
- | * '' | + | |
- | * '' | + | |
- | * '' | + | |
- | + | ||
- | ===== Independent and Dependent Styles ===== | + | |
- | Two main types of CSL styles exist: independent and dependent styles. An independent style contains a full style description, | + | |
- | + | ||
- | Note that dependent styles cannot be used to indicate changes compared to the master style. If there is any difference in formatting between two styles, however small, two separate CSL styles have to be created. | + | |
- | + | ||
- | ===== Preamble ===== | + | |
- | + | ||
- | Before the style element, each CSL style should include the XML declaration element, specifying the version of XML used as well as the character encoding. The '' | + | |
- | + | ||
- | * '' | + | |
- | * '' | + | |
- | * '' | + | |
- | * '' | + | |
- | + | ||
- | An example of a preamble is shown below. For most styles only the value of '' | + | |
- | + | ||
- | <code xml> | + | |
- | <?xml version=" | + | |
- | <style xmlns=" | + | |
- | </ | + | |
- | + | ||
- | ===== Info ===== | + | |
- | The '' | + | |
- | + | ||
- | <code xml> | + | |
- | < | + | |
- | < | + | |
- | < | + | |
- | < | + | |
- | < | + | |
- | < | + | |
- | < | + | |
- | < | + | |
- | </ | + | |
- | < | + | |
- | < | + | |
- | < | + | |
- | < | + | |
- | < | + | |
- | | + | |
- | | + | |
- | </ | + | |
- | </ | + | |
- | + | ||
- | Many elements available in the info section are borrowed from the [[http:// | + | |
- | + | ||
- | * '' | + | |
- | * '' | + | |
- | * '' | + | |
- | * '' | + | |
- | * '' | + | |
- | * '' | + | |
- | * the style' | + | |
- | * '' | + | |
- | * '' | + | |
- | * '' | + | |
- | * '' | + | |
- | * '' | + | |
- | * the field(s) the style applies to (the '' | + | |
- | * '' | + | |
- | * '' | + | |
- | + | ||
- | ===== Citation ===== | + | |
- | The '' | + | |
- | <code xml> | + | |
- | < | + | |
- | <option /> | + | |
- | < | + | |
- | some layout | + | |
- | </ | + | |
- | </ | + | |
- | </ | + | |
- | The '' | + | |
- | <code xml> | + | |
- | <layout prefix=" | + | |
- | </ | + | |
- | would result in a citation like " | + | |
- | + | ||
- | ===== Bibliography ===== | + | |
- | This is the second of the key parts, where the bibliography is formatted. It is very similar to the citations section. | + | |
- | <code xml> | + | |
- | < | + | |
- | <option .../> | + | |
- | < | + | |
- | ... | + | |
- | </ | + | |
- | </ | + | |
- | </ | + | |
- | Again, a set of options to control some of the layout, then the layout itself. | + | |
- | + | ||
- | ===== Macros ===== | + | |
- | A list of macro definitions is usually included between the '' | + | |
- | **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=" | + | |
- | <names variable=" | + | |
- | <name and=" | + | |
- | <label form=" | + | |
- | </ | + | |
- | </ | + | |
- | </ | + | |
- | + | ||
- | 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=" | + | |
- | <names variable=" | + | |
- | <name name-as-sort-order=" | + | |
- | and=" | + | |
- | sort-separator=", | + | |
- | initialize-with=" | + | |
- | delimiter=", | + | |
- | delimiter-precedes-last=" | + | |
- | <label form=" | + | |
- | < | + | |
- | <names variable=" | + | |
- | <names variable=" | + | |
- | <text macro=" | + | |
- | </ | + | |
- | </ | + | |
- | </ | + | |
- | </ | + | |
- | + | ||
- | 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=" | + | |
- | < | + | |
- | <if type=" | + | |
- | <text variable=" | + | |
- | </ | + | |
- | < | + | |
- | <text variable=" | + | |
- | </ | + | |
- | </ | + | |
- | </ | + | |
- | </ | + | |
- | Note here that CSL reserves three types as generic fallbacks. In this case, for example, " | + | |
- | + | ||
- | 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 " | + | |
- | * edition (for edition or version info) | + | |
- | + | ||
- | ===== Terms ===== | + | |
- | + | ||
- | CSL provides a number of localized strings like "et al.", " | + | |
- | <code xml>< | + | |
- | <locale xml: | + | |
- | <term name=" | + | |
- | <term name=" | + | |
- | < | + | |
- | < | + | |
- | </ | + | |
- | </ | + | |
- | </ | + | |
- | A complete list of localized terms, together with their translations, | + | |
- | + | ||
- | ====== Citation-Bibliography-Macro | + | |
- | + | ||
- | Most of following syntax applies to the '' | + | |
- | + | ||
- | ===== Options ===== | + | |
- | Styles are partially configured by setting a number of options. Some of these options are available in both the '' | + | |
- | + | ||
- | ==== Common options ==== | + | |
- | These apply to both '' | + | |
- | + | ||
- | * et-al-min - the minimum length of contributor lists (e.g. of authors or editors) for et-al abbreviation to kick in. | + | |
- | <code xml>< | + | |
- | * et-al-use-first - if et-al abbreviation is used, the number of contributors to be included before the et-al part. | + | |
- | <code xml>< | + | |
- | + | ||
- | ==== Citation only options ==== | + | |
- | * et-al-subsequent-min - the minimum authors for et-al in subsequent references. | + | |
- | <code xml>< | + | |
- | * et-al-subsequent-use-first - the minimum authors for et-al in subsequent references. | + | |
- | <code xml>< | + | |
- | * 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>< | + | |
- | * disambiguate-add-names - add additional names, disregarding the " | + | |
- | <code xml>< | + | |
- | * disambiguate-add-givenname - add a given name to a citation to disambiguate authors with the same last name, so J. Doe, 2005 compared to M. Doe, 2005. | + | |
- | <code xml>< | + | |
- | * 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>< | + | |
- | * 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>< | + | |
- | * subsequent-author-substitute - substitutes subsequent recurrences of an author for a given string, such as "--- --- ---". Help wanted here! | + | |
- | <code xml>< | + | |
- | * Spacing in the Bibliography is controlled by the " | + | |
- | <code xml>< | + | |
- | <option name=" | + | |
- | + | ||
- | ===== Sorting ===== | + | |
- | + | ||
- | The sorting order for in-text citation groups [e.g. (Doe 2001; Johnson 2003)], and for the bibliography can be set with the '' | + | |
- | + | ||
- | <code xml> | + | |
- | < | + | |
- | < | + | |
- | <key macro=" | + | |
- | <key variable=" | + | |
- | </ | + | |
- | </ | + | |
- | </ | + | |
- | + | ||
- | In this example, citations are first sorted by the output of the author macro. Multiple entries that share the same author macro output are further sorted in reverse order by date of issue (if not specified, the value of the '' | + | |
- | + | ||
- | ===== Variables ===== | + | |
- | These are the variables that can be used in the layout. They can also be tested in the ''< | + | |
- | * 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**, **Series Title** | + | |
- | * collection-number - maps to **Series Number** | + | |
- | * original-title - no mapping. | + | |
- | * publisher - maps to **Publisher**, | + | |
- | * publisher-place - maps to **Place**. | + | |
- | * event - maps to **Meeting Name**, **Conference Name** | + | |
- | * event-place - maps to **Place** | + | |
- | * page - maps to **Pages** | + | |
- | * number-of-pages - maps to **# of Pages**. | + | |
- | * references - maps to **History** (Bill) | + | |
- | * locator - maps to the location in the cite dialog. | + | |
- | * version - maps to **Version** | + | |
- | * volume - maps to **Volume**. | + | |
- | * number-of-volumes - maps to **# of Volumes**. | + | |
- | * issue - maps to **Issue**. | + | |
- | * medium - maps to **Medium** (Interview), | + | |
- | * status - no mapping | + | |
- | * section - maps to **Section** (Bill) | + | |
- | * edition - maps to **Edition**. | + | |
- | * genre - maps to **Type**, **Artwork Size**. | + | |
- | * note - maps to **Extra** | + | |
- | * annote - no mapping. | + | |
- | * authority - maps to **Court** (Case) | + | |
- | * abstract - maps to **Abstract**. | + | |
- | * keyword - no mapping. | + | |
- | * number - maps to **Bill Number**, **Docket Number** | + | |
- | * archive - maps to **Repository**. | + | |
- | * archive_location - maps to **Loc. in Archive**. | + | |
- | * archive-place - no mapping. | + | |
- | * URL - maps to **URL**. | + | |
- | * DOI - maps to **DOI**. | + | |
- | * ISBN - maps to **ISBN**. | + | |
- | * 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 ''< | + | |
- | + | ||
- | * 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 | + | |
- | * collection-editor - maps to the **Series Editor** field. | + | |
- | * composer - no mapping | + | |
- | + | ||
- | Author markup is done using the ''< | + | |
- | The names wraps the whole thing, and the name how to format an individual. | + | |
- | The names also allows a < | + | |
- | For the < | + | |
- | * form - long or short. | + | |
- | * and - set to either //symbol// to use & or //text// to use the word " | + | |
- | * delimiter - set to something like "," | + | |
- | * delimiter-precedes-last - //always// uses the delimiter even for the last author, //never// doesn' | + | |
- | * name-as-sort-order - determines the order of //last name// and //first name// | + | |
- | * 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=" | + | |
- | < | + | |
- | </ | + | |
- | </ | + | |
- | The < | + | |
- | <code xml> | + | |
- | <names variable=" | + | |
- | < | + | |
- | delimiter=", | + | |
- | < | + | |
- | < | + | |
- | < | + | |
- | < | + | |
- | < | + | |
- | </ | + | |
- | </ | + | |
- | </ | + | |
- | 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 ''< | + | |
- | + | ||
- | * issued - maps to the **Date**. | + | |
- | * event - no mapping | + | |
- | * accessed | + | |
- | * container - no mapping. | + | |
- | + | ||
- | Dates are processed with the ''< | + | |
- | The ''< | + | |
- | The < | + | |
- | * 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=" | + | |
- | < | + | |
- | < | + | |
- | < | + | |
- | </ | + | |
- | </ | + | |
- | + | ||
- | 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 < | + | |
- | + | ||
- | <code xml> | + | |
- | <text variable=" | + | |
- | </ | + | |
- | + | ||
- | 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 ' | + | |
- | You can also include any of the Formatting directives. | + | |
- | + | ||
- | ===== Formatting ===== | + | |
- | The following formatting parameters for most elements specifying output. | + | |
- | + | ||
- | * **'' | + | |
- | * **'' | + | |
- | * **'' | + | |
- | * **'' | + | |
- | * **'' | + | |
- | * **'' | + | |
- | * **'' | + | |
- | * **'' | + | |
- | * **'' | + | |
- | * **'' | + | |
- | * **'' | + | |
- | For instance | + | |
- | <code xml> | + | |
- | <text variable=" | + | |
- | <text term=" | + | |
- | </ | + | |
- | + | ||
- | + | ||
- | ===== Labels ===== | + | |
- | Labels are used to add common text that may be dependent on the item. An example is | + | |
- | the label for pages, which can be p. or pp. depending on the number of pages referenced. | + | |
- | For instance | + | |
- | <code xml> | + | |
- | <group prefix=" | + | |
- | <label variable=" | + | |
- | <text variable=" | + | |
- | </ | + | |
- | </ | + | |
- | '' | + | |
- | Label elements allow for the usual text formatting, the choice between different forms (short, long, etc.) and an option to include a trailing ' | + | |
- | Labels can also be applied without a variable inside a ''< | + | |
- | + | ||
- | ===== Groups ===== | + | |
- | The group construct allows you to group together elements with a format applied to the whole group. | + | |
- | <code xml> | + | |
- | <group delimiter=": | + | |
- | < | + | |
- | < | + | |
- | </ | + | |
- | </ | + | |
- | 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=" | + | |
- | </ | + | |
- | + | ||
- | + | ||
- | + | ||
- | ===== Conditionals ===== | + | |
- | + | ||
- | Conditional information is tested with the ''< | + | |
- | It is common in bibliographies to do different arrangements based on the type, as in | + | |
- | <code xml> | + | |
- | < | + | |
- | <if type=" | + | |
- | ... | + | |
- | </ | + | |
- | <else-if type=" | + | |
- | ... | + | |
- | </ | + | |
- | < | + | |
- | ... | + | |
- | </ | + | |
- | </ | + | |
- | </ | + | |
- | Things that can be tested are type's as above, variables (which includes authors and dates). Also are a few meta variables which include | + | |
- | * '' | + | |
- | * '' | + | |
- | * '' | + | |
- | * '' | + | |
- | Multiple variables can be tested as in | + | |
- | <code xml> | + | |
- | <if type=" | + | |
- | </ | + | |
- | + | ||
- | ===== Item Types ===== | + | |
- | + | ||
- | Here is a list of Zotero item types which have a specific mapping ([[http:// | + | |
- | These types can be tested in the ''< | + | |
- | + | ||
- | * article-journal - maps to **journalArticle** Type | + | |
- | * article-magazine - maps to **magazineArticle** | + | |
- | * article-newspaper - maps to **newspaperArticle** | + | |
- | * thesis - maps to **thesis** | + | |
- | * paper-conference - maps to **conferencePaper** | + | |
- | * personal_communication - maps to **letter**, **email** and **instantMessage** | + | |
- | * manuscript - maps to **manuscript** | + | |
- | * interview - maps to **interview** | + | |
- | * motion_picture - maps to **film** | + | |
- | * graphic - maps to **artwork** | + | |
- | * webpage - maps to **webpage** | + | |
- | * report - maps to **report** | + | |
- | * bill - maps to **bill**, **hearing** (?) and **statute** (?) | + | |
- | * legal_case - maps to **case** | + | |
- | * patent - maps to **patent** | + | |
- | * map - maps to **map** | + | |
- | * book - maps to **computerProgram** (?) | + | |
- | * webpage - maps to **blogPost** and **forumPost** | + | |
- | * song - maps to **audioRecording** (?) and **podcast** (?) | + | |
- | * speech - maps to **presentation** | + | |
- | * motion_picture - maps to **videoRecording** | + | |
- | * broadcast - maps to **tvBroadcast** and **radioBroadcast** | + | |
- | + | ||
- | + | ||
- | However CSL reserves some types as generic fallbacks. Thus, for example, a film will use the rule which has been defined for book in the absence of any rules specific to its type. | + | |
- | + | ||
- | You must test a specific type before its generic fallback. For instance, as " | + | |
- | + | ||
- | * " | + | |
- | * " | + | |
- | * " | + |