Optional. A language tag compliant with RFC 5646. Defaults to en.
Styles that contain a default-locale attribute value
on the style node will ignore this option unless
the forceLang argument is set to a non-nil value.

forceLang

Optional. When set to a non-nil value, force the use of the
locale set in the lang argument, overriding
any language set in the default-locale attribute
on the style node.

The retrieveLocale() function fetches CSL locales needed at
runtime. The locale source is available for download from the CSL
locales repository. The function
takes a single RFC 5646 language tag as its sole argument, and returns
a locale object. The return may be a serialized XML string, an E4X
object, a DOM document, or a JSON or JavaScript representation of the
locale XML. If the requested locale is not available, the function
must return a value that tests false. The function must return a
value for the us locale.

The instantiated processor offers a few basic methods for handling
input and obtaining rendered output. A few terms will be used with
a specific meaning in the descriptions below.

item

An item is a single bundle of metadata for a source to be referenced.
See the CSL Specification
for details on the fields available on an item, and the CSL-JSON chapter of this manual
for the format of specific field types. Every item must have an id
and a type.

citation

A citation is a set of one or more items, optionally supplemented by
locator information, prefixes or suffixes supplied by the user.

registry

The processor maintains a stateful registry of details on each item
submitted for processing. Registry entries are maintained
automatically, and cover matters such as disambiguation parameters,
sort sequence, and the first reference in which an item occurs.

citable items

Citable items are those meant for inclusion only if used in one or
more citations.

uncited items

Uncited items are those meant for inclusion regardless of whether
they are used in a citation.

The updateItems() method accepts a single argument when invoked
as a public method, and refreshes the registry with a designated
set of citable items. Citable items not listed in the argument are removed from the
registry:

Like its corollary above, the updateUncitedItems() method the registry accepts a single
argument, but refreshes the registry with a designated set of uncited items.
Uncited items not listed in the argument are removed from the registry.

citeproc.updateUncitedItems(idList);

idList

Required. A JavaScript array of item id values,
which may be number or string:

Use previewCitationCluster() to generate accurately formatted
citations as they would appear at a given location within a document
managed using processCitationCluster(). The method accepts four
arguments, the first three of which are identical to those accepted
by processCitationCluster(). The fourth argument may be used to
control the output mode.

The optional format argument may be one of html, text or rtf.
If this argument is not provided, the default value set in the instantiated
processor is used.

The result is a string representation of the target citation, in the
specified format. Changes made to the registry (necessary for correct
disambiguation, sorting and other adjustments) are reversed after the
citation is generated, leaving the registry in its original state.

Use makeCitationCluster() to generate citations without the burden of
registry adjustments. The method accepts an array of cite-items as its
sole argument:

varresult=citeproc.makeCitationCluster(idList);

idList

An array of cite-items, as specified in the CSL-JSON section of
this manual. Note the additional cite-item options noted there.

While makeCitationCluster() is faster than its companions, note that
it does not perform the citation sort, if any, that might be required by the
style, and that it does not perform disambiguation or apply style rules to
adjust the cites as appropriate to the context. This method is primarily
useful for writing simplified test fixtures. It should not be relied on
in production.

The makeBibliography() method returns a single bibliography object based on
the current state of the processor registry. It accepts on optional argument.

varresult=citeproc.makeBibliography(filter);

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, with registered items “Item-1” and “Item-2”).

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

A boolean value indicating whether hanging indent should be applied.

second-field-align

When the second-field-align CSL option is set, this returns
either “flush” or “margin”. The calling application should
align text in bibliography output as described in the CSL specification.
Where second-field-align is not set, this return value is set to false.

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.

Errors and warnings are issued by the functions CSL.error and CSL.debug
respectively, both of which take a single string as argument. The former
throws an error. The latter reports the string to console.log if available,
otherwise dump is used. The functions can be redefined to use any reporting
mechanism you like. For example:

In ordinary operation, the processor generates citation strings
suitable for a given position in the document, in accordance with the
CSL Specification. The
processor is also capable of rendering citation content in three special
forms:

author-only

Render only the author of the item, or where a title is substituted
in lieu of an author, the title, without citation affixes or styling.

suppress-author

Render the citation omitting the author, or where the title was
substituted in lieu of an author, the title.

composite

Render the author-only form, optionally followed by a user-supplied
infix, followed by the suppress-author form.

These effects are achieved by setting “citation flags” on processor
input items. For styles that do not produce satisfactory results for
the author-only form by default (such as numeric or “trigraph”
styles), an optional cs:intext element can be added to the style
as a sibling to cs:citation and cs:bibliography. (Note that
the cs:intext element is outside the official CSL Specification.)

The citation flags are applied differently in the two methods of running the
processor (makeCitationCluster and processCitationCluster). As the
former is used primarily for testing purposes, it is explained only briefly
below, followed by a more complete explanation of citation flags with
the processCitationCluster method.

The processCitationCluster method provides full support for
citation flags. In addition to recognizing composite, this method
will ignore citations set with the author-only flag for
back-referencing purposes (i.e. ibid and targeted references using
first-reference-note-number). The following input sample
exercises the flags in a series of four citations. Note the use
of the mode attribute on the properties segment of each
citation:

In a simple author-date style that italicizes author names, this
produces the following citation strings. Note that formatting is
stripped from the author-only and composite renderings of the
author name:

(<i>Kesey</i> 1964)
Kesey
(1964)
Kesey (1964)

When suppress-author or composite are set on a multiple
citation, collapsing is performed in the usual way. For example, in
our simple italicizing author-date style, a citation to Ken Kesey’s
novels One Flew Over the Cuckoo’s Nest and Sometimes a Great
Notion, followed by Ursula Le Guin’s Left Hand of Darkness will
render as follows if collapse="year" is set on the cs:citation
element:

Kesey (1962, 1964; <i>Le Guin</i> 1969)

An infix attribute can be used to insert text between the two
halves of a composite citation, with input like the following:

[[{"citationID":"CITATION-1","citationItems":[{"id":"ITEM-1"},{"id":"ITEM-2"},{"id":"ITEM-3","prefix":"cf."}],"properties":{"mode":"composite","noteIndex":0,"infix":"'s early work"}},[],[]]]

In our simple style, this produces the following output:

Kesey’s early work (1962, 1964; cf. <i>Le Guin</i> 1969)

In the example above, space before the apostrophe is quashed
automatically: text without leading punctuation will attract
a leading space. Note also that affixes are recognized
within items.

To support styles that require discrete formatting of names written
into the document text, the processor recognizes a cs:intext
element as a sibling to cs:citation and cs:bibliography. The
following minimal style will render author names joined by & in citations,
and by and in the author-only or composite forms:

The style produces the output below when called against Fisher &
Ury’s classic negotiation text, Getting to Yes: Reaching Agreement
Without Giving In, with no citation flags, and with the composite
flag respectively:

(<i>Fisher</i>&#38;<i>Ury</i> 1991)
Fisher and Ury (1991)

In some cases, the processor will be unable to produce content for an
author-only citation flag, or for the corresponding portion of a
composite citation. This may occur when no cs:intext is
provided, and the item begins with a bare cs:text or other
non-names element. This may be true for a legal item type, and is
always true of numeric and trigraph styles; and a cs:intext
element may itself fail to produce output for a particular item. By
default in such cases, the processor will output an ugly slug:

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.

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.