Selective output

The makeBibliography() command accepts one optional argument, which is a nested Javascript object that may contain one of the objects select, include or exclude, and optionally an additional quash object. Each of these four objects is an array containing one or more objects with field and value attributes, each with a simple string value (see the examples below). The matching behavior for each of the four object types, with accompanying input examples, is as follows:

select

For each item in the bibliography, try every match object in the array against the item, and include the item if, and only if, all of the objects match.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

var myarg = {
   "select" : [
      {
         "field" : "type",
         "value" : "book"
      },
      {  "field" : "categories",
          "value" : "1990s"
      }
   ]
}

var mybib = cp.makeBibliography(myarg);

include

Try every match object in the array against the item, and include the item if any of the objects match.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

var myarg = {
   "include" : [
      {
         "field" : "type",
         "value" : "book"
      }
   ]
}

var mybib = cp.makeBibliography(myarg);

exclude

Include the item if none of the objects match.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

var myarg = {
   "exclude" : [
      {
         "field" : "type",
         "value" : "legal_case"
      },
      {
         "field" : "type",
         "value" : "legislation"
      }
   ]
}

var mybib = cp.makeBibliography(myarg);

quash

Regardless of the result from select, include or exclude, skip the item if all of the objects match.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

var myarg = {
   "include" : [
      {
         "field" : "categories",
         "value" : "classical"
      }
   ],
   "quash" : [
      {
         "field" : "type",
         "value" : "manuscript"
      },
      {
         "field" : "issued",
         "value" : ""
      }
   ]
}

var mybib = cp.makeBibliography(myarg);

Return value

The value returned by this command is a two-element list, composed of a Javascript array containing certain formatting parameters, and a list of strings representing bibliography entries. It is the responsibility of the calling application to compose the list into a finish string for insertion into the document. The first element —- the array of formatting parameters —- contains the key/value pairs shown below (the values shown are the processor defaults in the HTML output mode):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

[
   {
      "maxoffset": 0,
      "entryspacing": 1,
      "linespacing": 1,
      "hangingindent": 0,
      "bibstart": "<div class=\"csl-bib-body\">\n",
      "bibend": "</div>"
   },
   [
      "<div class=\"csl-entry\">Book A</div>",
      "<div class=\"csl-entry\">Book C</div>"
   ]
]

maxoffset

Some citation styles apply a label (either a number or an alphanumeric code) to each bibliography entry, and use this label to cite bibliography items in the main text. In the bibliography, the labels may either be hung in the margin, or they may be set flush to the margin, with the citations indented by a uniform amount to the right. In the latter case, the amount of indentation needed depends on the maximum width of any label. The maxoffset value gives the maximum number of characters that appear in any label used in the bibliography. The client that controls the final rendering of the bibliography string should use this value to calculate and apply a suitable indentation length.

entryspacing

An integer representing the spacing between entries in the bibliography.

linespacing

An integer representing the spacing between the lines within each bibliography entry.

hangingindent

The number of em-spaces to apply in hanging indents within the bibliography.

bibstart

A string to be appended to the front of the finished bibliography string.

bibend

A string to be appended to the end of the finished bibliography string.

appendCitationCluster()

The appendCitationCluster() command takes a single citation object as argument, and an optional flag to indicate whether a full list of bibliography items has already been registered in the processor with the updateItems() command. If the flag is true, the command should return an array containing exactly one two-element array, consisting of the current index position as the first element, and a string for insertion into the document as the second. To wit:

1
2
3
4
5

citeproc.appendCitationCluster(mycitation,true);

[
   [ 5, "(J. Doe 2000)" ]
]

If the flag is false, invocations of the command may return multiple elements in the list, when the processor sense that the additional bibliography items added by the citation require changes to other citations to achieve disambiguation. In this case, a typical return value might look like this:

1
2
3
4
5
6

citeproc.appendCitationCluster(mycitation);

[
   [ 2, "(Jake Doe 2000)" ],
   [ 5, "(John Doe 2000)" ]
]

processCitationCluster()

The processCitationCluster() command is used to generate and maintain citations dynamically in the text of a document. It takes three arguments: a citation object, a list of citation ID/note index pairs representing existing citations that precede the target citation, and a similar list of pairs for citations coming after the target. Like the appendCitationCluster() command run without a flag, its return array may contain multiple elements, where the edit or addition of a citation triggers changes to other citations:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

