version 1.00##a114##
=D=26 September 2015=D=
Table of Contents
This is the site administrator's manual for citeproc-js, a
JavaScript implementation of the Citation Style Language
(CSL) [1] The processor complies with version 1.0.1 of the CSL
specification, has been written and tested as an independent module,
and can be run by any ECMAscript-compliant interpreter. It has
deployed in browser plugins, desktop applications, and in server-side
configurations.
This manual covers the processor command set, the expected format of input data, and placeholder functions to be supplied by the calling application. [2] In addition, notes are provided on the test suite, on the infrastructure requirements for running the processor in particular environments, and on extended functionality that is available to address certain special requirements.
Comments regarding the processor and this document should be filed on
the project issue tracker.
[1] | The repository is currently housed at zotero.org. Note that styles in the Zotero styles repository are currently at CSL version 0.8.1. Use the tools provided by the CSL project to convert CSL 0.8.1 styles to the version 1.0 syntax supported by this processor. |
[2] | For further details on required infrastructure, see the sections Locally defined system functions and Data Input below. |
The processor is written in JavaScript, which lacks a standard I/O
method, and so must be wrapped in code for that purpose. If you get
stuck and want advice, or if you find something in this manual that is
out of date or just wrong, please feel free to post to the
tracker.
The citeproc-js sources are hosted on BitBucket.
To obtain the sources, install the
Mercurial version control system
on a computer within your control (if you're on a Linux distro or a Mac,
just do a package install), and run the following command:
hg clone http://bitbucket.org/fbennett/citeproc-js/
This should get you a copy of the sources, and you should be able to exercise the test framework using the ./test.py script.
To run the test suite, the standard test fixtures must be added to the processor source bundle. To do so, enter the directory ./tests/fixtures, and issue the following command:
hg clone http://bitbucket.org/bdarcus/citeproc-test std
Note the explicit target directory "std" following the repository address.
The processor requires a set of standard CSL 1.0 locale files in order to run. These may be installed using the following command (under Linux command line). From the root of the citeproc-js source directory:
git clone git://github.com/citation-style-language/locales.git locale
The processor will run in any modern ECMAscript (JavaScript) interpreter.
To parse the XML files used to define locales and styles, the processor relies on supplementary code, which must be loaded into the same JavaScript context as the processor itself. The xmldom.js and xmljson.js files shipped with the processor source serve that purpose. The xmldom.js file is suitable for browser environments or system that provide DOM support. Use the xmljson.js code in environments (such as node.js or a Firefox worker thread) where native DOM is not available. The XML code of CSL locales and styles can be converted to JSON on the fly using csl-json-walker (JavaScript code that relies on DOM access) or by using makejson.py (a Python script) for external pre-processing.
For an example of working code, the source behind the
processor demo page may be useful as a reference.
Instructions on running the processor test suite can be found in the section Running the test suite at the end of this manual.
The primary source code of the processor is in the ./src subdirectory. Files for use in a runtime environment are catenated, in the appropriate sequence, in the citeproc.js file, located in the root of the source archive. This file and the test fixtures can be refreshed using the ./test.py -r command.
To build the processor, the citeproc.js source code should be loaded into the JavaScript interpreter context, together with a sys object provided by the integrator (see below), and the desired CSL style (as a string).
The processor recognizes styles that validate under two separate schemata, distinguished by the version attribute on the cs:style node. Styles with version="1.0" (or version="1.0.1") are assumed to be valid under the CSL Specification, and by default the processor will adopt internal settings that produce compliant output.
Styles with version="1.1mlz1" are assumed to be valid under the Juris-M Schema described in the Juris-M (CSL-m) Specification Supplement. With this version setting, internal settings of the processor will be adapted automatically to comply with the expectations of Juris-M.
The instantiated processor has several readable flags that can be used by the calling application to shape the user interface to the processor. These include the following: [3]
True if the style is one that sorts citations in any way.
True if citations are sorted by citation
[3] | Note that these are information variables intended for reading only; changing their value directly will have no effect on the actual behavior of the processor. |
Instances of the processor are produced using CSL.Engine() function. Note that, as detailed below under Locally defined system functions, certain local data access functions must be defined separately on an object supplied to the processor as its first argument.
The instantiated processor provides a small set of runtime configuration methods. Instance methods are also used to load item data into the processor, and to produce output objects suitable for consumption by a word processor plugin, or for constructing bibliographies. Details of these and other methods available on processor instances are given below.
The CSL.Engine() command is invoked as shown below. The command takes up to four arguments (two are required, two optional):
Important
See the section Locally defined system functions below for guidance on the definition of the functions contained in the sys object.
1 2 3 4 | var citeproc = new CSL.Engine(sys,
style,
lang,
forceLang)
|
The version of the processor itself can be obtained from the attribute processor_version. The supported CSL version can be obtained from csl_version.
Two functions must be supplied to the processor upon instantiation on the sys object. These functions are used by the processor to obtain locale and item data from the environment. Their exact definition may vary.
The retrieveLocale() function is used internally to retrieve the serialized XML (or JavaScript object, if xmljson.js is used) 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).
1 2 3 | sys.retrieveLocale = function(lang){
return DATA._locales[lang];
};
|
The retrieveItem() function is used by the processor to fetch individual items from storage. The function must be synchronous with the processor.
1 2 3 | sys.retrieveItem = function(id){
return DATA._items[id];
};
|
The default output format of the processor is HTML. Output formats for
RTF and plain text are defined in the distribution source file
./src/formats.js. Additional formats can be added if desired.
See the file itself for details; it's pretty
straightforward.
The output format of the processor can be changed to any of the defined formats after instantiation, using the setOutputFormat() command:
1 | citeproc.setOutputFormat("rtf");
|
Rebuilds the processor from scratch, based on a cached list of citation objects. In a dynamic application, once the internal state of processor is established, citations should edited with individual invocations of processCitationCluster().
Returns an array of [citationID,noteIndex,string] triples in document order, where string is the fully disambiguated citation cluster for the given document position.
1 | citeproc.rebuildProcessorState(citations, mode, uncitedItemIDs);
|
An array of citation input objects in document order. Each citation object must be in the following form, with correct values for citationID, for each id, and for noteIndex. Set noteIndex to 0 for in-text citations. Default is to return an empty document update array.
1 2 3 4 5 6 7 8 9 10 11 | {
"citationID": "CITATION-1",
"citationItems": [
{
"id": "ITEM-1"
}
],
"properties": {
"noteIndex": 1
}
}
|
This function is deprecated. Use rebuildProcessorState() instead.
This function is used in Juris-M. Pending documentation here, please refer to the Juris-M source code for examples of its use.
This function is used in Juris-M. Pending documentation here, please refer to the Juris-M source code for examples of its use.
This function is used in Juris-M. Pending documentation here, please refer to the Juris-M source code for examples of its use.
This function is used in Juris-M. Pending documentation here, please refer to the Juris-M source code for examples of its use.
This function is used in Juris-M. Pending documentation here, please refer to the Juris-M source code for examples of its use.
The optional getAbbreviation() function returns short-forms and other transforms of field content. Its signature is as follows:
1 2 3 4 5 6 7 8 | citeproc.sys.getAbbreviation(
styleID,
cacheObject,
jurisdiction,
category,
key,
noHints
);
|
The abbreviation category of the field to be matched. Categories and their associated variables are as follows:
This function is used in Juris-M. Pending documentation here, please refer to the Juris-M source code for examples of its use.
This function is used in Juris-M. Pending documentation here, please refer to the Juris-M source code for examples of its use.
This function is used in Juris-M. Pending documentation here, please refer to the Juris-M source code for examples of its use.
This function is used in Juris-M. Pending documentation here, please refer to the Juris-M source code for examples of its use.
Before citations or a bibliography can be generated, an ordered list of reference items must ordinarily be loaded into the processor using the updateItems() command, as shown below. This command takes a list of item IDs as its sole argument, and will reconcile the internal state of the processor to the provided list of items, making any necessary insertions and deletions, and making any necessary adjustments to internal registers related to disambiguation and so forth.
Hint
The sequence in which items are listed in the argument to updateItems() will ordinarily be reflected in the ordering of bibliographies only if the style installed in the processor does not impose its own sort order.
1 2 3 4 5 6 7 | var my_ids = [
"ID-1",
"ID-53",
"ID-27"
]
citeproc.updateItems( my_ids );
|
To suppress sorting, give a second argument to the command with a value of true.
1 | citeproc.updateItems(my_ids, true);
|
Note that only IDs may be used to identify items. The ID is an arbitrary, system-dependent identifier, used by the locally customized retrieveItem() method to retrieve actual item data.
The updateUncitedItems() command has the same interface as updateItems() (including the option to suppress sorting by the style), but the reference items it adds are not subject to deletion when no longer referenced by a cite anywhere in the document.
The makeBibliography() command does what its name implies. If invoked without an argument, it dumps a formatted bibliography containing all items currently registered in the processor:
1 | var mybib = citeproc.makeBibliography();
|
Important
Matches against the content of name and date variables are not possible, but empty fields can be matched for all variable types. See the quash example below for details.
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 15 16 | [
{
maxoffset: 0,
entryspacing: 0,
linespacing: 0,
hangingindent: 0,
second-field-align: false,
bibstart: "<div class=\"csl-bib-body\">\n",
bibend: "</div>",
bibliography_errors: []
},
[
"<div class=\"csl-entry\">Book A</div>",
"<div class=\"csl-entry\">Book C</div>"
]
]
|
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:
Hint
The target field in the data items registered in the processor may either be a string or an array. In the latter case, an array containing a value identical to the relevant value is treated as a 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);
|
1 2 3 4 5 6 7 8 9 10 | var myarg = {
"include" : [
{
"field" : "type",
"value" : "book"
}
]
}
var mybib = cp.makeBibliography(myarg);
|
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);
|
Hint
An empty string given as the field value will match items for which that field is missing or has a nil value.
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);
|
The available citation commands are:
Citation commands generate strings for insertion into the text of a target document. Citations can be added to a document in one of two ways: as a batch process (BibTeX, for example, works in this way) or interactively (Endnote, Mendeley and Zotero work in this way, through a connection to the user's word processing software). These two modes of operation are supported in citeproc-js by two separate commands, respectively appendCitationCluster(), and processCitationCluster(). [4]
The appendCitationCluster() and processCitationCluster() commands use a similar input format for citation data, which is described below in the Data Input → Citation data object section below.
[4] | A third, simpler command (makeCitationCluster()), is not covered by this manual. It is primarily useful as a tool for testing the processor, as it lacks any facility for position evaluation, which is needed in production environments. |
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 value is an array of two elements: a data object, and an array of one or more index/string pairs, one for each citation affected by the citation edit or insertion operation. As shown below, the data object currently has a single boolean value, bibchange, which indicates whether the document bibliography is in need of refreshing as a result of the processCitationCluster() operation.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 | var citationsPre = [ ["citation-abc",1], ["citation-def",2] ];
var citationsPost = [ ["citation-ghi",4] ];
citeproc.processCitationCluster(citation,citationsPre,citationsPost);
...
[
{
"bibchange": true
},
[
[ 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.
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)" ]
]
|
The previewCitationCluster() command takes the same arguments as processCitationCluster(), plus a flag to indicate the output mode.
The return value is a string representing the citation as it would be rendered in the specified context. This command will preview citations exactly as they will appear in the document, and will have no effect on processor state: the next edit will return updates as if the preview command had not been run.
1 2 3 4 5 6 7 8 | var citationsPre = [ ["citation-abc",1], ["citation-def",2] ];
var citationsPost = [ ["citation-ghi",4] ];
citeproc.previewCitationCluster(citation,citationsPre,citationsPost,"html");
...
"(Richard Snoakes 1950)"
|
The processor might fail to produce meaningful rendered output in three situations:
The processor handles these three cases as described below.
When the makeBibliography() command is run on a style that has no bibliography node, the command returns a value of false.
When the return value of the makeBibliography() command contains entries that produce no output other than for the (automatically generated) citation-number variable, an error object with ID and position information on the offending entry, and a bitwise error code (always CSL.ERROR_NO_RENDERED_FORM, currently) is pushed to the bibliography_errors array in the data segment of the return object:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 | [
{
maxoffset: 0,
entryspacing: 0,
linespacing: 0,
hangingindent: 0,
second-field-align: false,
bibstart: "<div class=\"csl-bib-body\">\n",
bibend: "</div>",
bibliography_errors: [
{
index: 2,
itemID: "ITEM-2",
error_code: CSL.ERROR_NO_RENDERED_FORM
}
]
},
[
"[1] Snoakes, Big Book (2000)",
"[2] Doe, Bigger Book (2001)",
"[3] ",
"[4] Roe, Her Book (2002)"
]
]
|
The calling application may use the information in bibliography_errors to prompt the user concerning possible corrective action.
When a citation processing command produces no output for a citation, an error object with ID and position information on the offending cite, and a bitwise error code (always CSL.ERROR_NO_RENDERED_FORM, currently) is pushed to the citation_errors array in the data segment of the return object.
Note that previewCitationCluster() returns only a string value, with no data segment; citation errors are not available with this command.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 | [
{
bibchange: true,
citation_errors: [
{
citationID: "citationID_12345",
index: 4,
noteIndex: 3, // for example
itemID: "itemID_67890",
citationItem_pos: 0,
error_code: CSL.ERROR_NO_RENDERED_FORM
}
]
},
[
[ 1,"(Ronald Snoakes 1950)" ],
[ 4,"[CSL STYLE ERROR: reference with no printed form.]" ],
[ 5,"(Richard Snoakes 1950)" ]
]
]
|
The locally defined retrieveItem() function must return data for the target item as a simple JavaScript array containing recognized CSL fields. [5] The layout of the three field types is described below.
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"
}
|
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" }
]
}
|
Name particles, such as the "von" in "Werner von Braun", can be delivered separately from the family and given name, as dropping-particle and non-dropping-particle elements.
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"
}
]
}
|
Name suffixes such as the "Jr." in "Frank Bennett, Jr." and the "III" in "Horatio Ramses III" can be delivered as a suffix element.
Hint
A simplified format for delivering particles and name suffixes to the processor is described below in the section Dirty Tricks → Input data rescue → Names.
1 2 3 4 5 6 7 8 9 10 11 12 | { "author" : [
{ "family" : "Bennett",
"given" : "Frank G.",
"suffix" : "Jr.",
"comma-suffix": "true"
},
{ "family" : "Ramses",
"given" : "Horatio",
"suffix" : "III"
}
]
}
|
Note the use of the comma-suffix field in the example above. This hint must be included for suffixes that are preceded by a comma, which render differently from "ordinary" suffixes in the ordinary long form.
Names not written in the Latin or Cyrillic scripts [6] are always displayed with the family name first. No special hint is needed in the input data; the processor is sensitive to the character set used in the name elements, and will handle such names appropriately.
1 2 3 4 5 6 | { "author" : [
{ "family" : "村上",
"given" : "春樹"
}
]
}
|
Hint
When the romanized transliteration is selected from a multilingual name field, the static-ordering flag is not required. See the section Dirty Tricks → Multilingual content below for further details.
Sometimes it might be desired to handle a Latin or Cyrillic transliteration as if it were a fixed (non-Byzantine) name. This behavior can be prompted by including a static-ordering element in the name array. The actual value of the element is irrelevant, so long as it returns true when tested by the JavaScript interpreter.
1 2 3 4 5 6 7 | { "author" : [
{ "family" : "Murakami",
"given" : "Haruki",
"static-ordering" : 1
}
]
}
|
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.
Hint
A simplified format for providing date input
is described below in the section
Dirty Tricks → Input data rescue → Dates.
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"
}
}
|
A minimal citation data object, used as input by both the processCitationCluster() and appendCitationCluster() command, has the following form:
1 2 3 4 5 6 7 8 9 10 | {
"citationItems": [
{
"id": "ITEM-1"
}
],
"properties": {
"noteIndex": 1
}
}
|
The citationItems array is a list of one or more citation item objects, each containing an id used to retrieve the bibliographic details of the target resource. A citation item object may contain one or more additional optional values:
In the properties portion of a citation, the noteIndex value indicates the footnote number in which the citation is located within the document. Citations within the main text of the document have a noteIndex of zero.
The processor will add a number of data items to a citation during processing. Values added at the top level of the citation structure include:
Values added to individual citation item objects may include:
Citations are registered and accessed by the processor internally in arrays and JavaScript objects. Data that may be of use to calling applications can be accessed at the following locations (note that the content of these variables should not be modified directly; the processor will update them automatically when citation data is processed or updated via the API):
1 2 3 4 5 6 7 8 9 10 11 | citeproc.registry.citationreg.citationById // (object, returns object)
citeproc.registry.citationreg.citationsByItemId // (object, returns array)
citeproc.registry.citationreg.citationByIndex // (array of objects)
citeproc.registry.getSortedRegistryItems() // (returns an array of
// registry objects, with
// ``uncited`` set ``true``
// as appropriate, and
// item data on key ``ref``)
|
[5] | For information on valid CSL variable names, please refer to the CSL specification, available via http://citationstyles.org/. |
[6] | The Latin and Cyrillic scripts are referred to here collectively as "Byzantine scripts", after the confluence of cultures in the first millenium that spanned both. |
This section presents features of the citeproc-js processor that are not properly speaking a part of the CSL specification. The functionality described here may or may not be found in other CSL 1.0 compliant processors, when they arrive on the scene.
Where the calling application provides a user interface for adding and editing bibliographic items, a limited set of fields is typically provided for each if the item types recognized by the application. Fields that map to valid CSL variables needed for a particular type of reference may not be available.
If the calling application provides a mapping of the note variable to all types, the processor can parse missing fields out of this variable, for use in rendering citations. This facility is intended only for testing purposes. It provides a means of illustrating citation use cases, with a view to requesting an adjustment to the field lists or the user interface of the calling application. It should not be relied upon as a permanent workaround in production data; and it should never be used to add variables that are not in the CSL specification.
The syntax for adding supplementary fields via the note variable is as follows:
1 | {:authority:Superior Court of California}{:section:A}
|
Supplementary variables are read by the processor as flat strings, so names and date parsing will not work with them.
Systems that use a simple two-field entry format can encode non-dropping-particle, dropping-particle and suffix name sub-elements by including them in the family or given name fields as illustrated below.
By default, the processor will attempt to parse such names into their component parts. Parsing can be disabled by setting the parse_names processor configuration flag to false:
1 | citeproc.opt.development_extensions.parse_names = false;
|
A string at the beginning of the family field consisting of spaces and lowercase roman or Cyrillic characters will be treated as a non-dropping-particle (but see Particles as part of the last name below.
1 2 3 4 5 6 | { "author" : [
{ "family" : "van Gogh",
"given" : "Vincent"
}
]
}
|
A string at the end of the given name field consisting of spaces and lowercase roman or Cyrillic characters will be treated as a dropping-particle.
1 2 3 4 5 6 | { "author" : [
{ "family" : "Humboldt",
"given" : "Alexander von"
}
]
}
|
Content following the first comma in the given name field will be parsed out as a name suffix.
1 2 3 4 5 6 7 8 9 | { "author" : [
{ "family" : "King",
"given" : "Martin Luther, Jr."
},
{ "family" : "Gates",
"given" : "William Henry, III"
}
]
}
|
Modern typographical convention does not place a comma between suffixes such as "Jr." and the last name, when rendering the name in normal order: "John Doe Jr." If an individual prefers that the traditional comma be used in rendering their name, the comma can be forced by placing a exclamation mark after the initial comma that marks the beginning of the suffix:
1 2 3 4 5 6 | { "author" : [
{ "family" : "Bennett",
"given" : "Frank G.,! Jr."
}
]
}
|
As noted above, a comma in the given field marks the beginning of a suffix. Parsing of dropping particles is limited to the portion of the given field that precedes any comma:
1 2 3 4 5 6 | { "author" : [
{ "family" : "Moltke",
"given" : "Helmuth von, Sr."
}
]
}
|
The particles preceding some names should be treated as part of the last name, depending on the cultural heritage and personal preferences of the individual. To suppress parsing and treat such particles as part of the family name field, enclose the family name field content in double-quotes:
1 2 3 4 5 6 | { "author" : [
{ "family" : "\"van der Vlist\"",
"given" : "Eric"
}
]
}
|
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.
In ordinary operation, the processor generates citation strings suitable for a given position in the document. To support some use cases, the processor is capable of delivering special-purpose fragments of a citation.
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 ...
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.
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 7 8 | var citation, result;
citation = {
"citationItems": ["ID-3", {"suppress-author": 1}],
"properties": { "noteIndex": 5 }
}
[data, 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:
The version of citeproc-js described by this manual incorporates a mechanism for supporting cross-lingual and mixed-language citation styles, such as 我妻栄 [Wagatsuma Sakae], 債権各論 [Obligations in Detail] (1969). The scheme described below should be considered experimental for the present. The code is intended for deployment in the Zotero reference manager; when it is eventually accepted for deployment (possibly with further modifications), the implementation can be considered stable.
For multilingual operation, a style may be set to request alternative versions and translations of the title field, and of the author and other name fields. There are two methods of setting multilingual parameters: via default-locale (intended primarily for testing) and via API methods (intended for production use).
When set via default-locale, extensions consist of an extension tag, followed by
a language setting that conforms to RFC 5646 (typically constructed
from components listed in the
IANA Language Subtag Registry).
When set via an API method, the argument to the appropriate method should
be a list of RFC 5646 language tags.
Recognized extension tags for use with default-locale [and corresponding API methods] are as follows:
An example of default-locale configuration:
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. For readability in test fixtures, 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">
|
An example of API configuration:
1 | citeproc.setLangTagsForCslSort(["zh-alalc97", "ja-alalc97"]);
|
The processor offers three boolean API methods that are not available via default-locale:
Multilingual 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).
For titles and other ordinary string fields, alternative representations are placed in a separate multi segment on the item, keyed to the field name and the language tag (note the use of the _keys element on the multi object):
1 2 3 4 5 6 7 8 9 10 | { "title" : "民法",
"multi": {
"_keys": {
"title": {
"ja-alalc97": "Minpō",
"en":"Civil Code"
}
}
}
}
|
For names, alternative representations are set on a multi segment of the name object itself (note the use of the _key element on the multi object):
Hint
As described above, fixed ordering is used for non-Byzantine names. When such names are transliterated, the static-ordering element is set on them, to preserve their original formatting behavior.
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 | { "author" : [
{ "family" : "穂積",
"given" : "陳重",
"multi": {
"_key": {
"ja-alalc97": {
"family" : "Hozumi",
"given" : "Nobushige"
}
}
}
},
{ "family" : "中川",
"given" : "善之助"
"multi": {
"_key": {
"ja-alalc97": {
"family" : "Nakagawa",
"given" : "Zennosuke"
}
}
}
}
]
}
|
A parser that converts human-readable dates to a structured form is available as a self-contained module, under the name CSL.DateParser.
When used as a standalone module, the parser must be instantiated in the usual way before use:
1 | var parser = new CSL.DateParser;
|
The following methods are available on the parser object, to control parsing behavior and to parse string input.
Set the date value on the date object returned by the parse() method as a nested array under a date-parts key. For example, the date range 31 January 2000 to 28 February 2001 would look like this in array format:
1 2 3 4 5 6 | {
"date-parts": [
[2000, 1, 31],
[2001, 2, 28]
]
}
|
Set the date value on the date object returned by the parse() method as a set of name/value pairs. For example, the date range 31 January 2000 to 28 February 2001 would look like this in keys format:
1 2 3 4 5 6 7 8 | {
year: 2000,
month: 1,
day: 31,
year_end: 2001,
month_end: 2,
day_end: 28
}
|
Important
Note that the standard CSL test fixtures are not distributed with the processor, and must be added to the source tree separately.
Citeproc-js ships with a large bundle of test data and a set of scripts that can be used to confirm that the system performs correctly after installation. The tests begin as individual human-friendly fixtures written in a special format, shown in the sample file immediately below. Tests are prepared for use by grinding them into a machine-friendly form (JSON), and by preparing an appropriate JavaScript execution wrapper for each. These operations are performed automatically by the top-level test runner script that ships with the sources.
Tests are controlled by the ./test.py script in the root directory of the archive. To run all standard tests in the suite using the rhino interpreted shipped with the processor, use the following command:
./test.py -s
Options and arguments can be used to select an alternative JavaScript interpreter, or to change or limit the set of tests run. The script options are as follows:
For information on the layout of the test fixtures, see the CSL Test Suite manual.
When accessed using a JavaScript-enabled browser with E4X support
(such as Firefox), the ./demo/demo.html file in the source archive
(or
online) will invoke the processor to render a few citations. The JavaScript
files accompanying the page in the ./demo directory show the basic
steps required to load and run the processor, whether in the browser
or server-side.