CINXE.COM

<!DOCTYPE html>   <html class="no-js" lang="en" >  <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>CSL 1.0.2 Specification — Citation Style Language 1.0.1-dev documentation</title> <script type="text/javascript" src="_static/js/modernizr.min.js"></script> <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script> <script type="text/javascript" src="_static/jquery.js"></script> <script type="text/javascript" src="_static/underscore.js"></script> <script type="text/javascript" src="_static/doctools.js"></script> <script type="text/javascript" src="_static/language_data.js"></script> <script type="text/javascript" src="_static/js/theme.js"></script> <link rel="stylesheet" href="_static/css/theme.css" type="text/css" /> <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> <link rel="index" title="Index" href="genindex.html" /> <link rel="search" title="Search" href="search.html" /> <link rel="prev" title="Guide to Translating CSL Locale Files" href="translating-locale-files.html" />  <script type="application/json" id="READTHEDOCS_DATA">{"ad_free": false, "api_host": "https://readthedocs.org", "build_date": "2022-04-19T11:43:12Z", "builder": "sphinx", "canonical_url": null, "commit": "ea75983c", "docroot": "/", "features": {"docsearch_disabled": false}, "global_analytics_code": "UA-17997319-1", "language": "en", "page": "specification", "programming_language": "py", "project": "citation-style-language", "proxied_api_host": "/_", "source_suffix": ".rst", "subprojects": {}, "theme": "sphinx_rtd_theme", "user_analytics_code": "", "version": "stable"}</script>  <script type="text/javascript"> READTHEDOCS_DATA = JSON.parse(document.getElementById('READTHEDOCS_DATA').innerHTML); </script>  <script async type="text/javascript" src="/_/static/javascript/readthedocs-addons.js"></script><meta name="readthedocs-project-slug" content="citation-style-language" /><meta name="readthedocs-version-slug" content="stable" /><meta name="readthedocs-resolver-filename" content="/specification.html" /><meta name="readthedocs-http-status" content="200" /></head> <body class="wy-body-for-nav"> <div class="wy-grid-for-nav"> <nav data-toggle="wy-nav-shift" class="wy-nav-side"> <div class="wy-side-scroll"> <div class="wy-side-nav-search" > <a href="index.html" class="icon icon-home"> Citation Style Language </a> <div class="version"> stable </div> <div role="search"> <form id="rtd-search-form" class="wy-form" action="search.html" method="get"> <input type="text" name="q" placeholder="Search docs" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> </div> </div> <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation"> <ul class="current"> <li class="toctree-l1"><a class="reference internal" href="primer.html">Primer — An Introduction to CSL</a></li> <li class="toctree-l1"><a class="reference internal" href="translating-locale-files.html">Guide to Translating CSL Locale Files</a></li> <li class="toctree-l1 current"><a class="current reference internal" href="#">CSL 1.0.2 Specification</a><ul> <li class="toctree-l2"><a class="reference internal" href="#introduction">Introduction</a><ul> <li class="toctree-l3"><a class="reference internal" href="#terminology">Terminology</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="#namespacing">Namespacing</a></li> <li class="toctree-l2"><a class="reference internal" href="#whitespace-handling">Whitespace Handling</a></li> <li class="toctree-l2"><a class="reference internal" href="#file-types">File Types</a><ul> <li class="toctree-l3"><a class="reference internal" href="#independent-styles">Independent Styles</a></li> <li class="toctree-l3"><a class="reference internal" href="#dependent-styles">Dependent Styles</a></li> <li class="toctree-l3"><a class="reference internal" href="#locale-files">Locale Files</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="#xml-declaration">XML Declaration</a></li> <li class="toctree-l2"><a class="reference internal" href="#styles-structure">Styles - Structure</a><ul> <li class="toctree-l3"><a class="reference internal" href="#the-root-element-cs-style">The Root Element - <code class="docutils literal notranslate"><span class="pre">cs:style</span></code></a></li> <li class="toctree-l3"><a class="reference internal" href="#child-elements-of-cs-style">Child Elements of <code class="docutils literal notranslate"><span class="pre">cs:style</span></code></a><ul> <li class="toctree-l4"><a class="reference internal" href="#info">Info</a></li> <li class="toctree-l4"><a class="reference internal" href="#citation">Citation</a></li> <li class="toctree-l4"><a class="reference internal" href="#bibliography">Bibliography</a></li> <li class="toctree-l4"><a class="reference internal" href="#macro">Macro</a></li> <li class="toctree-l4"><a class="reference internal" href="#locale">Locale</a></li> </ul> </li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="#locale-files-structure">Locale Files - Structure</a><ul> <li class="toctree-l3"><a class="reference internal" href="#info-1">Info</a></li> <li class="toctree-l3"><a class="reference internal" href="#terms">Terms</a><ul> <li class="toctree-l4"><a class="reference internal" href="#ordinal-suffixes">Ordinal Suffixes</a></li> <li class="toctree-l4"><a class="reference internal" href="#long-ordinals">Long Ordinals</a></li> <li class="toctree-l4"><a class="reference internal" href="#gender-specific-ordinals">Gender-specific Ordinals</a></li> </ul> </li> <li class="toctree-l3"><a class="reference internal" href="#localized-date-formats">Localized Date Formats</a></li> <li class="toctree-l3"><a class="reference internal" href="#localized-options">Localized Options</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="#rendering-elements">Rendering Elements</a><ul> <li class="toctree-l3"><a class="reference internal" href="#layout-1">Layout</a></li> <li class="toctree-l3"><a class="reference internal" href="#text">Text</a></li> <li class="toctree-l3"><a class="reference internal" href="#date">Date</a><ul> <li class="toctree-l4"><a class="reference internal" href="#date-part">Date-part</a></li> <li class="toctree-l4"><a class="reference internal" href="#ad-and-bc">AD and BC</a></li> <li class="toctree-l4"><a class="reference internal" href="#seasons">Seasons</a></li> <li class="toctree-l4"><a class="reference internal" href="#approximate-dates">Approximate Dates</a></li> </ul> </li> <li class="toctree-l3"><a class="reference internal" href="#number">Number</a></li> <li class="toctree-l3"><a class="reference internal" href="#names">Names</a><ul> <li class="toctree-l4"><a class="reference internal" href="#name">Name</a></li> <li class="toctree-l4"><a class="reference internal" href="#et-al">Et-al</a></li> <li class="toctree-l4"><a class="reference internal" href="#substitute">Substitute</a></li> <li class="toctree-l4"><a class="reference internal" href="#label-in-cs-names">Label in <code class="docutils literal notranslate"><span class="pre">cs:names</span></code></a></li> </ul> </li> <li class="toctree-l3"><a class="reference internal" href="#label">Label</a></li> <li class="toctree-l3"><a class="reference internal" href="#group">Group</a></li> <li class="toctree-l3"><a class="reference internal" href="#choose">Choose</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="#style-behavior">Style Behavior</a><ul> <li class="toctree-l3"><a class="reference internal" href="#options">Options</a><ul> <li class="toctree-l4"><a class="reference internal" href="#citation-specific-options">Citation-specific Options</a></li> <li class="toctree-l4"><a class="reference internal" href="#bibliography-specific-options">Bibliography-specific Options</a></li> <li class="toctree-l4"><a class="reference internal" href="#global-options">Global Options</a></li> <li class="toctree-l4"><a class="reference internal" href="#inheritable-name-options">Inheritable Name Options</a></li> <li class="toctree-l4"><a class="reference internal" href="#locale-options">Locale Options</a></li> </ul> </li> <li class="toctree-l3"><a class="reference internal" href="#sorting">Sorting</a><ul> <li class="toctree-l4"><a class="reference internal" href="#sorting-variables">Sorting Variables</a></li> <li class="toctree-l4"><a class="reference internal" href="#sorting-macros">Sorting Macros</a></li> </ul> </li> <li class="toctree-l3"><a class="reference internal" href="#range-delimiters">Range Delimiters</a></li> <li class="toctree-l3"><a class="reference internal" href="#formatting">Formatting</a></li> <li class="toctree-l3"><a class="reference internal" href="#affixes">Affixes</a></li> <li class="toctree-l3"><a class="reference internal" href="#delimiter">Delimiter</a></li> <li class="toctree-l3"><a class="reference internal" href="#display">Display</a></li> <li class="toctree-l3"><a class="reference internal" href="#quotes">Quotes</a></li> <li class="toctree-l3"><a class="reference internal" href="#strip-periods">Strip-periods</a></li> <li class="toctree-l3"><a class="reference internal" href="#text-case">Text-case</a><ul> <li class="toctree-l4"><a class="reference internal" href="#sentence-case-conversion">Sentence Case Conversion</a></li> <li class="toctree-l4"><a class="reference internal" href="#title-case-conversion">Title Case Conversion</a></li> </ul> </li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="#appendix-i-categories">Appendix I - Categories</a></li> <li class="toctree-l2"><a class="reference internal" href="#appendix-ii-terms">Appendix II - Terms</a><ul> <li class="toctree-l3"><a class="reference internal" href="#type-terms">Type Terms</a></li> <li class="toctree-l3"><a class="reference internal" href="#name-variable-terms">Name Variable Terms</a></li> <li class="toctree-l3"><a class="reference internal" href="#number-variable-terms">Number Variable Terms</a></li> <li class="toctree-l3"><a class="reference internal" href="#locators">Locators</a></li> <li class="toctree-l3"><a class="reference internal" href="#months">Months</a></li> <li class="toctree-l3"><a class="reference internal" href="#ordinals">Ordinals</a></li> <li class="toctree-l3"><a class="reference internal" href="#punctuation">Punctuation</a></li> <li class="toctree-l3"><a class="reference internal" href="#seasons-1">Seasons</a></li> <li class="toctree-l3"><a class="reference internal" href="#miscellaneous">Miscellaneous</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="#appendix-iii-types">Appendix III - Types</a></li> <li class="toctree-l2"><a class="reference internal" href="#appendix-iv-variables">Appendix IV - Variables</a><ul> <li class="toctree-l3"><a class="reference internal" href="#standard-variables">Standard Variables</a><ul> <li class="toctree-l4"><a class="reference internal" href="#number-variables">Number Variables</a></li> </ul> </li> <li class="toctree-l3"><a class="reference internal" href="#date-variables">Date Variables</a></li> <li class="toctree-l3"><a class="reference internal" href="#name-variables">Name Variables</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="#appendix-v-page-range-formats">Appendix V - Page Range Formats</a></li> <li class="toctree-l2"><a class="reference internal" href="#appendix-vi-links">Appendix VI: Links</a></li> </ul> </li> </ul> </div> </div> </nav> <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"> <nav class="wy-nav-top" aria-label="top navigation"> <i data-toggle="wy-nav-top" class="fa fa-bars"></i> <a href="index.html">Citation Style Language</a> </nav> <div class="wy-nav-content"> <div class="rst-content"> <div role="navigation" aria-label="breadcrumbs navigation"> <ul class="wy-breadcrumbs"> <li><a href="index.html">Docs</a> »</li> <li>CSL 1.0.2 Specification</li> <li class="wy-breadcrumbs-aside"> <a href="https://github.com/citation-style-language/documentation/blob/ea75983cc9f409a88ede93878d9525a734dbeb63/specification.rst" class="fa fa-github"> Edit on GitHub</a> </li> </ul> <hr/> </div> <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article"> <div itemprop="articleBody"> <div class="section" id="csl-1-0-2-specification"> <h1><a class="toc-backref" href="#toc-entry-1">CSL 1.0.2 Specification</a><a class="headerlink" href="#csl-1-0-2-specification" title="Permalink to this headline">¶</a></h1> <p>Principal Authors <a class="reference external" href="https://twitter.com/rintzezelle">Rintze M. Zelle, PhD</a>, <a class="reference external" href="https://twitter.com/bmwiernik">Brenton M. Wiernik</a>, Frank G. Bennett, Jr., Bruce D’Arcus, Denis Maier</p> <p>with additional contributions from Julien Gonzalez, Sebastian Karcher, Sylvester Keil, Cormac Relf, Lars Willighagen, and other CSL contributors.</p> <div class="line-block"> <div class="line"><a class="reference external" href="https://creativecommons.org/licenses/by-sa/4.0/"><img alt="CCBYSA" src="_images/cc-by-sa-80x15.png" /></a></div> <div class="line">This work is licensed under a <a class="reference external" href="https://creativecommons.org/licenses/by-sa/4.0/">Creative Commons Attribution-ShareAlike 4.0 International License</a>.</div> </div> <div class="contents topic" id="table-of-contents"> <p class="topic-title"><strong>Table of Contents</strong></p> <ul class="simple"> <li><a class="reference internal" href="#csl-1-0-2-specification" id="toc-entry-1">CSL 1.0.2 Specification</a><ul> <li><a class="reference internal" href="#introduction" id="toc-entry-2">Introduction</a><ul> <li><a class="reference internal" href="#terminology" id="toc-entry-3">Terminology</a></li> </ul> </li> <li><a class="reference internal" href="#namespacing" id="toc-entry-4">Namespacing</a></li> <li><a class="reference internal" href="#whitespace-handling" id="toc-entry-5">Whitespace Handling</a></li> <li><a class="reference internal" href="#file-types" id="toc-entry-6">File Types</a><ul> <li><a class="reference internal" href="#independent-styles" id="toc-entry-7">Independent Styles</a></li> <li><a class="reference internal" href="#dependent-styles" id="toc-entry-8">Dependent Styles</a></li> <li><a class="reference internal" href="#locale-files" id="toc-entry-9">Locale Files</a></li> </ul> </li> <li><a class="reference internal" href="#xml-declaration" id="toc-entry-10">XML Declaration</a></li> <li><a class="reference internal" href="#styles-structure" id="toc-entry-11">Styles - Structure</a><ul> <li><a class="reference internal" href="#the-root-element-cs-style" id="toc-entry-12">The Root Element - <code class="docutils literal notranslate"><span class="pre">cs:style</span></code></a></li> <li><a class="reference internal" href="#child-elements-of-cs-style" id="toc-entry-13">Child Elements of <code class="docutils literal notranslate"><span class="pre">cs:style</span></code></a><ul> <li><a class="reference internal" href="#info" id="toc-entry-14">Info</a></li> <li><a class="reference internal" href="#citation" id="toc-entry-15">Citation</a></li> <li><a class="reference internal" href="#bibliography" id="toc-entry-16">Bibliography</a></li> <li><a class="reference internal" href="#macro" id="toc-entry-17">Macro</a></li> <li><a class="reference internal" href="#locale" id="toc-entry-18">Locale</a><ul> <li><a class="reference internal" href="#locale-fallback" id="toc-entry-19">Locale Fallback</a></li> </ul> </li> </ul> </li> </ul> </li> <li><a class="reference internal" href="#locale-files-structure" id="toc-entry-20">Locale Files - Structure</a><ul> <li><a class="reference internal" href="#info-1" id="toc-entry-21">Info</a></li> <li><a class="reference internal" href="#terms" id="toc-entry-22">Terms</a><ul> <li><a class="reference internal" href="#ordinal-suffixes" id="toc-entry-23">Ordinal Suffixes</a></li> <li><a class="reference internal" href="#long-ordinals" id="toc-entry-24">Long Ordinals</a></li> <li><a class="reference internal" href="#gender-specific-ordinals" id="toc-entry-25">Gender-specific Ordinals</a></li> </ul> </li> <li><a class="reference internal" href="#localized-date-formats" id="toc-entry-26">Localized Date Formats</a></li> <li><a class="reference internal" href="#localized-options" id="toc-entry-27">Localized Options</a></li> </ul> </li> <li><a class="reference internal" href="#rendering-elements" id="toc-entry-28">Rendering Elements</a><ul> <li><a class="reference internal" href="#layout-1" id="toc-entry-29">Layout</a></li> <li><a class="reference internal" href="#text" id="toc-entry-30">Text</a></li> <li><a class="reference internal" href="#date" id="toc-entry-31">Date</a><ul> <li><a class="reference internal" href="#date-part" id="toc-entry-32">Date-part</a><ul> <li><a class="reference internal" href="#date-ranges" id="toc-entry-33">Date Ranges</a></li> </ul> </li> <li><a class="reference internal" href="#ad-and-bc" id="toc-entry-34">AD and BC</a></li> <li><a class="reference internal" href="#seasons" id="toc-entry-35">Seasons</a></li> <li><a class="reference internal" href="#approximate-dates" id="toc-entry-36">Approximate Dates</a></li> </ul> </li> <li><a class="reference internal" href="#number" id="toc-entry-37">Number</a></li> <li><a class="reference internal" href="#names" id="toc-entry-38">Names</a><ul> <li><a class="reference internal" href="#name" id="toc-entry-39">Name</a><ul> <li><a class="reference internal" href="#name-part-order" id="toc-entry-40">Name-part Order</a></li> <li><a class="reference internal" href="#name-part-formatting" id="toc-entry-41">Name-part Formatting</a></li> </ul> </li> <li><a class="reference internal" href="#et-al" id="toc-entry-42">Et-al</a></li> <li><a class="reference internal" href="#substitute" id="toc-entry-43">Substitute</a></li> <li><a class="reference internal" href="#label-in-cs-names" id="toc-entry-44">Label in <code class="docutils literal notranslate"><span class="pre">cs:names</span></code></a></li> </ul> </li> <li><a class="reference internal" href="#label" id="toc-entry-45">Label</a></li> <li><a class="reference internal" href="#group" id="toc-entry-46">Group</a></li> <li><a class="reference internal" href="#choose" id="toc-entry-47">Choose</a></li> </ul> </li> <li><a class="reference internal" href="#style-behavior" id="toc-entry-48">Style Behavior</a><ul> <li><a class="reference internal" href="#options" id="toc-entry-49">Options</a><ul> <li><a class="reference internal" href="#citation-specific-options" id="toc-entry-50">Citation-specific Options</a><ul> <li><a class="reference internal" href="#disambiguation" id="toc-entry-51">Disambiguation</a></li> <li><a class="reference internal" href="#cite-grouping" id="toc-entry-52">Cite Grouping</a></li> <li><a class="reference internal" href="#cite-collapsing" id="toc-entry-53">Cite Collapsing</a></li> <li><a class="reference internal" href="#note-distance" id="toc-entry-54">Note Distance</a></li> </ul> </li> <li><a class="reference internal" href="#bibliography-specific-options" id="toc-entry-55">Bibliography-specific Options</a><ul> <li><a class="reference internal" href="#whitespace" id="toc-entry-56">Whitespace</a></li> <li><a class="reference internal" href="#reference-grouping" id="toc-entry-57">Reference Grouping</a></li> </ul> </li> <li><a class="reference internal" href="#global-options" id="toc-entry-58">Global Options</a><ul> <li><a class="reference internal" href="#hyphenation-of-initialized-names" id="toc-entry-59">Hyphenation of Initialized Names</a></li> <li><a class="reference internal" href="#page-ranges" id="toc-entry-60">Page Ranges</a></li> <li><a class="reference internal" href="#name-particles" id="toc-entry-61">Name Particles</a></li> </ul> </li> <li><a class="reference internal" href="#inheritable-name-options" id="toc-entry-62">Inheritable Name Options</a></li> <li><a class="reference internal" href="#locale-options" id="toc-entry-63">Locale Options</a></li> </ul> </li> <li><a class="reference internal" href="#sorting" id="toc-entry-64">Sorting</a><ul> <li><a class="reference internal" href="#sorting-variables" id="toc-entry-65">Sorting Variables</a></li> <li><a class="reference internal" href="#sorting-macros" id="toc-entry-66">Sorting Macros</a></li> </ul> </li> <li><a class="reference internal" href="#range-delimiters" id="toc-entry-67">Range Delimiters</a></li> <li><a class="reference internal" href="#formatting" id="toc-entry-68">Formatting</a></li> <li><a class="reference internal" href="#affixes" id="toc-entry-69">Affixes</a></li> <li><a class="reference internal" href="#delimiter" id="toc-entry-70">Delimiter</a></li> <li><a class="reference internal" href="#display" id="toc-entry-71">Display</a></li> <li><a class="reference internal" href="#quotes" id="toc-entry-72">Quotes</a></li> <li><a class="reference internal" href="#strip-periods" id="toc-entry-73">Strip-periods</a></li> <li><a class="reference internal" href="#text-case" id="toc-entry-74">Text-case</a><ul> <li><a class="reference internal" href="#sentence-case-conversion" id="toc-entry-75">Sentence Case Conversion</a></li> <li><a class="reference internal" href="#title-case-conversion" id="toc-entry-76">Title Case Conversion</a><ul> <li><a class="reference internal" href="#non-english-items" id="toc-entry-77">Non-English Items</a></li> </ul> </li> </ul> </li> </ul> </li> <li><a class="reference internal" href="#appendix-i-categories" id="toc-entry-78">Appendix I - Categories</a></li> <li><a class="reference internal" href="#appendix-ii-terms" id="toc-entry-79">Appendix II - Terms</a><ul> <li><a class="reference internal" href="#type-terms" id="toc-entry-80">Type Terms</a></li> <li><a class="reference internal" href="#name-variable-terms" id="toc-entry-81">Name Variable Terms</a></li> <li><a class="reference internal" href="#number-variable-terms" id="toc-entry-82">Number Variable Terms</a></li> <li><a class="reference internal" href="#locators" id="toc-entry-83">Locators</a></li> <li><a class="reference internal" href="#months" id="toc-entry-84">Months</a></li> <li><a class="reference internal" href="#ordinals" id="toc-entry-85">Ordinals</a></li> <li><a class="reference internal" href="#punctuation" id="toc-entry-86">Punctuation</a></li> <li><a class="reference internal" href="#seasons-1" id="toc-entry-87">Seasons</a></li> <li><a class="reference internal" href="#miscellaneous" id="toc-entry-88">Miscellaneous</a></li> </ul> </li> <li><a class="reference internal" href="#appendix-iii-types" id="toc-entry-89">Appendix III - Types</a></li> <li><a class="reference internal" href="#appendix-iv-variables" id="toc-entry-90">Appendix IV - Variables</a><ul> <li><a class="reference internal" href="#standard-variables" id="toc-entry-91">Standard Variables</a><ul> <li><a class="reference internal" href="#number-variables" id="toc-entry-92">Number Variables</a></li> </ul> </li> <li><a class="reference internal" href="#date-variables" id="toc-entry-93">Date Variables</a></li> <li><a class="reference internal" href="#name-variables" id="toc-entry-94">Name Variables</a></li> </ul> </li> <li><a class="reference internal" href="#appendix-v-page-range-formats" id="toc-entry-95">Appendix V - Page Range Formats</a></li> <li><a class="reference internal" href="#appendix-vi-links" id="toc-entry-96">Appendix VI: Links</a></li> </ul> </li> </ul> </div> <div class="section" id="introduction"> <h2><a class="toc-backref" href="#toc-entry-2">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2> <p>The Citation Style Language (CSL) is an XML-based format to describe the formatting of citations, notes and bibliographies, offering:</p> <ul class="simple"> <li>An open format</li> <li>Compact and robust styles</li> <li>Extensive support for style requirements</li> <li>Automatic style localization</li> <li>Infrastructure for style distribution and updating</li> <li>Thousands of freely available styles (Creative Commons BY-SA licensed)</li> </ul> <p>For additional documentation, the CSL schema, styles, and locales, visit the CSL project home, <a class="reference external" href="http://citationstyles.org">citationstyles.org</a>.</p> <div class="section" id="terminology"> <h3><a class="toc-backref" href="#toc-entry-3">Terminology</a><a class="headerlink" href="#terminology" title="Permalink to this headline">¶</a></h3> <p>The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL, are to be interpreted as described in <a class="reference external" href="http://tools.ietf.org/html/rfc2119">IETF RFC 2119</a>.</p> </div> </div> <div class="section" id="namespacing"> <h2><a class="toc-backref" href="#toc-entry-4">Namespacing</a><a class="headerlink" href="#namespacing" title="Permalink to this headline">¶</a></h2> <p>The CSL <a class="reference external" href="http://en.wikipedia.org/wiki/XML_Namespace">XML namespace URI</a> is “<a class="reference external" href="http://purl.org/net/xbiblio/csl">http://purl.org/net/xbiblio/csl</a>”. The namespace prefix <code class="docutils literal notranslate"><span class="pre">cs:</span></code> is used throughout this specification when referring to CSL elements, but is generally omitted in favor of a default namespace declaration (set with the <code class="docutils literal notranslate"><span class="pre">xmlns</span></code> attribute) on the root <code class="docutils literal notranslate"><span class="pre">cs:style</span></code> or <code class="docutils literal notranslate"><span class="pre">cs:locale</span></code> element.</p> </div> <div class="section" id="whitespace-handling"> <h2><a class="toc-backref" href="#toc-entry-5">Whitespace Handling</a><a class="headerlink" href="#whitespace-handling" title="Permalink to this headline">¶</a></h2> <p>CSL styles are valid XML, but CSL processors MUST NOT normalize attribute values by trimming leading or trailing whitespace from attributes which define text that is intended for output:</p> <ul class="simple"> <li>after-collapse-delimiter</li> <li>cite-group-delimiter</li> <li>delimiter</li> <li>initialize-with</li> <li>name-delimiter</li> <li>names-delimiter</li> <li>prefix</li> <li>range-delimiter</li> <li>sort-separator</li> <li>suffix</li> <li>year-suffix-delimiter</li> <li>value</li> </ul> </div> <div class="section" id="file-types"> <h2><a class="toc-backref" href="#toc-entry-6">File Types</a><a class="headerlink" href="#file-types" title="Permalink to this headline">¶</a></h2> <p>There are three types of CSL files: independent and dependent styles (both types use the “.csl” extension), and locale files (named “locales-xx-XX.xml”, where “xx-XX” is a language dialect, e.g. “en-US” for American English).</p> <div class="section" id="independent-styles"> <h3><a class="toc-backref" href="#toc-entry-7">Independent Styles</a><a class="headerlink" href="#independent-styles" title="Permalink to this headline">¶</a></h3> <p>Independent styles contain formatting instructions for citations, notes and bibliographies. While mostly self-contained, they rely on locale files for (default) localization data.</p> </div> <div class="section" id="dependent-styles"> <h3><a class="toc-backref" href="#toc-entry-8">Dependent Styles</a><a class="headerlink" href="#dependent-styles" title="Permalink to this headline">¶</a></h3> <p>A dependent style is an alias for an independent style. Its contents are limited to style metadata, and doesn’t include any formatting instructions (the sole exception is that dependent styles can specify an overriding style locale). By linking dependent styles for journals that share the same citation style (e.g., “Nature Biotechnology”, “Nature Nanotechnology”, etc.) to a single independent style (e.g., “Nature Journals”), there is no need to duplicate formatting instructions.</p> </div> <div class="section" id="locale-files"> <h3><a class="toc-backref" href="#toc-entry-9">Locale Files</a><a class="headerlink" href="#locale-files" title="Permalink to this headline">¶</a></h3> <p>Each locale file contains a set of localization data (term translations, localized date formats, and grammar options) for a particular language dialect.</p> </div> </div> <div class="section" id="xml-declaration"> <h2><a class="toc-backref" href="#toc-entry-10">XML Declaration</a><a class="headerlink" href="#xml-declaration" title="Permalink to this headline">¶</a></h2> <p>Each style or locale should begin with an XML declaration, specifying the XML version and character encoding. In most cases, the declaration will be:</p> <div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="cp"><?xml version="1.0" encoding="UTF-8"?></span> </pre></div> </div> </div> <div class="section" id="styles-structure"> <h2><a class="toc-backref" href="#toc-entry-11">Styles - Structure</a><a class="headerlink" href="#styles-structure" title="Permalink to this headline">¶</a></h2> <div class="section" id="the-root-element-cs-style"> <h3><a class="toc-backref" href="#toc-entry-12">The Root Element - <code class="docutils literal notranslate"><span class="pre">cs:style</span></code></a><a class="headerlink" href="#the-root-element-cs-style" title="Permalink to this headline">¶</a></h3> <p>The root element of styles is <code class="docutils literal notranslate"><span class="pre">cs:style</span></code>. In independent styles, the element carries the following attributes:</p> <dl class="docutils"> <dt><code class="docutils literal notranslate"><span class="pre">class</span></code></dt> <dd>Determines whether the style uses in-text citations (value “in-text”) or notes (“note”).</dd> <dt><code class="docutils literal notranslate"><span class="pre">default-locale</span></code> (optional)</dt> <dd>Sets a default locale for style localization. Value must be a <a class="reference external" href="http://books.xmlschemata.org/relaxng/ch19-77191.html">locale code</a>.</dd> <dt><code class="docutils literal notranslate"><span class="pre">version</span></code></dt> <dd>The CSL version of the style. Must be “1.0” for CSL 1.0-compatible styles.</dd> </dl> <p>In addition, <code class="docutils literal notranslate"><span class="pre">cs:style</span></code> may carry any of the <a class="reference internal" href="#global-options">global options</a> and <a class="reference internal" href="#inheritable-name-options">inheritable name options</a>.</p> <p>Of these attributes, only <code class="docutils literal notranslate"><span class="pre">version</span></code> is required on <code class="docutils literal notranslate"><span class="pre">cs:style</span></code> in dependent styles, while the <code class="docutils literal notranslate"><span class="pre">default-locale</span></code> attribute may be set to specify an overriding style locale. The other attributes are allowed but ignored.</p> <p>An example of <code class="docutils literal notranslate"><span class="pre">cs:style</span></code> for an independent style, preceded by the XML declaration:</p> <div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="cp"><?xml version="1.0" encoding="UTF-8"?></span> <span class="nt"><style</span> <span class="na">xmlns=</span><span class="s">"http://purl.org/net/xbiblio/csl"</span> <span class="na">version=</span><span class="s">"1.0"</span> <span class="na">class=</span><span class="s">"in-text"</span> <span class="na">default-locale=</span><span class="s">"fr-FR"</span><span class="nt">/></span> </pre></div> </div> </div> <div class="section" id="child-elements-of-cs-style"> <h3><a class="toc-backref" href="#toc-entry-13">Child Elements of <code class="docutils literal notranslate"><span class="pre">cs:style</span></code></a><a class="headerlink" href="#child-elements-of-cs-style" title="Permalink to this headline">¶</a></h3> <p>In independent styles, the <code class="docutils literal notranslate"><span class="pre">cs:style</span></code> root element has the following child elements:</p> <dl class="docutils"> <dt><code class="docutils literal notranslate"><span class="pre">cs:info</span></code></dt> <dd>Must appear as the first child element of <code class="docutils literal notranslate"><span class="pre">cs:style</span></code>. Contains the metadata describing the style (style name, ID, authors, etc.).</dd> <dt><code class="docutils literal notranslate"><span class="pre">cs:citation</span></code></dt> <dd>Must appear once. Describes the formatting of in-text citations or notes.</dd> <dt><code class="docutils literal notranslate"><span class="pre">cs:bibliography</span></code> (optional)</dt> <dd>May appear once. Describes the formatting of the bibliography.</dd> <dt><code class="docutils literal notranslate"><span class="pre">cs:macro</span></code> (optional)</dt> <dd>May appear multiple times. Macros allow formatting instructions to be reused, keeping styles compact and maintainable.</dd> <dt><code class="docutils literal notranslate"><span class="pre">cs:locale</span></code> (optional)</dt> <dd>May appear multiple times. Used to specify (overriding) localization data.</dd> </dl> <p>In <a class="reference internal" href="#dependent-styles">dependent styles</a>, <code class="docutils literal notranslate"><span class="pre">cs:style</span></code> has only one child element, <code class="docutils literal notranslate"><span class="pre">cs:info</span></code>.</p> <div class="section" id="info"> <h4><a class="toc-backref" href="#toc-entry-14">Info</a><a class="headerlink" href="#info" title="Permalink to this headline">¶</a></h4> <p>The <code class="docutils literal notranslate"><span class="pre">cs:info</span></code> element contains the style’s metadata. Its structure is based on the <a class="reference external" href="http://tools.ietf.org/html/rfc4287">Atom Syndication Format</a>.</p> <p>In independent styles, <code class="docutils literal notranslate"><span class="pre">cs:info</span></code> has the following child elements:</p> <dl class="docutils"> <dt><code class="docutils literal notranslate"><span class="pre">cs:author</span></code> and <code class="docutils literal notranslate"><span class="pre">cs:contributor</span></code> (optional)</dt> <dd><code class="docutils literal notranslate"><span class="pre">cs:author</span></code> and <code class="docutils literal notranslate"><span class="pre">cs:contributor</span></code>, used to respectively acknowledge style authors and contributors, may each be used multiple times. Within these elements, the child element <code class="docutils literal notranslate"><span class="pre">cs:name</span></code> must appear once, while <code class="docutils literal notranslate"><span class="pre">cs:email</span></code> and <code class="docutils literal notranslate"><span class="pre">cs:uri</span></code> each may appear once. These child elements should contain respectively the name, email address and URI of the author or contributor.</dd> <dt><code class="docutils literal notranslate"><span class="pre">cs:category</span></code> (optional)</dt> <dd><p class="first">Styles may be assigned one or more categories. <code class="docutils literal notranslate"><span class="pre">cs:category</span></code> may be used once to describe how in-text citations are rendered, using the <code class="docutils literal notranslate"><span class="pre">citation-format</span></code> attribute set to one of the following values:</p> <ul class="simple"> <li>“author-date” - e.g. “… (Doe, 1999)”</li> <li>“author” - e.g. “… (Doe)”</li> <li>“numeric” - e.g. “… [1]”</li> <li>“label” - e.g. “… [doe99]”</li> <li>“note” - the citation appears as a footnote or endnote</li> </ul> <p class="last"><code class="docutils literal notranslate"><span class="pre">cs:category</span></code> may be used multiple times with the <code class="docutils literal notranslate"><span class="pre">field</span></code> attribute, set to one of the discipline categories (see <a class="reference internal" href="#appendix-i-categories">Appendix I - Categories</a>), to indicates the field(s) for which the style is relevant.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">cs:id</span></code></dt> <dd>Must appear once and contain a stable, unique identifier to establish the identity of the style. For historical reasons, existing styles may use URIs, but new styles should use a UUID to guarantee stability and uniqueness.</dd> <dt><code class="docutils literal notranslate"><span class="pre">cs:issn</span></code>/<code class="docutils literal notranslate"><span class="pre">cs:eissn</span></code>/<code class="docutils literal notranslate"><span class="pre">cs:issnl</span></code> (optional)</dt> <dd>The <code class="docutils literal notranslate"><span class="pre">cs:issn</span></code> element may be used multiple times to indicate the ISSN identifier(s) of the journal for which the style was written. The <code class="docutils literal notranslate"><span class="pre">cs:eissn</span></code> and <code class="docutils literal notranslate"><span class="pre">cs:issnl</span></code> elements may each be used once for the eISSN and <a class="reference external" href="http://www.issn.org/2-22637-What-is-an-ISSN-L.php">ISSN-L</a> identifiers, respectively.</dd> <dt><code class="docutils literal notranslate"><span class="pre">cs:link</span></code> (optional)</dt> <dd><p class="first">May be used multiple times. <code class="docutils literal notranslate"><span class="pre">cs:link</span></code> must carry two attributes: <code class="docutils literal notranslate"><span class="pre">href</span></code>, set to a URI (usually a URL), and <code class="docutils literal notranslate"><span class="pre">rel</span></code>, whose value indicates how the URI relates to the style. The possible values of <code class="docutils literal notranslate"><span class="pre">rel</span></code>:</p> <ul class="simple"> <li>“self” - style URI</li> <li>“template” - URI of the style from which the current style is derived</li> <li>“documentation” - URI of style documentation</li> </ul> <p class="last">The <code class="docutils literal notranslate"><span class="pre">cs:link</span></code> element may contain content describing the link.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">cs:published</span></code> (optional)</dt> <dd>May appear once. The contents of <code class="docutils literal notranslate"><span class="pre">cs:published</span></code> must be a <a class="reference external" href="http://books.xmlschemata.org/relaxng/ch19-77049.html">timestamp</a>, indicating when the style was initially created or made available.</dd> <dt><code class="docutils literal notranslate"><span class="pre">cs:rights</span></code> (optional)</dt> <dd>May appear once. The contents of <code class="docutils literal notranslate"><span class="pre">cs:rights</span></code> specifies the license under which the style file is released. The element may carry a <code class="docutils literal notranslate"><span class="pre">license</span></code> attribute to specify the URI of the license.</dd> <dt><code class="docutils literal notranslate"><span class="pre">cs:summary</span></code> (optional)</dt> <dd>May appear once. The contents of <code class="docutils literal notranslate"><span class="pre">cs:summary</span></code> gives a (short) description of the style.</dd> <dt><code class="docutils literal notranslate"><span class="pre">cs:title</span></code></dt> <dd>Must appear once. The contents of <code class="docutils literal notranslate"><span class="pre">cs:title</span></code> should be the name of the style as shown to users.</dd> <dt><code class="docutils literal notranslate"><span class="pre">cs:title-short</span></code> (optional)</dt> <dd>May appear once. The contents of <code class="docutils literal notranslate"><span class="pre">cs:title-short</span></code> should be a shortened style name (e.g. “APA”).</dd> <dt><code class="docutils literal notranslate"><span class="pre">cs:updated</span></code></dt> <dd>Must appear once. The contents of <code class="docutils literal notranslate"><span class="pre">cs:updated</span></code> must be a <a class="reference external" href="http://books.xmlschemata.org/relaxng/ch19-77049.html">timestamp</a> that shows when the style was last updated.</dd> </dl> <p>The <code class="docutils literal notranslate"><span class="pre">cs:link</span></code>, <code class="docutils literal notranslate"><span class="pre">cs:rights</span></code>, <code class="docutils literal notranslate"><span class="pre">cs:summary</span></code>, <code class="docutils literal notranslate"><span class="pre">cs:title</span></code> and <code class="docutils literal notranslate"><span class="pre">cs:title-short</span></code> elements may carry a <code class="docutils literal notranslate"><span class="pre">xml:lang</span></code> attribute to specify the language of the element’s content (the value must be an <a class="reference external" href="http://books.xmlschemata.org/relaxng/ch19-77191.html">xsd:language locale code</a>). For <code class="docutils literal notranslate"><span class="pre">cs:link</span></code>, the attribute can also be used to indicate the language of the link target.</p> <p>In <a class="reference internal" href="#dependent-styles">dependent styles</a>, <code class="docutils literal notranslate"><span class="pre">cs:link</span></code> must be used with <code class="docutils literal notranslate"><span class="pre">rel</span></code> set to “independent-parent”, with the URI of the independent parent style set on <code class="docutils literal notranslate"><span class="pre">href</span></code>. In addition, <code class="docutils literal notranslate"><span class="pre">cs:link</span></code> may not be used with <code class="docutils literal notranslate"><span class="pre">rel</span></code> set to “template”.</p> <p>An example of <code class="docutils literal notranslate"><span class="pre">cs:info</span></code> for an independent style:</p> <div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="nt"><info></span> <span class="nt"><title></span>Style Title<span class="nt"></title></span> <span class="nt"><id></span>http://www.zotero.org/styles/style-title<span class="nt"></id></span> <span class="nt"><link</span> <span class="na">href=</span><span class="s">"http://www.zotero.org/styles/style-title"</span> <span class="na">rel=</span><span class="s">"self"</span><span class="nt">/></span> <span class="nt"><link</span> <span class="na">href=</span><span class="s">"http://www.example.org/instructions-to-authors#references"</span> <span class="na">rel=</span><span class="s">"documentation"</span><span class="nt">/></span> <span class="nt"><author></span> <span class="nt"><name></span>Author Name<span class="nt"></name></span> <span class="nt"><email></span>name@example.org<span class="nt"></email></span> <span class="nt"><uri></span>http://www.example.org/name<span class="nt"></uri></span> <span class="nt"></author></span> <span class="nt"><category</span> <span class="na">citation-format=</span><span class="s">"author-date"</span><span class="nt">/></span> <span class="nt"><category</span> <span class="na">field=</span><span class="s">"zoology"</span><span class="nt">/></span> <span class="nt"><updated></span>2011-10-29T21:01:24+00:00<span class="nt"></updated></span> <span class="nt"><rights</span> <span class="na">license=</span><span class="s">"http://creativecommons.org/licenses/by-sa/3.0/"</span><span class="nt">></span>This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 License<span class="nt"></rights></span> <span class="nt"></info></span> </pre></div> </div> </div> <div class="section" id="citation"> <h4><a class="toc-backref" href="#toc-entry-15">Citation</a><a class="headerlink" href="#citation" title="Permalink to this headline">¶</a></h4> <p>The <code class="docutils literal notranslate"><span class="pre">cs:citation</span></code> element describes the formatting of citations, which consist of one or more references (“cites”) to bibliographic sources. Citations appear in the form of either in-text citations (in the author (e.g. “[Doe]”), author-date (“[Doe 1999]”), label (“[doe99]”) or number (“[1]”) format) or notes. The required <code class="docutils literal notranslate"><span class="pre">cs:layout</span></code> child element describes what, and how, bibliographic data should be included in the citations (see <a class="reference external" href="#layout">Layout</a>). <code class="docutils literal notranslate"><span class="pre">cs:layout</span></code> may be preceded by a <code class="docutils literal notranslate"><span class="pre">cs:sort</span></code> element, which can be used to specify how cites within a citation should be sorted (see <a class="reference internal" href="#sorting">Sorting</a>). The <code class="docutils literal notranslate"><span class="pre">cs:citation</span></code> element may carry attributes for <a class="reference internal" href="#citation-specific-options">Citation-specific Options</a> and <a class="reference internal" href="#inheritable-name-options">Inheritable Name Options</a>. An example of a <code class="docutils literal notranslate"><span class="pre">cs:citation</span></code> element:</p> <div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="nt"><citation></span> <span class="nt"><sort></span> <span class="nt"><key</span> <span class="na">variable=</span><span class="s">"citation-number"</span><span class="nt">/></span> <span class="nt"></sort></span> <span class="nt"><layout></span> <span class="nt"><text</span> <span class="na">variable=</span><span class="s">"citation-number"</span><span class="nt">/></span> <span class="nt"></layout></span> <span class="nt"></citation></span> </pre></div> </div> <p><strong>A note to CSL processor developers</strong> In note styles, a citation is often a sentence by itself. Therefore, the first character of a citation should preferably be uppercased when there is no preceding text in the note. In all other cases (e.g. when a citation is inserted into the middle of a pre-existing footnote), the citation should be printed as is.</p> </div> <div class="section" id="bibliography"> <h4><a class="toc-backref" href="#toc-entry-16">Bibliography</a><a class="headerlink" href="#bibliography" title="Permalink to this headline">¶</a></h4> <p>The <code class="docutils literal notranslate"><span class="pre">cs:bibliography</span></code> element describes the formatting of bibliographies, which list one or more bibliographic sources. The required <code class="docutils literal notranslate"><span class="pre">cs:layout</span></code> child element describes how each bibliographic entry should be formatted. <code class="docutils literal notranslate"><span class="pre">cs:layout</span></code> may be preceded by a <code class="docutils literal notranslate"><span class="pre">cs:sort</span></code> element, which can be used to specify how references within the bibliography should be sorted (see <a class="reference internal" href="#sorting">Sorting</a>). The <code class="docutils literal notranslate"><span class="pre">cs:bibliography</span></code> element may carry attributes for <a class="reference internal" href="#bibliography-specific-options">Bibliography-specific Options</a> and <a class="reference internal" href="#inheritable-name-options">Inheritable Name Options</a>. An example of a <code class="docutils literal notranslate"><span class="pre">cs:bibliography</span></code> element:</p> <div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="nt"><bibliography></span> <span class="nt"><sort></span> <span class="nt"><key</span> <span class="na">macro=</span><span class="s">"author"</span><span class="nt">/></span> <span class="nt"></sort></span> <span class="nt"><layout></span> <span class="nt"><group</span> <span class="na">delimiter=</span><span class="s">". "</span><span class="nt">></span> <span class="nt"><text</span> <span class="na">macro=</span><span class="s">"author"</span><span class="nt">/></span> <span class="nt"><text</span> <span class="na">variable=</span><span class="s">"title"</span><span class="nt">/></span> <span class="nt"></group></span> <span class="nt"></layout></span> <span class="nt"></bibliography></span> </pre></div> </div> </div> <div class="section" id="macro"> <h4><a class="toc-backref" href="#toc-entry-17">Macro</a><a class="headerlink" href="#macro" title="Permalink to this headline">¶</a></h4> <p>Macros, defined with <code class="docutils literal notranslate"><span class="pre">cs:macro</span></code> elements, contain formatting instructions. Macros can be called with <code class="docutils literal notranslate"><span class="pre">cs:text</span></code> from within other macros and the <code class="docutils literal notranslate"><span class="pre">cs:layout</span></code> element of <code class="docutils literal notranslate"><span class="pre">cs:citation</span></code> and <code class="docutils literal notranslate"><span class="pre">cs:bibliography</span></code>, and with <code class="docutils literal notranslate"><span class="pre">cs:key</span></code> from within <code class="docutils literal notranslate"><span class="pre">cs:sort</span></code> of <code class="docutils literal notranslate"><span class="pre">cs:citation</span></code> and <code class="docutils literal notranslate"><span class="pre">cs:bibliography</span></code>. It is recommended to place macros after any <code class="docutils literal notranslate"><span class="pre">cs:locale</span></code> elements and before the <code class="docutils literal notranslate"><span class="pre">cs:citation</span></code> element.</p> <p>Macros are referenced by the value of the required <code class="docutils literal notranslate"><span class="pre">name</span></code> attribute on <code class="docutils literal notranslate"><span class="pre">cs:macro</span></code>. The <code class="docutils literal notranslate"><span class="pre">cs:macro</span></code> element must contain one or more <a class="reference internal" href="#rendering-elements">rendering elements</a>.</p> <p>The use of macros can improve style readability, compactness and maintainability. It is recommended to keep the contents of <code class="docutils literal notranslate"><span class="pre">cs:citation</span></code> and <code class="docutils literal notranslate"><span class="pre">cs:bibliography</span></code> compact and agnostic of item types (e.g. books, journal articles, etc.) by depending on macro calls. To allow for easy reuse of macros in other styles, it is recommended to use common macro names.</p> <p>In the example below, cites consist of the item title, rendered in italics when the item type is “book”:</p> <div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="nt"><style></span> <span class="nt"><macro</span> <span class="na">name=</span><span class="s">"title"</span><span class="nt">></span> <span class="nt"><choose></span> <span class="nt"><if</span> <span class="na">type=</span><span class="s">"book"</span><span class="nt">></span> <span class="nt"><text</span> <span class="na">variable=</span><span class="s">"title"</span> <span class="na">font-style=</span><span class="s">"italic"</span><span class="nt">/></span> <span class="nt"></if></span> <span class="nt"><else></span> <span class="nt"><text</span> <span class="na">variable=</span><span class="s">"title"</span><span class="nt">/></span> <span class="nt"></else></span> <span class="nt"></choose></span> <span class="nt"></macro></span> <span class="nt"><citation></span> <span class="nt"><layout></span> <span class="nt"><text</span> <span class="na">macro=</span><span class="s">"title"</span><span class="nt">/></span> <span class="nt"></layout></span> <span class="nt"></citation></span> <span class="nt"></style></span> </pre></div> </div> <p>Delimiters from any ancestor delimiting element are not applied within the output of a <code class="docutils literal notranslate"><span class="pre"><text</span> <span class="pre">macro="..."></span></code> element (see <a class="reference internal" href="#delimiter">delimiter</a>).</p> </div> <div class="section" id="locale"> <h4><a class="toc-backref" href="#toc-entry-18">Locale</a><a class="headerlink" href="#locale" title="Permalink to this headline">¶</a></h4> <p>Localization data, by default drawn from the “locales-xx-XX.xml” locale files, may be redefined or supplemented with <code class="docutils literal notranslate"><span class="pre">cs:locale</span></code> elements, which should be placed directly after the <code class="docutils literal notranslate"><span class="pre">cs:info</span></code> element.</p> <p>The value of the optional <code class="docutils literal notranslate"><span class="pre">xml:lang</span></code> attribute on <code class="docutils literal notranslate"><span class="pre">cs:locale</span></code>, which must be set to an <a class="reference external" href="http://books.xmlschemata.org/relaxng/ch19-77191.html">xsd:language locale code</a>, determines which languages or language dialects are affected (see <a class="reference internal" href="#locale-fallback">Locale Fallback</a>).</p> <p>See <a class="reference internal" href="#terms">Terms</a>, <a class="reference internal" href="#localized-date-formats">Localized Date Formats</a> and <a class="reference internal" href="#localized-options">Localized Options</a> for further details on the use of <code class="docutils literal notranslate"><span class="pre">cs:locale</span></code>.</p> <p>An example of <code class="docutils literal notranslate"><span class="pre">cs:locale</span></code> in a style:</p> <div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="nt"><style></span> <span class="nt"><locale</span> <span class="na">xml:lang=</span><span class="s">"en"</span><span class="nt">></span> <span class="nt"><terms></span> <span class="nt"><term</span> <span class="na">name=</span><span class="s">"editortranslator"</span> <span class="na">form=</span><span class="s">"short"</span><span class="nt">></span> <span class="nt"><single></span>ed. <span class="ni">&amp;</span> trans.<span class="nt"></single></span> <span class="nt"><multiple></span>eds. <span class="ni">&amp;</span> trans.<span class="nt"></multiple></span> <span class="nt"></term></span> <span class="nt"></terms></span> <span class="nt"></locale></span> <span class="nt"></style></span> </pre></div> </div> <div class="section" id="locale-fallback"> <h5><a class="toc-backref" href="#toc-entry-19">Locale Fallback</a><a class="headerlink" href="#locale-fallback" title="Permalink to this headline">¶</a></h5> <p>Locale files provide localization data for language dialects (e.g. “en-US” for American English), whereas the optional <code class="docutils literal notranslate"><span class="pre">cs:locale</span></code> elements in styles can either lack the <code class="docutils literal notranslate"><span class="pre">xml:lang</span></code> attribute, or have it set to either a language (e.g. “en” for English) or dialect. Locale fallback is the mechanism determining from which of these sources each localizable unit (a date format, localized option, or specific form of a term) is retrieved.</p> <p>For dialects of the same language, one is designated the primary dialect. All others are secondaries. At the moment of writing, the available locale files include:</p> <table border="1" class="docutils"> <colgroup> <col width="34%" /> <col width="66%" /> </colgroup> <thead valign="bottom"> <tr class="row-odd"><th class="head">Primary dialect</th> <th class="head">Secondary dialect(s)</th> </tr> </thead> <tbody valign="top"> <tr class="row-even"><td>de-DE (German)</td> <td>de-AT (Austria), de-CH (Switzerland)</td> </tr> <tr class="row-odd"><td>en-US (English)</td> <td>en-GB (UK)</td> </tr> <tr class="row-even"><td>es-ES (Spanish)</td> <td>es-CL (Chile), es-MX (Mexico)</td> </tr> <tr class="row-odd"><td>fr-FR (French)</td> <td>fr-CA (Canada)</td> </tr> <tr class="row-even"><td>pt-PT (Portuguese)</td> <td>pt-BR (Brazil)</td> </tr> <tr class="row-odd"><td>zh-CN (Chinese)</td> <td>zh-TW (Taiwan)</td> </tr> </tbody> </table> <p>Locale fallback is best described with an example. If the chosen output locale is “de-AT” (Austrian German), localizable units are individually drawn from the following sources, in decreasing order of priority:</p> <ol class="upperalpha simple"> <li>In-style <code class="docutils literal notranslate"><span class="pre">cs:locale</span></code> elements<ol class="arabic"> <li><code class="docutils literal notranslate"><span class="pre">xml:lang</span></code> set to chosen dialect, “de-AT”</li> <li><code class="docutils literal notranslate"><span class="pre">xml:lang</span></code> set to matching language, “de” (German)</li> <li><code class="docutils literal notranslate"><span class="pre">xml:lang</span></code> not set</li> </ol> </li> <li>Locale files<ol class="arabic" start="4"> <li><code class="docutils literal notranslate"><span class="pre">xml:lang</span></code> set to chosen dialect, “de-AT”</li> <li><code class="docutils literal notranslate"><span class="pre">xml:lang</span></code> set to matching primary dialect, “de-DE” (Standard German) (only applicable when the chosen locale is a secondary dialect)</li> <li><code class="docutils literal notranslate"><span class="pre">xml:lang</span></code> set to “en-US” (American English)</li> </ol> </li> </ol> <p>If the chosen output locale is a language (e.g. “de”), the (primary) dialect is used in step 1 (e.g. “de-DE”).</p> <p>Fallback stops once a localizable unit has been found. For terms, this even is the case when they are defined as empty strings (e.g. <code class="docutils literal notranslate"><span class="pre"><term</span> <span class="pre">name="and"/></span></code> or <code class="docutils literal notranslate"><span class="pre"><term</span> <span class="pre">name="and"></term></span></code>). Locale fallback takes precedence over fallback of term forms (see <a class="reference internal" href="#terms">Terms</a>).</p> </div> </div> </div> </div> <div class="section" id="locale-files-structure"> <h2><a class="toc-backref" href="#toc-entry-20">Locale Files - Structure</a><a class="headerlink" href="#locale-files-structure" title="Permalink to this headline">¶</a></h2> <p>While localization data can be included in styles (see <a class="reference internal" href="#locale">Locale</a>), locale files conveniently provide sets of default localization data, consisting of terms, date formats and grammar options.</p> <p>Each locale file contains localization data for a single language dialect. This <a class="reference external" href="http://books.xmlschemata.org/relaxng/ch19-77191.html">locale code</a> is set on the required <code class="docutils literal notranslate"><span class="pre">xml:lang</span></code> attribute on the <code class="docutils literal notranslate"><span class="pre">cs:locale</span></code> root element. The same locale code must also be used in the file name of the locale file (the “xx-XX” in “locales-xx-XX.xml”). The root element must carry the <code class="docutils literal notranslate"><span class="pre">version</span></code> attribute, indicating the CSL version of the locale file (must be “1.0” for CSL 1.0-compatible locale files). Locale files have the same requirements for <a class="reference internal" href="#namespacing">namespacing</a> as styles. The <code class="docutils literal notranslate"><span class="pre">cs:locale</span></code> element may contain <code class="docutils literal notranslate"><span class="pre">cs:info</span></code> as its first child element, and requires the child elements <code class="docutils literal notranslate"><span class="pre">cs:terms</span></code>, <code class="docutils literal notranslate"><span class="pre">cs:date</span></code> and <code class="docutils literal notranslate"><span class="pre">cs:style-options</span></code> (these elements are described below). An example showing part of a locale file:</p> <div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="cp"><?xml version="1.0" encoding="UTF-8"?></span> <span class="nt"><locale</span> <span class="na">xml:lang=</span><span class="s">"en-US"</span> <span class="na">version=</span><span class="s">"1.0"</span> <span class="na">xmlns=</span><span class="s">"http://purl.org/net/xbiblio/csl"</span><span class="nt">></span> <span class="nt"><style-options</span> <span class="na">punctuation-in-quote=</span><span class="s">"true"</span><span class="nt">/></span> <span class="nt"><date</span> <span class="na">form=</span><span class="s">"text"</span><span class="nt">></span> <span class="nt"><date-part</span> <span class="na">name=</span><span class="s">"month"</span> <span class="na">suffix=</span><span class="s">" "</span><span class="nt">/></span> <span class="nt"><date-part</span> <span class="na">name=</span><span class="s">"day"</span> <span class="na">suffix=</span><span class="s">", "</span><span class="nt">/></span> <span class="nt"><date-part</span> <span class="na">name=</span><span class="s">"year"</span><span class="nt">/></span> <span class="nt"></date></span> <span class="nt"><date</span> <span class="na">form=</span><span class="s">"numeric"</span><span class="nt">></span> <span class="nt"><date-part</span> <span class="na">name=</span><span class="s">"year"</span><span class="nt">/></span> <span class="nt"><date-part</span> <span class="na">name=</span><span class="s">"month"</span> <span class="na">form=</span><span class="s">"numeric"</span> <span class="na">prefix=</span><span class="s">"-"</span> <span class="na">range-delimiter=</span><span class="s">"/"</span><span class="nt">/></span> <span class="nt"><date-part</span> <span class="na">name=</span><span class="s">"day"</span> <span class="na">prefix=</span><span class="s">"-"</span> <span class="na">range-delimiter=</span><span class="s">"/"</span><span class="nt">/></span> <span class="nt"></date></span> <span class="nt"><terms></span> <span class="nt"><term</span> <span class="na">name=</span><span class="s">"no date"</span><span class="nt">></span>n.d.<span class="nt"></term></span> <span class="nt"><term</span> <span class="na">name=</span><span class="s">"et-al"</span><span class="nt">></span>et al.<span class="nt"></term></span> <span class="nt"><term</span> <span class="na">name=</span><span class="s">"page"</span><span class="nt">></span> <span class="nt"><single></span>page<span class="nt"></single></span> <span class="nt"><multiple></span>pages<span class="nt"></multiple></span> <span class="nt"></term></span> <span class="nt"><term</span> <span class="na">name=</span><span class="s">"page"</span> <span class="na">form=</span><span class="s">"short"</span><span class="nt">></span> <span class="nt"><single></span>p.<span class="nt"></single></span> <span class="nt"><multiple></span>pp.<span class="nt"></multiple></span> <span class="nt"></term></span> <span class="nt"></terms></span> <span class="nt"></locale></span> </pre></div> </div> <div class="section" id="info-1"> <h3><a class="toc-backref" href="#toc-entry-21">Info</a><a class="headerlink" href="#info-1" title="Permalink to this headline">¶</a></h3> <p>The <code class="docutils literal notranslate"><span class="pre">cs:info</span></code> element may be used to give metadata on the locale file. It has the following child elements:</p> <dl class="docutils"> <dt><code class="docutils literal notranslate"><span class="pre">cs:translator</span></code> (optional)</dt> <dd><code class="docutils literal notranslate"><span class="pre">cs:translator</span></code>, used to acknowledge locale translators, may be used multiple times. Within the element, the child element <code class="docutils literal notranslate"><span class="pre">cs:name</span></code> must appear once, while <code class="docutils literal notranslate"><span class="pre">cs:email</span></code> and <code class="docutils literal notranslate"><span class="pre">cs:uri</span></code> each may appear once. These child elements should contain respectively the name, email address and URI of the translator.</dd> <dt><code class="docutils literal notranslate"><span class="pre">cs:rights</span></code> (optional)</dt> <dd>May appear once. The contents of <code class="docutils literal notranslate"><span class="pre">cs:rights</span></code> specifies the license under which the locale file is released. The element may carry a <code class="docutils literal notranslate"><span class="pre">license</span></code> attribute to specify the URI of the license, and a <code class="docutils literal notranslate"><span class="pre">xml:lang</span></code> attribute to specify the language of the element’s content (the value must be an <a class="reference external" href="http://books.xmlschemata.org/relaxng/ch19-77191.html">xsd:language locale code</a>).</dd> <dt><code class="docutils literal notranslate"><span class="pre">cs:updated</span></code> (optional)</dt> <dd>May appear once. The contents of <code class="docutils literal notranslate"><span class="pre">cs:updated</span></code> must be a <a class="reference external" href="http://books.xmlschemata.org/relaxng/ch19-77049.html">timestamp</a> that shows when the locale file was last updated.</dd> </dl> </div> <div class="section" id="terms"> <h3><a class="toc-backref" href="#toc-entry-22">Terms</a><a class="headerlink" href="#terms" title="Permalink to this headline">¶</a></h3> <p>Terms are localized strings (e.g. by using the “and” term, “Doe and Smith” automatically becomes “Doe und Smith” when the style locale is switched from English to German). Terms are defined with <code class="docutils literal notranslate"><span class="pre">cs:term</span></code> elements, child elements of <code class="docutils literal notranslate"><span class="pre">cs:terms</span></code>. Each <code class="docutils literal notranslate"><span class="pre">cs:term</span></code> element must carry a <code class="docutils literal notranslate"><span class="pre">name</span></code> attribute, set to one of the terms listed in <a class="reference internal" href="#appendix-ii-terms">Appendix II - Terms</a>.</p> <p>Terms are either directly defined in the content of <code class="docutils literal notranslate"><span class="pre">cs:term</span></code>, or, in cases where singular and plural variants are needed (e.g. “page” and “pages”), in the content of the child elements <code class="docutils literal notranslate"><span class="pre">cs:single</span></code> and <code class="docutils literal notranslate"><span class="pre">cs:multiple</span></code>, respectively.</p> <p>Terms may be defined for specific forms by using <code class="docutils literal notranslate"><span class="pre">cs:term</span></code> with the optional <code class="docutils literal notranslate"><span class="pre">form</span></code> attribute set to:</p> <ul class="simple"> <li>“long” - (default), e.g. “editor” and “editors” for the “editor” term</li> <li>“short” - e.g. “ed.” and “eds.” for the term “editor”</li> <li>“verb” - e.g. “edited by” for the term “editor”</li> <li>“verb-short” - e.g. “ed.” for the term “editor”</li> <li>“symbol” - e.g. “§” and “§§” for the term “section”</li> </ul> <p>If a style uses a term in a form that is undefined (even after <a class="reference internal" href="#locale-fallback">Locale Fallback</a>), there is fallback to other forms: “verb-short” first falls back to “verb”, “symbol” first falls back to “short”, and “verb” and “short” both fall back to “long”. In addition, the terms “long-ordinal-01” to “long-ordinal-10” fall back to the set of ordinal suffix terms. If no locale or form fallback is available, the term is rendered as an empty string.</p> <p>The <code class="docutils literal notranslate"><span class="pre">match</span></code>, <code class="docutils literal notranslate"><span class="pre">gender</span></code>, and <code class="docutils literal notranslate"><span class="pre">gender-form</span></code> attributes can be used on <code class="docutils literal notranslate"><span class="pre">cs:term</span></code> for the formatting of number variables rendered as ordinals (e.g. “first”, “2nd”). See <a class="reference internal" href="#ordinal-suffixes">Ordinal Suffixes</a> and <a class="reference internal" href="#gender-specific-ordinals">Gender-specific Ordinals</a> below.</p> <p>Term content should not contain markup such as LaTeX or HTML. <a class="reference external" href="http://unicode.org/reports/tr30/datafiles/SuperscriptFolding.txt">Superscripted Unicode characters</a> can be used for superscripting.</p> <div class="section" id="ordinal-suffixes"> <h4><a class="toc-backref" href="#toc-entry-23">Ordinal Suffixes</a><a class="headerlink" href="#ordinal-suffixes" title="Permalink to this headline">¶</a></h4> <p>Number variables can be rendered with <code class="docutils literal notranslate"><span class="pre">cs:number</span></code> in the “ordinal” form, e.g. “2nd” (see <a class="reference internal" href="#number">Number</a>). The ordinal suffixes (“nd” for “2nd”) are defined with terms.</p> <p>The “ordinal” term defines the default ordinal suffix. This default suffix may be overridden for certain numbers with the following terms:</p> <ul class="simple"> <li>“ordinal-00” through “ordinal-09” - by default, a term in this group is used when the last digit in the term name matches the last digit of the rendered number. E.g. “ordinal-00” would match the numbers “0”, “10”, “20”, etc. By setting the optional <code class="docutils literal notranslate"><span class="pre">match</span></code> attribute to “last-two-digits” (“last-digit” is the default), matches are limited to numbers where the two last digits agree (“0”, “100”, “200”, etc.). When <code class="docutils literal notranslate"><span class="pre">match</span></code> is set to “whole-number”, there is only a match if the number is the same as that of the term.</li> <li>“ordinal-10” through “ordinal-99” - by default, a term in this group is used when the last two digits in the term name match the last two digits of the rendered number. When the optional <code class="docutils literal notranslate"><span class="pre">match</span></code> attribute is set to “whole-number” (“last-two-digits” is the default), there is only a match if the number is the same as that of the term.</li> </ul> <p>When a number has matching terms from both groups (e.g. “13” can match “ordinal-03” and “ordinal-13”), the term from the “ordinal-10” through “ordinal-99” group is used.</p> <p>Ordinal terms work differently in CSL 1.0.1 and later than they did in CSL 1.0. When neither the style or locale file define the “ordinal” term, but do define the terms “ordinal-01” through “ordinal-04”, the original CSL 1.0 scheme is used: “ordinal-01” is used for numbers ending on a 1 (except those ending on 11), “ordinal-02” for those ending on a 2 (except those ending on 12), “ordinal-03” for those ending on a 3 (except those ending on 13) and “ordinal-04” for all other numbers.</p> <p>The “ordinal” term, and “ordinal-00” through “ordinal-99” terms, behave differently from other terms when it comes to <cite>Locale Fallback</cite>. Whereas other terms can be (re)defined individually, (re)defining any of the ordinal terms through <code class="docutils literal notranslate"><span class="pre">cs:locale</span></code> replaces all previously defined ordinal terms.</p> </div> <div class="section" id="long-ordinals"> <h4><a class="toc-backref" href="#toc-entry-24">Long Ordinals</a><a class="headerlink" href="#long-ordinals" title="Permalink to this headline">¶</a></h4> <div class="line-block"> <div class="line">Number variables can be rendered with <code class="docutils literal notranslate"><span class="pre">cs:number</span></code> in the “long-ordinal” form, e.g. “second” (see <a class="reference internal" href="#number">Number</a>). The long ordinal terms (e.g. “second” for “2”) are defined with the “long-ordinal-01” through “long-ordinal-10” terms.</div> <div class="line">Long ordinal forms are available for the numbers 1 through 10. For other numbers “long-ordinal” falls back to “ordinal”.</div> <div class="line">For the numbers 1 through 10 in “long-ordinal” form, the <code class="docutils literal notranslate"><span class="pre">match</span></code> attribute is always treated as “whole-number”. For other numbers rendered in “long-ordinal” form, the optional <code class="docutils literal notranslate"><span class="pre">match</span></code> attribute follows the behavior described in <a class="reference internal" href="#ordinal-suffixes">Ordinal Suffixes</a> (“last-two-digits” is the default).</div> </div> </div> <div class="section" id="gender-specific-ordinals"> <h4><a class="toc-backref" href="#toc-entry-25">Gender-specific Ordinals</a><a class="headerlink" href="#gender-specific-ordinals" title="Permalink to this headline">¶</a></h4> <p>Some languages use gender-specific ordinals. For example, the English “1st” and “first” translate in French to “1<sup>er</sup>” and “premier” if the target noun is masculine, and “1<sup>re</sup>” and “première” if the noun is feminine.</p> <p>Feminine and masculine variants of the ordinal terms (see <a class="reference internal" href="#ordinals">Ordinals</a>) may be specified by setting the <code class="docutils literal notranslate"><span class="pre">gender-form</span></code> attribute to “feminine” or “masculine” (the term without <code class="docutils literal notranslate"><span class="pre">gender-form</span></code> represents the neuter variant). There are two types of target nouns: a) the terms accompanying the <a class="reference internal" href="#number-variables">number variables</a>, and b) the month terms (see <a class="reference internal" href="#months">Months</a>). The gender of these nouns may be specified on the “long” (default) form of the term using the <code class="docutils literal notranslate"><span class="pre">gender</span></code> attribute (set to “feminine” or “masculine”). When a number variable is rendered with <code class="docutils literal notranslate"><span class="pre">cs:number</span></code> in the “ordinal” or “long-ordinal” form, the ordinal term of the same gender is used, with a fallback to the neuter variant if the feminine or masculine variant is undefined. When the “day” date-part is rendered in the “ordinal” form, the ordinal gender is matched against that of the month term.</p> <p>The example below gives “1re éd.” (“1st ed.”), “1er janvier” (“January 1st”), and “3e édition” (“3rd edition”):</p> <div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="cp"><?xml version="1.0" encoding="UTF-8"?></span> <span class="nt"><locale</span> <span class="na">xml:lang=</span><span class="s">"fr-FR"</span><span class="nt">></span> <span class="nt"><terms></span> <span class="nt"><term</span> <span class="na">name=</span><span class="s">"edition"</span> <span class="na">gender=</span><span class="s">"feminine"</span><span class="nt">></span> <span class="nt"><single></span>édition<span class="nt"></single></span> <span class="nt"><multiple></span>éditions<span class="nt"></multiple></span> <span class="nt"></term></span> <span class="nt"><term</span> <span class="na">name=</span><span class="s">"edition"</span> <span class="na">form=</span><span class="s">"short"</span><span class="nt">></span>éd.<span class="nt"></term></span> <span class="nt"><term</span> <span class="na">name=</span><span class="s">"month-01"</span> <span class="na">gender=</span><span class="s">"masculine"</span><span class="nt">></span>janvier<span class="nt"></term></span> <span class="nt"><term</span> <span class="na">name=</span><span class="s">"ordinal"</span><span class="nt">></span>e<span class="nt"></term></span> <span class="nt"><term</span> <span class="na">name=</span><span class="s">"ordinal-01"</span> <span class="na">gender-form=</span><span class="s">"feminine"</span> <span class="na">match=</span><span class="s">"whole-number"</span><span class="nt">></span>re<span class="nt"></term></span> <span class="nt"><term</span> <span class="na">name=</span><span class="s">"ordinal-01"</span> <span class="na">gender-form=</span><span class="s">"masculine"</span> <span class="na">match=</span><span class="s">"whole-number"</span><span class="nt">></span>er<span class="nt"></term></span> <span class="nt"></terms></span> <span class="nt"></locale></span> </pre></div> </div> </div> </div> <div class="section" id="localized-date-formats"> <h3><a class="toc-backref" href="#toc-entry-26">Localized Date Formats</a><a class="headerlink" href="#localized-date-formats" title="Permalink to this headline">¶</a></h3> <p>Two localized date formats can be defined with <code class="docutils literal notranslate"><span class="pre">cs:date</span></code> elements: a “numeric” (e.g. “12-15-2005”) and a “text” format (e.g. “December 15, 2005”). The format is set on <code class="docutils literal notranslate"><span class="pre">cs:date</span></code> with the required <code class="docutils literal notranslate"><span class="pre">form</span></code> attribute.</p> <p>A date format is constructed using <code class="docutils literal notranslate"><span class="pre">cs:date-part</span></code> child elements (see <a class="reference internal" href="#date-part">Date-part</a>). With a required <code class="docutils literal notranslate"><span class="pre">name</span></code> attribute set to either <code class="docutils literal notranslate"><span class="pre">day</span></code>, <code class="docutils literal notranslate"><span class="pre">month</span></code> or <code class="docutils literal notranslate"><span class="pre">year</span></code>, the order of these elements reflects the display order of respectively the day, month, and year. The date can be formatted with <a class="reference internal" href="#formatting">formatting</a> and <a class="reference internal" href="#text-case">text-case</a> attributes on the <code class="docutils literal notranslate"><span class="pre">cs:date</span></code> and <code class="docutils literal notranslate"><span class="pre">cs:date-part</span></code> elements. The <a class="reference internal" href="#delimiter">delimiter</a> attribute may be set on <code class="docutils literal notranslate"><span class="pre">cs:date</span></code> to specify the delimiter for the <code class="docutils literal notranslate"><span class="pre">cs:date-part</span></code> elements, and <a class="reference internal" href="#affixes">affixes</a> may be applied to the <code class="docutils literal notranslate"><span class="pre">cs:date-part</span></code> elements.</p> <p><strong>Note</strong> Affixes are not allowed on <code class="docutils literal notranslate"><span class="pre">cs:date</span></code> when defining localized date formats. This restriction is in place to separate locale-specific affixes (set on the <code class="docutils literal notranslate"><span class="pre">cs:date-part</span></code> elements) from any style-specific affixes (set on the calling <code class="docutils literal notranslate"><span class="pre">cs:date</span></code> element), such as parentheses. An example of a macro calling a localized date format:</p> <div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="nt"><macro</span> <span class="na">name=</span><span class="s">"issued"</span><span class="nt">></span> <span class="nt"><date</span> <span class="na">variable=</span><span class="s">"issued"</span> <span class="na">form=</span><span class="s">"numeric"</span> <span class="na">prefix=</span><span class="s">"("</span> <span class="na">suffix=</span><span class="s">")"</span><span class="nt">/></span> <span class="nt"></macro></span> </pre></div> </div> </div> <div class="section" id="localized-options"> <h3><a class="toc-backref" href="#toc-entry-27">Localized Options</a><a class="headerlink" href="#localized-options" title="Permalink to this headline">¶</a></h3> <p>There are two localized options, <code class="docutils literal notranslate"><span class="pre">limit-day-ordinals-to-day-1</span></code> and <code class="docutils literal notranslate"><span class="pre">punctuation-in-quote</span></code> (see <a class="reference internal" href="#locale-options">Locale Options</a>). These global options (which affect both citations and the bibliography) are set as optional attributes on <code class="docutils literal notranslate"><span class="pre">cs:style-options</span></code>.</p> </div> </div> <div class="section" id="rendering-elements"> <h2><a class="toc-backref" href="#toc-entry-28">Rendering Elements</a><a class="headerlink" href="#rendering-elements" title="Permalink to this headline">¶</a></h2> <p>Rendering elements specify which, and in what order, pieces of bibliographic metadata are included in citations and bibliographies, and offer control over their formatting.</p> <div class="section" id="layout-1"> <h3><a class="toc-backref" href="#toc-entry-29">Layout</a><a class="headerlink" href="#layout-1" title="Permalink to this headline">¶</a></h3> <p>The <code class="docutils literal notranslate"><span class="pre">cs:layout</span></code> rendering element is a required child element of <code class="docutils literal notranslate"><span class="pre">cs:citation</span></code> and <code class="docutils literal notranslate"><span class="pre">cs:bibliography</span></code>. It must contain one or more of the other rendering elements described below, and may carry <a class="reference internal" href="#affixes">affixes</a> and <a class="reference internal" href="#formatting">formatting</a> attributes. When used within <code class="docutils literal notranslate"><span class="pre">cs:citation</span></code>, the <a class="reference internal" href="#delimiter">delimiter</a> attribute may be used to specify a delimiter for cites within a citation. For example, a citation like “(1, 2)” can be achieved with:</p> <div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="nt"><citation></span> <span class="nt"><layout</span> <span class="na">prefix=</span><span class="s">"("</span> <span class="na">suffix=</span><span class="s">")"</span> <span class="na">delimiter=</span><span class="s">", "</span><span class="nt">></span> <span class="nt"><text</span> <span class="na">variable=</span><span class="s">"citation-number"</span><span class="nt">/></span> <span class="nt"></layout></span> <span class="nt"></citation></span> </pre></div> </div> </div> <div class="section" id="text"> <h3><a class="toc-backref" href="#toc-entry-30">Text</a><a class="headerlink" href="#text" title="Permalink to this headline">¶</a></h3> <p>The <code class="docutils literal notranslate"><span class="pre">cs:text</span></code> rendering element outputs text. It must carry one of the following attributes to select what should be rendered:</p> <ul class="simple"> <li><code class="docutils literal notranslate"><span class="pre">variable</span></code> - renders the text contents of a variable. Attribute value must be one of the <a class="reference internal" href="#standard-variables">standard variables</a>. May be accompanied by the <code class="docutils literal notranslate"><span class="pre">form</span></code> attribute to select the “long” (default) or “short” form of a variable (e.g. the full or short title). If the “short” form is selected but unavailable, the “long” form is rendered instead.</li> <li><code class="docutils literal notranslate"><span class="pre">macro</span></code> - renders the text output of a macro. Attribute value must match the value of the <code class="docutils literal notranslate"><span class="pre">name</span></code> attribute of a <code class="docutils literal notranslate"><span class="pre">cs:macro</span></code> element (see <a class="reference internal" href="#macro">Macro</a>).</li> <li><code class="docutils literal notranslate"><span class="pre">term</span></code> - renders a term. Attribute value must be one of the terms listed in <a class="reference internal" href="#appendix-ii-terms">Appendix II - Terms</a>. May be accompanied by the <code class="docutils literal notranslate"><span class="pre">plural</span></code> attribute to select the singular (“false”, default) or plural (“true”) variant of a term, and by the <code class="docutils literal notranslate"><span class="pre">form</span></code> attribute to select the “long” (default), “short”, “verb”, “verb-short” or “symbol” form variant (see also <a class="reference internal" href="#terms">Terms</a>).</li> <li><code class="docutils literal notranslate"><span class="pre">value</span></code> - renders the attribute value itself.</li> </ul> <p>An example of <code class="docutils literal notranslate"><span class="pre">cs:text</span></code> rendering the “title” variable:</p> <div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="nt"><text</span> <span class="na">variable=</span><span class="s">"title"</span><span class="nt">/></span> </pre></div> </div> <p><code class="docutils literal notranslate"><span class="pre">cs:text</span></code> may also carry <a class="reference internal" href="#affixes">affixes</a>, <a class="reference internal" href="#display">display</a>, <a class="reference internal" href="#formatting">formatting</a>, <a class="reference internal" href="#quotes">quotes</a>, <a class="reference internal" href="#strip-periods">strip-periods</a> and <a class="reference internal" href="#text-case">text-case</a> attributes.</p> </div> <div class="section" id="date"> <h3><a class="toc-backref" href="#toc-entry-31">Date</a><a class="headerlink" href="#date" title="Permalink to this headline">¶</a></h3> <p>The <code class="docutils literal notranslate"><span class="pre">cs:date</span></code> rendering element outputs the date selected from the list of <a class="reference internal" href="#date-variables">date variables</a> with the required <code class="docutils literal notranslate"><span class="pre">variable</span></code> attribute. A date can be rendered in either a localized or non-localized format.</p> <p><a class="reference internal" href="#localized-date-formats">Localized date formats</a> are selected with the optional <code class="docutils literal notranslate"><span class="pre">form</span></code> attribute, which must be set to either “numeric” (for fully numeric formats, e.g. “12-15-2005”), or “text” (for formats with a non-numeric month, e.g. “December 15, 2005”). Localized date formats can be customized in two ways. First, the <code class="docutils literal notranslate"><span class="pre">date-parts</span></code> attribute may be used to show fewer date parts. The possible values are:</p> <ul class="simple"> <li>“year-month-day” - (default), renders the year, month and day</li> <li>“year-month” - renders the year and month</li> <li>“year” - renders the year</li> </ul> <p>Secondly, <code class="docutils literal notranslate"><span class="pre">cs:date</span></code> may have one or more <code class="docutils literal notranslate"><span class="pre">cs:date-part</span></code> child elements (see <a class="reference internal" href="#date-part">Date-part</a>). The attributes set on these elements override those specified for the localized date formats (e.g. to get abbreviated months for all locales, the <code class="docutils literal notranslate"><span class="pre">form</span></code> attribute on the month-<code class="docutils literal notranslate"><span class="pre">cs:date-part</span></code> element can be set to “short”). These <code class="docutils literal notranslate"><span class="pre">cs:date-part</span></code> elements do not affect which, or in what order, date parts are rendered. <a class="reference internal" href="#affixes">Affixes</a>, which are very locale-specific, are not allowed on these <code class="docutils literal notranslate"><span class="pre">cs:date-part</span></code> elements.</p> <p>In the absence of the <code class="docutils literal notranslate"><span class="pre">form</span></code> attribute, <code class="docutils literal notranslate"><span class="pre">cs:date</span></code> describes a self-contained non-localized date format. In this case, the date format is constructed using <code class="docutils literal notranslate"><span class="pre">cs:date-part</span></code> child elements. With a required <code class="docutils literal notranslate"><span class="pre">name</span></code> attribute set to either <code class="docutils literal notranslate"><span class="pre">day</span></code>, <code class="docutils literal notranslate"><span class="pre">month</span></code> or <code class="docutils literal notranslate"><span class="pre">year</span></code>, the order of these elements reflects the display order of respectively the day, month, and year. The date can be formatted with <a class="reference internal" href="#formatting">formatting</a> attributes on the <code class="docutils literal notranslate"><span class="pre">cs:date-part</span></code> elements, as well as several <code class="docutils literal notranslate"><span class="pre">cs:date-part</span></code>-specific attributes (see <a class="reference internal" href="#date-part">Date-part</a>). The <a class="reference internal" href="#delimiter">delimiter</a> attribute may be set on <code class="docutils literal notranslate"><span class="pre">cs:date</span></code> to specify the delimiter for the <code class="docutils literal notranslate"><span class="pre">cs:date-part</span></code> elements, and <a class="reference internal" href="#affixes">affixes</a> may be applied to the <code class="docutils literal notranslate"><span class="pre">cs:date-part</span></code> elements.</p> <p>For both localized and non-localized dates, <code class="docutils literal notranslate"><span class="pre">cs:date</span></code> may carry <a class="reference internal" href="#affixes">affixes</a>, <a class="reference internal" href="#display">display</a>, <a class="reference internal" href="#formatting">formatting</a> and <a class="reference internal" href="#text-case">text-case</a> attributes.</p> <div class="section" id="date-part"> <h4><a class="toc-backref" href="#toc-entry-32">Date-part</a><a class="headerlink" href="#date-part" title="Permalink to this headline">¶</a></h4> <p>The <code class="docutils literal notranslate"><span class="pre">cs:date-part</span></code> elements control how date parts are rendered. Unless the parent <code class="docutils literal notranslate"><span class="pre">cs:date</span></code> element calls a localized date format, they also determine which, and in what order, date parts appear. A <code class="docutils literal notranslate"><span class="pre">cs:date-part</span></code> element describes the date part selected with the required <code class="docutils literal notranslate"><span class="pre">name</span></code> attribute:</p> <dl class="docutils"> <dt>“day”</dt> <dd><p class="first">For “day”, <code class="docutils literal notranslate"><span class="pre">cs:date-part</span></code> may carry the <code class="docutils literal notranslate"><span class="pre">form</span></code> attribute, with values:</p> <ul class="simple"> <li>“numeric” - (default), e.g. “1”</li> <li>“numeric-leading-zeros” - e.g. “01”</li> <li>“ordinal” - e.g. “1st”</li> </ul> <p class="last">Some languages, such as French, only use the “ordinal” form for the first day of the month (“1er janvier”, “2 janvier”, “3 janvier”, etc.). Such output can be achieved with the “ordinal” form and use of the <code class="docutils literal notranslate"><span class="pre">limit-day-ordinals-to-day-1</span></code> attribute (see <a class="reference internal" href="#locale-options">Locale Options</a>).</p> </dd> <dt>“month”</dt> <dd><p class="first">For “month”, <code class="docutils literal notranslate"><span class="pre">cs:date-part</span></code> may carry the <a class="reference internal" href="#strip-periods">strip-periods</a> and <code class="docutils literal notranslate"><span class="pre">form</span></code> attributes. In locale files, month abbreviations (the “short” form of the month <a class="reference internal" href="#terms">terms</a>) should be defined with periods if applicable (e.g. “Jan.”, “Feb.”, etc.). These periods can be removed by setting <a class="reference internal" href="#strip-periods">strip-periods</a> to “true” (“false” is the default). The <code class="docutils literal notranslate"><span class="pre">form</span></code> attribute can be set to:</p> <ul class="last simple"> <li>“long” - (default), e.g. “January”</li> <li>“short” - e.g. “Jan.”</li> <li>“numeric” - e.g. “1”</li> <li>“numeric-leading-zeros” - e.g. “01”</li> </ul> </dd> <dt>“year”</dt> <dd><p class="first">For “year”, <code class="docutils literal notranslate"><span class="pre">cs:date-part</span></code> may carry the <code class="docutils literal notranslate"><span class="pre">form</span></code> attribute, with values:</p> <ul class="last simple"> <li>“long” - (default), e.g. “2005”</li> <li>“short” - e.g. “05”</li> </ul> </dd> </dl> <p><code class="docutils literal notranslate"><span class="pre">cs:date-part</span></code> may also carry <a class="reference internal" href="#formatting">formatting</a>, <a class="reference internal" href="#text-case">text-case</a> and <code class="docutils literal notranslate"><span class="pre">range-delimiter</span></code> (see <a class="reference internal" href="#date-ranges">Date Ranges</a>) attributes. Attributes for <a class="reference internal" href="#affixes">affixes</a> are allowed, unless <code class="docutils literal notranslate"><span class="pre">cs:date</span></code> calls a localized date format.</p> <div class="section" id="date-ranges"> <h5><a class="toc-backref" href="#toc-entry-33">Date Ranges</a><a class="headerlink" href="#date-ranges" title="Permalink to this headline">¶</a></h5> <p>The default delimiter for dates in a date range is an en-dash (e.g. “May–July 2008”). Custom range delimiters can be set on <code class="docutils literal notranslate"><span class="pre">cs:date-part</span></code> elements with the optional <code class="docutils literal notranslate"><span class="pre">range-delimiter</span></code> attribute. When a date range is rendered, the range delimiter is drawn from the <code class="docutils literal notranslate"><span class="pre">cs:date-part</span></code> element matching the largest date part (“year”, “month”, or “day”) that differs between the two dates. For example,</p> <div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="nt"><style></span> <span class="nt"><citation></span> <span class="nt"><layout></span> <span class="nt"><date</span> <span class="na">variable=</span><span class="s">"issued"</span><span class="nt">></span> <span class="nt"><date-part</span> <span class="na">name=</span><span class="s">"day"</span> <span class="na">suffix=</span><span class="s">" "</span> <span class="na">range-delimiter=</span><span class="s">"-"</span><span class="nt">/></span> <span class="nt"><date-part</span> <span class="na">name=</span><span class="s">"month"</span> <span class="na">suffix=</span><span class="s">" "</span><span class="nt">/></span> <span class="nt"><date-part</span> <span class="na">name=</span><span class="s">"year"</span> <span class="na">range-delimiter=</span><span class="s">"/"</span><span class="nt">/></span> <span class="nt"></date></span> <span class="nt"></layout></span> <span class="nt"></citation></span> <span class="nt"></style></span> </pre></div> </div> <p>would result in “1-4 May 2008”, “May–July 2008” and “May 2008/June 2009”.</p> </div> </div> <div class="section" id="ad-and-bc"> <h4><a class="toc-backref" href="#toc-entry-34">AD and BC</a><a class="headerlink" href="#ad-and-bc" title="Permalink to this headline">¶</a></h4> <p>The “ad” term (Anno Domini) is automatically appended to positive years of less than four digits (e.g. “79” becomes “79AD”). The “bc” term (Before Christ) is automatically appended to negative years (e.g. “-2500” becomes “2500BC”).</p> </div> <div class="section" id="seasons"> <h4><a class="toc-backref" href="#toc-entry-35">Seasons</a><a class="headerlink" href="#seasons" title="Permalink to this headline">¶</a></h4> <p>If a date includes a season instead of a month, a season term (“season-01” to “season-04”, respectively Spring, Summer, Autumn and Winter) take the place of the month term. E.g.,</p> <div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="nt"><style></span> <span class="nt"><citation></span> <span class="nt"><layout></span> <span class="nt"><date</span> <span class="na">variable=</span><span class="s">"issued"</span><span class="nt">></span> <span class="nt"><date-part</span> <span class="na">name=</span><span class="s">"month"</span> <span class="na">suffix=</span><span class="s">" "</span><span class="nt">/></span> <span class="nt"><date-part</span> <span class="na">name=</span><span class="s">"year"</span><span class="nt">/></span> <span class="nt"></date></span> <span class="nt"></layout></span> <span class="nt"></citation></span> <span class="nt"></style></span> </pre></div> </div> <p>would result in “May 2008” and “Winter 2009”.</p> </div> <div class="section" id="approximate-dates"> <h4><a class="toc-backref" href="#toc-entry-36">Approximate Dates</a><a class="headerlink" href="#approximate-dates" title="Permalink to this headline">¶</a></h4> <p>Approximate dates test “true” for the <code class="docutils literal notranslate"><span class="pre">is-uncertain-date</span></code> conditional (see <a class="reference internal" href="#choose">Choose</a>). For example,</p> <div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="nt"><style></span> <span class="nt"><citation></span> <span class="nt"><layout></span> <span class="nt"><choose></span> <span class="nt"><if</span> <span class="na">is-uncertain-date=</span><span class="s">"issued"</span><span class="nt">></span> <span class="nt"><text</span> <span class="na">term=</span><span class="s">"circa"</span> <span class="na">form=</span><span class="s">"short"</span> <span class="na">suffix=</span><span class="s">" "</span><span class="nt">/></span> <span class="nt"></if></span> <span class="nt"></choose></span> <span class="nt"><date</span> <span class="na">variable=</span><span class="s">"issued"</span><span class="nt">></span> <span class="nt"><date-part</span> <span class="na">name=</span><span class="s">"year"</span><span class="nt">/></span> <span class="nt"></date></span> <span class="nt"></layout></span> <span class="nt"></citation></span> <span class="nt"></style></span> </pre></div> </div> <p>would result in “2005” (normal date) and “ca. 2003” (approximate date).</p> </div> </div> <div class="section" id="number"> <h3><a class="toc-backref" href="#toc-entry-37">Number</a><a class="headerlink" href="#number" title="Permalink to this headline">¶</a></h3> <p>The <code class="docutils literal notranslate"><span class="pre">cs:number</span></code> rendering element outputs the number variable selected with the required <code class="docutils literal notranslate"><span class="pre">variable</span></code> attribute. <a class="reference internal" href="#number-variables">Number variables</a> are a subset of the list of <a class="reference internal" href="#standard-variables">standard variables</a>.</p> <p>If a number variable is rendered with <code class="docutils literal notranslate"><span class="pre">cs:number</span></code> and only contains numeric content (as determined by the rules for <code class="docutils literal notranslate"><span class="pre">is-numeric</span></code>, see <a class="reference internal" href="#choose">Choose</a>), the number(s) are extracted. Variable content is rendered “as is” when the variable contains any non-numeric content (e.g. “Special edition”).</p> <p>During the extraction, numbers separated by a hyphen are stripped of intervening spaces (“2 - 4” becomes “2-4”). Numbers separated by a comma receive one space after the comma (“2,3” and “2 , 3” become “2, 3”), while numbers separated by an ampersand receive one space before and one after the ampersand (“2&3” becomes “2 & 3”).</p> <p>Extracted numbers can be formatted via the optional <code class="docutils literal notranslate"><span class="pre">form</span></code> attribute, with values:</p> <ul class="simple"> <li>“numeric” - (default), e.g. “1”, “2”, “3”</li> <li>“ordinal” - e.g. “1st”, “2nd”, “3rd”. Ordinal suffixes are defined with terms (see <a class="reference internal" href="#ordinal-suffixes">Ordinal Suffixes</a>).</li> <li>“long-ordinal” - e.g. “first”, “second”, “third”. Long ordinals are defined with the <a class="reference internal" href="#terms">terms</a> “long-ordinal-01” to “long-ordinal-10”, which are used for the numbers 1 through 10. For other numbers “long-ordinal” falls back to “ordinal”.</li> <li>“roman” - e.g. “i”, “ii”, “iii”</li> </ul> <p>Numbers with prefixes or suffixes are never ordinalized or rendered in roman numerals (e.g. “2E” remains “2E). Numbers without affixes are individually transformed (“2, 3” can become “2nd, 3rd”, “second, third” or “ii, iii”).</p> <p><code class="docutils literal notranslate"><span class="pre">cs:number</span></code> may carry <a class="reference internal" href="#affixes">affixes</a>, <a class="reference internal" href="#display">display</a>, <a class="reference internal" href="#formatting">formatting</a> and <a class="reference internal" href="#text-case">text-case</a> attributes.</p> </div> <div class="section" id="names"> <h3><a class="toc-backref" href="#toc-entry-38">Names</a><a class="headerlink" href="#names" title="Permalink to this headline">¶</a></h3> <p>The <code class="docutils literal notranslate"><span class="pre">cs:names</span></code> rendering element outputs the contents of one or more <a class="reference internal" href="#name-variables">name variables</a> (selected with the required <code class="docutils literal notranslate"><span class="pre">variable</span></code> attribute), each of which can contain multiple names (e.g. the “author” variable contains all the author names of the cited item). If multiple variables are selected (separated by single spaces, see example below), each variable is independently rendered in the order specified, with one exception: when the selection consists of “editor” and “translator”, and when the contents of these two name variables is identical, then the contents of only one name variable is rendered. In addition, the “editortranslator” term is used if the <code class="docutils literal notranslate"><span class="pre">cs:names</span></code> element contains a <code class="docutils literal notranslate"><span class="pre">cs:label</span></code> element, replacing the default “editor” and “translator” terms (e.g. resulting in “Doe (editor & translator)”). The <a class="reference internal" href="#delimiter">delimiter</a> attribute may be set on <code class="docutils literal notranslate"><span class="pre">cs:names</span></code> to separate the names of the different name variables (e.g. the semicolon in “Doe, Smith (editors); Johnson (translator)”).</p> <div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="nt"><names</span> <span class="na">variable=</span><span class="s">"editor translator"</span> <span class="na">delimiter=</span><span class="s">"; "</span><span class="nt">></span> <span class="nt"><label</span> <span class="na">prefix=</span><span class="s">" ("</span> <span class="na">suffix=</span><span class="s">")"</span><span class="nt">/></span> <span class="nt"></names></span> </pre></div> </div> <p><code class="docutils literal notranslate"><span class="pre">cs:names</span></code> has four child elements (discussed below): <code class="docutils literal notranslate"><span class="pre">cs:name</span></code>, <code class="docutils literal notranslate"><span class="pre">cs:et-al</span></code>, <code class="docutils literal notranslate"><span class="pre">cs:substitute</span></code> and <code class="docutils literal notranslate"><span class="pre">cs:label</span></code>. The <code class="docutils literal notranslate"><span class="pre">cs:names</span></code> element may carry <a class="reference internal" href="#affixes">affixes</a>, <a class="reference internal" href="#display">display</a> and <a class="reference internal" href="#formatting">formatting</a> attributes.</p> <div class="section" id="name"> <h4><a class="toc-backref" href="#toc-entry-39">Name</a><a class="headerlink" href="#name" title="Permalink to this headline">¶</a></h4> <p>The <code class="docutils literal notranslate"><span class="pre">cs:name</span></code> element, an optional child element of <code class="docutils literal notranslate"><span class="pre">cs:names</span></code>, can be used to describe the formatting of individual names, and the separation of names within a name variable. <code class="docutils literal notranslate"><span class="pre">cs:name</span></code> may carry the following attributes:</p> <dl class="docutils"> <dt><code class="docutils literal notranslate"><span class="pre">and</span></code></dt> <dd>Specifies the delimiter between the second to last and last name of the names in a name variable. Allowed values are “text” (selects the “and” term, e.g. “Doe, Johnson and Smith”) and “symbol” (selects the ampersand, e.g. “Doe, Johnson & Smith”).</dd> <dt><code class="docutils literal notranslate"><span class="pre">delimiter</span></code></dt> <dd>Specifies the text string used to separate names in a name variable. Default is “, ” (e.g. “Doe, Smith”).</dd> <dt><code class="docutils literal notranslate"><span class="pre">delimiter-precedes-et-al</span></code></dt> <dd><p class="first">Determines when the name delimiter or a space is used between a truncated name list and the “et-al” (or “and others”) term in case of et-al abbreviation. Allowed values:</p> <ul class="last simple"> <li>“contextual” - (default), name delimiter is only used for name lists truncated to two or more names<ul> <li>1 name: “J. Doe et al.”</li> <li>2 names: “J. Doe, S. Smith, et al.”</li> </ul> </li> <li>“after-inverted-name” - name delimiter is only used if the preceding name is inverted as a result of the <code class="docutils literal notranslate"><span class="pre">name-as-sort-order</span></code> attribute. E.g. with <code class="docutils literal notranslate"><span class="pre">name-as-sort-order</span></code> set to “first”:<ul> <li>“Doe, J., et al.”</li> <li>“Doe, J., S. Smith et al.”</li> </ul> </li> <li>“always” - name delimiter is always used<ul> <li>1 name: “J. Doe, et al.”</li> <li>2 names: “J. Doe, S. Smith, et al.”</li> </ul> </li> <li>“never” - name delimiter is never used<ul> <li>1 name: “J. Doe et al.”</li> <li>2 names: “J. Doe, S. Smith et al.”</li> </ul> </li> </ul> </dd> <dt><code class="docutils literal notranslate"><span class="pre">delimiter-precedes-last</span></code></dt> <dd><p class="first">Determines when the name delimiter is used to separate the second to last and the last name in name lists (if <code class="docutils literal notranslate"><span class="pre">and</span></code> is not set, the name delimiter is always used, regardless of the value of <code class="docutils literal notranslate"><span class="pre">delimiter-precedes-last</span></code>). Allowed values:</p> <ul class="last simple"> <li>“contextual” - (default), name delimiter is only used for name lists with three or more names<ul> <li>2 names: “J. Doe and T. Williams”</li> <li>3 names: “J. Doe, S. Smith, and T. Williams”</li> </ul> </li> <li>“after-inverted-name” - name delimiter is only used if the preceding name is inverted as a result of the <code class="docutils literal notranslate"><span class="pre">name-as-sort-order</span></code> attribute. E.g. with <code class="docutils literal notranslate"><span class="pre">name-as-sort-order</span></code> set to “first”:<ul> <li>“Doe, J., and T. Williams”</li> <li>“Doe, J., S. Smith and T. Williams”</li> </ul> </li> <li>“always” - name delimiter is always used<ul> <li>2 names: “J. Doe, and T. Williams”</li> <li>3 names: “J. Doe, S. Smith, and T. Williams”</li> </ul> </li> <li>“never” - name delimiter is never used<ul> <li>2 names: “J. Doe and T. Williams”</li> <li>3 names: “J. Doe, S. Smith and T. Williams”</li> </ul> </li> </ul> </dd> <dt><code class="docutils literal notranslate"><span class="pre">et-al-min</span></code> / <code class="docutils literal notranslate"><span class="pre">et-al-use-first</span></code></dt> <dd>Use of these two attributes enables et-al abbreviation. If the number of names in a name variable matches or exceeds the number set on <code class="docutils literal notranslate"><span class="pre">et-al-min</span></code>, the rendered name list is truncated after reaching the number of names set on <code class="docutils literal notranslate"><span class="pre">et-al-use-first</span></code>. The “et-al” (or “and others”) term is appended to truncated name lists (see also <a class="reference internal" href="#et-al">Et-al</a>). By default, when a name list is truncated to a single name, the name and the “et-al” (or “and others”) term are separated by a space (e.g. “Doe et al.”). When a name list is truncated to two or more names, the name delimiter is used (e.g. “Doe, Smith, et al.”). This behavior can be changed with the <code class="docutils literal notranslate"><span class="pre">delimiter-precedes-et-al</span></code> attribute.</dd> <dt><code class="docutils literal notranslate"><span class="pre">et-al-subsequent-min</span></code> / <code class="docutils literal notranslate"><span class="pre">et-al-subsequent-use-first</span></code></dt> <dd>If used, the values of these attributes replace those of respectively <code class="docutils literal notranslate"><span class="pre">et-al-min</span></code> and <code class="docutils literal notranslate"><span class="pre">et-al-use-first</span></code> for subsequent cites (cites referencing earlier cited items).</dd> <dt><code class="docutils literal notranslate"><span class="pre">et-al-use-last</span></code></dt> <dd><p class="first">When set to “true” (the default is “false”), name lists truncated by et-al abbreviation are followed by the name delimiter, the ellipsis character, and the last name of the original name list. This is only possible when the original name list has at least two more names than the truncated name list (for this the value of <code class="docutils literal notranslate"><span class="pre">et-al-use-first</span></code>/<code class="docutils literal notranslate"><span class="pre">et-al-subsequent-min</span></code> must be at least 2 less than the value of <code class="docutils literal notranslate"><span class="pre">et-al-min</span></code>/<code class="docutils literal notranslate"><span class="pre">et-al-subsequent-use-first</span></code>). An example:</p> <div class="last highlight-default notranslate"><div class="highlight"><pre><span></span>A. Goffeau, B. G. Barrell, H. Bussey, R. W. Davis, B. Dujon, H. Feldmann, … S. G. Oliver </pre></div> </div> </dd> </dl> <p>The remaining attributes, discussed below, only affect personal names. Personal names require a “family” name-part, and may also contain “given”, “suffix”, “non-dropping-particle” and “dropping-particle” name-parts. These name-parts are defined as:</p> <ul class="simple"> <li>“family” - surname minus any particles and suffixes</li> <li>“given” - given names, either full (“John Edward”) or initialized (“J. E.”)</li> <li>“suffix” - name suffix, e.g. “Jr.” in “John Smith Jr.” and “III” in “Bill Gates III”</li> <li>“non-dropping-particle” - name particles that are not dropped when only the surname is shown (“van” in the Dutch surname “van Gogh”) but which may be treated separately from the family name, e.g. for sorting</li> <li>“dropping-particle” - name particles that are dropped when only the surname is shown (“van” in “Ludwig van Beethoven”, which becomes “Beethoven”, or “von” in “Alexander von Humboldt”, which becomes “Humboldt”)</li> </ul> <p>The attributes affecting personal names:</p> <dl class="docutils"> <dt><code class="docutils literal notranslate"><span class="pre">form</span></code></dt> <dd>Specifies whether all the name-parts of personal names should be displayed (value “long”, the default), or only the family name and the non-dropping-particle (value “short”). A third value, “count”, returns the total number of names that would otherwise be rendered by the use of the <code class="docutils literal notranslate"><span class="pre">cs:names</span></code> element (taking into account the effects of et-al abbreviation and editor/translator collapsing), which allows for advanced <a class="reference internal" href="#sorting">sorting</a>.</dd> <dt><code class="docutils literal notranslate"><span class="pre">initialize</span></code></dt> <dd>When set to “false” (the default is “true”), given names are no longer initialized when “initialize-with” is set. However, the value of “initialize-with” is still added after initials present in the full name (e.g. with <code class="docutils literal notranslate"><span class="pre">initialize</span></code> set to “false”, and <code class="docutils literal notranslate"><span class="pre">initialize-with</span></code> set to “.”, “James T Kirk” becomes “James T. Kirk”).</dd> <dt><code class="docutils literal notranslate"><span class="pre">initialize-with</span></code></dt> <dd>When set, given names are converted to initials. The attribute value is added after each initial (“.” results in “J. J. Doe”). For compound given names (e.g. “Jean-Luc”), hyphenation of the initials can be controlled with the global <code class="docutils literal notranslate"><span class="pre">initialize-with-hyphen</span></code> option (see <a class="reference internal" href="#hyphenation-of-initialized-names">Hyphenation of Initialized Names</a>).</dd> <dt><code class="docutils literal notranslate"><span class="pre">name-as-sort-order</span></code></dt> <dd><p class="first">Specifies that names should be displayed with the given name following the family name (e.g. “John Doe” becomes “Doe, John”). The attribute has two possible values:</p> <ul class="simple"> <li>“first” - attribute only has an effect on the first name of each name variable</li> <li>“all” - attribute has an effect on all names</li> </ul> <p class="last">Note that even when <code class="docutils literal notranslate"><span class="pre">name-as-sort-order</span></code> changes the name-part order, the display order is not necessarily the same as the sorting order for names containing particles and suffixes (see <a class="reference internal" href="#name-part-order">Name-part order</a>). Also, <code class="docutils literal notranslate"><span class="pre">name-as-sort-order</span></code> only affects names written in scripts where the given name typically precedes the family name, such as Latin, Greek, Cyrillic and Arabic. In contrast, names written in Asian scripts are always displayed with the family name preceding the given name.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">sort-separator</span></code></dt> <dd>Sets the delimiter for name-parts that have switched positions as a result of <code class="docutils literal notranslate"><span class="pre">name-as-sort-order</span></code>. The default value is “, ” (“Doe, John”). As is the case for <code class="docutils literal notranslate"><span class="pre">name-as-sort-order</span></code>, this attribute only affects names in scripts that know “given-name family-name” order.</dd> </dl> <p><code class="docutils literal notranslate"><span class="pre">cs:name</span></code> may also carry <a class="reference internal" href="#affixes">affixes</a> and <a class="reference internal" href="#formatting">formatting</a> attributes.</p> <div class="section" id="name-part-order"> <h5><a class="toc-backref" href="#toc-entry-40">Name-part Order</a><a class="headerlink" href="#name-part-order" title="Permalink to this headline">¶</a></h5> <p>The order of name-parts depends on the values of the <code class="docutils literal notranslate"><span class="pre">form</span></code> and <code class="docutils literal notranslate"><span class="pre">name-as-sort-order</span></code> attributes on <code class="docutils literal notranslate"><span class="pre">cs:name</span></code>, the value of the <code class="docutils literal notranslate"><span class="pre">demote-non-dropping-particle</span></code> attribute on <code class="docutils literal notranslate"><span class="pre">cs:style</span></code> (one of the <a class="reference internal" href="#global-options">global options</a>), and the script of the individual name. Note that the display and sorting order of name-parts often differs. An overview of the possible orders:</p> <p><strong>Display order of names in “given-name family-name” scripts (Latin, etc.)</strong></p> <hr class="docutils" /> <table class="docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field-odd field"><th class="field-name">Conditions:</th><td class="field-body"><p class="first"><code class="docutils literal notranslate"><span class="pre">form</span></code> set to “long”</p> </td> </tr> <tr class="field-even field"><th class="field-name">Order:</th><td class="field-body"><ol class="first arabic simple"> <li>given</li> <li>dropping-particle</li> <li>non-dropping-particle</li> <li>family</li> <li>suffix</li> </ol> </td> </tr> <tr class="field-odd field"><th class="field-name">Example:</th><td class="field-body"><p class="first">[Vincent] [] [van] [Gogh] [III]</p> </td> </tr> <tr class="field-even field"><th class="field-name">Example:</th><td class="field-body"><p class="first last">[Alexander] [von] [] [Humboldt] [Jr.]</p> </td> </tr> </tbody> </table> <hr class="docutils" /> <table class="docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field-odd field"><th class="field-name">Conditions:</th><td class="field-body"><p class="first"><code class="docutils literal notranslate"><span class="pre">form</span></code> set to “long”, name-as-sort-order active, <code class="docutils literal notranslate"><span class="pre">demote-non-dropping-particle</span></code> set to “never” or “sort-only”</p> </td> </tr> <tr class="field-even field"><th class="field-name">Order:</th><td class="field-body"><ol class="first arabic simple"> <li>non-dropping-particle</li> <li>family</li> <li>given</li> <li>dropping-particle</li> <li>suffix</li> </ol> </td> </tr> <tr class="field-odd field"><th class="field-name">Example:</th><td class="field-body"><p class="first last">[van] [Gogh], [Vincent] [], [III]</p> </td> </tr> </tbody> </table> <hr class="docutils" /> <table class="docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field-odd field"><th class="field-name">Conditions:</th><td class="field-body"><p class="first"><code class="docutils literal notranslate"><span class="pre">form</span></code> set to “long”, name-as-sort-order active, <code class="docutils literal notranslate"><span class="pre">demote-non-dropping-particle</span></code> set to “display-and-sort”</p> </td> </tr> <tr class="field-even field"><th class="field-name">Order:</th><td class="field-body"><ol class="first arabic simple"> <li>family</li> <li>given</li> <li>dropping-particle</li> <li>non-dropping-particle</li> <li>suffix</li> </ol> </td> </tr> <tr class="field-odd field"><th class="field-name">Example:</th><td class="field-body"><p class="first last">[Gogh], [Vincent] [] [van], [III]</p> </td> </tr> </tbody> </table> <hr class="docutils" /> <table class="docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field-odd field"><th class="field-name">Conditions:</th><td class="field-body"><p class="first"><code class="docutils literal notranslate"><span class="pre">form</span></code> set to “short”</p> </td> </tr> <tr class="field-even field"><th class="field-name">Order:</th><td class="field-body"><ol class="first arabic simple"> <li>non-dropping-particles</li> <li>family</li> </ol> </td> </tr> <tr class="field-odd field"><th class="field-name">Example:</th><td class="field-body"><p class="first last">[van] [Gogh]</p> </td> </tr> </tbody> </table> <hr class="docutils" /> <p><strong>Sorting order of names in “given-name family-name” scripts (Latin, etc.)</strong></p> <p>N.B. The sort keys are listed in descending order of priority.</p> <hr class="docutils" /> <table class="docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field-odd field"><th class="field-name">Conditions:</th><td class="field-body"><p class="first"><code class="docutils literal notranslate"><span class="pre">demote-non-dropping-particle</span></code> set to “never”</p> </td> </tr> <tr class="field-even field"><th class="field-name">Order:</th><td class="field-body"><ol class="first arabic simple"> <li>non-dropping-particle + family</li> <li>dropping-particle</li> <li>given</li> <li>suffix</li> </ol> </td> </tr> <tr class="field-odd field"><th class="field-name">Example:</th><td class="field-body"><p class="first last">[van Gogh] [] [Vincent] [III]</p> </td> </tr> </tbody> </table> <hr class="docutils" /> <table class="docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field-odd field"><th class="field-name">Conditions:</th><td class="field-body"><p class="first"><code class="docutils literal notranslate"><span class="pre">demote-non-dropping-particle</span></code> set to “sort-only” or “display-and-sort”</p> </td> </tr> <tr class="field-even field"><th class="field-name">Order:</th><td class="field-body"><ol class="first arabic simple"> <li>family</li> <li>dropping-particle + non-dropping-particle</li> <li>given</li> <li>suffix</li> </ol> </td> </tr> <tr class="field-odd field"><th class="field-name">Example:</th><td class="field-body"><p class="first last">[Gogh] [van] [Vincent] [III]</p> </td> </tr> </tbody> </table> <hr class="docutils" /> <p><strong>Display and sorting order of names in “family-name given-name” scripts (Chinese, etc.)</strong></p> <hr class="docutils" /> <table class="docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field-odd field"><th class="field-name">Conditions:</th><td class="field-body"><p class="first"><code class="docutils literal notranslate"><span class="pre">form</span></code> set to “long”</p> </td> </tr> <tr class="field-even field"><th class="field-name">Order:</th><td class="field-body"><ol class="first arabic simple"> <li>family</li> <li>given</li> </ol> </td> </tr> <tr class="field-odd field"><th class="field-name">Example:</th><td class="field-body"><p class="first last">毛泽东 [Mao Zedong]</p> </td> </tr> </tbody> </table> <hr class="docutils" /> <table class="docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field-odd field"><th class="field-name">Conditions:</th><td class="field-body"><p class="first"><code class="docutils literal notranslate"><span class="pre">form</span></code> set to “short”</p> </td> </tr> <tr class="field-even field"><th class="field-name">Order:</th><td class="field-body"><ol class="first arabic simple"> <li>family</li> </ol> </td> </tr> <tr class="field-odd field"><th class="field-name">Example:</th><td class="field-body"><p class="first last">毛 [Mao]</p> </td> </tr> </tbody> </table> <hr class="docutils" /> <p>Non-personal names lack name-parts and are sorted as is, although English articles (“a”, “an” and “the”) at the start of the name are stripped. For example, “The New York Times” sorts as “New York Times”.</p> </div> <div class="section" id="name-part-formatting"> <h5><a class="toc-backref" href="#toc-entry-41">Name-part Formatting</a><a class="headerlink" href="#name-part-formatting" title="Permalink to this headline">¶</a></h5> <p>The <code class="docutils literal notranslate"><span class="pre">cs:name</span></code> element may contain one or two <code class="docutils literal notranslate"><span class="pre">cs:name-part</span></code> child elements for name-part-specific formatting. <code class="docutils literal notranslate"><span class="pre">cs:name-part</span></code> must carry the <code class="docutils literal notranslate"><span class="pre">name</span></code> attribute, set to either “given” or “family”.</p> <p>If set to “given”, <a class="reference internal" href="#formatting">formatting</a> and <a class="reference internal" href="#text-case">text-case</a> attributes on <code class="docutils literal notranslate"><span class="pre">cs:name-part</span></code> affect the “given” and “dropping-particle” name-parts. <a class="reference internal" href="#affixes">affixes</a> surround the “given” name-part, enclosing any demoted name particles for inverted names.</p> <p>If set to “family”, <a class="reference internal" href="#formatting">formatting</a> and <a class="reference internal" href="#text-case">text-case</a> attributes affect the “family” and “non-dropping-particle” name-parts. <a class="reference internal" href="#affixes">affixes</a> surround the “family” name-part, enclosing any preceding name particles, as well as the “suffix” name-part for non-inverted names.</p> <p>The “suffix” name-part is not subject to name-part formatting. The use of <code class="docutils literal notranslate"><span class="pre">cs:name-part</span></code> elements does not influence which, or in what order, name-parts are rendered. An example, yielding names like “Jane DOE”:</p> <div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="nt"><names</span> <span class="na">variable=</span><span class="s">"author"</span><span class="nt">></span> <span class="nt"><name></span> <span class="nt"><name-part</span> <span class="na">name=</span><span class="s">"family"</span> <span class="na">text-case=</span><span class="s">"uppercase"</span><span class="nt">/></span> <span class="nt"></name></span> <span class="nt"></names></span> </pre></div> </div> </div> </div> <div class="section" id="et-al"> <h4><a class="toc-backref" href="#toc-entry-42">Et-al</a><a class="headerlink" href="#et-al" title="Permalink to this headline">¶</a></h4> <p>Et-al abbreviation, controlled via the <code class="docutils literal notranslate"><span class="pre">et-al-…</span></code> attributes (see <a class="reference internal" href="#name">Name</a>), can be further customized with the optional <code class="docutils literal notranslate"><span class="pre">cs:et-al</span></code> element, which must follow the <code class="docutils literal notranslate"><span class="pre">cs:name</span></code> element (if present).</p> <p>The <a class="reference internal" href="#formatting">formatting</a> attributes may be used on <code class="docutils literal notranslate"><span class="pre">cs:et-al</span></code>, for example to italicize the “et-al” term:</p> <div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="nt"><names</span> <span class="na">variable=</span><span class="s">"author"</span><span class="nt">></span> <span class="nt"><et-al</span> <span class="na">font-style=</span><span class="s">"italic"</span><span class="nt">/></span> <span class="nt"></names></span> </pre></div> </div> <p>The <code class="docutils literal notranslate"><span class="pre">term</span></code> attribute may also be set, to either “et-al” (the default) or “and others”, to use either term:</p> <div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="nt"><names</span> <span class="na">variable=</span><span class="s">"author"</span><span class="nt">></span> <span class="nt"><et-al</span> <span class="na">term=</span><span class="s">"and others"</span><span class="nt">/></span> <span class="nt"></names></span> </pre></div> </div> </div> <div class="section" id="substitute"> <h4><a class="toc-backref" href="#toc-entry-43">Substitute</a><a class="headerlink" href="#substitute" title="Permalink to this headline">¶</a></h4> <p>The optional <code class="docutils literal notranslate"><span class="pre">cs:substitute</span></code> element, which must be included as the last child element of <code class="docutils literal notranslate"><span class="pre">cs:names</span></code>, adds substitution in case the <a class="reference internal" href="#name-variables">name variables</a> specified in the parent <code class="docutils literal notranslate"><span class="pre">cs:names</span></code> element are empty. The substitutions are specified as child elements of <code class="docutils literal notranslate"><span class="pre">cs:substitute</span></code>, and must consist of one or more <a class="reference internal" href="#rendering-elements">rendering elements</a> (with the exception of <code class="docutils literal notranslate"><span class="pre">cs:layout</span></code>). A shorthand version of <code class="docutils literal notranslate"><span class="pre">cs:names</span></code> without child elements, which inherits the attributes values set on the <code class="docutils literal notranslate"><span class="pre">cs:name</span></code> and <code class="docutils literal notranslate"><span class="pre">cs:et-al</span></code> child elements of the original <code class="docutils literal notranslate"><span class="pre">cs:names</span></code> element, may also be used. If <code class="docutils literal notranslate"><span class="pre">cs:substitute</span></code> contains multiple child elements, the first element to return a non-empty result is used for substitution. Substituted variables are suppressed in the rest of the output to prevent duplication. Substituted variables are considered empty for the purposes of determining whether to suppress an enclosing <code class="docutils literal notranslate"><span class="pre">cs:group</span></code>. If the variable was rendered earlier in the citation, before the “substitute” element, it is not suppressed. An example, where an empty “author” name variable is substituted by the “editor” name variable, or, when no editors exist, by the “title” macro:</p> <div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="nt"><macro</span> <span class="na">name=</span><span class="s">"author"</span><span class="nt">></span> <span class="nt"><names</span> <span class="na">variable=</span><span class="s">"author"</span><span class="nt">></span> <span class="nt"><substitute></span> <span class="nt"><names</span> <span class="na">variable=</span><span class="s">"editor"</span><span class="nt">/></span> <span class="nt"><text</span> <span class="na">macro=</span><span class="s">"title"</span><span class="nt">/></span> <span class="nt"></substitute></span> <span class="nt"></names></span> <span class="nt"></macro></span> </pre></div> </div> </div> <div class="section" id="label-in-cs-names"> <h4><a class="toc-backref" href="#toc-entry-44">Label in <code class="docutils literal notranslate"><span class="pre">cs:names</span></code></a><a class="headerlink" href="#label-in-cs-names" title="Permalink to this headline">¶</a></h4> <p>A <code class="docutils literal notranslate"><span class="pre">cs:label</span></code> element (see <a class="reference internal" href="#label">label</a>) may optionally be included in <code class="docutils literal notranslate"><span class="pre">cs:names</span></code>. It must appear before the <code class="docutils literal notranslate"><span class="pre">cs:substitute</span></code> element. The position of <code class="docutils literal notranslate"><span class="pre">cs:label</span></code> relative to <code class="docutils literal notranslate"><span class="pre">cs:name</span></code> determines the order of the name and label in the rendered text. When used as a child element of <code class="docutils literal notranslate"><span class="pre">cs:names</span></code>, <code class="docutils literal notranslate"><span class="pre">cs:label</span></code> does not carry the <code class="docutils literal notranslate"><span class="pre">variable</span></code> attribute; it uses the variable(s) set on the parent <code class="docutils literal notranslate"><span class="pre">cs:names</span></code> element instead. A second difference is that the <code class="docutils literal notranslate"><span class="pre">form</span></code> attribute may also be set to “verb” or “verb-short”, so that the allowed values are:</p> <ul class="simple"> <li>“long” - (default), e.g. “editor” and “editors” for the “editor” term</li> <li>“short” - e.g. “ed.” and “eds.” for the term “editor”</li> <li>“verb” - e.g. “edited by” for the term “editor”</li> <li>“verb-short” - e.g. “ed.” for the term “editor”</li> <li>“symbol” - e.g. “§” and “§§” for the term “section”</li> </ul> </div> </div> <div class="section" id="label"> <h3><a class="toc-backref" href="#toc-entry-45">Label</a><a class="headerlink" href="#label" title="Permalink to this headline">¶</a></h3> <p>The <code class="docutils literal notranslate"><span class="pre">cs:label</span></code> rendering element outputs the term matching the variable selected with the required <code class="docutils literal notranslate"><span class="pre">variable</span></code> attribute, which must be set to “locator”, “page”, or one of the <a class="reference internal" href="#number-variables">number variables</a>. The term is only rendered if the selected variable is non-empty. For example,</p> <div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="nt"><group</span> <span class="na">delimiter=</span><span class="s">" "</span><span class="nt">></span> <span class="nt"><label</span> <span class="na">variable=</span><span class="s">"page"</span><span class="nt">/></span> <span class="nt"><text</span> <span class="na">variable=</span><span class="s">"page"</span><span class="nt">/></span> <span class="nt"></group></span> </pre></div> </div> <p>can result in “page 3” or “pages 5-7”. <code class="docutils literal notranslate"><span class="pre">cs:label</span></code> may carry the following attributes:</p> <dl class="docutils"> <dt><code class="docutils literal notranslate"><span class="pre">form</span></code></dt> <dd><p class="first">Selects the form of the term, with allowed values:</p> <ul class="last simple"> <li>“long” - (default), e.g. “page”/”pages” for the “page” term</li> <li>“short” - e.g. “p.”/”pp.” for the “page” term</li> <li>“symbol” - e.g. “§”/”§§” for the “section” term</li> </ul> </dd> <dt><code class="docutils literal notranslate"><span class="pre">plural</span></code></dt> <dd><p class="first">Sets pluralization of the term, with allowed values:</p> <ul class="last simple"> <li>“contextual” - (default), the term plurality matches that of the variable content. Content is considered plural when it contains multiple numbers (e.g. “page 1”, “pages 1-3”, “volume 2”, “volumes 2 & 4”), or, in the case of the “number-of-pages” and “number-of-volumes” variables, when the number is higher than 1 (“1 volume” and “3 volumes”).</li> <li>“always” - always use the plural form, e.g. “pages 1” and “pages 1-3”</li> <li>“never” - always use the singular form, e.g. “page 1” and “page 1-3”</li> </ul> </dd> </dl> <p><code class="docutils literal notranslate"><span class="pre">cs:label</span></code> may also carry <a class="reference internal" href="#affixes">affixes</a>, <a class="reference internal" href="#formatting">formatting</a>, <a class="reference internal" href="#text-case">text-case</a> and <a class="reference internal" href="#strip-periods">strip-periods</a> attributes.</p> </div> <div class="section" id="group"> <h3><a class="toc-backref" href="#toc-entry-46">Group</a><a class="headerlink" href="#group" title="Permalink to this headline">¶</a></h3> <p>The <code class="docutils literal notranslate"><span class="pre">cs:group</span></code> rendering element must contain one or more <a class="reference internal" href="#rendering-elements">rendering elements</a> (with the exception of <code class="docutils literal notranslate"><span class="pre">cs:layout</span></code>). <code class="docutils literal notranslate"><span class="pre">cs:group</span></code> may carry the <a class="reference internal" href="#delimiter">delimiter</a> attribute to separate its child elements, as well as <a class="reference internal" href="#affixes">affixes</a>, <a class="reference internal" href="#display">display</a>, and <a class="reference internal" href="#formatting">formatting</a> attributes (applied to the output of the group as a whole). <code class="docutils literal notranslate"><span class="pre">cs:group</span></code> implicitly acts as a conditional: <code class="docutils literal notranslate"><span class="pre">cs:group</span></code> and its child elements are suppressed if a) at least one rendering element in <code class="docutils literal notranslate"><span class="pre">cs:group</span></code> calls a variable (either directly or via a macro), and b) all variables that are called are empty. This accommodates descriptive <cite>cs:text</cite> and <a href="#system-message-1"><span class="problematic" id="problematic-1">`</span></a>cs:label`elements. For example,</p> <div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="nt"><layout></span> <span class="nt"><group</span> <span class="na">delimiter=</span><span class="s">" "</span><span class="nt">></span> <span class="nt"><text</span> <span class="na">term=</span><span class="s">"retrieved"</span><span class="nt">/></span> <span class="nt"><text</span> <span class="na">term=</span><span class="s">"from"</span><span class="nt">/></span> <span class="nt"><text</span> <span class="na">variable=</span><span class="s">"URL"</span><span class="nt">/></span> <span class="nt"></group></span> <span class="nt"></layout></span> </pre></div> </div> <p>can result in “retrieved from <a class="reference external" href="https://doi.org/10.1128/AEM.02591-07">https://doi.org/10.1128/AEM.02591-07</a>”, but doesn’t generate output when the “URL” variable is empty.</p> <p>If a <code class="docutils literal notranslate"><span class="pre">cs:group</span></code> is nested within another <code class="docutils literal notranslate"><span class="pre">cs:group</span></code>, the inner group is evaluated first: a non-empty nested <code class="docutils literal notranslate"><span class="pre">cs:group</span></code> is treated as a non-empty variable for the puropses of determining suppression of the outer <code class="docutils literal notranslate"><span class="pre">cs:group</span></code>.</p> <p>When a <code class="docutils literal notranslate"><span class="pre">cs:group</span></code> contains a child <code class="docutils literal notranslate"><span class="pre">cs:macro</span></code>, if the <code class="docutils literal notranslate"><span class="pre">cs:macro</span></code> is non-empty, it is treated as a non-empty variable for the purposes of determining suppression of the outer <code class="docutils literal notranslate"><span class="pre">cs:group</span></code>.</p> </div> <div class="section" id="choose"> <h3><a class="toc-backref" href="#toc-entry-47">Choose</a><a class="headerlink" href="#choose" title="Permalink to this headline">¶</a></h3> <p>The <code class="docutils literal notranslate"><span class="pre">cs:choose</span></code> rendering element allows for conditional rendering of <a class="reference internal" href="#rendering-elements">rendering elements</a>. An example that renders the “issued” date variable when it exists, and the “no date” term when it doesn’t:</p> <div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="nt"><choose></span> <span class="nt"><if</span> <span class="na">variable=</span><span class="s">"issued"</span><span class="nt">></span> <span class="nt"><date</span> <span class="na">variable=</span><span class="s">"issued"</span> <span class="na">form=</span><span class="s">"numeric"</span><span class="nt">/></span> <span class="nt"></if></span> <span class="nt"><else></span> <span class="nt"><text</span> <span class="na">term=</span><span class="s">"no date"</span><span class="nt">/></span> <span class="nt"></else></span> <span class="nt"></choose></span> </pre></div> </div> <p><code class="docutils literal notranslate"><span class="pre">cs:choose</span></code> requires a <code class="docutils literal notranslate"><span class="pre">cs:if</span></code> child element, which may be followed by one or more <code class="docutils literal notranslate"><span class="pre">cs:else-if</span></code> child elements, and an optional closing <code class="docutils literal notranslate"><span class="pre">cs:else</span></code> child element. The <code class="docutils literal notranslate"><span class="pre">cs:if</span></code> and <code class="docutils literal notranslate"><span class="pre">cs:else-if</span></code> elements may contain any number of <a class="reference internal" href="#rendering-elements">rendering elements</a> (except for <code class="docutils literal notranslate"><span class="pre">cs:layout</span></code>). As an empty <code class="docutils literal notranslate"><span class="pre">cs:else</span></code> element would be superfluous, <code class="docutils literal notranslate"><span class="pre">cs:else</span></code> must contain at least one rendering element. <code class="docutils literal notranslate"><span class="pre">cs:if</span></code> and <code class="docutils literal notranslate"><span class="pre">cs:else-if</span></code> elements must carry one or more conditions, which are set with the attributes:</p> <dl class="docutils"> <dt><code class="docutils literal notranslate"><span class="pre">disambiguate</span></code></dt> <dd>When set to “true” (the only allowed value), the element content is only rendered if it disambiguates two otherwise identical citations. This attempt at <a class="reference internal" href="#disambiguation">disambiguation</a> is only made when all other disambiguation methods have failed to uniquely identify the target source.</dd> <dt><code class="docutils literal notranslate"><span class="pre">is-numeric</span></code></dt> <dd>Tests whether the given variables (<a class="reference internal" href="#appendix-iv-variables">Appendix IV - Variables</a>) contain numeric content. Content is considered numeric if it solely consists of numbers. Numbers may have prefixes and suffixes (“D2”, “2b”, “L2d”), and may be separated by a comma, hyphen, or ampersand, with or without spaces (“2, 3”, “2-4”, “2 & 4”). For example, “2nd” tests “true” whereas “second” and “2nd edition” test “false”.</dd> <dt><code class="docutils literal notranslate"><span class="pre">is-uncertain-date</span></code></dt> <dd>Tests whether the given <a class="reference internal" href="#date-variables">date variables</a> contain <a class="reference internal" href="#approximate-dates">approximate dates</a>.</dd> <dt><code class="docutils literal notranslate"><span class="pre">locator</span></code></dt> <dd>Tests whether the locator matches the given locator types (see <a class="reference internal" href="#locators">Locators</a>). Use “sub-verbo” to test for the “sub verbo” locator type.</dd> <dt><code class="docutils literal notranslate"><span class="pre">position</span></code></dt> <dd><p class="first">Tests whether the cite position matches the given positions (terminology: citations consist of one or more cites to individual items). When called within the scope of cs:bibliography, <code class="docutils literal notranslate"><span class="pre">position</span></code> tests “false”. The positions that can be tested are:</p> <ul> <li><p class="first">“first”: position of cites that are the first to reference an item</p> </li> <li><p class="first">“ibid”/”ibid-with-locator”/”subsequent”: cites referencing previously cited items have the “subsequent” position. Such cites may also have the “ibid” or “ibid-with-locator” position when:</p> <ol class="loweralpha simple"> <li>the current cite immediately follows on another cite, within the same citation, that references the same item</li> </ol> <p>or</p> <ol class="loweralpha simple" start="2"> <li>the current cite is the first cite in the citation, and the previous citation consists of a single cite referencing the same item</li> </ol> <p>If either requirement is met, the presence of locators determines which position is assigned:</p> <ul class="simple"> <li><strong>Preceding cite does not have a locator</strong>: if the current cite has a locator, the position of the current cite is “ibid-with-locator”. Otherwise the position is “ibid”.</li> <li><strong>Preceding cite does have a locator</strong>: if the current cite has the same locator, the position of the current cite is “ibid”. If the locator differs the position is “ibid-with-locator”. If the current cite lacks a locator its only position is “subsequent”.</li> </ul> </li> <li><p class="first">“near-note”: position of a cite following another cite referencing the same item. Both cites have to be located in foot or endnotes, and the distance between both cites may not exceed the maximum distance (measured in number of foot or endnotes) set with the <code class="docutils literal notranslate"><span class="pre">near-note-distance</span></code> option (see <a class="reference internal" href="#note-distance">Note Distance</a>).</p> </li> </ul> <p class="last">Whenever position=”ibid-with-locator” tests true, position=”ibid” also tests true. And whenever position=”ibid” or position=”near-note” test true, position=”subsequent” also tests true.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">type</span></code></dt> <dd>Tests whether the item matches the given types (<a class="reference internal" href="#appendix-iii-types">Appendix III - Types</a>).</dd> <dt><code class="docutils literal notranslate"><span class="pre">variable</span></code></dt> <dd>Tests whether the default (long) forms of the given variables (<a class="reference internal" href="#appendix-iv-variables">Appendix IV - Variables</a>) contain non-empty values.</dd> </dl> <p>With the exception of <code class="docutils literal notranslate"><span class="pre">disambiguate</span></code>, all conditions allow for multiple test values (separated with spaces, e.g. “book thesis”).</p> <p>The <code class="docutils literal notranslate"><span class="pre">cs:if</span></code> and <code class="docutils literal notranslate"><span class="pre">cs:else-if</span></code> elements may carry the <code class="docutils literal notranslate"><span class="pre">match</span></code> attribute to control the testing logic, with allowed values:</p> <ul class="simple"> <li>“all” - (default), element only tests “true” when all conditions test “true” for all given test values</li> <li>“any” - element tests “true” when any condition tests “true” for any given test value</li> <li>“none” - element only tests “true” when none of the conditions test “true” for any given test value</li> </ul> <p>Delimiters from the nearest delimiters from the nearest ancestor delimiting element <em>are</em> applied within the output of <code class="docutils literal notranslate"><span class="pre">cs:choose</span></code> (i.e., the output of the matching <code class="docutils literal notranslate"><span class="pre">cs:if</span></code>, <code class="docutils literal notranslate"><span class="pre">cs:else-if</span></code>, or <code class="docutils literal notranslate"><span class="pre">cs:else</span></code>; see <a class="reference internal" href="#delimiter">delimiter</a>).</p> </div> </div> <div class="section" id="style-behavior"> <h2><a class="toc-backref" href="#toc-entry-48">Style Behavior</a><a class="headerlink" href="#style-behavior" title="Permalink to this headline">¶</a></h2> <div class="section" id="options"> <h3><a class="toc-backref" href="#toc-entry-49">Options</a><a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h3> <p>Styles may be configured with <a class="reference internal" href="#citation-specific-options">citation-specific options</a>, set as attributes on set on <code class="docutils literal notranslate"><span class="pre">cs:citation</span></code>, <a class="reference internal" href="#bibliography-specific-options">bibliography-specific options</a>, set on <code class="docutils literal notranslate"><span class="pre">cs:bibliography</span></code>, and <a class="reference internal" href="#global-options">global options</a> (these affect both citations and the bibliography), set on <code class="docutils literal notranslate"><span class="pre">cs:style</span></code>. <a class="reference internal" href="#inheritable-name-options">Inheritable name options</a> may be set on <code class="docutils literal notranslate"><span class="pre">cs:style</span></code>, <code class="docutils literal notranslate"><span class="pre">cs:citation</span></code> and <code class="docutils literal notranslate"><span class="pre">cs:bibliography</span></code>. Finally, <a class="reference internal" href="#locale-options">locale options</a> may be set on <code class="docutils literal notranslate"><span class="pre">cs:locale</span></code> elements.</p> <div class="section" id="citation-specific-options"> <h4><a class="toc-backref" href="#toc-entry-50">Citation-specific Options</a><a class="headerlink" href="#citation-specific-options" title="Permalink to this headline">¶</a></h4> <div class="section" id="disambiguation"> <h5><a class="toc-backref" href="#toc-entry-51">Disambiguation</a><a class="headerlink" href="#disambiguation" title="Permalink to this headline">¶</a></h5> <p>A cite is ambiguous when it matches multiple bibliographic entries <a class="footnote-reference" href="#footnote-1" id="footnote-reference-1">[1]</a>. Four methods are available to eliminate such ambiguity, which are always tried in the following order:</p> <ol class="arabic simple"> <li>Expand names (adding initials or full given names)</li> <li>Show more names</li> <li>Render the cite with the <code class="docutils literal notranslate"><span class="pre">disambiguate</span></code> attribute of <code class="docutils literal notranslate"><span class="pre">cs:choose</span></code> conditions testing “true”</li> <li>Add a year-suffix</li> </ol> <p>Method 1 can also be used for the separate purpose of global <em>name disambiguation</em>, covering both ambiguous and unambiguous cites throughout the document.</p> <p>The four disambiguation methods can be individually activated with the following optional attributes:</p> <dl class="docutils"> <dt><code class="docutils literal notranslate"><span class="pre">disambiguate-add-givenname</span></code> [Method (1)]</dt> <dd><p class="first">If set to “true” (“false” is the default), ambiguous names (names that are identical in their “short” or initialized “long” form, but differ when initials are added or the full given name is shown) are expanded. Name expansion can be configured with <code class="docutils literal notranslate"><span class="pre">givenname-disambiguation-rule</span></code>. An example of cite disambiguation:</p> <table border="1" class="last docutils"> <colgroup> <col width="48%" /> <col width="52%" /> </colgroup> <thead valign="bottom"> <tr class="row-odd"><th class="head">Original ambiguous cites</th> <th class="head">Disambiguated cites</th> </tr> </thead> <tbody valign="top"> <tr class="row-even"><td>(Simpson 2005; Simpson 2005)</td> <td>(H. Simpson 2005; B. Simpson 2005)</td> </tr> <tr class="row-odd"><td>(Doe 1950; Doe 1950)</td> <td>(John Doe 1950; Jane Doe 1950)</td> </tr> </tbody> </table> </dd> <dt><code class="docutils literal notranslate"><span class="pre">givenname-disambiguation-rule</span></code></dt> <dd><p class="first">Specifies (a) whether the purpose of name expansion is limited to disambiguating cites, or has the additional goal of disambiguating names (only in the latter case are ambiguous names in unambiguous cites expanded, e.g. from “(Doe 1950; Doe 2000)” to “(Jane Doe 1950; John Doe 2000)”), (b) whether name expansion targets all, or just the first name of each cite, and (c) the method by which each name is expanded.</p> <dl class="last docutils"> <dt><strong>Expansion of Individual Names</strong></dt> <dd><p class="first">The steps for expanding individual names are:</p> <ol class="last arabic"> <li><p class="first">If <code class="docutils literal notranslate"><span class="pre">initialize-with</span></code> is set and <code class="docutils literal notranslate"><span class="pre">initialize</span></code> has its default value of “true”, then:</p> <p>(a) Initials can be shown by rendering the name with a <code class="docutils literal notranslate"><span class="pre">form</span></code> value of “long” instead of “short” (e.g. “Doe” becomes “J. Doe”).</p> <p>(b) Full given names can be shown instead of initials by rendering the name with <code class="docutils literal notranslate"><span class="pre">initialize</span></code> set to “false” (e.g. “J. Doe” becomes “John Doe”).</p> </li> <li><p class="first">If <code class="docutils literal notranslate"><span class="pre">initialize-with</span></code> is <em>not</em> set, full given names can be shown by rendering the name with a <code class="docutils literal notranslate"><span class="pre">form</span></code> value of “long” instead of “short” (e.g. “Doe” becomes “John Doe”).</p> </li> </ol> </dd> <dt><strong>Given Name Disambiguation Rules</strong></dt> <dd><p class="first">Allowed values of <code class="docutils literal notranslate"><span class="pre">givenname-disambiguation-rule</span></code>:</p> <dl class="last docutils"> <dt>“all-names”</dt> <dd>Name expansion has the dual purpose of disambiguating cites and names. All rendered ambiguous names, in both ambiguous and unambiguous cites, are subject to disambiguation. Each name is progressively transformed until it is disambiguated. Names that cannot be disambiguated remain in their original form.</dd> <dt>“all-names-with-initials”</dt> <dd>As “all-names”, but name expansion is limited to showing initials (see step 1(a) above). No disambiguation attempt is made when <code class="docutils literal notranslate"><span class="pre">initialize-with</span></code> is not set or when <code class="docutils literal notranslate"><span class="pre">initialize</span></code> is set to “false”.</dd> <dt>“primary-name”</dt> <dd>As “all-names”, but disambiguation is limited to the first name of each cite.</dd> <dt>“primary-name-with-initials”</dt> <dd>As “all-names-with-initials”, but disambiguation is limited to the first name of each cite.</dd> <dt>“by-cite”</dt> <dd>Default. As “all-names”, but the goal of name expansion is limited to disambiguating cites. Only ambiguous names in ambiguous cites are affected, and disambiguation stops after the first name that eliminates cite ambiguity.</dd> </dl> </dd> </dl> </dd> <dt><code class="docutils literal notranslate"><span class="pre">disambiguate-add-names</span></code> [Method (2)]</dt> <dd>If set to “true” (“false” is the default), names that would otherwise be hidden as a result of et-al abbreviation are added one by one to all members of a set of ambiguous cites, until no more cites in the set can be disambiguated by adding names.</dd> </dl> <p>If both <code class="docutils literal notranslate"><span class="pre">disambiguate-add-givenname</span></code> and <code class="docutils literal notranslate"><span class="pre">disambiguate-add-names</span></code> are set to “true”, given name expansion is applied to rendered names first. If cites cannot be (fully) disambiguated by expanding the rendered names, then the names still hidden as a result of et-al abbreviation are added one by one to all members of a set of ambiguous cites. Added names are expanded if doing so would disambiguate the ambiguous cites. This process contines until no more cites in the set can be disambiguated by adding expanded names.</p> <p>In the description of disambiguation methods (1) and (2) above, we assumed that each (disambiguated) cite has an unambiguous link to its bibliographic entry. To assure that each cite does in fact uniquely identify its entry in the bibliography, detail that distinguishes cites (such as names, initials, and full given names) must be shown in the corresponding bibliography entries. If this is not the case, disambiguation methods (1) and (2) also act on all members of a set of ambiguously cited bibliographic entries, until no more entries in the set can be unambiguously cited by adding (expanded) names. Each method only takes effect on the involved bibliographic entries after it has been used to disambiguate cites.</p> <dl class="docutils"> <dt><code class="docutils literal notranslate"><span class="pre">disambiguate</span></code> condition [Method (3)]</dt> <dd>A disambiguation attempt can also be made by rendering ambiguous cites with the <code class="docutils literal notranslate"><span class="pre">disambiguate</span></code> condition testing “true” (see <a class="reference internal" href="#choose">Choose</a>).</dd> <dt><code class="docutils literal notranslate"><span class="pre">disambiguate-add-year-suffix</span></code> [Method (4)]</dt> <dd>If set to “true” (“false” is the default), an alphabetic year-suffix is added to ambiguous cites (e.g. “Doe 2007, Doe 2007” becomes “Doe 2007a, Doe 2007b”) and to their corresponding bibliographic entries. This final disambiguation method is always successful. The assignment of year-suffixes follows the order of the bibliographies entries, and additional letters are used once “z” is reached (“z”, “aa”, “ab”, …, “az”, “ba”, etc.). By default, the year-suffix is appended the first year rendered through <code class="docutils literal notranslate"><span class="pre">cs:date</span></code> in the cite and in the bibliographic entry, but its location can be controlled by explicitly rendering the “year-suffix” variable using <code class="docutils literal notranslate"><span class="pre">cs:text</span></code>. If “year-suffix” is rendered through <code class="docutils literal notranslate"><span class="pre">cs:text</span></code> in the scope of <code class="docutils literal notranslate"><span class="pre">cs:citation</span></code>, it is suppressed for <code class="docutils literal notranslate"><span class="pre">cs:bibliography</span></code>, unless it is also rendered through <code class="docutils literal notranslate"><span class="pre">cs:text</span></code> in the scope of <code class="docutils literal notranslate"><span class="pre">cs:bibliography</span></code>, and vice versa.</dd> </dl> <table class="docutils footnote" frame="void" id="footnote-1" rules="none"> <colgroup><col class="label" /><col /></colgroup> <tbody valign="top"> <tr><td class="label"><a class="fn-backref" href="#footnote-reference-1">[1]</a></td><td>Including uncited entries in the bibliography can make cites in the document ambiguous. To make sure such cites are disambiguated, the CSL processor should include (invisible) cites for such uncited bibliographic entries in the disambiguation process.</td></tr> </tbody> </table> </div> <div class="section" id="cite-grouping"> <h5><a class="toc-backref" href="#toc-entry-52">Cite Grouping</a><a class="headerlink" href="#cite-grouping" title="Permalink to this headline">¶</a></h5> <p>With cite grouping, cites in in-text citations with identical rendered names are grouped together, e.g. the year-sorted “(Doe 1999; Smith 2002; Doe 2006; Doe et al. 2007)” becomes “(Doe 1999; Doe 2006; Smith 2002; Doe et al. 2007)”. The comparison is limited to the output of the (first) <code class="docutils literal notranslate"><span class="pre">cs:names</span></code> element, but includes output rendered through <code class="docutils literal notranslate"><span class="pre">cs:substitute</span></code>. Cite grouping takes places after cite sorting and disambiguation. Grouped cites maintain their relative order, and are moved to the original location of the first cite of the group.</p> <p>Cite grouping can be activated by setting the <code class="docutils literal notranslate"><span class="pre">cite-group-delimiter</span></code> attribute or the <code class="docutils literal notranslate"><span class="pre">collapse</span></code> attributes on <code class="docutils literal notranslate"><span class="pre">cs:citation</span></code> (see also <a class="reference internal" href="#cite-collapsing">Cite Collapsing</a>).</p> <dl class="docutils"> <dt><code class="docutils literal notranslate"><span class="pre">cite-group-delimiter</span></code></dt> <dd>Activates cite grouping and specifies the delimiter for cites within a cite group. Defaults to “, “. E.g. with <code class="docutils literal notranslate"><span class="pre">delimiter</span></code> on <code class="docutils literal notranslate"><span class="pre">cs:layout</span></code> in <code class="docutils literal notranslate"><span class="pre">cs:citation</span></code> set to “; “, <code class="docutils literal notranslate"><span class="pre">collapse</span></code> set to “year”, and <code class="docutils literal notranslate"><span class="pre">cite-group-delimiter</span></code> set to “,”, citations look like “(Doe 1999,2001; Jones 2000)”.</dd> </dl> </div> <div class="section" id="cite-collapsing"> <h5><a class="toc-backref" href="#toc-entry-53">Cite Collapsing</a><a class="headerlink" href="#cite-collapsing" title="Permalink to this headline">¶</a></h5> <p>Cite groups (author and author-date styles), and numeric cite ranges (numeric styles) can be collapsed through the use of the <code class="docutils literal notranslate"><span class="pre">collapse</span></code> attribute. Delimiters for collapsed cite groups can be customized with the <code class="docutils literal notranslate"><span class="pre">year-suffix-delimiter</span></code> and <code class="docutils literal notranslate"><span class="pre">after-collapse-delimiter</span></code> attributes:</p> <dl class="docutils"> <dt><code class="docutils literal notranslate"><span class="pre">collapse</span></code></dt> <dd><p class="first">Activates cite grouping and collapsing. Allowed values:</p> <ul class="simple"> <li>“citation-number” - collapses ranges of cite numbers (rendered through the “citation-number” variable) in citations for “numeric” styles (e.g. from “[1, 2, 3, 5]” to “[1–3, 5]”). Only increasing ranges collapse, e.g. “[3, 2, 1]” will not collapse (to see how to sort cites by “citation-number”, see <a class="reference internal" href="#sorting">Sorting</a>).</li> <li>“year” - collapses cite groups by suppressing the output of the <code class="docutils literal notranslate"><span class="pre">cs:names</span></code> element for subsequent cites in the group, e.g. “(Doe 2000, Doe 2001)” becomes “(Doe 2000, 2001)”.</li> <li>“year-suffix” - collapses as “year”, but also suppresses repeating years within the cite group, e.g. “(Doe 2000a, b)” instead of “(Doe 2000a, 2000b)”.</li> <li>“year-suffix-ranged” - collapses as “year-suffix”, but also collapses ranges of year-suffixes, e.g. “(Doe 2000a–c,e)” instead of “(Doe 2000a, b, c, e)”.</li> </ul> <p class="last">“year-suffix” and “year-suffix-ranged” fall back to “year” when <code class="docutils literal notranslate"><span class="pre">disambiguate-add-year-suffix</span></code> is “false” (see <a class="reference internal" href="#disambiguation">Disambiguation</a>), or when a cite has a locator (e.g. “(Doe 2000a-c, 2000d, p. 5, 2000e,f)”, where the cite for “Doe 2000d” has a locator that prevents the cite from further collapsing).</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">year-suffix-delimiter</span></code></dt> <dd>Specifies the delimiter for year-suffixes. Defaults to the delimiter set on <code class="docutils literal notranslate"><span class="pre">cs:layout</span></code> in <code class="docutils literal notranslate"><span class="pre">cs:citation</span></code>. E.g. with <code class="docutils literal notranslate"><span class="pre">collapse</span></code> set to “year-suffix”, <code class="docutils literal notranslate"><span class="pre">delimiter</span></code> on <code class="docutils literal notranslate"><span class="pre">cs:layout</span></code> in <code class="docutils literal notranslate"><span class="pre">cs:citation</span></code> set to “; “, and <code class="docutils literal notranslate"><span class="pre">year-suffix-delimiter</span></code> set to “,”, citations look like “(Doe 1999a,b; Jones 2000)”.</dd> <dt><code class="docutils literal notranslate"><span class="pre">after-collapse-delimiter</span></code></dt> <dd>Specifies the cite delimiter to be used <em>after</em> a collapsed cite group. Defaults to the delimiter set on <code class="docutils literal notranslate"><span class="pre">cs:layout</span></code> in <code class="docutils literal notranslate"><span class="pre">cs:citation</span></code>. E.g. with <code class="docutils literal notranslate"><span class="pre">collapse</span></code> set to “year”, <code class="docutils literal notranslate"><span class="pre">delimiter</span></code> on <code class="docutils literal notranslate"><span class="pre">cs:layout</span></code> in <code class="docutils literal notranslate"><span class="pre">cs:citation</span></code> set to “, “, and <code class="docutils literal notranslate"><span class="pre">after-collapse-delimiter</span></code> set to “; “, citations look like “(Doe 1999, 2001; Jones 2000, Brown 2001)”.</dd> </dl> </div> <div class="section" id="note-distance"> <h5><a class="toc-backref" href="#toc-entry-54">Note Distance</a><a class="headerlink" href="#note-distance" title="Permalink to this headline">¶</a></h5> <dl class="docutils"> <dt><code class="docutils literal notranslate"><span class="pre">near-note-distance</span></code></dt> <dd>A cite tests true for the “near-note” position (see <a class="reference internal" href="#choose">Choose</a>) when a preceding note exists that a) refers to the same item and b) does not precede the current note by more footnotes or endnotes than the value of <code class="docutils literal notranslate"><span class="pre">near-note-distance</span></code> (default value is “5”).</dd> </dl> </div> </div> <div class="section" id="bibliography-specific-options"> <h4><a class="toc-backref" href="#toc-entry-55">Bibliography-specific Options</a><a class="headerlink" href="#bibliography-specific-options" title="Permalink to this headline">¶</a></h4> <div class="section" id="whitespace"> <h5><a class="toc-backref" href="#toc-entry-56">Whitespace</a><a class="headerlink" href="#whitespace" title="Permalink to this headline">¶</a></h5> <dl class="docutils"> <dt><code class="docutils literal notranslate"><span class="pre">hanging-indent</span></code></dt> <dd>If set to “true” (“false” is the default), bibliographic entries are rendered with hanging-indents.</dd> <dt><code class="docutils literal notranslate"><span class="pre">second-field-align</span></code></dt> <dd><p class="first">If set, subsequent lines of bibliographic entries are aligned along the second field. With “flush”, the first field is flush with the margin. With “margin”, the first field is put in the margin, and subsequent lines are aligned with the margin. An example, where the first field is <code class="docutils literal notranslate"><span class="pre"><text</span> <span class="pre">variable="citation-number"</span> <span class="pre">suffix=".</span> <span class="pre">"/></span></code>:</p> <div class="last highlight-default notranslate"><div class="highlight"><pre><span></span><span class="mf">9.</span> <span class="n">Adams</span><span class="p">,</span> <span class="n">D</span><span class="o">.</span> <span class="p">(</span><span class="mi">2002</span><span class="p">)</span><span class="o">.</span> <span class="n">The</span> <span class="n">Ultimate</span> <span class="n">Hitchhiker</span><span class="s1">'s Guide to the</span> <span class="n">Galaxy</span> <span class="p">(</span><span class="mi">1</span><span class="n">st</span> <span class="n">ed</span><span class="o">.</span><span class="p">)</span><span class="o">.</span> <span class="mf">10.</span> <span class="n">Asimov</span><span class="p">,</span> <span class="n">I</span><span class="o">.</span> <span class="p">(</span><span class="mi">1951</span><span class="p">)</span><span class="o">.</span> <span class="n">Foundation</span><span class="o">.</span> </pre></div> </div> </dd> <dt><code class="docutils literal notranslate"><span class="pre">line-spacing</span></code></dt> <dd>Specifies vertical line distance. Defaults to “1” (single-spacing), and can be set to any positive integer to specify a multiple of the standard unit of line height (e.g. “2” for double-spacing).</dd> <dt><code class="docutils literal notranslate"><span class="pre">entry-spacing</span></code></dt> <dd>Specifies vertical distance between bibliographic entries. By default (with a value of “1”), entries are separated by a single additional line-height (as set by the line-spacing attribute). Can be set to any non-negative integer to specify a multiple of this amount.</dd> </dl> </div> <div class="section" id="reference-grouping"> <h5><a class="toc-backref" href="#toc-entry-57">Reference Grouping</a><a class="headerlink" href="#reference-grouping" title="Permalink to this headline">¶</a></h5> <dl class="docutils"> <dt><code class="docutils literal notranslate"><span class="pre">subsequent-author-substitute</span></code></dt> <dd>If set, the value of this attribute replaces names in a bibliographic entry that also occur in the preceding entry. The exact method of substitution depends on the value of the <code class="docutils literal notranslate"><span class="pre">subsequent-author-substitute-rule</span></code> attribute. Substitution is limited to the names of the first <code class="docutils literal notranslate"><span class="pre">cs:names</span></code> element rendered.</dd> <dt><code class="docutils literal notranslate"><span class="pre">subsequent-author-substitute-rule</span></code></dt> <dd><p class="first">Specifies when and how names are substituted as a result of <code class="docutils literal notranslate"><span class="pre">subsequent-author-substitute</span></code>. Allowed values:</p> <ul class="simple"> <li>“complete-all” - (default), when all names of the name variable match those in the preceding bibliographic entry, the value of <code class="docutils literal notranslate"><span class="pre">subsequent-author-substitute</span></code> replaces the entire name list (including punctuation and terms like “et al” and “and”), except for the affixes set on the <code class="docutils literal notranslate"><span class="pre">cs:names</span></code> element.</li> <li>“complete-each” - requires a complete match like “complete-all”, but now the value of <code class="docutils literal notranslate"><span class="pre">subsequent-author-substitute</span></code> substitutes for each rendered name.</li> <li>“partial-each” - when one or more rendered names in the name variable match those in the preceding bibliographic entry, the value of <code class="docutils literal notranslate"><span class="pre">subsequent-author-substitute</span></code> substitutes for each matching name. Matching starts with the first name, and continues up to the first mismatch.</li> <li>“partial-first” - as “partial-each”, but substitution is limited to the first name of the name variable.</li> </ul> <p>For example, take the following bibliographic entries:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Doe</span><span class="o">.</span> <span class="mf">1999.</span> <span class="n">Doe</span><span class="o">.</span> <span class="mf">2000.</span> <span class="n">Doe</span><span class="p">,</span> <span class="n">Johnson</span> <span class="o">&</span> <span class="n">Williams</span><span class="o">.</span> <span class="mf">2001.</span> <span class="n">Doe</span> <span class="o">&</span> <span class="n">Smith</span><span class="o">.</span> <span class="mf">2002.</span> <span class="n">Doe</span><span class="p">,</span> <span class="n">Stevens</span> <span class="o">&</span> <span class="n">Miller</span><span class="o">.</span> <span class="mf">2003.</span> <span class="n">Doe</span><span class="p">,</span> <span class="n">Stevens</span> <span class="o">&</span> <span class="n">Miller</span><span class="o">.</span> <span class="mf">2004.</span> <span class="n">Doe</span><span class="p">,</span> <span class="n">Williams</span> <span class="n">et</span> <span class="n">al</span><span class="o">.</span> <span class="mf">2005.</span> <span class="n">Doe</span><span class="p">,</span> <span class="n">Williams</span> <span class="n">et</span> <span class="n">al</span><span class="o">.</span> <span class="mf">2006.</span> </pre></div> </div> <p>With <code class="docutils literal notranslate"><span class="pre">subsequent-author-substitute</span></code> set to “—”, and <code class="docutils literal notranslate"><span class="pre">subsequent-author-substitute-rule</span></code> set to “complete-all”, this becomes:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Doe</span><span class="o">.</span> <span class="mf">1999.</span> <span class="o">---.</span> <span class="mf">2000.</span> <span class="n">Doe</span><span class="p">,</span> <span class="n">Johnson</span> <span class="o">&</span> <span class="n">Williams</span><span class="o">.</span> <span class="mf">2001.</span> <span class="n">Doe</span> <span class="o">&</span> <span class="n">Smith</span><span class="o">.</span> <span class="mf">2002.</span> <span class="n">Doe</span><span class="p">,</span> <span class="n">Stevens</span> <span class="o">&</span> <span class="n">Miller</span><span class="o">.</span> <span class="mf">2003.</span> <span class="o">---.</span> <span class="mf">2004.</span> <span class="n">Doe</span><span class="p">,</span> <span class="n">Williams</span> <span class="n">et</span> <span class="n">al</span><span class="o">.</span> <span class="mf">2005.</span> <span class="o">---.</span> <span class="mf">2005.</span> </pre></div> </div> <p>With <code class="docutils literal notranslate"><span class="pre">subsequent-author-substitute-rule</span></code> set to “complete-each”, this becomes:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Doe</span><span class="o">.</span> <span class="mf">1999.</span> <span class="o">---.</span> <span class="mf">2000.</span> <span class="n">Doe</span><span class="p">,</span> <span class="n">Johnson</span> <span class="o">&</span> <span class="n">Williams</span><span class="o">.</span> <span class="mf">2001.</span> <span class="n">Doe</span> <span class="o">&</span> <span class="n">Smith</span><span class="o">.</span> <span class="mf">2002.</span> <span class="n">Doe</span><span class="p">,</span> <span class="n">Stevens</span> <span class="o">&</span> <span class="n">Miller</span><span class="o">.</span> <span class="mf">2003.</span> <span class="o">---</span><span class="p">,</span> <span class="o">---</span> <span class="o">&</span> <span class="o">---.</span> <span class="mf">2004.</span> <span class="n">Doe</span><span class="p">,</span> <span class="n">Williams</span> <span class="n">et</span> <span class="n">al</span><span class="o">.</span> <span class="mf">2005.</span> <span class="o">---</span><span class="p">,</span> <span class="o">---</span> <span class="n">et</span> <span class="n">al</span><span class="o">.</span> <span class="mf">2006.</span> </pre></div> </div> <p>With <code class="docutils literal notranslate"><span class="pre">subsequent-author-substitute-rule</span></code> set to “partial-each”, this becomes:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Doe</span><span class="o">.</span> <span class="mf">1999.</span> <span class="o">---.</span> <span class="mf">2000.</span> <span class="n">Doe</span><span class="p">,</span> <span class="n">Johnson</span> <span class="o">&</span> <span class="n">Williams</span><span class="o">.</span> <span class="mf">2001.</span> <span class="o">---</span> <span class="o">&</span> <span class="n">Smith</span><span class="o">.</span> <span class="mf">2002.</span> <span class="n">Doe</span><span class="p">,</span> <span class="n">Stevens</span> <span class="o">&</span> <span class="n">Miller</span><span class="o">.</span> <span class="mf">2003.</span> <span class="o">---</span><span class="p">,</span> <span class="o">---</span> <span class="o">&</span> <span class="o">---.</span> <span class="mf">2004.</span> <span class="n">Doe</span><span class="p">,</span> <span class="n">Williams</span> <span class="n">et</span> <span class="n">al</span><span class="o">.</span> <span class="mf">2005.</span> <span class="o">---</span><span class="p">,</span> <span class="o">---</span> <span class="n">et</span> <span class="n">al</span><span class="o">.</span> <span class="mf">2005.</span> </pre></div> </div> <p>With <code class="docutils literal notranslate"><span class="pre">subsequent-author-substitute-rule</span></code> set to “partial-first”, this becomes:</p> <div class="last highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Doe</span><span class="o">.</span> <span class="mf">1999.</span> <span class="o">---.</span> <span class="mf">2000.</span> <span class="n">Doe</span><span class="p">,</span> <span class="n">Johnson</span> <span class="o">&</span> <span class="n">Williams</span><span class="o">.</span> <span class="mf">2001.</span> <span class="o">---</span> <span class="o">&</span> <span class="n">Smith</span><span class="o">.</span> <span class="mf">2002.</span> <span class="n">Doe</span><span class="p">,</span> <span class="n">Stevens</span> <span class="o">&</span> <span class="n">Miller</span><span class="o">.</span> <span class="mf">2003.</span> <span class="o">---</span><span class="p">,</span> <span class="n">Stevens</span> <span class="o">&</span> <span class="n">Miller</span><span class="o">.</span> <span class="mf">2004.</span> <span class="n">Doe</span><span class="p">,</span> <span class="n">Williams</span> <span class="n">et</span> <span class="n">al</span><span class="o">.</span> <span class="mf">2005.</span> <span class="o">---</span><span class="p">,</span> <span class="n">Williams</span> <span class="n">et</span> <span class="n">al</span><span class="o">.</span> <span class="mf">2005.</span> </pre></div> </div> </dd> </dl> </div> </div> <div class="section" id="global-options"> <h4><a class="toc-backref" href="#toc-entry-58">Global Options</a><a class="headerlink" href="#global-options" title="Permalink to this headline">¶</a></h4> <div class="section" id="hyphenation-of-initialized-names"> <h5><a class="toc-backref" href="#toc-entry-59">Hyphenation of Initialized Names</a><a class="headerlink" href="#hyphenation-of-initialized-names" title="Permalink to this headline">¶</a></h5> <dl class="docutils"> <dt><code class="docutils literal notranslate"><span class="pre">initialize-with-hyphen</span></code></dt> <dd>Specifies whether compound given names (e.g. “Jean-Luc”) should be initialized with a hyphen (“J.-L.”, value “true”, default) or without (“J. L.”, value “false”).</dd> </dl> </div> <div class="section" id="page-ranges"> <h5><a class="toc-backref" href="#toc-entry-60">Page Ranges</a><a class="headerlink" href="#page-ranges" title="Permalink to this headline">¶</a></h5> <dl class="docutils"> <dt><code class="docutils literal notranslate"><span class="pre">page-range-format</span></code></dt> <dd>Activates expansion or collapsing of page ranges: “chicago” (“321–28”), “expanded” (e.g. “321–328”), “minimal” (“321–8”), or “minimal-two” (“321–28”) (see also <a class="reference internal" href="#appendix-v-page-range-formats">Appendix V - Page Range Formats</a>). Delimits page ranges with the “page-range-delimiter” term (introduced with CSL 1.0.1, and defaults to an en-dash). If the attribute is not set, page ranges are rendered without reformatting.</dd> </dl> </div> <div class="section" id="name-particles"> <h5><a class="toc-backref" href="#toc-entry-61">Name Particles</a><a class="headerlink" href="#name-particles" title="Permalink to this headline">¶</a></h5> <p>Western names frequently contain one or more name particles (e.g. “van” in the Dutch name “Vincent van Gogh”). These name particles can be either kept or dropped when only the surname is shown: these two types are referred to as non-dropping and dropping particles, respectively. Theoretically, a single name might contain particles of both types (with non-dropping particles always following dropping particles), though currently we are not aware of any real-life examples. For example, the Dutch name “Vincent van Gogh”, the German name “Alexander von Humboldt”, and the Arabic name “Tawfiq al-Hakim” can be deconstructed into:</p> <blockquote> <div><div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span> <span class="s2">"author"</span><span class="p">:</span> <span class="p">[</span> <span class="p">{</span> <span class="s2">"given"</span><span class="p">:</span> <span class="s2">"Vincent"</span><span class="p">,</span> <span class="s2">"non-dropping-particle"</span><span class="p">:</span> <span class="s2">"van"</span><span class="p">,</span> <span class="s2">"family"</span><span class="p">:</span> <span class="s2">"Gogh"</span> <span class="p">},</span> <span class="p">{</span> <span class="s2">"given"</span><span class="p">:</span> <span class="s2">"Alexander"</span><span class="p">,</span> <span class="s2">"dropping-particle"</span><span class="p">:</span> <span class="s2">"von"</span><span class="p">,</span> <span class="s2">"family"</span><span class="p">:</span> <span class="s2">"Humboldt"</span> <span class="p">}</span> <span class="p">{</span> <span class="s2">"given"</span><span class="p">:</span> <span class="s2">"Tawfiq"</span><span class="p">,</span> <span class="s2">"non-dropping-particle"</span><span class="p">:</span> <span class="s2">"al-"</span><span class="p">,</span> <span class="s2">"family"</span><span class="p">:</span> <span class="s2">"Hakim"</span> <span class="p">}</span> <span class="p">]</span> <span class="p">}</span> </pre></div> </div> </div></blockquote> <p>When just the surname is shown, only the non-dropping-particle is kept: “Van Gogh” and “al-Hakim”, but “Humboldt”.</p> <p>In the case of inverted names, where the family name precedes the given name, the dropping-particle is always appended to the family name, but the non-dropping-particle can be either prepended (e.g. “van Gogh, Vincent”) or appended (after initials or given names, e.g. “Gogh, Vincent van”). For inverted names where the non-dropping-particle is prepended, names can either be sorted by keeping the non-dropping-particle together with the family name as part of the primary sort key (sort order A), or by separating the non-dropping-particle from the family name and have it become (part of) a secondary sort key, joining the dropping-particle, if available (sort order B):</p> <p><strong>Sort order A: non-dropping-particle not demoted</strong></p> <ul class="simple"> <li>primary sort key: “van Gogh”</li> <li>secondary sort key: “”</li> <li>tertiary sort key: “Vincent”</li> </ul> <p><strong>Sort order B: non-dropping-particle demoted</strong></p> <ul class="simple"> <li>primary sort key: “Gogh”</li> <li>secondary sort key: “van”</li> <li>tertiary sort key: “Vincent”</li> </ul> <p>The handling of the non-dropping-particle can be customized with the <code class="docutils literal notranslate"><span class="pre">demote-non-dropping-particle</span></code> option:</p> <dl class="docutils"> <dt><code class="docutils literal notranslate"><span class="pre">demote-non-dropping-particle</span></code></dt> <dd><p class="first">Sets the display and sorting behavior of the non-dropping-particle in inverted names (e.g. “Gogh, Vincent van”). Allowed values:</p> <ul class="last simple"> <li>“never”: the non-dropping-particle is treated as part of the family name, whereas the dropping-particle is appended (e.g. “van Gogh, Vincent”, “Humboldt, Alexander von”). The non-dropping-particle is part of the primary sort key (sort order A, e.g. “van Gogh, Vincent” appears under “V”).</li> <li>“sort-only”: same display behavior as “never”, but the non-dropping-particle is demoted to a secondary sort key (sort order B, e.g. “van Gogh, Vincent” appears under “G”).</li> <li>“display-and-sort” (default): the dropping and non-dropping-particle are appended (e.g. “Gogh, Vincent van” and “Humboldt, Alexander von”). For name sorting, all particles are part of the secondary sort key (sort order B, e.g. “Gogh, Vincent van” appears under “G”).</li> </ul> </dd> </dl> <p>Some names include a particle that should never be demoted. For these cases the particle should just be included in the family name field, for example for the French general Charles de Gaulle and the writer Jean de La Fontaine:</p> <blockquote> <div><div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span> <span class="s2">"author"</span><span class="p">:</span> <span class="p">[</span> <span class="p">{</span> <span class="s2">"given"</span><span class="p">:</span> <span class="s2">"Charles"</span> <span class="s2">"family"</span><span class="p">:</span> <span class="s2">"de Gaulle"</span><span class="p">,</span> <span class="p">},</span> <span class="p">{</span> <span class="s2">"given"</span><span class="p">:</span> <span class="s2">"Jean"</span> <span class="s2">"dropping-particle"</span><span class="p">:</span> <span class="s2">"de"</span><span class="p">,</span> <span class="s2">"family"</span><span class="p">:</span> <span class="s2">"La Fontaine"</span><span class="p">,</span> <span class="p">}</span> <span class="p">]</span> <span class="p">}</span> </pre></div> </div> </div></blockquote> </div> </div> <div class="section" id="inheritable-name-options"> <h4><a class="toc-backref" href="#toc-entry-62">Inheritable Name Options</a><a class="headerlink" href="#inheritable-name-options" title="Permalink to this headline">¶</a></h4> <p>Attributes for the <code class="docutils literal notranslate"><span class="pre">cs:names</span></code> and <code class="docutils literal notranslate"><span class="pre">cs:name</span></code> elements may also be set on <code class="docutils literal notranslate"><span class="pre">cs:style</span></code>, <code class="docutils literal notranslate"><span class="pre">cs:citation</span></code> and <code class="docutils literal notranslate"><span class="pre">cs:bibliography</span></code>. This eliminates the need to repeat the same attributes and attribute values for every occurrence of the <code class="docutils literal notranslate"><span class="pre">cs:names</span></code> and <code class="docutils literal notranslate"><span class="pre">cs:name</span></code> elements.</p> <p>The available inheritable attributes for <code class="docutils literal notranslate"><span class="pre">cs:name</span></code> are <code class="docutils literal notranslate"><span class="pre">and</span></code>, <code class="docutils literal notranslate"><span class="pre">delimiter-precedes-et-al</span></code>, <code class="docutils literal notranslate"><span class="pre">delimiter-precedes-last</span></code>, <code class="docutils literal notranslate"><span class="pre">et-al-min</span></code>, <code class="docutils literal notranslate"><span class="pre">et-al-use-first</span></code>, <code class="docutils literal notranslate"><span class="pre">et-al-use-last</span></code>, <code class="docutils literal notranslate"><span class="pre">et-al-subsequent-min</span></code>, <code class="docutils literal notranslate"><span class="pre">et-al-subsequent-use-first</span></code>, <code class="docutils literal notranslate"><span class="pre">initialize</span></code>, <code class="docutils literal notranslate"><span class="pre">initialize-with</span></code>, <code class="docutils literal notranslate"><span class="pre">name-as-sort-order</span></code> and <code class="docutils literal notranslate"><span class="pre">sort-separator</span></code>. The attributes <code class="docutils literal notranslate"><span class="pre">name-form</span></code> and <code class="docutils literal notranslate"><span class="pre">name-delimiter</span></code> correspond to the <code class="docutils literal notranslate"><span class="pre">form</span></code> and <code class="docutils literal notranslate"><span class="pre">delimiter</span></code> attributes on <code class="docutils literal notranslate"><span class="pre">cs:name</span></code>. Similarly, <code class="docutils literal notranslate"><span class="pre">names-delimiter</span></code> corresponds to the <code class="docutils literal notranslate"><span class="pre">delimiter</span></code> attribute on <code class="docutils literal notranslate"><span class="pre">cs:names</span></code>.</p> <p>When an inheritable name attribute is set on <code class="docutils literal notranslate"><span class="pre">cs:style</span></code>, <code class="docutils literal notranslate"><span class="pre">cs:citation</span></code> or <code class="docutils literal notranslate"><span class="pre">cs:bibliography</span></code>, its value is used for all <code class="docutils literal notranslate"><span class="pre">cs:names</span></code> elements within the scope of the element carrying the attribute. If an attribute is set on multiple hierarchical levels, the value set at the lowest level is used.</p> </div> <div class="section" id="locale-options"> <h4><a class="toc-backref" href="#toc-entry-63">Locale Options</a><a class="headerlink" href="#locale-options" title="Permalink to this headline">¶</a></h4> <dl class="docutils"> <dt><code class="docutils literal notranslate"><span class="pre">limit-day-ordinals-to-day-1</span></code></dt> <dd>Date formats are defined by the <code class="docutils literal notranslate"><span class="pre">cs:date</span></code> element and its <code class="docutils literal notranslate"><span class="pre">cs:date-part</span></code> child elements (see <a class="reference internal" href="#date">Date</a>). By default, when the <code class="docutils literal notranslate"><span class="pre">cs:date-part</span></code> element with <code class="docutils literal notranslate"><span class="pre">name</span></code> set to “day” has <code class="docutils literal notranslate"><span class="pre">form</span></code> set to “ordinal”, all days (1 through 31) are rendered in the ordinal form, e.g. “January 1st”, “January 2nd”, etc. By setting <code class="docutils literal notranslate"><span class="pre">limit-day-ordinals-to-day-1</span></code> to “true” (“false” is the default), the “ordinal” form is limited to the first day of each month (other days will use the “numeric” form). This is desirable for some languages, such as French: “1er janvier”, but “2 janvier”, “3 janvier”, etc.</dd> <dt><code class="docutils literal notranslate"><span class="pre">punctuation-in-quote</span></code></dt> <dd>For <code class="docutils literal notranslate"><span class="pre">cs:text</span></code> elements rendered with the <code class="docutils literal notranslate"><span class="pre">quotes</span></code> attribute set to “true” (see <a class="reference internal" href="#formatting">Formatting</a>), and for which the output is followed by a comma or period, <code class="docutils literal notranslate"><span class="pre">punctuation-in-quote</span></code> specifies whether this punctuation is placed outside (value “false”, default) or inside (value “true”) the closing quotation mark.</dd> </dl> </div> </div> <div class="section" id="sorting"> <h3><a class="toc-backref" href="#toc-entry-64">Sorting</a><a class="headerlink" href="#sorting" title="Permalink to this headline">¶</a></h3> <p><code class="docutils literal notranslate"><span class="pre">cs:citation</span></code> and <code class="docutils literal notranslate"><span class="pre">cs:bibliography</span></code> may include a <code class="docutils literal notranslate"><span class="pre">cs:sort</span></code> child element before the <code class="docutils literal notranslate"><span class="pre">cs:layout</span></code> element to specify the sorting order of respectively cites within citations, and bibliographic entries within the bibliography. In the absence of <code class="docutils literal notranslate"><span class="pre">cs:sort</span></code>, cites and bibliographic entries appear in the order in which they are cited.</p> <p>The <code class="docutils literal notranslate"><span class="pre">cs:sort</span></code> element must contain one or more <code class="docutils literal notranslate"><span class="pre">cs:key</span></code> child elements. The sort key, set as an attribute on <code class="docutils literal notranslate"><span class="pre">cs:key</span></code>, must be a variable (see <a class="reference internal" href="#appendix-iv-variables">Appendix IV - Variables</a>) or macro name. For each <code class="docutils literal notranslate"><span class="pre">cs:key</span></code> element, the sort direction can be set to either “ascending” (default) or “descending” with the <code class="docutils literal notranslate"><span class="pre">sort</span></code> attribute. Sorting is case-insensitive. The attributes <code class="docutils literal notranslate"><span class="pre">names-min</span></code>, <code class="docutils literal notranslate"><span class="pre">names-use-first</span></code>, and <code class="docutils literal notranslate"><span class="pre">names-use-last</span></code> may be used to override the values of the corresponding <code class="docutils literal notranslate"><span class="pre">et-al-min</span></code>/<code class="docutils literal notranslate"><span class="pre">et-al-subsequent-min</span></code>, <code class="docutils literal notranslate"><span class="pre">et-al-use-first</span></code>/<code class="docutils literal notranslate"><span class="pre">et-al-subsequent-use-first</span></code> and <code class="docutils literal notranslate"><span class="pre">et-al-use-last</span></code> attributes, and affect all names generated via macros called by <code class="docutils literal notranslate"><span class="pre">cs:key</span></code>.</p> <p>Sort keys are evaluated in sequence. A primary sort is performed on all items using the first sort key. A secondary sort, using the second sort key, is applied to items sharing the first sort key value. A tertiary sort, using the third sort key, is applied to items sharing the first and second sort key values. Sorting continues until either the order of all items is fixed, or until the sort keys are exhausted. Items with an empty sort key value are placed at the end of the sort, both for ascending and descending sorts.</p> <p>An example, where cites are first sorted by the output of the “author” macro, with overriding settings for et-al abbreviation. Cites sharing the primary sort key are subsequently sorted in descending order by the “issued” date variable.</p> <div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="nt"><citation></span> <span class="nt"><sort></span> <span class="nt"><key</span> <span class="na">macro=</span><span class="s">"author"</span> <span class="na">names-min=</span><span class="s">"3"</span> <span class="na">names-use-first=</span><span class="s">"3"</span><span class="nt">/></span> <span class="nt"><key</span> <span class="na">variable=</span><span class="s">"issued"</span> <span class="na">sort=</span><span class="s">"descending"</span><span class="nt">/></span> <span class="nt"></sort></span> <span class="nt"><layout></span> <span class="c"></span> <span class="nt"></layout></span> <span class="nt"></citation></span> </pre></div> </div> <p>The sort key value of a variable or macro can differ from the “normal” rendered output. The specifics of sorting variables and macros:</p> <div class="section" id="sorting-variables"> <h4><a class="toc-backref" href="#toc-entry-65">Sorting Variables</a><a class="headerlink" href="#sorting-variables" title="Permalink to this headline">¶</a></h4> <p>The sort key value for a variable called by <code class="docutils literal notranslate"><span class="pre">cs:key</span></code> via the <code class="docutils literal notranslate"><span class="pre">variable</span></code> attribute consists of the string value, without rich text markup. Exceptions are name, date and numeric variables:</p> <p><strong>names:</strong> <a class="reference internal" href="#name-variables">Name variables</a> called via the <code class="docutils literal notranslate"><span class="pre">variable</span></code> attribute (e.g. <code class="docutils literal notranslate"><span class="pre"><key</span> <span class="pre">variable="author"/></span></code>) are returned as a name list string, with the <code class="docutils literal notranslate"><span class="pre">cs:name</span></code> attributes <code class="docutils literal notranslate"><span class="pre">form</span></code> set to “long”, and <code class="docutils literal notranslate"><span class="pre">name-as-sort-order</span></code> set to “all”.</p> <p><strong>dates:</strong> <a class="reference internal" href="#date-variables">Date variables</a> called via the <code class="docutils literal notranslate"><span class="pre">variable</span></code> attribute are returned in the YYYYMMDD format, with zeros substituted for any missing date-parts (e.g. 20001200 for December 2000). As a result, less specific dates precede more specific dates in ascending sorts, e.g. “2000, May 2000, May 1st 2000”. Negative years are sorted inversely, e.g. “100BC, 50BC, 50AD, 100AD”. Seasons are ignored for sorting, as the chronological order of the seasons differs between the northern and southern hemispheres. In the case of date ranges, the start date is used for the primary sort, and the end date is used for a secondary sort, e.g. “2000–2001, 2000–2005, 2002–2003, 2002–2009”. Date ranges are placed after single dates when they share the same (start) date, e.g. “2000, 2000–2002”.</p> <p><strong>numbers:</strong> <a class="reference internal" href="#number-variables">Number variables</a> called via the <code class="docutils literal notranslate"><span class="pre">variable</span></code> attribute are returned as integers (<code class="docutils literal notranslate"><span class="pre">form</span></code> is “numeric”). If the original variable value only consists of non-numeric text, the value is returned as a text string.</p> </div> <div class="section" id="sorting-macros"> <h4><a class="toc-backref" href="#toc-entry-66">Sorting Macros</a><a class="headerlink" href="#sorting-macros" title="Permalink to this headline">¶</a></h4> <p>The sort key value for a macro called via <code class="docutils literal notranslate"><span class="pre">cs:key</span></code> via the <code class="docutils literal notranslate"><span class="pre">macro</span></code> attribute generally consists of the string value the macro would ordinarily generate, without rich text markup (exceptions are discussed below).</p> <p>When sorting by <a class="reference internal" href="#name-variables">name variables</a> rendered within the macro, any <code class="docutils literal notranslate"><span class="pre">cs:label</span></code> elements are excluded from the sort key values. Name variables are also returned with the <code class="docutils literal notranslate"><span class="pre">cs:name</span></code> attribute <code class="docutils literal notranslate"><span class="pre">name-as-sort-order</span></code> set to “all”. When et-al abbreviation occurs, the “et-al” and “and others” terms are excluded from the sort key values.</p> <p>There are four advantages in using the same macro for rendering and sorting, instead of sorting directly on the name variable. First, substitution is available (e.g. the “editor” variable might substitute for an empty “author” variable). Second, et-al abbreviation can be used (using either the <code class="docutils literal notranslate"><span class="pre">et-al-min</span></code>/<code class="docutils literal notranslate"><span class="pre">et-al-subsequent-min</span></code>, <code class="docutils literal notranslate"><span class="pre">et-al-use-first</span></code>/<code class="docutils literal notranslate"><span class="pre">et-al-subsequent-use-first</span></code>, and <code class="docutils literal notranslate"><span class="pre">et-al-use-last</span></code> options defined for the macro, or the overriding <code class="docutils literal notranslate"><span class="pre">names-min</span></code>, <code class="docutils literal notranslate"><span class="pre">names-use-first</span></code> and <code class="docutils literal notranslate"><span class="pre">names-use-last</span></code> attributes set on <code class="docutils literal notranslate"><span class="pre">cs:key</span></code>). Third, names can be sorted by just the surname (using a macro for which the <code class="docutils literal notranslate"><span class="pre">form</span></code> attribute on <code class="docutils literal notranslate"><span class="pre">cs:name</span></code> is set to “short”). Fourth, it is possible to sort by the number of names in a name list, by calling a macro for which the <code class="docutils literal notranslate"><span class="pre">form</span></code> attribute on <code class="docutils literal notranslate"><span class="pre">cs:name</span></code> is set to “count”.</p> <p><a class="reference internal" href="#number-variables">Number variables</a> rendered within the macro with <code class="docutils literal notranslate"><span class="pre">cs:number</span></code> and <a class="reference internal" href="#date-variables">date variables</a> are treated the same as when they are called via <code class="docutils literal notranslate"><span class="pre">variable</span></code>. The only exception is that the complete date is returned if a date variable is called via the <code class="docutils literal notranslate"><span class="pre">variable</span></code> attribute. In contrast, macros return only those date-parts that would otherwise be rendered (respecting the value of the <code class="docutils literal notranslate"><span class="pre">date-parts</span></code> attribute for localized dates, or the listing of <code class="docutils literal notranslate"><span class="pre">cs:date-part</span></code> elements for non-localized dates).</p> </div> </div> <div class="section" id="range-delimiters"> <h3><a class="toc-backref" href="#toc-entry-67">Range Delimiters</a><a class="headerlink" href="#range-delimiters" title="Permalink to this headline">¶</a></h3> <p>Collapsed ranges for the “citation-number” and “year-suffix” variables are delimited by an en-dash (e.g. “(1–3, 5)” and “(Doe 2000a–c,e)”).</p> <p>The “locator” variable is always rendered with an en-dash replacing any hyphens. For the “page” variable, this replacement is only performed if the <code class="docutils literal notranslate"><span class="pre">page-range-format</span></code> attribute is set on <code class="docutils literal notranslate"><span class="pre">cs:style</span></code> (see <a class="reference internal" href="#page-ranges">Page Ranges</a>).</p> </div> <div class="section" id="formatting"> <h3><a class="toc-backref" href="#toc-entry-68">Formatting</a><a class="headerlink" href="#formatting" title="Permalink to this headline">¶</a></h3> <p>The following formatting attributes may be set on <code class="docutils literal notranslate"><span class="pre">cs:date</span></code>, <code class="docutils literal notranslate"><span class="pre">cs:date-part</span></code>, <code class="docutils literal notranslate"><span class="pre">cs:et-al</span></code>, <code class="docutils literal notranslate"><span class="pre">cs:group</span></code>, <code class="docutils literal notranslate"><span class="pre">cs:label</span></code>, <code class="docutils literal notranslate"><span class="pre">cs:layout</span></code>, <code class="docutils literal notranslate"><span class="pre">cs:name</span></code>, <code class="docutils literal notranslate"><span class="pre">cs:name-part</span></code>, <code class="docutils literal notranslate"><span class="pre">cs:names</span></code>, <code class="docutils literal notranslate"><span class="pre">cs:number</span></code> and <code class="docutils literal notranslate"><span class="pre">cs:text</span></code>:</p> <dl class="docutils"> <dt><code class="docutils literal notranslate"><span class="pre">font-style</span></code></dt> <dd><p class="first">Sets the font style, with values:</p> <ul class="last simple"> <li>“normal” (default)</li> <li>“italic”</li> <li>“oblique” (i.e. slanted)</li> </ul> </dd> <dt><code class="docutils literal notranslate"><span class="pre">font-variant</span></code></dt> <dd><p class="first">Allows for the use of small capitals, with values:</p> <ul class="last simple"> <li>“normal” (default)</li> <li>“small-caps”</li> </ul> </dd> <dt><code class="docutils literal notranslate"><span class="pre">font-weight</span></code></dt> <dd><p class="first">Sets the font weight, with values:</p> <ul class="last simple"> <li>“normal” (default)</li> <li>“bold”</li> <li>“light”</li> </ul> </dd> <dt><code class="docutils literal notranslate"><span class="pre">text-decoration</span></code></dt> <dd><p class="first">Allows for the use of underlining, with values:</p> <ul class="last simple"> <li>“none” (default)</li> <li>“underline”</li> </ul> </dd> <dt><code class="docutils literal notranslate"><span class="pre">vertical-align</span></code></dt> <dd><p class="first">Sets the vertical alignment, with values:</p> <ul class="last simple"> <li>“baseline” (default)</li> <li>“sup” (superscript)</li> <li>“sub” (subscript)</li> </ul> </dd> </dl> </div> <div class="section" id="affixes"> <h3><a class="toc-backref" href="#toc-entry-69">Affixes</a><a class="headerlink" href="#affixes" title="Permalink to this headline">¶</a></h3> <p>The affixes attributes <code class="docutils literal notranslate"><span class="pre">prefix</span></code> and <code class="docutils literal notranslate"><span class="pre">suffix</span></code> may be set on <code class="docutils literal notranslate"><span class="pre">cs:date</span></code> (except when <code class="docutils literal notranslate"><span class="pre">cs:date</span></code> defines a localized date format), <code class="docutils literal notranslate"><span class="pre">cs:date-part</span></code> (except when the parent <code class="docutils literal notranslate"><span class="pre">cs:date</span></code> element calls a localized date format), <code class="docutils literal notranslate"><span class="pre">cs:group</span></code>, <code class="docutils literal notranslate"><span class="pre">cs:label</span></code>, <code class="docutils literal notranslate"><span class="pre">cs:layout</span></code>, <code class="docutils literal notranslate"><span class="pre">cs:name</span></code>, <code class="docutils literal notranslate"><span class="pre">cs:name-part</span></code>, <code class="docutils literal notranslate"><span class="pre">cs:names</span></code>, <code class="docutils literal notranslate"><span class="pre">cs:number</span></code> and <code class="docutils literal notranslate"><span class="pre">cs:text</span></code>. The attribute value is either added before (<code class="docutils literal notranslate"><span class="pre">prefix</span></code>) or after (<code class="docutils literal notranslate"><span class="pre">suffix</span></code>) the output of the element carrying the attribute, but affixes are only rendered if the element produces output. With the exception of affixes set on <code class="docutils literal notranslate"><span class="pre">cs:layout</span></code>, affixes are outside the scope of <a class="reference internal" href="#formatting">formatting</a>, <a class="reference internal" href="#quotes">quotes</a>, <a class="reference internal" href="#strip-periods">strip-periods</a> and <a class="reference internal" href="#text-case">text-case</a> attributes set on the same element (as a workaround, these attributes take effect on affixes when set on a parent <code class="docutils literal notranslate"><span class="pre">cs:group</span></code> element).</p> </div> <div class="section" id="delimiter"> <h3><a class="toc-backref" href="#toc-entry-70">Delimiter</a><a class="headerlink" href="#delimiter" title="Permalink to this headline">¶</a></h3> <p>The <code class="docutils literal notranslate"><span class="pre">delimiter</span></code> attribute, whose value delimits non-empty pieces of output, may be set on <code class="docutils literal notranslate"><span class="pre">cs:date</span></code> (delimiting the date-parts; <code class="docutils literal notranslate"><span class="pre">delimiter</span></code> is not allowed when <code class="docutils literal notranslate"><span class="pre">cs:date</span></code> calls a localized date format), <code class="docutils literal notranslate"><span class="pre">cs:names</span></code> (delimiting name lists from different <a class="reference internal" href="#name-variables">name variables</a>), <code class="docutils literal notranslate"><span class="pre">cs:name</span></code> (delimiting names within name lists), <code class="docutils literal notranslate"><span class="pre">cs:group</span></code> and <code class="docutils literal notranslate"><span class="pre">cs:layout</span></code> (delimiting the output of the child elements).</p> <p>A delimiting element is any element as above which takes a <code class="docutils literal notranslate"><span class="pre">delimiter</span></code> attribute, whether the attribute is supplied or not.</p> <p>Delimiters from any ancestor delimiting element are not applied within the output of a delimiting element. The following produces <code class="docutils literal notranslate"><span class="pre">retrieved:</span> <span class="pre"><http://example.com></span></code>:</p> <div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="nt"><group</span> <span class="na">delimiter=</span><span class="s">": "</span><span class="nt">></span> <span class="nt"><text</span> <span class="na">term=</span><span class="s">"retrieved"</span> <span class="nt">/></span> <span class="nt"><group></span> <span class="nt"><text</span> <span class="na">value=</span><span class="s">"&lt;"</span> <span class="nt">/></span> <span class="nt"><text</span> <span class="na">variable=</span><span class="s">"URL"</span> <span class="nt">/></span> <span class="nt"><text</span> <span class="na">value=</span><span class="s">"&gt;"</span> <span class="nt">/></span> <span class="nt"></group></span> <span class="nt"></group></span> </pre></div> </div> </div> <div class="section" id="display"> <h3><a class="toc-backref" href="#toc-entry-71">Display</a><a class="headerlink" href="#display" title="Permalink to this headline">¶</a></h3> <p>The <code class="docutils literal notranslate"><span class="pre">display</span></code> attribute (similar the “display” property in CSS) may be used to structure individual bibliographic entries into one or more text blocks. If used, all rendering elements should be under the control of a display attribute. The allowed values:</p> <ul class="simple"> <li>“block” - block stretching from margin to margin.</li> <li>“left-margin” - block starting at the left margin. If followed by a “right-inline” block, the “left-margin” blocks of all bibliographic entries are set to a fixed width to accommodate the longest content string found among these “left-margin” blocks. In the absence of a “right-inline” block the “left-margin” block extends to the right margin.</li> <li>“right-inline” - block starting to the right of a preceding “left-margin” block (behaves as “block” in the absence of such a “left-margin” block). Extends to the right margin.</li> <li>“indent” - block indented to the right by a standard amount. Extends to the right margin.</li> </ul> <p><strong>Examples</strong></p> <ol class="upperalpha"> <li><p class="first">Instead of using <code class="docutils literal notranslate"><span class="pre">second-field-align</span></code> (see <a class="reference internal" href="#whitespace">Whitespace</a>), a similar layout can be achieved with a “left-margin” and “right-inline” block. A potential benefit is that the styling of blocks can be further controlled in the final output (e.g. using CSS for HTML, styles for Word, etc.).</p> <div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="nt"><bibliography></span> <span class="nt"><layout></span> <span class="nt"><text</span> <span class="na">display=</span><span class="s">"left-margin"</span> <span class="na">variable=</span><span class="s">"citation-number"</span> <span class="na">prefix=</span><span class="s">"["</span> <span class="na">suffix=</span><span class="s">"]"</span><span class="nt">/></span> <span class="nt"><group</span> <span class="na">display=</span><span class="s">"right-inline"</span><span class="nt">></span> <span class="c"></span> <span class="nt"></group></span> <span class="nt"></layout></span> <span class="nt"></bibliography></span> </pre></div> </div> </li> </ol> <hr class="docutils" /> <ol class="upperalpha" start="2"> <li><p class="first">A per-author publication listing. With <code class="docutils literal notranslate"><span class="pre">subsequent-author-substitute</span></code> (see <a class="reference internal" href="#reference-grouping">Reference Grouping</a>) set to an empty string, the block with the author names is only rendered once for items by the same authors.</p> <div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="nt"><bibliography</span> <span class="na">subsequent-author-substitute=</span><span class="s">""</span><span class="nt">></span> <span class="nt"><sort></span> <span class="nt"><key</span> <span class="na">variable=</span><span class="s">"author"</span><span class="nt">/></span> <span class="nt"><key</span> <span class="na">variable=</span><span class="s">"issued"</span><span class="nt">/></span> <span class="nt"></sort></span> <span class="nt"><layout></span> <span class="nt"><group</span> <span class="na">display=</span><span class="s">"block"</span><span class="nt">></span> <span class="nt"><names</span> <span class="na">variable=</span><span class="s">"author"</span><span class="nt">/></span> <span class="nt"></group></span> <span class="nt"><group</span> <span class="na">display=</span><span class="s">"left-margin"</span><span class="nt">></span> <span class="nt"><date</span> <span class="na">variable=</span><span class="s">"issued"</span><span class="nt">></span> <span class="nt"><date-part</span> <span class="na">name=</span><span class="s">"year"</span> <span class="nt">/></span> <span class="nt"></date></span> <span class="nt"></group></span> <span class="nt"><group</span> <span class="na">display=</span><span class="s">"right-inline"</span><span class="nt">></span> <span class="nt"><text</span> <span class="na">variable=</span><span class="s">"title"</span><span class="nt">/></span> <span class="nt"></group></span> <span class="nt"></layout></span> <span class="nt"></bibliography></span> </pre></div> </div> <p>The output of this example would look like:</p> <table border="1" class="docutils"> <colgroup> <col width="45%" /> <col width="55%" /> </colgroup> <tbody valign="top"> <tr class="row-odd"><td colspan="2">Author1</td> </tr> <tr class="row-even"><td>year-publication1</td> <td>title-publication1</td> </tr> <tr class="row-odd"><td>year-publication2</td> <td>title-publication2</td> </tr> <tr class="row-even"><td colspan="2">Author2</td> </tr> <tr class="row-odd"><td>year-publication3</td> <td>title-publication3</td> </tr> <tr class="row-even"><td>year-publication4</td> <td>title-publication4</td> </tr> </tbody> </table> </li> </ol> <hr class="docutils" /> <ol class="upperalpha" start="3"> <li><p class="first">An annotated bibliography, where the annotation appears in an indented block below the reference.</p> <div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="nt"><bibliography></span> <span class="nt"><layout></span> <span class="nt"><group</span> <span class="na">display=</span><span class="s">"block"</span><span class="nt">></span> <span class="c"></span> <span class="nt"></group></span> <span class="nt"><text</span> <span class="na">display=</span><span class="s">"indent"</span> <span class="na">variable=</span><span class="s">"abstract"</span> <span class="nt">/></span> <span class="nt"></layout></span> <span class="nt"></bibliography></span> </pre></div> </div> </li> </ol> </div> <div class="section" id="quotes"> <h3><a class="toc-backref" href="#toc-entry-72">Quotes</a><a class="headerlink" href="#quotes" title="Permalink to this headline">¶</a></h3> <p>The <code class="docutils literal notranslate"><span class="pre">quotes</span></code> attribute may set on <code class="docutils literal notranslate"><span class="pre">cs:text</span></code>. When set to “true” (“false” is default), the rendered text is wrapped in quotes (the quotation marks used are terms). The localized <code class="docutils literal notranslate"><span class="pre">punctuation-in-quote</span></code> option controls whether an adjoining comma or period appears outside (default) or inside the closing quotation mark (see <a class="reference internal" href="#locale-options">Locale Options</a>).</p> </div> <div class="section" id="strip-periods"> <h3><a class="toc-backref" href="#toc-entry-73">Strip-periods</a><a class="headerlink" href="#strip-periods" title="Permalink to this headline">¶</a></h3> <p>The <code class="docutils literal notranslate"><span class="pre">strip-periods</span></code> attribute may be set on <code class="docutils literal notranslate"><span class="pre">cs:date-part</span></code> (but only if <code class="docutils literal notranslate"><span class="pre">name</span></code> is set to “month”), <code class="docutils literal notranslate"><span class="pre">cs:label</span></code> and <code class="docutils literal notranslate"><span class="pre">cs:text</span></code>. When set to “true” (“false” is the default), any periods in the rendered text are removed.</p> </div> <div class="section" id="text-case"> <h3><a class="toc-backref" href="#toc-entry-74">Text-case</a><a class="headerlink" href="#text-case" title="Permalink to this headline">¶</a></h3> <p>The <code class="docutils literal notranslate"><span class="pre">text-case</span></code> attribute may be set on <code class="docutils literal notranslate"><span class="pre">cs:date</span></code>, <code class="docutils literal notranslate"><span class="pre">cs:date-part</span></code>, <code class="docutils literal notranslate"><span class="pre">cs:label</span></code>, <code class="docutils literal notranslate"><span class="pre">cs:name-part</span></code>, <code class="docutils literal notranslate"><span class="pre">cs:number</span></code> and <code class="docutils literal notranslate"><span class="pre">cs:text</span></code>. The allowed values:</p> <ul class="simple"> <li>“lowercase”: renders text in lowercase</li> <li>“uppercase”: renders text in uppercase</li> <li>“capitalize-first”: capitalizes the first character of the first word, if the word is lowercase</li> <li>“capitalize-all”: capitalizes the first character of every lowercase word</li> <li>“sentence”: renders text in sentence case (deprecated; do not use)</li> <li>“title”: renders text in title case</li> </ul> <div class="section" id="sentence-case-conversion"> <h4><a class="toc-backref" href="#toc-entry-75">Sentence Case Conversion</a><a class="headerlink" href="#sentence-case-conversion" title="Permalink to this headline">¶</a></h4> <p>Sentence case conversion (with <code class="docutils literal notranslate"><span class="pre">text-case</span></code> set to “sentence”) is performed by:</p> <ol class="arabic simple"> <li>For uppercase strings, the first character of the string remains capitalized. All other letters are lowercased.</li> <li>For lower or mixed case strings, the first character of the first word is capitalized if the word is lowercase. The case of all other words stays the same.</li> </ol> <p>CSL processors don’t recognize proper nouns. As a result, strings in sentence case can be accurately converted to title case, but not vice versa. For this reason, it is generally preferable to store strings such as titles in sentence case, and only use <code class="docutils literal notranslate"><span class="pre">text-case</span></code> if a style desires another case.</p> <p>Sentence case conversion is deprecated and will be removed in a future version.</p> </div> <div class="section" id="title-case-conversion"> <h4><a class="toc-backref" href="#toc-entry-76">Title Case Conversion</a><a class="headerlink" href="#title-case-conversion" title="Permalink to this headline">¶</a></h4> <p>Title case conversion (with <code class="docutils literal notranslate"><span class="pre">text-case</span></code> set to “title”) for English-language items is performed by:</p> <ol class="arabic simple"> <li>For uppercase strings, the first character of each word remains capitalized. All other letters are lowercased.</li> <li>For lower or mixed case strings, the first character of each lowercase word is capitalized. The case of words in mixed or uppercase stays the same.</li> </ol> <p>In both cases, stop words are lowercased, unless they are the first or last word in the string, or follow a colon. The stop words are listed in the CSL Schema file <a class="reference external" href="https://resource.citationstyles.org/schema/latest/styles/stop-words.json">stop-words.json</a>. Hyphenated word parts are treated as distinct words (e.g., “two-thirds” becomes “Two-Thirds”).</p> <div class="section" id="non-english-items"> <h5><a class="toc-backref" href="#toc-entry-77">Non-English Items</a><a class="headerlink" href="#non-english-items" title="Permalink to this headline">¶</a></h5> <p>As many languages do not use title case, title case conversion (with <code class="docutils literal notranslate"><span class="pre">text-case</span></code> set to “title”) only affects English-language items.</p> <p>If the <code class="docutils literal notranslate"><span class="pre">default-locale</span></code> attribute on <code class="docutils literal notranslate"><span class="pre">cs:style</span></code> isn’t set, or set to a locale code with a primary language tag of “en” (English), items are assumed to be English. An item is only considered to be non-English if its metadata contains a <code class="docutils literal notranslate"><span class="pre">language</span></code> field with a non-nil value that doesn’t start with the “en” primary language tag.</p> <p>If <code class="docutils literal notranslate"><span class="pre">default-locale</span></code> is set to a locale code with a primary language tag other than “en”, items are assumed to be non-English. An item is only considered to be English if the value of its <code class="docutils literal notranslate"><span class="pre">language</span></code> field starts with the “en” primary language tag.</p> </div> </div> </div> </div> <div class="section" id="appendix-i-categories"> <h2><a class="toc-backref" href="#toc-entry-78">Appendix I - Categories</a><a class="headerlink" href="#appendix-i-categories" title="Permalink to this headline">¶</a></h2> <ul class="simple"> <li>anthropology</li> <li>astronomy</li> <li>biology</li> <li>botany</li> <li>chemistry</li> <li>communications</li> <li>engineering</li> <li>generic-base - used for generic styles like Harvard and APA</li> <li>geography</li> <li>geology</li> <li>history</li> <li>humanities</li> <li>law</li> <li>linguistics</li> <li>literature</li> <li>math</li> <li>medicine</li> <li>philosophy</li> <li>physics</li> <li>political_science</li> <li>psychology</li> <li>science</li> <li>social_science</li> <li>sociology</li> <li>theology</li> <li>zoology</li> </ul> </div> <div class="section" id="appendix-ii-terms"> <h2><a class="toc-backref" href="#toc-entry-79">Appendix II - Terms</a><a class="headerlink" href="#appendix-ii-terms" title="Permalink to this headline">¶</a></h2> <div class="section" id="type-terms"> <h3><a class="toc-backref" href="#toc-entry-80">Type Terms</a><a class="headerlink" href="#type-terms" title="Permalink to this headline">¶</a></h3> <p>For each item type listed in <a class="reference internal" href="#appendix-iii-types">Appendix III - Types</a>, there is a corresponding term.</p> </div> <div class="section" id="name-variable-terms"> <h3><a class="toc-backref" href="#toc-entry-81">Name Variable Terms</a><a class="headerlink" href="#name-variable-terms" title="Permalink to this headline">¶</a></h3> <p>For each of the <a class="reference internal" href="#name-variables">Name Variables</a> listed in <a class="reference internal" href="#appendix-iv-variables">Appendix IV - Variables</a>, there is a corresponding term.</p> </div> <div class="section" id="number-variable-terms"> <h3><a class="toc-backref" href="#toc-entry-82">Number Variable Terms</a><a class="headerlink" href="#number-variable-terms" title="Permalink to this headline">¶</a></h3> <p>For each of the <a class="reference internal" href="#number-variables">Number Variables</a> listed in <a class="reference internal" href="#appendix-iv-variables">Appendix IV - Variables</a>, there is a corresponding term.</p> </div> <div class="section" id="locators"> <h3><a class="toc-backref" href="#toc-entry-83">Locators</a><a class="headerlink" href="#locators" title="Permalink to this headline">¶</a></h3> <ul class="simple"> <li>appendix</li> <li>article-locator</li> <li>book</li> <li>canon</li> <li>chapter</li> <li>column</li> <li>elocation</li> <li>equation</li> <li>figure</li> <li>folio</li> <li>issue</li> <li>line</li> <li>note</li> <li>opus</li> <li>page</li> <li>paragraph</li> <li>part</li> <li>rule</li> <li>section</li> <li>sub-verbo</li> <li>supplement</li> <li>table</li> <li>timestamp</li> <li>title</li> <li>verse</li> <li>volume</li> </ul> </div> <div class="section" id="months"> <h3><a class="toc-backref" href="#toc-entry-84">Months</a><a class="headerlink" href="#months" title="Permalink to this headline">¶</a></h3> <ul class="simple"> <li>month-01</li> <li>month-02</li> <li>month-03</li> <li>month-04</li> <li>month-05</li> <li>month-06</li> <li>month-07</li> <li>month-08</li> <li>month-09</li> <li>month-10</li> <li>month-11</li> <li>month-12</li> </ul> </div> <div class="section" id="ordinals"> <h3><a class="toc-backref" href="#toc-entry-85">Ordinals</a><a class="headerlink" href="#ordinals" title="Permalink to this headline">¶</a></h3> <ul class="simple"> <li>ordinal</li> <li>ordinal-00 through ordinal-99</li> <li>long-ordinal-01</li> <li>long-ordinal-02</li> <li>long-ordinal-03</li> <li>long-ordinal-04</li> <li>long-ordinal-05</li> <li>long-ordinal-06</li> <li>long-ordinal-07</li> <li>long-ordinal-08</li> <li>long-ordinal-09</li> <li>long-ordinal-10</li> </ul> </div> <div class="section" id="punctuation"> <h3><a class="toc-backref" href="#toc-entry-86">Punctuation</a><a class="headerlink" href="#punctuation" title="Permalink to this headline">¶</a></h3> <ul class="simple"> <li>open-quote</li> <li>close-quote</li> <li>open-inner-quote</li> <li>close-inner-quote</li> <li>page-range-delimiter</li> <li>colon</li> <li>comma</li> <li>semicolon</li> </ul> </div> <div class="section" id="seasons-1"> <h3><a class="toc-backref" href="#toc-entry-87">Seasons</a><a class="headerlink" href="#seasons-1" title="Permalink to this headline">¶</a></h3> <ul class="simple"> <li>season-01</li> <li>season-02</li> <li>season-03</li> <li>season-04</li> </ul> </div> <div class="section" id="miscellaneous"> <h3><a class="toc-backref" href="#toc-entry-88">Miscellaneous</a><a class="headerlink" href="#miscellaneous" title="Permalink to this headline">¶</a></h3> <ul class="simple"> <li>accessed</li> <li>ad</li> <li>advance-online-publication</li> <li>album</li> <li>and</li> <li>and others</li> <li>anonymous</li> <li>at</li> <li>audio-recording</li> <li>available at</li> <li>bc</li> <li>bce</li> <li>by</li> <li>ce</li> <li>circa</li> <li>cited</li> <li>et-al</li> <li>film</li> <li>forthcoming</li> <li>from</li> <li>henceforth</li> <li>ibid</li> <li>in</li> <li>in press</li> <li>internet</li> <li>interview</li> <li>letter</li> <li>loc-cit</li> <li>no date</li> <li>no-place</li> <li>no-publisher</li> <li>on</li> <li>online</li> <li>op-cit</li> <li>original-work-published</li> <li>personal-communication</li> <li>podcast</li> <li>podcast-episode</li> <li>preprint</li> <li>presented at</li> <li>radio-broadcast</li> <li>radio-series</li> <li>radio-series-episode</li> <li>reference</li> <li>retrieved</li> <li>review-of</li> <li>scale</li> <li>special-issue</li> <li>special-section</li> <li>television-broadcast</li> <li>television-series</li> <li>television-series-episode</li> <li>video</li> <li>working-paper</li> </ul> </div> </div> <div class="section" id="appendix-iii-types"> <h2><a class="toc-backref" href="#toc-entry-89">Appendix III - Types</a><a class="headerlink" href="#appendix-iii-types" title="Permalink to this headline">¶</a></h2> <dl class="docutils"> <dt>article</dt> <dd><div class="first last line-block"> <div class="line">A self-contained work made widely available but not published in a journal or other publication;</div> <div class="line">Use for preprints, working papers, and similar works posted on a platform where some level of persistence or stewardship is expected (e.g. arXiv or other preprint repositories, working paper series);</div> <div class="line">For unpublished works not made widely available or only hosted on personal websites, use <code class="docutils literal notranslate"><span class="pre">manuscript</span></code></div> </div> </dd> <dt>article-journal</dt> <dd>An article published in an academic journal</dd> <dt>article-magazine</dt> <dd>An article published in a non-academic magazine</dd> <dt>article-newspaper</dt> <dd>An article published in a newspaper</dd> <dt>bill</dt> <dd>A proposed piece of legislation</dd> <dt>book</dt> <dd><div class="first last line-block"> <div class="line">A book or similar work;</div> <div class="line">Can be an authored book or an edited collection of self-contained chapters;</div> <div class="line">Can be a physical book or an ebook;</div> <div class="line">The format for an ebook may be specified using <code class="docutils literal notranslate"><span class="pre">medium</span></code>;</div> <div class="line">Can be a single-volume work, a multivolume work, or one volume of a multivolume work;</div> <div class="line">If a <code class="docutils literal notranslate"><span class="pre">container-title</span></code> is present, the item is interpreted as a book republished in a collection or anthology;</div> <div class="line">Also used for whole conference proceedings volumes or exhibition catalogs by specifying <code class="docutils literal notranslate"><span class="pre">event</span></code> and related variables</div> </div> </dd> <dt>broadcast</dt> <dd><div class="first last line-block"> <div class="line">A recorded work broadcast over an electronic medium (e.g. a radio broadcast, a television show, a podcast);</div> <div class="line">The type of broadcast may be specified using <code class="docutils literal notranslate"><span class="pre">genre</span></code>;</div> <div class="line">If <code class="docutils literal notranslate"><span class="pre">container-title</span></code> is present, the item is interpreted as an episode contained within a larger broadcast series (e.g. an episode in a television show or an episode of a podcast)</div> </div> </dd> <dt>chapter</dt> <dd><div class="first last line-block"> <div class="line">A part of a book cited separately from the book as a whole (e.g. a chapter in an edited book);</div> <div class="line">Also used for introductions, forewords, and similar supplemental components of a book</div> </div> </dd> <dt>classic</dt> <dd>A classical or ancient work, sometimes cited using a common abbreviation</dd> <dt>collection</dt> <dd>An archival collection in a museum or other institution</dd> <dt>dataset</dt> <dd>A data set or a similar collection of (mostly) raw data</dd> <dt>document</dt> <dd><div class="first last line-block"> <div class="line">A catch-all category for items not belonging to other types;</div> <div class="line">Use a more specific type when appropriate</div> </div> </dd> <dt>entry</dt> <dd><div class="first last line-block"> <div class="line">An entry in a database, directory, or catalog;</div> <div class="line">For entries in a dictionary, use <code class="docutils literal notranslate"><span class="pre">entry-dictionary</span></code>;</div> <div class="line">For entries in an encyclopedia, use <code class="docutils literal notranslate"><span class="pre">entry-encyclopedia</span></code></div> </div> </dd> <dt>entry-dictionary</dt> <dd>An entry in a dictionary</dd> <dt>entry-encyclopedia</dt> <dd>An entry in an encyclopedia or similar reference work</dd> <dt>event</dt> <dd><div class="first last line-block"> <div class="line">An organized event (e.g., an exhibition or conference);</div> <div class="line">Use for direct citations to the event, rather than to works contained within an event (e.g. a <code class="docutils literal notranslate"><span class="pre">presentation</span></code> in a conference, a <code class="docutils literal notranslate"><span class="pre">graphic</span></code> in an exhibition) or based on an event (e.g. a <code class="docutils literal notranslate"><span class="pre">paper-conference</span></code> published in a proceedings, an exhibition catalog)</div> </div> </dd> <dt>figure</dt> <dd><div class="first last line-block"> <div class="line">A illustration or representation of data, typically as part of a journal article or other larger work;</div> <div class="line">May be in any format (e.g. image, video, audio recording, 3D model);</div> <div class="line">The format of the item can be specified using <code class="docutils literal notranslate"><span class="pre">medium</span></code></div> </div> </dd> <dt>graphic</dt> <dd><div class="first last line-block"> <div class="line">A still visual work;</div> <div class="line">Can be used for artwork or other works (e.g. journalistic or historical photographs);</div> <div class="line">Can be used for any still visual work (e.g. photographs, drawings, paintings, sculptures, clothing);</div> <div class="line">The format of the item can be specified using <code class="docutils literal notranslate"><span class="pre">medium</span></code></div> </div> </dd> <dt>hearing</dt> <dd><div class="first last line-block"> <div class="line">A hearing by a government committee or transcript thereof</div> </div> </dd> <dt>interview</dt> <dd><div class="first last line-block"> <div class="line">An interview of a person;</div> <div class="line">Also used for a recording or transcript of an interview; <code class="docutils literal notranslate"><span class="pre">author</span></code> is interpreted as the interviewee</div> </div> </dd> <dt>legal_case</dt> <dd>A legal case</dd> <dt>legislation</dt> <dd>A law or resolution enacted by a governing body</dd> <dt>manuscript</dt> <dd><div class="first last line-block"> <div class="line">An unpublished manuscript;</div> <div class="line">Use for both modern unpublished works and classical manuscripts;</div> <div class="line">For working papers, preprints, and similar works posted to a repository, use <code class="docutils literal notranslate"><span class="pre">article</span></code></div> </div> </dd> <dt>map</dt> <dd>A geographic map</dd> <dt>motion_picture</dt> <dd><div class="first last line-block"> <div class="line">A video or visual recording;</div> <div class="line">If a <code class="docutils literal notranslate"><span class="pre">container-title</span></code> is present, the item is interpreted as a part contained within a larger compilation of recordings (e.g. a part of a multipart documentary))</div> </div> </dd> <dt>musical_score</dt> <dd><div class="first last line-block"> <div class="line">The printed score for a piece of music;</div> <div class="line">For a live performance of the music, use <code class="docutils literal notranslate"><span class="pre">performance</span></code>;</div> <div class="line">For recordings of the music, use <code class="docutils literal notranslate"><span class="pre">song</span></code> (for audio recordings) or <code class="docutils literal notranslate"><span class="pre">motion_picture</span></code> (for video recordings)</div> </div> </dd> <dt>pamphlet</dt> <dd>A fragment, historical document, or other unusually-published or ephemeral work (e.g. a sales brochure)</dd> <dt>paper-conference</dt> <dd><div class="first last line-block"> <div class="line">A paper formally published in conference proceedings;</div> <div class="line">For papers presented at a conference, but not published in a proceedings, use <code class="docutils literal notranslate"><span class="pre">speech</span></code></div> </div> </dd> <dt>patent</dt> <dd>A patent for an invention</dd> <dt>performance</dt> <dd><div class="first last line-block"> <div class="line">A live performance of an artistic work;</div> <div class="line">For non-artistic presentations, use <code class="docutils literal notranslate"><span class="pre">speech</span></code>;</div> <div class="line">For recordings of a performance, use <code class="docutils literal notranslate"><span class="pre">song</span></code> or <code class="docutils literal notranslate"><span class="pre">motion_picture</span></code></div> </div> </dd> <dt>periodical</dt> <dd>A full issue or run of issues in a periodical publication (e.g. a special issue of a journal)</dd> <dt>personal_communication</dt> <dd><div class="first last line-block"> <div class="line">Personal communications between multiple parties;</div> <div class="line">May be unpublished (e.g. private correspondence between two researchers) or collected/published (e.g. a letter published in a collection)</div> </div> </dd> <dt>post</dt> <dd><div class="first last line-block"> <div class="line">A post on a online forum, social media platform, or similar platform;</div> <div class="line">Also used for comments posted to online items</div> </div> </dd> <dt>post-weblog</dt> <dd>A blog post</dd> <dt>regulation</dt> <dd>An administrative order from any level of government</dd> <dt>report</dt> <dd><div class="first last line-block"> <div class="line">A technical report, government report, white paper, brief, or similar work distributed by an institution;</div> <div class="line">Also used for manuals and similar technical documentation (e.g. a software, instrument, or test manual);</div> <div class="line">If a <code class="docutils literal notranslate"><span class="pre">container-title</span></code> is present, the item is interpreted as a chapter contained within a larger report</div> </div> </dd> <dt>review</dt> <dd><div class="first last line-block"> <div class="line">A review of an item other than a book (e.g. a film review, posted peer review of an article);</div> <div class="line">If <code class="docutils literal notranslate"><span class="pre">reviewed-title</span></code> is absent, <code class="docutils literal notranslate"><span class="pre">title</span></code> is taken to be the title of the reviewed item</div> </div> </dd> <dt>review-book</dt> <dd><div class="first last line-block"> <div class="line">A review of a book;</div> <div class="line">If <code class="docutils literal notranslate"><span class="pre">reviewed-title</span></code> is absent, <code class="docutils literal notranslate"><span class="pre">title</span></code> is taken to be the title of the reviewed book</div> </div> </dd> <dt>software</dt> <dd>A computer program, app, or other piece of software</dd> <dt>song</dt> <dd><div class="first last line-block"> <div class="line">An audio recording;</div> <div class="line">Can be used for any audio recording (not only music);</div> <div class="line">If a <code class="docutils literal notranslate"><span class="pre">container-title</span></code> is present, the item is interpreted as a track contained within a larger album or compilation of recordings</div> </div> </dd> <dt>speech</dt> <dd><div class="first last line-block"> <div class="line">A speech or other presentation (e.g. a paper, talk, poster, or symposium at a conference);</div> <div class="line">Use <code class="docutils literal notranslate"><span class="pre">genre</span></code> to specify the type of presentation;</div> <div class="line">Use <code class="docutils literal notranslate"><span class="pre">event</span></code> to indicate the event where the presentation was made (e.g. the conference name);</div> <div class="line">Use <code class="docutils literal notranslate"><span class="pre">container-title</span></code> if the presentation is part of a larger session (e.g. a paper in a symposium);</div> <div class="line">For papers published in conference proceedings, use <code class="docutils literal notranslate"><span class="pre">paper-conference</span></code>;</div> <div class="line">For artistic performances, use <code class="docutils literal notranslate"><span class="pre">performance</span></code></div> </div> </dd> <dt>standard</dt> <dd>A technical standard or similar set of rules or norms</dd> <dt>thesis</dt> <dd><div class="first last line-block"> <div class="line">A thesis written to satisfy requirements for a degree;</div> <div class="line">Use <code class="docutils literal notranslate"><span class="pre">genre</span></code> to specify the type of thesis</div> </div> </dd> <dt>treaty</dt> <dd>A treaty agreement among political authorities</dd> <dt>webpage</dt> <dd><div class="first last line-block"> <div class="line">A website or page on a website;</div> <div class="line">Intended for sources which are intrinsically online; use a more specific type when appropriate (e.g. <code class="docutils literal notranslate"><span class="pre">article-journal</span></code>, <code class="docutils literal notranslate"><span class="pre">post-weblog</span></code>, <code class="docutils literal notranslate"><span class="pre">report</span></code>, <code class="docutils literal notranslate"><span class="pre">entry</span></code>);</div> <div class="line">If a <code class="docutils literal notranslate"><span class="pre">container-title</span></code> is present, the item is interpreted as a page contained within a larger website</div> </div> </dd> </dl> </div> <div class="section" id="appendix-iv-variables"> <h2><a class="toc-backref" href="#toc-entry-90">Appendix IV - Variables</a><a class="headerlink" href="#appendix-iv-variables" title="Permalink to this headline">¶</a></h2> <div class="section" id="standard-variables"> <h3><a class="toc-backref" href="#toc-entry-91">Standard Variables</a><a class="headerlink" href="#standard-variables" title="Permalink to this headline">¶</a></h3> <dl class="docutils"> <dt>abstract</dt> <dd>Abstract of the item (e.g. the abstract of a journal article)</dd> <dt>annote</dt> <dd><div class="first last line-block"> <div class="line">Short markup, decoration, or annotation to the item (e.g., to indicate items included in a review);</div> <div class="line">For descriptive text (e.g., in an annotated bibliography), use <code class="docutils literal notranslate"><span class="pre">note</span></code> instead</div> </div> </dd> <dt>archive</dt> <dd>Archive storing the item</dd> <dt>archive_collection</dt> <dd>Collection the item is part of within an archive</dd> <dt>archive_location</dt> <dd>Storage location within an archive (e.g. a box and folder number)</dd> <dt>archive-place</dt> <dd>Geographic location of the archive</dd> <dt>authority</dt> <dd>Issuing or judicial authority (e.g. “USPTO” for a patent, “Fairfax Circuit Court” for a legal case)</dd> <dt>call-number</dt> <dd>Call number (to locate the item in a library)</dd> <dt>citation-key</dt> <dd><div class="first last line-block"> <div class="line">Identifier of the item in the input data file (analogous to BibTeX entrykey);</div> <div class="line">Use this variable to facilitate conversion between word-processor and plain-text writing systems;</div> <div class="line">For an identifer intended as formatted output label for a citation (e.g. “Ferr78”), use <code class="docutils literal notranslate"><span class="pre">citation-label</span></code> instead</div> </div> </dd> <dt>citation-label</dt> <dd><div class="first last line-block"> <div class="line">Label identifying the item in in-text citations of label styles (e.g. “Ferr78”);</div> <div class="line">May be assigned by the CSL processor based on item metadata;</div> <div class="line">For the identifier of the item in the input data file, use <code class="docutils literal notranslate"><span class="pre">citation-key</span></code> instead</div> </div> </dd> <dt>collection-title</dt> <dd><div class="first last line-block"> <div class="line">Title of the collection holding the item (e.g. the series title for a book; the lecture series title for a presentation)</div> </div> </dd> <dt>container-title</dt> <dd>Title of the container holding the item (e.g. the book title for a book chapter, the journal title for a journal article; the album title for a recording; the session title for multi-part presentation at a conference)</dd> <dt>container-title-short</dt> <dd><div class="first last line-block"> <div class="line">Short/abbreviated form of <code class="docutils literal notranslate"><span class="pre">container-title</span></code>;</div> <div class="line">Deprecated; use <code class="docutils literal notranslate"><span class="pre">variable="container-title"</span> <span class="pre">form="short"</span></code> instead</div> </div> </dd> <dt>dimensions</dt> <dd>Physical (e.g. size) or temporal (e.g. running time) dimensions of the item</dd> <dt>division</dt> <dd>Minor subdivision of a court with a <code class="docutils literal notranslate"><span class="pre">jurisdiction</span></code> for a legal item</dd> <dt>DOI</dt> <dd>Digital Object Identifier (e.g. “10.1128/AEM.02591-07”)</dd> <dt>event</dt> <dd>Deprecated legacy variant of <code class="docutils literal notranslate"><span class="pre">event-title</span></code></dd> <dt>event-title</dt> <dd>Name of the event related to the item (e.g. the conference name when citing a conference paper; the meeting where presentation was made)</dd> <dt>event-place</dt> <dd>Geographic location of the event related to the item (e.g. “Amsterdam, The Netherlands”)</dd> <dt>genre</dt> <dd><div class="first last line-block"> <div class="line">Type, class, or subtype of the item (e.g. “Doctoral dissertation” for a PhD thesis; “NIH Publication” for an NIH technical report);</div> <div class="line">Do not use for topical descriptions or categories (e.g. “adventure” for an adventure movie)</div> </div> </dd> <dt>ISBN</dt> <dd>International Standard Book Number (e.g. “978-3-8474-1017-1”)</dd> <dt>ISSN</dt> <dd>International Standard Serial Number</dd> <dt>jurisdiction</dt> <dd>Geographic scope of relevance (e.g. “US” for a US patent; the court hearing a legal case)</dd> <dt>keyword</dt> <dd>Keyword(s) or tag(s) attached to the item</dd> <dt>language</dt> <dd><div class="first last line-block"> <div class="line">The language of the item;</div> <div class="line">Should be entered as an ISO 639-1 two-letter language code (e.g. “en”, “zh”), optionally with a two-letter locale code (e.g. “de-DE”, “de-AT”)</div> </div> </dd> <dt>license</dt> <dd>The license information applicable to an item (e.g. the license an article or software is released under; the copyright information for an item; the classification status of a document)</dd> <dt>medium</dt> <dd>Description of the item’s format or medium (e.g. “CD”, “DVD”, “Album”, etc.)</dd> <dt>note</dt> <dd>Descriptive text or notes about an item (e.g. in an annotated bibliography)</dd> <dt>original-publisher</dt> <dd>Original publisher, for items that have been republished by a different publisher</dd> <dt>original-publisher-place</dt> <dd>Geographic location of the original publisher (e.g. “London, UK”)</dd> <dt>original-title</dt> <dd>Title of the original version (e.g. “Война и мир”, the untranslated Russian title of “War and Peace”)</dd> <dt>part-title</dt> <dd>Title of the specific part of an item being cited</dd> <dt>PMCID</dt> <dd>PubMed Central reference number</dd> <dt>PMID</dt> <dd>PubMed reference number</dd> <dt>publisher</dt> <dd>Publisher</dd> <dt>publisher-place</dt> <dd>Geographic location of the publisher</dd> <dt>references</dt> <dd><div class="first last line-block"> <div class="line">Resources related to the procedural history of a legal case or legislation;</div> <div class="line">Can also be used to refer to the procedural history of other items (e.g. “Conference canceled” for a presentation accepted as a conference that was subsequently canceled; details of a retraction or correction notice)</div> </div> </dd> <dt>reviewed-genre</dt> <dd>Type of the item being reviewed by the current item (e.g. book, film)</dd> <dt>reviewed-title</dt> <dd>Title of the item reviewed by the current item</dd> <dt>scale</dt> <dd>Scale of e.g. a map or model</dd> <dt>source</dt> <dd>Source from whence the item originates (e.g. a library catalog or database)</dd> <dt>status</dt> <dd>Publication status of the item (e.g. “forthcoming”; “in press”; “advance online publication”; “retracted”)</dd> <dt>title</dt> <dd>Primary title of the item</dd> <dt>title-short</dt> <dd><div class="first last line-block"> <div class="line">Short/abbreviated form of <code class="docutils literal notranslate"><span class="pre">title</span></code>;</div> <div class="line">Deprecated; use <code class="docutils literal notranslate"><span class="pre">variable="title"</span> <span class="pre">form="short"</span></code> instead</div> </div> </dd> <dt>URL</dt> <dd>Uniform Resource Locator (e.g. “<a class="reference external" href="https://aem.asm.org/cgi/content/full/74/9/2766">https://aem.asm.org/cgi/content/full/74/9/2766</a>”)</dd> <dt>volume-title</dt> <dd><div class="first last line-block"> <div class="line">Title of the volume of the item or container holding the item;</div> <div class="line">Also use for titles of periodical special issues, special sections, and the like</div> </div> </dd> <dt>year-suffix</dt> <dd>Disambiguating year suffix in author-date styles (e.g. “a” in “Doe, 1999a”)</dd> </dl> <div class="section" id="number-variables"> <h4><a class="toc-backref" href="#toc-entry-92">Number Variables</a><a class="headerlink" href="#number-variables" title="Permalink to this headline">¶</a></h4> <p>Number variables are a subset of the <a class="reference internal" href="#standard-variables">Standard Variables</a>.</p> <dl class="docutils"> <dt>chapter-number</dt> <dd>Chapter number (e.g. chapter number in a book; track number on an album)</dd> <dt>citation-number</dt> <dd>Index (starting at 1) of the cited reference in the bibliography (generated by the CSL processor)</dd> <dt>collection-number</dt> <dd>Number identifying the collection holding the item (e.g. the series number for a book)</dd> <dt>edition</dt> <dd>(Container) edition holding the item (e.g. “3” when citing a chapter in the third edition of a book)</dd> <dt>first-reference-note-number</dt> <dd><div class="first last line-block"> <div class="line">Number of a preceding note containing the first reference to the item;</div> <div class="line">Assigned by the CSL processor;</div> <div class="line">Empty in non-note-based styles or when the item hasn’t been cited in any preceding notes in a document</div> </div> </dd> <dt>issue</dt> <dd><div class="first last line-block"> <div class="line">Issue number of the item or container holding the item (e.g. “5” when citing a journal article from journal volume 2, issue 5);</div> <div class="line">Use <code class="docutils literal notranslate"><span class="pre">volume-title</span></code> for the title of the issue, if any</div> </div> </dd> <dt>locator</dt> <dd><div class="first last line-block"> <div class="line">A cite-specific pinpointer within the item (e.g. a page number within a book, or a volume in a multi-volume work);</div> <div class="line">Must be accompanied in the input data by a label indicating the locator type (see the <a class="reference internal" href="#locators">Locators</a> term list), which determines which term is rendered by <code class="docutils literal notranslate"><span class="pre">cs:label</span></code> when the <code class="docutils literal notranslate"><span class="pre">locator</span></code> variable is selected.</div> </div> </dd> <dt>number</dt> <dd>Number identifying the item (e.g. a report number)</dd> <dt>number-of-pages</dt> <dd>Total number of pages of the cited item</dd> <dt>number-of-volumes</dt> <dd>Total number of volumes, used when citing multi-volume books and such</dd> <dt>page</dt> <dd>Range of pages the item (e.g. a journal article) covers in a container (e.g. a journal issue)</dd> <dt>page-first</dt> <dd>First page of the range of pages the item (e.g. a journal article) covers in a container (e.g. a journal issue)</dd> <dt>part-number</dt> <dd><div class="first last line-block"> <div class="line">Number of the specific part of the item being cited (e.g. part 2 of a journal article);</div> <div class="line">Use <code class="docutils literal notranslate"><span class="pre">part-title</span></code> for the title of the part, if any</div> </div> </dd> <dt>printing-number</dt> <dd>Printing number of the item or container holding the item</dd> <dt>section</dt> <dd>Section of the item or container holding the item (e.g. “§2.0.1” for a law; “politics” for a newspaper article)</dd> <dt>supplement-number</dt> <dd>Supplement number of the item or container holding the item (e.g. for secondary legal items that are regularly updated between editions)</dd> <dt>version</dt> <dd>Version of the item (e.g. “2.0.9” for a software program)</dd> <dt>volume</dt> <dd><div class="first last line-block"> <div class="line">Volume number of the item (e.g. “2” when citing volume 2 of a book) or the container holding the item (e.g. “2” when citing a chapter from volume 2 of a book);</div> <div class="line">Use <code class="docutils literal notranslate"><span class="pre">volume-title</span></code> for the title of the volume, if any</div> </div> </dd> </dl> </div> </div> <div class="section" id="date-variables"> <h3><a class="toc-backref" href="#toc-entry-93">Date Variables</a><a class="headerlink" href="#date-variables" title="Permalink to this headline">¶</a></h3> <dl class="docutils"> <dt>accessed</dt> <dd>Date the item has been accessed</dd> <dt>available-date</dt> <dd>Date the item was initially available (e.g. the online publication date of a journal article before its formal publication date; the date a treaty was made available for signing)</dd> <dt>event-date</dt> <dd>Date the event related to an item took place</dd> <dt>issued</dt> <dd>Date the item was issued/published</dd> <dt>original-date</dt> <dd>Issue date of the original version</dd> <dt>submitted</dt> <dd>Date the item (e.g. a manuscript) was submitted for publication</dd> </dl> </div> <div class="section" id="name-variables"> <h3><a class="toc-backref" href="#toc-entry-94">Name Variables</a><a class="headerlink" href="#name-variables" title="Permalink to this headline">¶</a></h3> <dl class="docutils"> <dt>author</dt> <dd>Author</dd> <dt>chair</dt> <dd>The person leading the session containing a presentation (e.g. the organizer of the <code class="docutils literal notranslate"><span class="pre">container-title</span></code> of a <code class="docutils literal notranslate"><span class="pre">speech</span></code>)</dd> <dt>collection-editor</dt> <dd>Editor of the collection holding the item (e.g. the series editor for a book)</dd> <dt>compiler</dt> <dd>Person compiling or selecting material for an item from the works of various persons or bodies (e.g. for an anthology)</dd> <dt>composer</dt> <dd>Composer (e.g. of a musical score)</dd> <dt>container-author</dt> <dd>Author of the container holding the item (e.g. the book author for a book chapter)</dd> <dt>contributor</dt> <dd>A minor contributor to the item; typically cited using “with” before the name when listed in a bibliography</dd> <dt>curator</dt> <dd>Curator of an exhibit or collection (e.g. in a museum)</dd> <dt>director</dt> <dd>Director (e.g. of a film)</dd> <dt>editor</dt> <dd>Editor</dd> <dt>editorial-director</dt> <dd>Managing editor (“Directeur de la Publication” in French)</dd> <dt>editor-translator</dt> <dd><div class="first last line-block"> <div class="line">Combined editor and translator of a work;</div> <div class="line">The citation processory must be automatically generate if <code class="docutils literal notranslate"><span class="pre">editor</span></code> and <code class="docutils literal notranslate"><span class="pre">translator</span></code> variables are identical;</div> <div class="line">May also be provided directly in item data</div> </div> </dd> <dt>executive-producer</dt> <dd>Executive producer (e.g. of a television series)</dd> <dt>guest</dt> <dd>Guest (e.g. on a TV show or podcast)</dd> <dt>host</dt> <dd>Host (e.g. of a TV show or podcast)</dd> <dt>illustrator</dt> <dd>Illustrator (e.g. of a children’s book or graphic novel)</dd> <dt>interviewer</dt> <dd>Interviewer (e.g. of an interview)</dd> <dt>narrator</dt> <dd>Narrator (e.g. of an audio book)</dd> <dt>organizer</dt> <dd>Organizer of an event (e.g. organizer of a workshop or conference)</dd> <dt>original-author</dt> <dd>The original creator of a work (e.g. the form of the author name listed on the original version of a book; the historical author of a work; the original songwriter or performer for a musical piece; the original developer or programmer for a piece of software; the original author of an adapted work such as a book adapted into a screenplay)</dd> <dt>performer</dt> <dd>Performer of an item (e.g. an actor appearing in a film; a muscian performing a piece of music)</dd> <dt>producer</dt> <dd>Producer (e.g. of a television or radio broadcast)</dd> <dt>recipient</dt> <dd>Recipient (e.g. of a letter)</dd> <dt>reviewed-author</dt> <dd>Author of the item reviewed by the current item</dd> <dt>script-writer</dt> <dd>Writer of a script or screenplay (e.g. of a film)</dd> <dt>series-creator</dt> <dd>Creator of a series (e.g. of a television series)</dd> <dt>translator</dt> <dd>Translator</dd> </dl> </div> </div> <div class="section" id="appendix-v-page-range-formats"> <h2><a class="toc-backref" href="#toc-entry-95">Appendix V - Page Range Formats</a><a class="headerlink" href="#appendix-v-page-range-formats" title="Permalink to this headline">¶</a></h2> <p>The page abbreviation rules for the different values of the <code class="docutils literal notranslate"><span class="pre">page-range-format</span></code> attribute on <code class="docutils literal notranslate"><span class="pre">cs:style</span></code> are:</p> <dl class="docutils"> <dt>“chicago”</dt> <dd>Alias for “chicago-15”; will change to be an alias for “chicago-16” in CSL v1.1.</dd> <dt>“chicago-15”</dt> <dd><p class="first">Page ranges are abbreviated according to the <a href="#system-message-2"><span class="problematic" id="problematic-2">`Chicago Manual of Style (15th ed and earlier) rules`_</span></a> (see 15th ed, section 9.64):</p> <table border="1" class="last docutils"> <colgroup> <col width="32%" /> <col width="34%" /> <col width="34%" /> </colgroup> <thead valign="bottom"> <tr class="row-odd"><th class="head">First number</th> <th class="head">Second number</th> <th class="head">Examples</th> </tr> </thead> <tbody valign="top"> <tr class="row-even"><td>Less than 100</td> <td>Use all digits</td> <td>3–10; 71–72</td> </tr> <tr class="row-odd"><td>100 or multiple of 100</td> <td>Use all digits</td> <td>100–104; 600–613; 1100–1123</td> </tr> <tr class="row-even"><td>101 through 109 (in multiples of 100)</td> <td>Use changed part only, omitting unneeded zeros</td> <td>107–8; 505–17; 1002–6</td> </tr> <tr class="row-odd"><td>110 through 199 (in multiples of 100)</td> <td>Use two digits, or more as needed</td> <td>321–25; 415–532; 11564–68; 13792–803</td> </tr> <tr class="row-even"><td>4 digits</td> <td>If numbers are four digits long and three digits change, use all digits</td> <td>1496–1504; 2787–2816</td> </tr> </tbody> </table> </dd> <dt>“chicago-16”</dt> <dd><p class="first">Page ranges are abbreviated according to the <a class="reference external" href="http://cmosshoptalk.com/2018/04/10/316-7-316-17-or-316-317-chicago-style-for-number-ranges/">Chicago Manual of Style (16th ed and later) rules</a> (see 16th ed, section 9.61):</p> <table border="1" class="last docutils"> <colgroup> <col width="40%" /> <col width="36%" /> <col width="24%" /> </colgroup> <thead valign="bottom"> <tr class="row-odd"><th class="head">First number</th> <th class="head">Second number</th> <th class="head">Examples</th> </tr> </thead> <tbody valign="top"> <tr class="row-even"><td>Less than 100</td> <td>Use all digits</td> <td>3–10; 71–72; 92–113;</td> </tr> <tr class="row-odd"><td>100 or multiple of 100</td> <td>Use all digits</td> <td>100–104; 600–613; 1100–1123</td> </tr> <tr class="row-even"><td>101 through 109, 201 through 209, etc. (for each multiple of 100)</td> <td>Use changed part only, omitting unneeded zeros</td> <td>107–8; 505–17; 1002–6</td> </tr> <tr class="row-odd"><td><p class="first">Everything else (110 through 199,</p> <blockquote class="last"> <div>210 through 299, etc.; for each multiple of 100)</div></blockquote> </td> <td>Use two digits, unless more digits are needed to show the changed part</td> <td>321–25; 415–532; 1087–89; 1496–500; 11564–68; 13792–803 12991–3001</td> </tr> </tbody> </table> </dd> <dt>“expanded”</dt> <dd>Abbreviated page ranges are expanded to their non-abbreviated form: 42–45, 321–328, 2787–2816</dd> <dt>“minimal”</dt> <dd>All digits repeated in the second number are left out: 42–5, 321–8, 2787–816</dd> <dt>“minimal-two”</dt> <dd>As “minimal”, but at least two digits are kept in the second number when it has two or more digits long.</dd> </dl> </div> <div class="section" id="appendix-vi-links"> <h2><a class="toc-backref" href="#toc-entry-96">Appendix VI: Links</a><a class="headerlink" href="#appendix-vi-links" title="Permalink to this headline">¶</a></h2> <p>The CSL syntax does not have support for configuration of links. However, processors should include links on bibliographic references, using the following rules:</p> <p>If the bibliography entry for an item renders any of the following identifiers, the identifier should be anchored as a link, with the target of the link as follows:</p> <ol class="arabic simple"> <li><code class="docutils literal notranslate"><span class="pre">url</span></code>: output as is</li> <li><code class="docutils literal notranslate"><span class="pre">doi</span></code>: prepend with “<a class="reference external" href="https://doi.org/">https://doi.org/</a>”</li> <li><code class="docutils literal notranslate"><span class="pre">pmid</span></code>: prepend with “<a class="reference external" href="https://www.ncbi.nlm.nih.gov/pubmed/">https://www.ncbi.nlm.nih.gov/pubmed/</a>”</li> <li><code class="docutils literal notranslate"><span class="pre">pmcid</span></code>: prepend with “<a class="reference external" href="https://www.ncbi.nlm.nih.gov/pmc/articles/">https://www.ncbi.nlm.nih.gov/pmc/articles/</a>”</li> </ol> <p>If the identifier is rendered as a URI, include rendered URI components (e.g. “<a class="reference external" href="https://doi.org/">https://doi.org/</a>”) in the link anchor. Do not include any other affix text in the link anchor (e.g. “Available from: “, “doi: “, “PMID: “).</p> <p>Citation processors should include an option flag for calling applications to disable bibliography linking behavior.</p> </div> </div> </div> </div> <footer> <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation"> <a href="translating-locale-files.html" class="btn btn-neutral float-left" title="Guide to Translating CSL Locale Files" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a> </div> <hr/> <div role="contentinfo"> <p> © Copyright 2015, Rintze M. Zelle <span class="commit"> Revision <code>ea75983c</code>. </span> </p> </div> Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/rtfd/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>. </footer> </div> </div> </section> </div> <script type="text/javascript"> jQuery(function () { SphinxRtdTheme.Navigation.enable(true); }); </script> </body> </html>