var citationsPre = [ ["citation-abc",1], ["citation-def",2] ];

var citationsPost = [ ["citation-ghi",4] ];

citeproc.processCitationCluster(citation,citationsPre,citationsPost);

[
   [ 1,"(Ronald Snoakes 1950)" ],
   [ 3,"(Richard Snoakes 1950)" ]
]

A worked example showing the result of multiple transactions can be found in the processor test suite.

retrieveLocale()

The retrieveLocale() function is used internally by the processor to retrieve the serialized XML of a given locale. It takes a single RFC 4646 compliant language tag as argument, composed of a single language tag (en) or of a language tag and region subtag (en-US). The name of the XML document in the CSL distribution that contains the relevant locale data may be obtained from the CSL.localeRegistry array. The sample function below is provided for reference only.

1
2
3
4

sys.retrieveLocale = function(lang){
        var ret = DATA._locales[ CSL.localeRegistry[lang] ];
        return ret;
};

retrieveItem()

The retrieveItem() function is used by the processor to fetch individual items from storage.

1
2
3

sys.retrieveItem = function(id){
        return DATA._items[id];
};

getAbbreviations()

The getAbbreviations() command is invoked by the processor at startup, and when the setAbbreviations() command is invoked on the instantiated processor. The abbreviation list retrieved by the processor should have the following structure:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

ABBREVS = {
   "default": {
      "journal":{
         "Journal of Irreproducible Results":"J. Irrep. Res."
      },
      "series":{
         "International Rescue Wildlife Series":"I.R. Wildlife Series"
      },
      "authority":{
         "United States Patent and Trademark Office": "USPTO"
              },
      "institution":{
         "Bureau of Gaseous Unformed Stuff":"BoGUS"
      };
   };
};

If the object above provides the abbreviation store for the system, an appropriate sys.getAbbreviations() function might look like this:

1
2
3

sys.getAbbreviations = function(name){
   return ABBREVS[name];
};

Text and numeric variables

Text and numeric variables are not distinguished in the data layer; both should be presented as simple strings.

1
2
3

{  "title" : "My Anonymous Life",
   "volume" : "10"
}

Names

When present in the item data, CSL name variables must be delivered as a list of Javascript arrays, with one array for each name represented by the variable. Simple personal names are composed of family and given elements, containing respectively the family and given name of the individual.

1
2
3
4
5
6
7
8
9

{ "author" : [
    { "family" : "Doe", "given" : "Jonathan" },
    { "family" : "Roe", "given" : "Jane" }
  ],
  "editor" : [
    { "family" : "Saunders",
      "given" : "John Bertrand de Cusance Morant" }
  ]
}

Institutional and other names that should always be presented literally (such as "The Artist Formerly Known as Prince", "Banksy", or "Ramses IV") should be delivered as a single literal element in the name array:

1
2
3
4

