/
specification.txt
2823 lines (2214 loc) · 101 KB
/
specification.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
=================================
`Citation Style Language 1.0.1`__
=================================
~~~~~~~~~~~~~~~~~~~~~~
Language Specification
~~~~~~~~~~~~~~~~~~~~~~
__ `Table of Contents`_
.. class:: fixed
`citationstyles.org`__
__ http://citationstyles.org/
.. class:: info-version
2012-06-15
.. class:: version-links
This version:
http://citationstyles.org/downloads/specification-csl101-20120615.html
Latest version:
http://citationstyles.org/downloads/specification.html
Previous versions:
- http://citationstyles.org/downloads/specification-csl10-20100321.html
- http://citationstyles.org/downloads/specification-csl10-20100530.html
.. class:: contributors
**Author**
Rintze M. Zelle, PhD
**Contributors**
| Frank G. Bennett, Jr.
| Bruce D'Arcus
|CCBYSA|_
.. |CCBYSA| image:: http://i.creativecommons.org/l/by-sa/3.0/80x15.png
.. _CCBYSA: http://creativecommons.org/licenses/by-sa/3.0/
.. |--| unicode:: U+2013
:trim:
========
.. contents:: Table of Contents
========
Introduction
------------
The Citation Style Language (CSL) is an XML-based format to describe the
formatting of citations, notes and bibliographies, offering:
- An open format
- Compact and robust styles
- Extensive support for style requirements
- Automatic style localization
- Infrastructure for style distribution and updating
- Already over 2000 freely available styles (Creative Commons BY-SA licensed)
For additional documentation, the CSL schema, styles, and locales, visit the CSL
project home, `citationstyles.org <http://citationstyles.org>`_.
Terminology
~~~~~~~~~~~
The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT,
RECOMMENDED, MAY, and OPTIONAL, are to be interpreted as described in
`IETF RFC 2119 <http://tools.ietf.org/html/rfc2119>`_.
Namespacing
-----------
The CSL `XML namespace URI <http://en.wikipedia.org/wiki/XML_Namespace>`_
is "http://purl.org/net/xbiblio/csl". The namespace prefix ``cs:`` is used
throughout this specification when referring to CSL elements, but is generally
omitted in favor of a default namespace declaration (set with
the ``xmlns`` attribute) on the root ``cs:style`` or ``cs:locale`` element.
File Types
----------
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).
Independent Styles
~~~~~~~~~~~~~~~~~~
Independent styles contain formatting instructions for citations, notes and
bibliographies. While mostly self-contained, they rely on locale files for
(default) localization data.
Dependent Styles
~~~~~~~~~~~~~~~~
A dependent style is an alias for an independent style. Its contents is 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.
Locale Files
~~~~~~~~~~~~
Each locale file contains a set of localization data (term translations,
localized date formats, and grammar options) for a particular language dialect.
XML Declaration
---------------
Each style or locale should begin with an XML declaration, specifying the XML
version and character encoding. In most cases, the declaration will be:
.. sourcecode:: xml
<?xml version="1.0" encoding="UTF-8"?>
Styles - Structure
------------------
The Root Element - ``cs:style``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The root element of styles is ``cs:style``. In independent styles, the element
carries the following attributes:
``class``
Determines whether the style uses in-text citations (value "in-text") or
notes ("note").
``default-locale`` (optional)
Sets a default locale for style localization. Value must be a `locale
code <http://books.xmlschemata.org/relaxng/ch19-77191.html>`_.
``version``
The CSL version of the style. Must be "1.0" for CSL 1.0-compatible styles.
In addition, ``cs:style`` may carry any of the `global options`_ and
`inheritable name options`_.
Of these attributes, only ``version`` is required on ``cs:style`` in dependent
styles, while the ``default-locale`` attribute may be set to specify an
overriding style locale. The other attributes are allowed but ignored.
An example of ``cs:style`` for an independent style, preceded by the XML
declaration:
.. sourcecode:: xml
<?xml version="1.0" encoding="UTF-8"?>
<style xmlns="http://purl.org/net/xbiblio/csl" version="1.0" class="in-text" default-locale="fr-FR"/>
Child Elements of ``cs:style``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In independent styles, the ``cs:style`` root element has the following child
elements:
``cs:info``
Must appear as the first child element of ``cs:style``. Contains the
metadata describing the style (style name, ID, authors, etc.).
``cs:citation``
Must appear once. Describes the formatting of in-text citations or notes.
``cs:bibliography`` (optional)
May appear once. Describes the formatting of the bibliography.
``cs:macro`` (optional)
May appear multiple times. Macros allow formatting instructions to be
reused, keeping styles compact and maintainable.
``cs:locale`` (optional)
May appear multiple times. Used to specify (overriding) localization data.
In `dependent styles`_, ``cs:style`` has only one child element, ``cs:info``.
Info
^^^^
The ``cs:info`` element contains the style's metadata. Its structure is based on
the `Atom Syndication Format <http://tools.ietf.org/html/rfc4287>`_. In
independent styles, ``cs:info`` has the following child elements:
``cs:author`` and ``cs:contributor`` (optional)
``cs:author`` and ``cs:contributor``, used to respectively acknowledge style
authors and contributors, may each be used multiple times. Within these
elements, the child element ``cs:name`` must appear once, while ``cs:email``
and ``cs:uri`` each may appear once. These child elements should contain
respectively the name, email address and URI of the author or contributor.
``cs:category`` (optional)
Styles may be assigned one or more categories. ``cs:category`` may be used
once to describe how in-text citations are rendered, using the
``citation-format`` attribute set to one of the following values:
- "author-date" - e.g. "... (Doe, 1999)"
- "author" - e.g. "... (Doe)"
- "numeric" - e.g. "... [1]"
- "label" - e.g. "... [doe99]"
- "note" - the citation appears as a footnote or endnote
``cs:category`` may be used multiple times with the ``field`` attribute, set
to one of the discipline `categories`_, to indicates the field(s) for which
the style is relevant.
``cs:id``
Must appear once. The element should contain a URI to establish the identity
of the style. A stable, unique and dereferenceable URI is desired for
publicly available styles.
``cs:issn``/``cs:eissn``/``cs:issnl`` (optional)
The ``cs:issn`` element may be used multiple times to indicate the ISSN
identifier(s) of the journal for which the style was written. The
``cs:eissn`` and ``cs:issnl`` elements may each be used once for the eISSN
and `ISSN-L <http://www.issn.org/2-22637-What-is-an-ISSN-L.php>`_
identifiers, respectively.
``cs:link`` (optional)
May be used multiple times. ``cs:link`` must carry two attributes: ``href``,
set to a URI (usually a URL), and ``rel``, whose value indicates how the URI
relates to the style. The possible values of ``rel``:
- "self" - style URI
- "template" - URI of the style from which the current style is derived
- "documentation - URI of style documentation
The ``cs:link`` element may contain content describing the link.
``cs:published`` (optional)
May appear once. The contents of ``cs:published`` must be a
`timestamp <http://books.xmlschemata.org/relaxng/ch19-77049.html>`_,
indicating when the style was initially created or made available.
``cs:rights`` (optional)
May appear once. The contents of ``cs:rights`` specifies the license under
which the style file is released. The element may carry a ``license``
attribute to specify the URI of the license.
``cs:summary`` (optional)
May appear once. The contents of ``cs:summary`` gives a (short) description
of the style.
``cs:title``
Must appear once. The contents of ``cs:title`` should be the name of the
style as shown to users.
``cs:title-short`` (optional)
May appear once. The contents of ``cs:title-short`` should be a shortened
style name (e.g. "APA").
``cs:updated``
Must appear once. The contents of ``cs:updated`` must be a `timestamp
<http://books.xmlschemata.org/relaxng/ch19-77049.html>`_ that shows when the
style was last updated.
The ``cs:link``, ``cs:rights``, ``cs:summary``, ``cs:title`` and
``cs:title-short`` elements may carry a ``xml:lang`` attribute to specify the
language of the element's content (the value must be an `xsd:language
locale code <http://books.xmlschemata.org/relaxng/ch19-77191.html>`_). For
``cs:link``, the attribute can also be used to indicate the language of the link
target.
In `dependent styles`_, ``cs:link`` must be used with ``rel`` set to
"independent-parent", with the URI of the independent parent style set on
``href``. In addition, ``cs:link`` should not be used with ``rel`` set to
"template".
An example of ``cs:info`` for an independent style:
.. sourcecode:: xml
<info>
<title>Style Title</title>
<id>http://www.zotero.org/styles/style-title</id>
<link href="http://www.zotero.org/styles/style-title" rel="self"/>
<author>
<name>Author Name</name>
<email>name@domain.com</email>
<uri>http://www.domain.com/name</uri>
</author>
<category citation-format="author-date"/>
<category field="zoology"/>
<updated>2008-10-29T21:01:24+00:00</updated>
<rights license="http://creativecommons.org/licenses/by-sa/3.0/">This work
is licensed under a Creative Commons Attribution-Share Alike 3.0 Unported
License</rights>
</info>
Citation
^^^^^^^^
The ``cs:citation`` 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 ``cs:layout`` child element describes what, and how,
bibliographic data should be included in the citations (see `Layout
<#layout>`_). ``cs:layout`` may be preceded by a ``cs:sort`` element, which can
be used to specify how cites within a citation should be sorted (see
`Sorting`_). The ``cs:citation`` element may carry attributes for
`Citation-specific Options`_ and `Inheritable Name Options`_. An example of a
``cs:citation`` element:
.. sourcecode:: xml
<citation option="option-value">
<sort>
<!-- sort keys -->
</sort>
<layout>
<!-- rendering elements -->
</layout>
</citation>
**A note to CSL processor developers** 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.
Bibliography
^^^^^^^^^^^^
The ``cs:bibliography`` element describes the formatting of bibliographies,
which list one or more bibliographic sources. The required ``cs:layout`` child
element describes how each bibliographic entry should be formatted.
``cs:layout`` may be preceded by a ``cs:sort`` element, which can be used to
specify how references within the bibliography should be sorted (see
`Sorting`_). The ``cs:bibliography`` element may carry attributes for
`Bibliography-specific Options`_ and `Inheritable Name Options`_. An example of
a ``cs:bibliography`` element:
.. sourcecode:: xml
<bibliography option="option-value">
<sort>
<!-- sort keys -->
</sort>
<layout>
<!-- rendering elements -->
</layout>
</bibliography>
Macro
^^^^^
Macros, defined with ``cs:macro`` elements, contain formatting instructions.
Macros can be called with ``cs:text`` from within other macros and the
``cs:layout`` element of ``cs:citation`` and ``cs:bibliography``, and with
``cs:key`` from within ``cs:sort`` of ``cs:citation`` and ``cs:bibliography``.
It is recommended to place macros after any ``cs:locale`` elements and before
the ``cs:citation`` element.
Macros are referenced by the value of the required ``name`` attribute on
``cs:macro``. The ``cs:macro`` element must contain one or more `rendering
elements`_.
The use of macros can improve style readability, compactness and
maintainability. It is recommended to keep the contents of ``cs:citation`` and
``cs:bibliography`` 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.
In the example below, cites consist of the item title, rendered in italics when
the item type is "book":
.. sourcecode:: xml
<style>
<macro name="title">
<choose>
<if type="book">
<text variable="title" font-style="italic"/>
</if>
<else>
<text variable="title"/>
</else>
</choose>
</macro>
<citation>
<layout>
<text macro="title"/>
</layout>
</citation>
</style>
Locale
^^^^^^
Localization data, by default drawn from the "locales-xx-XX.xml" locale files,
may be redefined or supplemented with ``cs:locale`` elements, which should be
placed directly after the ``cs:info`` element.
The value of the optional ``xml:lang`` attribute on ``cs:locale``, which must be
set to an `xsd:language locale code
<http://books.xmlschemata.org/relaxng/ch19-77191.html>`_, determines which
languages or language dialects are affected (see `Locale Fallback`_).
See `Terms`_, `Localized Date Formats`_ and `Localized Options`_ for further
details on the use of ``cs:locale``.
An example of ``cs:locale`` in a style:
.. sourcecode:: xml
<style>
<locale xml:lang="en">
<terms>
<term name="editortranslator" form="short">
<single>ed. & trans.</single>
<multiple>eds. & trans.</multiple>
</term>
</terms>
</locale>
</style>
Locale Fallback
'''''''''''''''
Locale files provide localization data for language dialects (e.g. "en-US" for
American English), whereas the optional ``cs:locale`` elements in styles can
either lack the ``xml:lang`` 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.
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:
+-----------------+----------------------+
| Primary dialect | Secondary dialect(s) |
+=================+======================+
| de-DE | de-AT, de-CH |
+-----------------+----------------------+
| en-US | en-GB |
+-----------------+----------------------+
| pt-PT | pt-BR |
+-----------------+----------------------+
| zh-CN | zh-TW |
+-----------------+----------------------+
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:
A. In-style ``cs:locale`` elements
1. ``xml:lang`` set to chosen dialect, "de-AT"
2. ``xml:lang`` set to matching language, "de" (German)
3. ``xml:lang`` not set
B. Locale files
4. ``xml:lang`` set to chosen dialect, "de-AT"
5. ``xml:lang`` set to matching primary dialect, "de-DE" (Standard German)
(only applicable when the chosen locale is a secondary dialect)
6. ``xml:lang`` set to "en-US" (American English)
If the chosen output locale is a language (e.g. "de"), the (primary) dialect is
used in step 1 (e.g. "de-DE").
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. ``<term name="and"/>`` or
``<term name="and"></term>``). Locale fallback takes precedence over fallback of
term forms (see `Terms`_).
Locale Files - Structure
------------------------
While localization data can be included in styles (see `Locale`_), locale files
conveniently provide sets of default localization data, consisting of terms,
date formats and grammar options.
Each locale file contains localization data for a single language dialect. This
`locale code <http://books.xmlschemata.org/relaxng/ch19-77191.html>`_ is set on
the required ``xml:lang`` attribute on the ``cs:locale`` 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 ``version`` 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
`namespacing`_ as styles. The ``cs:locale`` element may contain ``cs:info`` as
its first child element, and requires the child elements ``cs:terms``,
``cs:date`` and ``cs:style-options`` (these elements are described below). An
example showing part of a locale file:
.. sourcecode:: xml
<?xml version="1.0" encoding="UTF-8"?>
<locale xml:lang="en-US" version="1.0" xmlns="http://purl.org/net/xbiblio/csl">
<style-options punctuation-in-quote="true"/>
<date form="text">
<date-part name="month" suffix=" "/>
<date-part name="day" suffix=", "/>
<date-part name="year"/>
</date>
<date form="numeric">
<date-part name="year"/>
<date-part name="month" form="numeric" prefix="-" range-delimiter="/"/>
<date-part name="day" prefix="-" range-delimiter="/"/>
</date>
<terms>
<term name="no date">n.d.</term>
<term name="et-al">et al.</term>
<term name="page">
<single>page</single>
<multiple>pages</multiple>
</term>
<term name="page" form="short">
<single>p.</single>
<multiple>pp.</multiple>
</term>
</terms>
</locale>
Info
~~~~
The ``cs:info`` element may be used to give metadata on the locale file. It has
the following child elements:
``cs:translator`` (optional)
``cs:translator``, used to acknowledge locale translators, may be used
multiple times. Within the element, the child element ``cs:name`` must
appear once, while ``cs:email`` and ``cs:uri`` each may appear once. These
child elements should contain respectively the name, email address and URI
of the translator.
``cs:rights`` (optional)
May appear once. The contents of ``cs:rights`` specifies the license under
which the locale file is released. The element may carry a ``license``
attribute to specify the URI of the license, and a ``xml:lang`` attribute to
specify the language of the element's content (the value must be an
`xsd:language locale code
<http://books.xmlschemata.org/relaxng/ch19-77191.html>`_).
``cs:updated`` (optional)
May appear once. The contents of ``cs:updated`` must be a `timestamp
<http://books.xmlschemata.org/relaxng/ch19-77049.html>`_ that shows when the
locale file was last updated.
Terms
~~~~~
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 ``cs:term`` elements, child elements
of ``cs:terms``. Each ``cs:term`` element must carry a ``name`` attribute, set
to one of the terms listed in `Appendix III - Terms`_.
Terms are either directly defined in the content of ``cs:term``, or, in cases
where singular and plural variants are needed (e.g. "page" and "pages"), in the
content of the child elements ``cs:single`` and ``cs:multiple``, respectively.
Terms may be defined for specific forms by using ``cs:term`` with the optional
``form`` attribute set to:
- "long" - (default), e.g. "editor" and "editors" for the "editor" term
- "short" - e.g. "ed." and "eds." for the term "editor"
- "verb" - e.g. "edited by" for the term "editor"
- "verb-short" - e.g. "ed." for the term "editor"
- "symbol" - e.g. "§" and "§§" for the term "section"
If a style uses a term in a form that is undefined (even after `Locale
Fallback`_), 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". If no locale or form fallback is available, the term is rendered
as a empty string.
`Gender-specific ordinals`_ are activated through the ``gender`` and
``gender-form`` attributes on ``cs:term``, which are described below.
Term content should not contain markup such as LaTeX or HTML. `Superscripted
Unicode characters`__ can be used for superscripting.
__ http://unicode.org/reports/tr30/datafiles/SuperscriptFolding.txt
Gender-specific Ordinals
^^^^^^^^^^^^^^^^^^^^^^^^
Some languages use gender-specific ordinals. For example, the English "1st" and
"first" translate in French to "1\ :sup:`er`\ " and "premier" if the target noun
is masculine, and "1\ :sup:`re`\ " and "première" if the noun is feminine.
Feminine and masculine variants of the ordinal terms (see `Ordinals`_) may be
specified by setting the ``gender-form`` attribute to "feminine" or "masculine"
(the term without ``gender-form`` represents the neuter variant). There are two
types of target nouns: a) the terms accompanying the `number variables`_, and b)
the month terms (see `Months`_). The gender of these nouns may be specified on
the "long" (default) form of the term using the ``gender`` attribute (set to
"feminine" or "masculine"). When a number variable is rendered with
``cs:number`` 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.
The example below gives "1re éd." ("1st ed."), "1er janvier" ("January 1st"),
and "3e janvier" ("January 3rd"):
.. sourcecode:: xml
<?xml version="1.0" encoding="UTF-8"?>
<locale xml:lang="fr-FR">
<terms>
<term name="edition" gender="feminine">
<single>édition</single>
<multiple>éditions</multiple>
</term>
<term name="edition" form="short">éd.</term>
<term name="month-01" gender="masculine">janvier</term>
<term name="ordinal-01" gender-form="feminine">re</term>
<term name="ordinal-01" gender-form="masculine">er</term>
<term name="ordinal-02">e</term>
<term name="ordinal-03">e</term>
<term name="ordinal-04">e</term>
</terms>
</locale>
Localized Date Formats
~~~~~~~~~~~~~~~~~~~~~~
Two localized date formats can be defined with ``cs:date`` elements: a "numeric"
(e.g. "12-15-2005") and a "text" format (e.g. "December 15, 2005"). The format
is set on ``cs:date`` with the required ``form`` attribute.
A date format is constructed using ``cs:date-part`` child elements (see
`Date-part`_). With a required ``name`` attribute set to either ``day``,
``month`` or ``year``, the order of these elements reflects the display order of
respectively the day, month, and year. The date can be formatted with
`formatting`_ and `text-case`_ attributes on the ``cs:date`` and
``cs:date-part`` elements. The `delimiter`_ attribute may be set on ``cs:date``
to specify the delimiter for the ``cs:date-part`` elements, and `affixes`_ may
be applied to the ``cs:date-part`` elements.
**Note** Affixes are not allowed on ``cs:date`` when defining localized date
formats. This restriction is in place to separate locale-specific affixes (set
on the ``cs:date-part`` elements) from any style-specific affixes (set on the
calling ``cs:date`` element), such as parentheses. An example of a macro calling
a localized date format:
.. sourcecode:: xml
<macro name="issued">
<date variable="issued" form="numeric" prefix="(" suffix=")"/>
</macro>
Localized Options
~~~~~~~~~~~~~~~~~
There is one localized option, ``punctuation-in-quote`` (see `Locale Options`_).
This global option (affecting both citations and the bibliography) is set as an
optional attribute on ``cs:style-options``.
Rendering Elements
------------------
Rendering elements specify which, and in what order, pieces of bibliographic
metadata are included in citations and bibliographies, and offer control over
their formatting.
Layout
~~~~~~
The ``cs:layout`` rendering element is a required child element of
``cs:citation`` and ``cs:bibliography``. It must contain one or more of the
other rendering elements described below, and may carry `affixes`_ and
`formatting`_ attributes. When used within ``cs:citation``, the `delimiter`_
attribute may be used to specify a delimiter for cites within a citation. For
example, a citation like "(1, 2)" can be achieved with:
.. sourcecode:: xml
<citation>
<layout prefix="(" suffix=")" delimiter=", ">
<text variable="citation-number"/>
</layout>
</citation>
Text
~~~~
The ``cs:text`` rendering element outputs text. It must carry one of the
following attributes to select what should be rendered:
- ``variable`` - renders the text contents of a variable. Attribute value must
be one of the `standard variables`_. May be accompanied by the ``form``
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.
- ``macro`` - renders the text output of a macro. Attribute value must match
the value of the ``name`` attribute of a ``cs:macro`` element (see `Macro`_).
- ``term`` - renders a term. Attribute value must be one of the terms listed in
`Appendix III - Terms`_. May be accompanied by the ``plural`` attribute to
select the singular ("false", default) or plural ("true") variant of a term,
and by the ``form`` attribute to select the "long" (default), "short",
"verb", "verb-short" or "symbol" form variant (see also `Terms`_).
- ``value`` - renders the attribute value itself.
An example of ``cs:text`` rendering the "title" variable:
.. sourcecode:: xml
<text variable="title"/>
``cs:text`` may also carry `affixes`_, `display`_, `formatting`_, `quotes`_,
`strip-periods`_ and `text-case`_ attributes.
Date
~~~~
The ``cs:date`` rendering element outputs the date selected from the list of
`date variables`_ with the required ``variable`` attribute. A date can be
rendered in either a localized or non-localized format.
`Localized date formats`_ are selected with the optional ``form`` attribute,
which must 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
``date-parts`` attribute may be used to show fewer date parts. The possible
values are:
- "year-month-day" - (default), renders the year, month and day
- "year-month" - renders the year and month
- "year" - renders the year
Secondly, ``cs:date`` may have one or more ``cs:date-part`` child elements (see
`Date-part`_). The attributes set on these elements override those specified for
the localized date formats (e.g. to get abbreviated months for all locales, the
``form`` attribute on the month-``cs:date-part`` element can be set to "short").
These ``cs:date-part`` elements do not affect which, or in what order, date
parts are rendered. `Affixes`_, which are very locale-specific, are not allowed
on these ``cs:date-part`` elements.
In the absence of the ``form`` attribute, ``cs:date`` describes a self-contained
non-localized date format. In this case, the date format is constructed using
``cs:date-part`` child elements. With a required ``name`` attribute set to
either ``day``, ``month`` or ``year``, the order of these elements reflects the
display order of respectively the day, month, and year. The date can be
formatted with `formatting`_ attributes on the ``cs:date-part`` elements, as
well as several ``cs:date-part``-specific attributes (see `Date-part`_). The
`delimiter`_ attribute may be set on ``cs:date`` to specify the delimiter for
the ``cs:date-part`` elements, and `affixes`_ may be applied to the
``cs:date-part`` elements.
For both localized and non-localized dates, ``cs:date`` may carry `affixes`_,
`display`_, `formatting`_ and `text-case`_ attributes.
Date-part
^^^^^^^^^
The ``cs:date-part`` elements control how date parts are rendered. Unless the
parent ``cs:date`` element calls a localized date format, they also determine
which, and in what order, date parts appear. A ``cs:date-part`` element
describes the date part selected with the required ``name`` attribute:
"day"
For "day", ``cs:date-part`` may carry the ``form`` attribute, with values:
- "numeric" - (default), e.g. "1"
- "numeric-leading-zeros" - e.g. "01"
- "ordinal" - e.g. "1st"
"month"
For "month", ``cs:date-part`` may carry the `strip-periods`_ and ``form``
attributes. In locale files, month abbreviations (the "short" form of the
month `terms`_) should be defined with periods if applicable (e.g. "Jan.",
"Feb.", etc.). These periods can be removed by setting `strip-periods`_ to
"true" ("false" is the default). The ``form`` attribute can be set to:
- "long" - (default), e.g. "January"
- "short" - e.g. "Jan."
- "numeric" - e.g. "1"
- "numeric-leading-zeros" - e.g. "01"
"year"
For "year", ``cs:date-part`` may carry the ``form`` attribute, with values:
- "long" - (default), e.g. "2005"
- "short" - e.g. "05"
``cs:date-part`` may also carry `formatting`_, `text-case`_ and
``range-delimiter`` (see `Date Ranges`_) attributes. Attributes for `affixes`_
are allowed, unless ``cs:date`` calls a localized date format.
Date Ranges
'''''''''''
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 ``cs:date-part`` elements
with the optional ``range-delimiter`` attribute. When a date range is rendered,
the range delimiter is drawn from the ``cs:date-part`` element matching the
largest date part ("year", "month", or "day") that differs between the two
dates. For example,
.. sourcecode:: xml
<style>
<citation>
<layout>
<date variable="issued">
<date-part name="day" suffix=" " range-delimiter="-"/>
<date-part name="month" suffix=" "/>
<date-part name="year" range-delimiter="/"/>
</date>
</layout>
</citation>
</style>
would result in "1-4 May 2008", "May |--| July 2008" and "May 2008/June 2009".
AD and BC
^^^^^^^^^
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").
Seasons
^^^^^^^
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.,
.. sourcecode:: xml
<style>
<citation>
<layout>
<date variable="issued">
<date-part name="month" suffix=" "/>
<date-part name="year"/>
</date>
</layout>
</citation>
</style>
would result in "May 2008" and "Winter 2009".
Approximate Dates
^^^^^^^^^^^^^^^^^
Approximate dates test "true" for the ``is-uncertain-date`` conditional (see
`Choose`_). For example,
.. sourcecode:: xml
<style>
<citation>
<layout>
<choose>
<if is-uncertain-date="issued">
<text term="circa" form="short" suffix=" "/>
</if>
</choose>
<date variable="issued">
<date-part name="year"/>
</date>
</layout>
</citation>
</style>
would result in "2005" (normal date) and "ca. 2003" (approximate date).
Number
~~~~~~
The ``cs:number`` rendering element outputs the number variable selected with
the required ``variable`` attribute. `Number variables`_ are a subset of the
list of `standard variables`_.
If a number variable is rendered with ``cs:number`` and only contains numeric
content (as determined by the rules for ``is-numeric``, see `Choose`_), the
number(s) are extracted. Variable content is rendered "as is" when the variable
contains any non-numeric content (e.g. "Special edition").
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 ampsersand ("2&3" becomes
"2 & 3").
Extracted numbers can be formatted via the optional ``form`` attribute, with
values:
- "numeric" - (default), e.g. "1", "2", "3"
- "ordinal" - e.g. "1st", "2nd", "3rd". Ordinal suffixes are defined with the
`terms`_ "ordinal-01" to "ordinal-04". "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.
- "long-ordinal" - e.g. "first", "second", "third". Long ordinals are defined
with the `terms`_ "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".
- "roman" - e.g. "i", "ii", "iii"
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").
``cs:number`` may carry `affixes`_, `display`_, `formatting`_ and `text-case`_
attributes.
Names
~~~~~
The ``cs:names`` rendering element outputs the contents of one or more `name
variables`_ (selected with the required ``variable`` 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 ``cs:names`` element contains a
``cs:label`` element, replacing the default "editor" and "translator" terms
(e.g. resulting in "Doe (editor & translator)"). The `delimiter`_ attribute may
be set on ``cs:names`` to separate the names of the different name variables
(e.g. the semicolon in "Doe, Smith (editors); Johnson (translator)").
.. sourcecode:: xml
<names variable="editor translator" delimiter="; ">
<label prefix=" (" suffix=")"/>
</names>
``cs:names`` has four child elements (discussed below): ``cs:name``,
``cs:et-al``, ``cs:substitute`` and ``cs:label``. The ``cs:names`` element may
carry `affixes`_, `display`_ and `formatting`_ attributes.
Name
^^^^
The ``cs:name`` element, an optional child element of ``cs:names``, can be used
to describe the formatting of individual names, and the separation of names
within a name variable. ``cs:name`` may carry the following attributes:
``and``
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").
``delimiter``
Specifies the text string used to separate names in a name variable. Default
is ", " (e.g. "Doe, Smith").
``delimiter-precedes-et-al``
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:
- "contextual" - (default), name delimiter is only used for name lists
truncated to two or more names
- 1 name: "J. Doe et al."
- 2 names: "J. Doe, S. Smith, et al."
- "always" - name delimiter is always used
- 1 name: "J. Doe, et al."
- 2 names: "J. Doe, S. Smith, et al."
- "never" - name delimiter is never used
- 1 name: "J. Doe et al."
- 2 names: "J. Doe, S. Smith et al."
``delimiter-precedes-last``
Determines when the name delimiter is used to separate the second to last
and the last name in name lists (if ``and`` is not set, the name delimiter
is always used, regardless of the value of ``delimiter-precedes-last``).
Allowed values:
- "contextual" - (default), name delimiter is only used for name lists
with three or more names
- 2 names: "J. Doe and T. Williams"
- 3 names: "J. Doe, S. Smith, and T. Williams"
- "always" - name delimiter is always used
- 2 names: "J. Doe, and T. Williams"
- 3 names: "J. Doe, S. Smith, and T. Williams"
- "never" - name delimiter is never used