CSL-M: extensions to CSL¶
Frank BennettThis supplement is a companion to the CSL 1.0.1 Specification. It is aimed at style authors, and documents differences between official CSL and the CSL-m schema recognised by Multilingual Zotero.
The changes are of two types:
- Modifications alter the behaviour or validation rules of existing CSL elements or attributes. Changes of this kind can cause official CSL repository to fail validation under the CSL-m schema: such styles will run, but may produce unexpected results. The potential effects of this category of changes are indicated where relevant.
- Extensions add entirely new elements or attributes to the schema. Styles making use of extended syntax will fail validation under the official CSL schema, and can be used only with Multilingual Zotero.
Table of Contents
- CSL-M: extensions to CSL
- Item Types
- Elements
- Variables
authority
(modification)available-date
(extension)dummy
(extension)hereinafter
(extension)locator
(modification)locator-date
andlocator-extra
(extension)page
andpage-first
(modification)publication-date
(extension)publication-number
(extension)supplement
(extension)volume-title
(extension)alt-translator
(extension)alt-title
(extension)alt-container-title
(extension)alt-issued
(extension)
- Attributes
require-match
(extension)exclude-types
(extension)exclude-with-fields
(extension)default-locale-sort
(extension)form="imperial"
(modification)form="short"
(modification)is-parallel
(extension)label-form
(extension)leading-noise-words
(extension)match="nand"
(extension)name-as-reverse-order
(extension)name-as-sort-order
(extension)name-never-short
(extension)oops
(extension)prefix
andsuffix
(modification)skip-words
(extension)subgroup-delimiter
,subgroup-delimiter-precedes-last
,and
(extension)suppress-min
(extension)suppress-max
(extension)text-case
(extension)year-range-format
(extension)
- Conditions
- Terms
- Locator Terms
Item Types¶
classic
¶
Use the classic
type for sources commonly cited within a field. Cites
of this type do not appear in the bibliography, and can be completely
reformatted to a compact, style-specific form using the Classic
abbreviation list in the Abbreviation Filter.
When a short form is supplied for a Classic item, the title
variable is suppressed, and the short form entirely replaces the
author
variable. When a volume number or other details are included,
these can be rendered on either side of the composite abbreviated form,
but not of course within it.
<choose>
<if type="classic">
<group delimiter=" ">
<text variable="volume"/>
<group delimiter=", ">
<names variable="author"/>
<text variable="title"/>
</group>
</if>
</choose>
gazette
¶
Use the gazette
type for instruments published through an official
gazette. Typical use cases would be cites to amending acts, to the initial
version of legislation, or to orders and other instruments that are not
available from other official sources. For consolidated acts or codified
statutes or regulations, use the legislation
(MLZ Statute) or
regulation
(MLZ Regulation) types instead.
<choose>
<if type="gazette">
<text macro="gazette-mac"/>
</if>
</choose>
The format of gazette citations may vary among jurisdictions. Test the
jurisdiction
variable (see below) to discriminate between citation
forms.
hearing
¶
The hearing
type is primarily intended for transcripts of official
hearings by government committees and the like (other documents
produced by a committee should be cast as the report
type
instead). The body conducting a hearing is set in the authority
variable (Legis. Body in MLZ).
<choose>
<if type="hearing">
<text macro="hearing-mac"/>
</if>
</choose>
regulation
¶
Use the regulation
type for administrative orders at all
levels of government.
<choose>
<if type="regulation">
<text macro="hearing-mac"/>
</if>
</choose>
video
¶
The video
type is appropriate for video works that are not
disseminated through an access-restricted distribution channel. For
example, content hosted on YouTube should be set to video
, while
a DVD release of “The Wizard of Oz” should be set to motion_picture
.
<choose>
<if type="regulation">
<text macro="hearing-mac"/>
</if>
</choose>
Elements¶
cs:alternative
¶
Use cs:alternative
to add supplementary reference information to a
cited item, such as a translation or reprint. Elements within the
scope of cs:alternative
are rendered only when the value of
language
contains two valid ISO language codes joined by <
or
>
(to indicate the direction of translation). The two language
codes may be identical.
In a multi-layout style, elements within the scope of
cs:alternative
are rendered in the primary locale associated with
the target language code. Thus, if the input item has a language
value of en>zh
, and a multi-layout style has a layout with
locale="ja zh"
, elements within the scope of cs:alternative
will be rendered in the Japanese locale, with Japanese term
definitions.
cs:alternative-text
¶
Use the cs:alternative-text
element to rerun the layout applied
to cs:alternative
with alternative item content. Variables
for rendering via cs:alternative-text
are set with an alt-
prefix.
cs:conditions
¶
Condition statements in official CSL take a single “match” attribute,
which determines how the tests will be combined. The match attribute
value (all
, any
, none
) applies to all tests within the
statement: grouping of tests with separate match values is not possible.
To simplify the coding of complex styles, CSL-m introduces an optional
alternative syntax for condition statements.
The alternative syntax may be applied to cs:if
or cs:else-if
elements (the “parent node” in this description). The parent node must
have no attributes, and a single cs:conditions
node as its first
child element. The cs:conditions
node must have one or more
cs:condition
children. The cs:condition
children each define a
conditional statement with attributes specified in the CSL 1.0.1
schema and in this Supplement. The cs:condition
statements are
joined according to a mandatory “match” attribute on
cs:conditions
.
Note that CSL-m adds a “nand” match value (true if at least one of the tests or condition statements to which it applies returns false), in addition to “all”, “any”, and “none”.
<choose>
<if>
<conditions match="any">
<condition type="chapter"/>
<condition variable="container-title collection-title" match="nand"/>
</conditions>
<text macro="some-chapter-mac"/>
</if>
</choose>
cs:institution
¶
Institutional names are fundamentally different in structure from personal names. CSL provides quite robust support for the presentation and sorting of personal names, but in CSL 1.0.1, institutional names have just one fixed form, and are otherwise treated the same as personal names in a list of creators.
Some publishing environments require greater flexibility. Institution names can consist of multiple subunits. Individuals may be credited together with the institution to which they belong. Unaffiliated personal authors may be cited together with an institution or with individuals affiliated with it. Some examples:
- Research & Pub. Policy Dep’t, Nat’l Urban League
- United Nations - ECLAC
- ECLAC (Economic Commission for Latin America and the Carribean)
- Canadian Conservation Institute (CCI)
- Nolan J. Malone and others, U.S. Bureau of the Census
- World Trade Organization and World Health Organization
- Smith with Jones, Bureau of Sloth, Ministry of Fear
- Doe et al. with Roe et al., Ministry of Fear & Noakes, Ministry of Destruction
Examples 3 and 4 render both the full form and the acronym of a single institution name, with arbitrary ordering of the two name parts. Example 1 begins with the smallest subunit in a list of related institutions, and example 2 does the opposite. Examples 1 and 2 are pure organizations, while example 5 is a mix of personal and institutional names. Examples 1, 2, 3 and 4 would be entered as literal strings currently, which has obvious drawbacks. Example 5 would require that the authorship information be spread across two variables, although all parties listed are equally authors of the resource. Example 6 can be produced in CSL 0.8, but examples 7 and 8 cannot.
The MLZ extensions to CSL 1.0.1 provide a cs:institution element, which can be used to produce any of the above forms, without interfering with the formatting of ordinary personal names. The extension is always enabled in citeproc-js, but the application calling citeproc-js (i.e. Zotero) must specially flag institutional names for it to take effect. MLZ provides this flag, while the official Zotero client does not. For this reason, this extension only works with the multilingual client at present.
Entry conventions¶
In multilingual Zotero, names entered in two-field mode are personal, and those entered in single-field mode are treated as organizations. Names should be entered in the order in which they should appear in citations, with one (extremely rare) exception: when an unaffiliated author is included in a list of names that includes one or more institutions, the name of the unaffiliated author(s) should come after that of the last institution in the list.
Subunits of an organizational name should be separated with a
field separator character |
.
Affiliated authors¶
Single or multiple personal Names that are co-authors with an organization would be entered above the relevant organization name.
In a very simple style, the sample above might be rendered as: Clarke, Ministry of Fear and Smith & Brown, Large Corporation.
Unaffiliated authors¶
Authors with no affiliation would be listed after any organizational names:
In a very simple style, the sample above might be rendered as: Doe & Roe with Clarke, Ministry of Fear and Smith & Brown, Large Corporation (note the reverse ordering in this case, with the names at the end placed at the front of the rendered list of names).
The structure of mixed personal and organizational names can thus be expressed in the current Zotero UI. We now turn to the extended CSL syntax used to control the appearance of such names.
CSL Extension¶
Element: cs:institution
¶
A cs:institution
element can be placed immediately after the
cs:name
element to control the formatting of organization
names.
Attributes: delimiter
and and
¶
The value of the delimiter
attribute on cs:institution
is used in the following locations:
- between organization names;
- between the subunits of an organization;
- between affiliated authors and their institution.
The and
attribute on cs:institution
, if any, is used for the
final join between two or more author/organization units.
A simple use of cs:institution
might read as follows:
<names variable="author">
<name and="symbol" initialize-with=". "/>
<institution and="text" delimiter=", ">
</names>
With this CSL, all of the delimiters in the following string would be
drawn from attributes on cs:institution
: R. Smith, Small
Committee, Large Corporation, G. Brown, Busy Group, Active Laboratory,
and S. Noakes, Powerful Ministry.
Attributes: use-first
, substitute-use-first
and use-last
¶
To control the omission of names from the middle of the list of
organizational subunits, either of use-first
or
substitute-use-first
may be used to pick names from the front of
the list. The use-last
attribute picks names from the end. The
substitute-use-first
attribute includes the leading (smallest)
subunit if and only if no personal names are associated with the
organization.
The following CSL code would format both example 1 and example 5 from the list of samples at the top of this section:
<names variable="author" delimiter=", ">
<name
and="symbol"
delimiter-precedes-last="never"
et-al-min="3"
et-al-use-first="1"/>
<et-al term="and others"/>
<institution
delimiter=", "
substitute-use-first="1"
use-last="1"/>
</names>
Attribute: reverse-order
¶
By convention, organizational names are rendered in “big endian”
order, from the smallest to the largest organizational unit. To
provide for cases such as example 2 in the list of samples, a
reverse-order
attribute can be applied on cs:institution
:
<names variable="author" delimiter=", ">
<name/>
<institution
delimiter=" - "
use-first="1"
use-last="1"
reverse-order="true"/>
</names>
Attribute: institution-parts
¶
The components of organization names are normally rendered in their long form only. When the Zotero Abbreviations Gadget is used with Zotero, abbreviated forms for these names may be available to the processor.
To use the short form, or combinations of the long and short form, an
institution-parts
attribute is available on cs:institution
.
The attribute accepts values of long
, short
, short-long
and long-short
. This attribute would be used to produce examples
3 and 4 in the list of samples, with values of short-long
and
long-short
respectively. A value of short
behaves in the same
way as form="short"
in other contexts in CSL, using the short form
if it is available, and falling back to the long form otherwise.
Element: cs:institution-part
¶
One or more cs:institution-part elements can be used to control the
formatting of long and short forms of organization names. Like
cs:name-part
, these elements are unordered, and affect only the
formatting of the target name element, specified (as on cs:name-part
)
with a required name
attribute.
Attribute: if-short
¶
In example 3, the parentheses should be included only if a short form
of the institution name is available. The if-short
attribute,
available on cs:institution-part
only when applied to the long
form of an organization name, makes the formatting in the element
conditional on the availability of a short form of the name. The
following CSL would render example 3 in the list of samples:
<names variable="author">
<name/>
<institution institution-parts="short-long">
<institution-part name="long" if-short="true" prefix=" (" suffix=")"/>
</institution>
</names>
Element: cs:with
¶
In rendered output, unaffiliated personal names are joined to a
following organizational name using an implicit localizable term
with
. Styling of this term is permitted through an optional
cs:with
element, placed immediately above cs:institution
:
<names variable="author">
<name/>
<with font-style="italic" prefix=" " suffix=" "/>
<institution institution-parts="short-long">
<institution-part name="long" if-short="true" prefix=" (" suffix=")"/>
</institution>
</names>
Simple style example¶
The simple style used in the illustrated examples in the Entry conventions section above would look like this in CSL:
<names variable="author">
<name form="short" and="symbol" delimiter=", "/>
<institution use-last="1" and="text" delimiter=", "/>
</names>
cs:layout
¶
In publishing outside of the English language domain, citation of foreign material in the style of the originating language is the norm. For example, a Japanese publication might include the following references in a single work:
- D. H. McQueen, “Patents and Swedish University Spin-off Companies: Patent Ownership and Economic Health”, Patent World, March 1996, pp.22–27.
- 北川善太郎「著作権法100年記念講演会/著作権制度の未来像」コピーマート No.465, 7頁 (2000年)。
To meet such requirements, the MLZ extensions to CSL permit multiple
cs:layout
elements within cs:citation
and cs:bibliography
.
Each cs:layout
element but the last must include a locale
attribute
specifying one or more recognized CSL locales, and the final element must
not carry a locale
attribute. The locale applied to an item is determined
by matching it against the locale set in the language
variable of
the item (this value is passed by Zotero). An example:
<citation>
<layout locale="en es de">
<text macro="layout-citation-roman"/>
</layout>
<layout locale="ru">
<text macro="layout-citation-cyrillic"/>
</layout>
<layout>
<text macro="layout-citation-ja"/>
</layout>
</citation>
In the example above, an item with en
, es
or de
(or de-AT
) set in the language
variable will be render by the layout-citation-roman
macro, with locale terms set to the appropriate language.
Variables¶
authority
¶
In CSL-m, authority
is handled as an institutional creator, not as an ordinary
variable. It is rendered with a cs:names
element.
<macro name="std-authority-child">
<names variable="authority">
<name suppress-min="0"/>
<institution institution-parts="short" use-first="1"/>
</names>
</macro>
The use of suppress-min="0"
in this example is documented below
under suppress-min (extension).
available-date
¶
The CSL-m available-date
variable is appropriate for the date on
which a treaty
was made available for signing.
<group delimiter=" ">
<text value="opened for signature" font-style="italic"/>
<date date-parts="year-month-day" form="text" variable="available-date"/>
</group>
dummy
¶
The dummy
name variable is always empty. Use it to force all
name variables called through a cs:names
node to render through
cs:substitute
, and so suppress whichever is chosen for rendering
to be suppressed through the remainder of the current cite.
<names variable="dummy">
<name/>
<label/>
<substitute>
<names variable="author"/>
<names variable="editor"/>
</substitute>
</names>
hereinafter
¶
The hereinafter
variable is a backreference form specific to a
particular item and style. In MLZ, it can be set only through the
Abbreviation Filter. The role of the variable in a given cite
(i.e. whether it provides an alternative title, an acronym or a
more complete formatted citation) depends on the the style and context.
<choose>
<if match="all" type="bill gazette legislation" variable="hereinafter">
<text variable="hereinafter"/>
</if>
<else>
<text variable="title" form="short"/>
</else>
</choose>
The Abbreviation Filter will offer an entry in the hereinafter
list
for every item cited in the document. It is not necessary to use form="short"
on the cs:text
node that renders the variable.
locator
¶
In CSL-m, locator
is a numeric variable. Validation requires that
it be rendered with cs:number
.
<number variable="locator"/>
The locator
variable will render exactly once in a citation;
subsequent attempts will render nothing. As with variables suppressed
via cs:substitute
, the test for variable="locator"
will
continue to return true
after the variable is suppressed from
further output.
locator-date
and locator-extra
¶
The variable “locator-date” is parsed out from the user-supplied locator, using the following syntax:
123|2010-12-01
In this example, “123” is the value of the locator
variable
(a page or other pinpoint string), the |
character marks the
end of the pinpoint, and the ten-character string immediately
following is a full date. If supplied, dates must be given as shown above,
zero-padded, in year-month-day order, and with no space between
the date and the |
character. Non-conforming strings following
the |
marker will be treated as a locator-extra
variable.
The locator-extra
variable consists of a string that is not a
date, following the locator-date
string (if any) as described
above. If supplied without a locator-date
, the
locator-extra
string must be preceded by a |
field
separator character. This variable can be used for version
descriptions associated with some looseleaf services.
These extensions are useful with looseleaf services, because the dates of the content in these services varies depending on the page cited and the time at which the resource was referenced. These extensions permit a single item in the calling application’s database to represent the volume on the library shelf, the page date being optionally supplied by the user when citing into a document.
page
and page-first
¶
The page
and page-first
variables are numeric in CSL-m.
The validator requires that they be rendered with cs:number
.
<number variable="page"/>
publication-date
¶
CSL-m adds a publication-date
variable to the language schema.
It is available on the gazette
, legal_case
, legislation
, patent
and regulation
types, and provides the date on which the instrument
was published in the given reporter. On the patent
type, it represents
the date on which the patent was published for opposition (applicable only in certain
jurisdictions).
<date date-parts="year-month-day" form="text" variable="publication-date"/>
publication-number
¶
The publication-number
variable is available on the patent
type,
and provides the number assigned to a patent published for opposition.
It is a numeric variable, and validation requires that it be rendered
with cs:number
.
<number variable="publication-number"/>
supplement
¶
The supplement
variable and its associated locale term are useful
for secondary sources that are regularly updated between fresh
editions. Such fine-grained updates are found in secondary legal
publications. Although a supplement may be identified by number or by
name, supplement
is a numeric variable, and validation requires
that it be rendered with cs:number
.
<choose>
<if is-numeric="supplement">
<group delimiter=" ">
<label variable="supplement"/>
<number variable="supplement"/>
</group>
</if>
<else>
<number variable="supplement"/>
</else>
</choose>
volume-title
¶
The volume-title
variable is available on items of the book
and chapter
type. Use it to identify the name of a volume within a
larger work known by an umbrella title (which may in turn be a part of
a publisher’s series, described by collection-title
).
<text variable="volume-title"/>
alt-translator
¶
While any variable can be set with an alt-
prefix for rendering in
cs:alternative-text
, a few variables are recognized as
first-class
variable names that can be referenced directly
in the style, for testing purposes.
alt-container-title
¶
See alt-translator
above.
alt-issued
¶
See alt-translator
above.
Attributes¶
require-match
¶
The require-match
attribute is available on cs:names
elements.
When set to true
, it takes effect if and only if exactly two
variables are called by the element, and the current locale contains a
term (such as editortranslator
) that matches the sorted and
concatenated variable names. If those conditions are not satisfied,
the variables will be rendered according to the standard CSL
Specification. If the conditions are satisfied, the attribute has
the following effects:
- If the content of the name variables match exactly, the matching content will be rendered once, using the matching term as label. This is in accordance with the standard CSL Specification.
- Otherwise, the variables will not be rendered, and processing
will proceed to
cs:substitute
, and the two variables called oncs:names
remain available for rendering.
This can be useful where and editor and a translator, for example, should be rendered as a unit if they refer to the same person, but in separate parts of the citation if they differ.
exclude-types
¶
The exclude-types
option is available on the cs:bibliography
element. Use it to specify a list of item types that are to be
excluded from the bibliography.
exclude-with-fields
¶
The exclude-with-fields
option is available on the cs:bibliography
element. Use it to specify a list of fields to be excluded from the
bibliography if they contain a value.
default-locale-sort
¶
Use the default-locale-sort
attribute on the cs:style
node to specify
the language collation to govern sorting behaviour. The sort locale has no effect
on the language of standard terms and labels.
<style xmlns="http://purl.org/net/xbiblio/csl"
class="note" version="1.1mlz1"
default-locale="en-US"
default-locale-sort="zh-TW">
If this attribute is not set, the sort locale is aligned with the default locale of the style or processor instance.
form="imperial"
¶
CSL-m allows conversion of ordinary Gregorian dates to the Japanese form often used in legal citations and other government records. The conversion is only valid for dates after 1873. Prior dates on the traditional lunar calendar are not supported, and should be written as literal strings in the input.
<date variable="issued" form="imperial" date-parts="year-month-day"/>
form="short"
¶
In CSL 1.0.1, rendering the title
variable with the attribute
form="short"
produces the same result with any item type: if the
title-short
variable has a value, that it used; otherwise the
title
variable is rendered as a fallback.
In CSL-m, on the legal_case
type only, the form="short"
attribute does not attempt to render title-short
, but instead
renders the title
variable, transformed by the Abbreviation Filter
if an entry for it exists in the list there. This permits the
application of style-specific abbreviation rules, as required by
law-specific style guides such as The Bluebook: A Uniform System
of Citation.
<text variable="title" form="short"/>
is-parallel
¶
Set on a cs:group
node, the is-parallel
attribute includes
or suppresses the content of the group node depending on whether it
is rendered in a trailing parallel cite. Four values are recognised
on the attribute:
false
- Renders when the cite is not one of a series of parallel cites.
true
- Renders when the cite is one of several cites in a parallel series.
master
- Renders when the cite is one of several in a parallel series, and is the first cite in the series.
servant
- Renders when the cite is one of several in a parallel series, and is not the first in the series.
<group delimiter=" ">
<text font-style="italic" value="supra"/>
<text value="note"/>
<text variable="first-reference-note-number"/>
</group>
<group delimiter=" " is-parallel="false">
<text value="at"/>
<number variable="page-first"/>
</group>
<group delimiter=" " is-parallel="true">
<number variable="volume"/>
<text variable="container-title"/>
<number variable="page-first"/>
</group>
label-form
¶
The label-form
attribute can be used on cs:number
and on
cs:text
with the macro
attribute. It accepts the same arguments
as the form
attribute for localised terms: long
, verb
,
short
, verb-short
and symbol
. Its effect is to override
the form
attribute applicable to terms called via the parent cs:text
or cs:number
node. This can be useful where macros are copied
across styles that require different label forms.
<text macro="locator-mac" label-form="symbol"/>
leading-noise-words
¶
When set on a cs:style-options
node in a locale file or in a
style, the leading-noise-words
attribute takes a comma-delimited
list of words as its argument.
When a list is set, the same attribute on a cs:text
node with
variable="title"
takes an argument of demote
or drop
. With
the demote
attribute, noise words at the start of the field are
rendered after the remainder of the title field, delimited by a comma.
With the drop
attribute the leading noise words are simply
removed.
<style-options leading-noise-words="a,an,the"/>
and
<text variable="title" leading-noise-words="demote"/>
match="nand"
¶
With the nand
argument to the match
attribute, a node test is true
if at least one of the tests it invokes is false.
<choose>
<if variable="volume issue" match="nand">
<text macro="volume-issue-mac"/>
</if>
</choose>
name-as-reverse-order
¶
This is the counterpart of name-as-sort-order
, available on cs:style-options
only. Its operation is identical to its counterpart, but has the opposite effect
of forcing reverse-order rendering of all names bearing the specified language
tags. The name-as-sort-order
attribute is described immediately below.
name-as-sort-order
¶
A name-as-sort-order
attribute is available on the cs:style-options
locale element, taking a list of space-delimited country codes as its argument.
Country codes in the argument should be limited to a single element
(i.e. the language only, without a country or other specifier): other elements
will be ignored.
When the first element of the field language (either explictly set, or
defaulting to the item language
field value, if any) matches one of
the specified locales, the name is forced to “sort order”, regardless of its
character set.
<style-options name-as-sort-order="kr ja zh"/>
The example above will force names tagged as Korean, Japanese, and Chinese to sort order (i.e. family name first). This attribute does not interfere with short-form rendering or abbreviation (see the next heading below for that setting).
name-never-short
¶
The name-never-short
attribute on the cs:style-options
locale
element takes a list of space-delimited country codes as its
argument. Country codes in the argument should be limited to a single
element (i.e. the language only, without a country or other
specifier): other elements will be ignored.
When the first element of the field language (either explictly set, or
defaulting to the item language
field value, if any) matches one of
the specified locales, the effect of form="short"
is suppressed
when rendering the name concerned.
<style-options name-never-short="hu kr ja my vi zh"/>
The example above suppresses form="short"
on names tagged as
Hungarian, Korean, Japanese, Myanmar, Vietnamese, or Chinese.
prefix
and suffix
¶
Ordinary affixes in CSL-m are subject to a restriction: a prefix
attribute may not begin with a space, and a suffix
attribute may
not end with a space. Affixes on cs:label
within a cs:names
element, and affixes within the scope of a cs:date
element are
not subject to this constraint.
The purpose of this requirement is to assure that styles are incapable
of rendering cites with stray punctuation or multiple spaces. Where
spaces are required between elements, they should be applied using
a delimiter
attribute value on a cs:group
element.
<group delimiter=", ">
<number variable="volume"/>
<text variable="container-title"/>
</group>
skip-words
¶
The processor carries a list of prepositions and other terms that
will not be capitalised when rendering a field with text-case="title"
.
Within a locale, the skip-words
attribute on cs:style-options
can be used to replace this list of terms with another. The attribute
value should be a comma-delimited list of words or phrases.
<style-options skip-words="a,an,the,or,and,over,under"/>
subgroup-delimiter
, subgroup-delimiter-precedes-last
, and
¶
The subgroup-delimiter
attribute is a field-parsing hack coded
into the citeproc-js
processor, enabled when the processor is run
in CSL-m mode. In a group containing only cs:text
elements rendering
the publisher
and publisher-place
variables, the processor will
split the content of both fields on a semicolon. If the length of the
resulting list objects is equal, each publisher
/publisher-place
pair will be joined with the delimiter
string set on the enclosing
cs:group
element. The composed pairs are then joined using the
subgroup-delimiter
value.
The subgroup-delimiter-precedes-last
attribute controls the use of
the delimiter between the last and the penultimate pair in the same
manner as delimiter-precedes-last
on a cs:name
element. The
and
attribute with an argument of text
or symbol
may be
used on the cs:group
element to join the final item with the
specified term.
<group delimiter=" " subgroup-delimiter=", "
subgroup-delimiter-precedes-last="always">
<text variable="publisher"/>
<text variable="publisher-place"/>
</group>
or
<group delimiter=" " subgroup-delimiter=", "
subgroup-delimiter-precedes-last="never"
and="symbol">
<text variable="publisher"/>
<text variable="publisher-place"/>
</group>
suppress-min
¶
In the MLZ extended schema, names can be suppressed in two ways.
First, using suppress-min
and suppress-max
with values of
1
or above, names rendered via a cs:name
element can be
suppressed entirely when the number of individual names is at or below
a minimum, or at or above a maximum.
Second, with a value of 0
, suppress-min
can be used
on a cs:name
or cs:institution
element to suppress
only names of that type. See the description of suppress-min
below for an example of how that works and why it might sometimes
be useful.
An example of suppress-min
with a value of 4
:
<locale xml:lang="en">
<terms>
<term name="and others"></term>
</terms>
</locale>
<macro name="first-position-author">
<names variable="author">
<name et-al-min="2" et-al-use-first="1"
suppress-min="4"
name-as-sort-order="first"/>
<et-al term="and others"/>
</names>
</macro>
<macro name="second-position-author">
<names variable="author">
<name et-al-min="4" et-al-use-first="1" delimiter=", "/>
</names>
</macro>
<citation>
<layout>
<group delimiter=" / ">
<group delimiter=" ">
<text macro="first-position-author"/>
<text variable="title"/>
</group>
<text macro="second-position-author"/>
</group>
</layout>
</citation>
In the above example, an item with two authors will render as follows:
Stamou, A.I. Title of the Article / A.I. Stamou, I. Katsiris
An item with four authors, however, will render as follows:
Title of the Article / A.I. Stamou et al.
suppress-min
with a value of 0
¶
When set to zero, the suppress-min
attribute is specific to the
cs:name
or cs:institution
node only (for clarity, the
attribute with this value should always be set directly on the
affected node, rather than relying on inheritance). The effect of the
setting is to suppress all institution or all personal names, leaving
a list of the remaining names in place. This can be useful where
personal and institutional authors must be listed in separate places
in a citation—one example of such formatting being Rule
21.7.3 of the Bluebook 18th ed. (applicable to U.N. reports) which
provides the following guidance and example:
If a personal author is given along with the institutional author, the author [sic] should be included in a parenthetical at the end of the citation.
U.N. Econ. & Soc. Council [ECOSOC], Sub-Comm. on Prevention of Discrimination & Prot. of Minorities, Working Group on Minorities, Working Paper: Universal and Regional Mechanisms for Minority Protection, ¶ 17, U.N. Doc. E/CN.4/Sub.2/AC.5/1999/WP.6 (May 5, 1999) (prepared by Vladimir Kartashkin).
suppress-max
¶
<macro name="authors">
<group delimiter=" ">
<names variable="author">
<name name-as-sort-order="all"
et-al-min="11" et-al-use-first="3"
and="text"/>
</names>
<group delimiter=" " prefix="(" suffix=")">
<names variable="author">
<name suppress-max="10" form="count"/>
</names>
<text value="co-authors"/>
</group>
</group>
</macro>
<citation>
<layout>
<text macro="authors"/>
</layout>
</citation>
In this example, an item with four authors would render as follows:
Doe, J, Roe, J, Noakes, R, and Snoakes, H
An item with eleven authors, on the other hand, would render like this:
Doe, J, Roe, J, Noakes, R, et al. (11 co-authors)
text-case
¶
CSL-m adds a normal
argument to the possible values of
text-case
. This is mainly useful when rendering a cs:number
element in the scope of an element that applies a text-case
transform, to prevent text content in the rendered variable from being
affected by the transform.
(The need for this attribute value is open to question.)
<number variable="number" text-case="normal"/>
year-range-format
¶
CSL-m offers a year-range-format
attribute on cs:style
, as a
complement to page-range-format
. It takes the same arguments:
expanded
, minimal
, minimal-two
, and chicago
. When
used, this attribute specifies a collapsing format for year ranges
separate from that applied to page ranges.
<style xmlns="http://purl.org/net/xbiblio/csl" class="note" default-locale="en-GB"
page-range-format="chicago" year-range-format="expanded"
version="1.1mlz1">
Conditions¶
context
¶
The context
test attribute takes exactly one of the arguments
bibliography
, citation
, or alternative
. It does exactly
what its name and value suggest, returning true when the condition is
executed in the relevant context. This test is useful where complex
logic is needed to compose a particular element, which changes only
slightly depending on context.
<choose>
<if context="citation">
<text variable="title" font-variant="small-caps"/>
</if>
<else>
<text variable="title" font-variant="small-caps" form="short"/>
</else>
</choose>
genre
¶
The genre
test attribute takes one of five arguments: email
,
instant-message
, podcast
, radio-broadcast
, or
television-broadcast
. These correspond to strings automatically
inserted into the genre
variable by MLZ (where no value is set
manually by the user) on the Email, Instant Message, Podcast,
Radio Broadcast and Television Broadcast types respectively.
This is obviously a hack, and mimicks the effect of having five separate types for these items in CSL, as opposed to two (i.e. personal_communication and broadcast).
<choose>
<if genre="podcast">
<text macro="podcast-mac"/>
</if>
</choose>
has-day
¶
The has-day
condition attribute tests whether the date variable given
as argument has a value that includes a day.
<choose>
<if has-day="issued">
<date variable="issued">
<date-part name="month" form="text"/>
<date-part name="day" form="numeric" prefix=" "/>
</date>
</if>
</choose>
has-to-month-or-season
¶
The has-to-month-or-season
condition attribute tests whether the date
variable given as argument has a month or season (and no day).
<choose>
<if has-to-month-or-season="issued">
<date variable="issued">
<date-part name="month"/>
</date>
</if>
</choose>
has-year-only
¶
The has-year-only
condition attribute test whether the date
variable given as argument has only a year (and no day, month or season).
<choose>
<if has-year-only="issued">
<date variable="issued"
date-parts="year" form="text"
prefix="[" suffix="]"/>
</if>
</choose>
jurisdiction
¶
When citing primary legal resources, the form of citation is often
fixed, for ease of reference, by the issuing
jurisdiction— “jurisdiction” referring in this case to
international rule-making bodies as well as national governments.
CSL 1.0.1 provides a jurisdiction
variable, but it cannot be used
because Zotero does not currently have a corresponding field.
The particular requirement for this variable is that it be tested in a
cs:if
and cs:else-if
condition, so that citations can be
varied according to the issuing jurisdiction. Testing of field content
is contrary to the design of CSL, so the approach of the MLZ extended
CSL schema is strictly circumscribed to address this particular need,
without opening a door to uncontrolled general testing of field
content.
The solution is in two parts, described below.
Jurisdiction constraint list¶
The CSL schema has been extended in accordance with the proposed URN:LEX standard for a uniform resource namespace for sources of law. This standard provides a concept of “jurisdiction” that suits the requirements of legal citation, including both national jurisdictions and international rule-making bodies. Following URN:LEX, the schema has been extended with an explicit list of the national jurisdictions of the world, plus selected rule-making international organizations designated by their permanent domain name. The former are drawn from ISO 3166 Alpha-2. The latter do not yet have official sanction, as URN:LEX is still at the proposal stage, but the list in the schema extension is conservative, including only a few of the most stable (and widely cited) organizations.
Controlled list¶
The list of acceptable jurisdictions codes is coupled with an
extension of the cs:if
and cs:else-if
elements, providing a
jurisdiction
test attribute. In styles, the value set on the
attribute must be present in the list of acceptable jurisdiction
values. A style that uses other values is invalid.
When the jurisdiction
test attribute is used, its value is
compared with the value of the jurisdiction
variable on the item
being processed. If the values match, the test returns true, otherwise
false. Matching is done at the granularity of the argument provided
in the test.
<choose>
<if jurisdiction="us">
<text macro="us-mac"/>
</if>
</choose>
The test above will be true for items with a jurisdiction
value of
jp
or de
, and false for values of us
, us;federal;oh
or us;ny
.
locale
¶
In CSL-m, alternative cs:layout
nodes can be set by giving each
a separate locale
attribute. See the description of cs:layout (extension)
above for further details.
page
¶
In CSL-m, the page
variable can be tested in the same way as
locator
. The test evaluates the label value, if any, set at the
start of the field using a recognized locator abbreviation. See
Locator Terms below for a list of recognised abbreviations and
their corresponding CSL-m label values.
<choose>
<if page="page" match="none">
<label form="symbol" variable="page"/>
</if>
</choose>
The cs:label
element in this example will render the localised term
for the label set in the page
field (e.g. “para. 3
” will render
in English as “¶ 3”).
subjurisdictions
¶
The CSL-m jurisdiction
variable contains a juridiction specifier
divided into subfields, with a colon as the subfield delimiter.
The subjurisdictions
test attribute takes an integer as
argument. It returns true if the jurisdiction
field on the item
contains a value with at least the specified number of
subjurisdictions.
<choose>
<if subjurisdictions="2">
<text variable="jurisdiction" form="short"/>
</if>
</choose>
The example above will render the value of the jurisdiction
field,
“abbreviated” according the any mapping set for the style in the
Abbreviation Filter. In the example, a value of us
or us;ca
will return false, while a value of us;federal;ny
will return
true.
Terms¶
unpublished
¶
The unpublished
localised term is available for use
by CSL-m styles.
<text term="unpublished"/>
Locator Terms¶
Label | Abbreviation | Label | Abbreviation |
---|---|---|---|
article |
art. |
paragraph |
para. |
book |
bk. |
subparagraph |
subpara. |
chapter |
ch. |
part |
pt. |
subchapter |
subch. |
rule |
r. |
column |
col. |
section |
sec. |
figure |
fig. |
subsection |
subsec. |
folio |
fol. |
sub-verbo |
sv. |
line |
l. |
schedule |
sch. |
note |
n. |
title |
tit. |
issue |
no. |
verse |
vrs. |
opus |
op. |
volume |
vol. |
page |
p. or pp. |
In addition to the extended terms (article
, rule
, and
title
), CSL-m styles automatically set the special alternative
terms Chapter
and Section
when rendering the corresponding
terms in the context of the first item in a parallel reference.