{ "author" : [
    { "literal" : "Society for Putting Things on Top of Other Things" }
  ]
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

{ "author" : [
    { "family" : "Humboldt",
      "given" : "Alexander",
      "dropping-particle" : "von"
    },
    { "family" : "Gogh",
      "given" : "Vincent",
      "non-dropping-particle" : "van"
    },
    { "family" : "Stephens",
      "given" : "James",
      "suffix" : "Jr."
    },
    { "family" : "van der Vlist",
      "given" : "Eric"
    }
  ]
}

1
2
3
4
5
6

{ "author" : [
    { "family" : "村上",
      "given" : "春樹"
    }
  ]
}

1
2
3
4
5
6
7

{ "author" : [
    { "family" : "Murakami",
      "given" : "Haruki",
      "static-ordering" : 1
    }
  ]
}

Dates

Date fields are Javascript objects, within which the "date-parts" element is a nested Javascript array containing a start date and optional end date, each of which consists of a year, an optional month and an optional day, in that order if present.

1
2
3
4
5
6

{  "issued" : {
      "date-parts" : [
         [ "2000", "1", "15" ]
      ]
   }
}

Date elements may be expressed either as numeric strings or as numbers.

1
2
3
4
5
6

{  "issued" : {
      "date-parts" : [
         [ 1895, 11 ]
      ]
   }
}

The year element may be negative, but never zero.

1
2
3
4
5
6

{  "issued" : {
      "date-parts" : [
         [ -200 ]
      ]
   }
}

A season element may also be included. If present, string or number values between 1 and 4 will be interpreted to correspond to Spring, Summer, Fall, and Winter, respectively.

1
2
3
4
5
6
7

{  "issued" : {
      "date-parts" : [
         [ 1950 ]
      ],
      "season" : "1"
   }
}

Other string values are permitted in the season element, but note that these will appear in the output as literal strings, without localization:

1
2
3
4
5
6
7

{  "issued" : {
      "date-parts" : [
         [ 1975 ]
      ],
      "season" : "Trinity"
   }
}

For approximate dates, a circa element should be included, with a non-nil value:

1
2
3
4
5
6
7

{  "issued" : {
      "date-parts" : [
         [ -225 ]
      ],
      "circa" : 1
   }
}

To input a date range, add an array representing the end date, with corresponding elements:

1
2
3
4
5
6
7

{  "issued" : {
      "date-parts" : [
         [ 2000, 11 ],
         [ 2000, 12 ]
      ]
   }
}

To specify an open-ended range, pass nil values for the end elements:

1
2
3
4
5
6
7

{  "issued" : {
      "date-parts" : [
         [ 2008, 11 ],
         [ 0, 0 ]
      ]
   }
}

A literal string may be passed through as a literal element:

1
2
3
4

{  "issued" : {
      "literal" : "13th century"
   }
}

Names

Systems that use a simple two-field entry format can encode non-dropping-particle and dropping-particle elements on a name by including them in the family or given fields, respectively, setting the parse-names flag on the name object to indicate that the processor should perform particle extraction on these fields:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{ "author" : [
    { "family" : "Humboldt",
       "given" : "Alexander von",
       "parse-names" : true
    },
    { "family" : "van Gogh",
      "given" : "Vincent",
      "parse-names" : true
    }
  ]
}

The extraction of "non-dropping" particles is done by scanning the family field for leading terms that contain no uppercase letters. The extraction of "dropping" particles is done by scanning the given field for trailing terms that contain no uppercase letters.

For some names, leading lowercase terms in the family field should be treated as part of the name itself, and not as particles. The parse-names flag should not be set on such names:

1
2
3
4
5
6

{ "author" : [
    { "family" : "van der Vlist",
       "given" : "Eric"
    }
  ]
}

Dates

The citeproc-js processor contains its own internal parsing code for raw date strings. Clients may take advantage of the processor's internal parser by supplying date strings as a single raw element:

1
2
3
4

{  "issued" : {
      "raw" : "25 Dec 2004"
   }
}

Note that the parsing of raw date strings is not part of the CSL 1.0 standard. Clients that need to interoperate with other CSL processors should be capable of preparing input in the form described above under Data Input → Dates.

author-only

When the makeCitationCluster() command (not documented here) is invoked with a non-nil author-only element, everything but the author name in a cite is suppressed. The name is returned without decorative markup (italics, superscript, and so forth).

1
2
3

var my_ids = {
  ["ID-1", {"author-only": 1}]
}

You might think that printing the author of a cited work, without printing the cite itself, is a useless thing to do. And if that were the end of the story, you would be right ...

suppress-author

To suppress the rendering of names in a cite, include a suppress-author element with a non-nil value in the supplementary data:

1
2
3

var my_ids = [
    ["ID-1", { "locator": "21", "suppress-author": 1 }]
]

This option is useful on its own. It can also be used in combination with the author-only element, as described below.

Automating text insertions

Calls to the makeCitationCluster() command with the author-only and to processCitationCluster() or appendCitationCluster() with the suppress-author control elements can be used to produce cites that divide their content into two parts. This permits the support of styles such as the Chinese national standard style GB7714-87, which requires formatting like the following:

The Discovery of Wetness

While it has long been known that rocks are dry ^[1] and that air is moist ^[2] it has been suggested by Source [3] that water is wet.

Bibliography

[1] John Noakes, The Dryness of Rocks (1952).

[2] Richard Snoakes, The Moistness of Air (1967).

[3] Jane Roe, The Wetness of Water (2000).

In an author-date style, the same passage should be rendered more or less as follows:

The Discovery of Wetness

While it has long been known that rocks are dry (Noakes 1952) and that air is moist (Snoakes 1967) it has been suggested by Roe (2000) that water is wet.

Bibliography

John Noakes, The Dryness of Rocks (1952).

Richard Snoakes, The Moistness of Air (1967).

Jane Roe, The Wetness of Water (2000).

In both of the example passages above, the cites to Noakes and Snoakes can be obtained with ordinary calls to citation processing commands. The cite to Roe must be obtained in two parts: the first with a call controlled by the author-only element; and the second with a call controlled by the suppress-author element, in that order:

1
2
3
4
5

var my_ids = {
  ["ID-3", {"author-only": 1}]
}

var result = citeproc.makeCitationCluster( my_ids );

... and then ...

1
2
3
4
5
6

var citation = {
  "citationItems": ["ID-3", {"suppress-author": 1}],
  "properties": { "noteIndex": 5 }
}

var result = citeproc.processCitationCluster( citation );

In the first call, the processor will automatically suppress decorations (superscripting). Also in the first call, if a numeric style is used, the processor will provide a localized label in lieu of the author name, and include the numeric source identifier, free of decorations. In the second call, if a numeric style is used, the processor will suppress output, since the numeric identifier was included in the return to the first call.

Detailed illustrations of the interaction of these two control elements are in the processor test fixtures in the "discretionary" category:

• AuthorOnly
• CitationNumberAuthorOnlyThenSuppressAuthor
• CitationNumberSuppressAuthor
• SuppressAuthorSolo

The default-locale declaration

The style tag in a CSL style may contain a default-locale attribute.

Hint

When the default-locale attribute is omitted, the default language is set to en-US.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

<style
    xmlns="http://purl.org/net/xbiblio/csl"
    class="in-text"
    version="1.0"
    default-locale="de">
  <info>
    <id />
    <title />
    <updated>2009-08-10T04:49:00+09:00</updated>
  </info>
  <citation>
    <layout>
      <names variable="author">
        <name />
      </names>
    </layout>
  </citation>
</style>

For multi-lingual operation, a style may be set to request alternative versions and translations of the title field, and of the author and other name fields, using an extension to the default-locale attribute. Extensions consist of an extension tag, followed by a language setting that conforms to RFC 4646 (typically constructed from components listed in the IANA Language Subtag Registry). Recognized extension tags are as follows:

-x-pri-

Sets a preferred language or translitertion for the title field.

-x-sec-

Sets an optional secondary translation for the title field. If this tag is present, a translation in the target language will (if available) be placed in square braces immediately after the title text.

-x-sort-

Sets the preferred language or transliteration to be used for both the title field and for names.

-x-name-

Sets the preferred language or transliteration for names.

The tags are applied to a style by appending them to the language string in the default-locale element:

1
2
3
4
5

<style
    xmlns="http://purl.org/net/xbiblio/csl"
    class="in-text"
    version="1.0"
    default-locale="en-US-x-pri-ja-Hrkt">

Multiple tags may be specified, and tags are cumulative, and for readability, individual tags may be separated by newlines within the attribute. The following will attempt to render titles in either Pinyin transliteration (for Chinese titles) or Hepburn romanization (for Japanese titles), sorting by the transliteration.

1
2
3
4
5
6
7
8
9

<style
    xmlns="http://purl.org/net/xbiblio/csl"
    class="in-text"
    version="1.0"
    default-locale="en-US
        -x-pri-zh-Latn-pinyin
        -x-pri-ja-Latn-hepburn
        -x-sort-zh-Latn-pinyin
        -x-sort-ja-Latn-hepburn">

Multi-lingual operation depends upon the presence of alternative representations of field content embedded in the item data. When alternative field content is not availaable, the "real" field content is used as a fallback. As a result, configuration of language and script selection parameters will have no effect when only a single language is available (as will normally be the case for an ordinary Zotero data store).

Title

For titles, alternative representations are appended directly to the field content, separated by the appropriate language tag with a leading and trailing colon:

1
2

{ "title" : "民法 :ja-Latn-hepburn-heploc: Minpō :en: Civil Code"
}

Names

For personal names, alternative representations should be presented as separate "name" entries, immediately following the original for the name element to which they apply. For example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

{ "author" : [
    { "family" : "穂積",
      "given" : "陳重"
    },
    { "family" : ":ja-Latn: Hozumi",
      "given" : "Nobushige"
    },
    { "family" : "中川",
      "given" : "善之助"
    },
    { "family" : ":ja-Latn: Nakagawa",
      "given" : "Zennosuke"
    }
  ]
}

Required sections

The following four sections (MODE, CSL, INPUT, RESULT) are required in all test fixtures.

1
2
3

>>===== MODE =====>>
citation
<<===== MODE =====<<

 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

>>===== CSL =====>>
<style
      xmlns="http://purl.org/net/xbiblio/csl"
      class="in-text"
      version="1.0">
  <info>
    <id />
    <title />
    <updated>2009-08-10T04:49:00+09:00</updated>
  </info>
  <citation
    et-al-min="3"
    et-al-use-first="1">
    <layout delimiter="; ">
      <group delimiter=" ">
        <names>
          <name form="short"/>
        </names>
        <date
            variable="issued"
            date-parts="year"
            form="text"
            prefix="("
            suffix=")"/>
      </group>
    </layout>
  </citation>
  <bibliography>
    <layout>
      <group delimiter=" ">
        <names variable="author">
          <name delimiter=" " initialize-with="."/>
        </names>
        <date
            variable="issued"
            date-parts="year"
            form="text"
            prefix="("
            suffix=")"/>
      </group>
    </layout>
  </bibliography>
</style>
<<===== CSL =====<<

 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

>>===== INPUT =====>>
[
 {
   "id":"ID-1",
   "author": [
        { "name":"Noakes, John" },
        { "name":"Doe, John" },
        { "name":"Roe, Jane" }
   ],
   "issued": {
      "date-parts": [
         [
            2005
         ]
      ]
   }
 },
 {
   "id":"ID-2",
   "author": [
        { "name":"Stoakes, Richard" }
   ],
   "issued": {
      "date-parts": [
         [
            1898
         ]
      ]
   }
 }
]
<<===== INPUT =====<<

1
2
3

>>===== RESULT =====>>
(Noakes, et al. 2005; Stoakes 1898)
<<===== RESULT =====<<

1
2
3
4
5
6

>>===== RESULT =====>>
<div class="csl-bib-body">
  <div class="csl-entry">J. Noakes, J. Doe, J. Roe (2005)</div>
  <div class="csl-entry">R. Stoakes (1898)</div>
</div>
<<===== RESULT =====<<

Optional sections

Four optional sections are available for use in a fixture to exercise special aspects of processor behavior.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

>>===== BIBENTRIES =====>>
[
  [
    "ITEM-1",
    "ITEM-2",
    "ITEM-3",
    "ITEM-4",
    "ITEM-5"
  ],
  [
    "ITEM-1",
    "ITEM-4",
    "ITEM-5"
  ]
]
<<===== BIBENTRIES =====<<

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

>>===== BIBSECTION =====>>
{
   "include" : [
      {
         "field" : "categories",
         "value" : "classical"
      }
   ],
   "quash" : [
      {
         "field" : "type",
         "value" : "manuscript"
      },
      {
         "field" : "issued",
         "value" : ""
      }
   ]
}
<<===== BIBSECTION =====<<

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

>>===== CITATION-ITEMS =====>>
[
  [
    {"id": "ITEM-1"}
  ],
  [
    {"id": "ITEM-2", "label": "page", "locator": "23"},
    {"id":"ITEM-3"}
  ]
]
<<===== CITATION-ITEMS =====<<

 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

>>===== CITATIONS =====>>
[
   [
      {
         "citationID": "CITATION-1",
         "citationItems": [
            {
               "id": "ITEM-1"
            }
         ],
         "properties": {
            "noteIndex": 1
         }
      },
      [],
      []
   ],
   [
      {
         "citationID": "CITATION-2",
         "citationItems": [
            {
               "id": "ITEM-2",
               "locator": 15
            },
            {
               "id": "ITEM-3"
            }
         ],
         "properties": {
            "noteIndex": 1
         }
      }
   ],
   ["CITATION-1"],
   []
]
<<===== CITATIONS =====<<