citeproc

=============
citeproc-js
=============
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A JavaScript implementation of the Citation Style Language
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

:Authors: Frank Bennett

.. image:: https://github.com/Juris-M/citeproc-js/actions/workflows/ci.yml/badge.svg
:target: https://github.com/Juris-M/citeproc-js/actions/workflows/ci.yml

-----
About
-----

The Citation Style Language_ (CSL) is
an XML grammar for expressing the detailed requirements of a citation
style. A CSL processor_ is a tool
that generates citations and bibliographies by applying CSL style rules
to bibliographic data.

The `citeproc-js CSL processor is over a decade in service, a fact
that shows through in ways both good and bad. On the downside, the
code base is not pretty, and can serve as a solid
illustration of the burden of technical debt (in case you need one of
those for your computer science class). On the upside, though,
citeproc-js passes a suite of over 1,300 integration tests with flying
colors. When run in CSL-M mode [1]_ it can handle multilingual and
legal content with a flexibility and precision unrivaled by any other
tool at any price. And it has been quite heavily field-tested, as the
citation formatter driving word processor integration in both
Mendeley_ and Zotero_.

More important than fleeting badges of popularity, though, is the CSL
standard. Developers can take comfort in the technical strength of the
CSL Specification_, and
the existence of other processors_ under active
development. CSL is the modern way to handle bibliographic projects,
and citeproc-js is a convenient way to take advantage of it.

----------------------
Submitting bug reports
----------------------

If you think you have found a processor bug, you can help track it
down by submitting a test item or items that expose the error. To
submit an item, join the public Jurism Test Submission group
,
sync, create a collection named for the style that shows the error,
drop the item into it, jot a description of the problem in the
Abstract field, and sync again.

For errors not associated with a particular style or item, file
reports on the citeproc-js GitHub tracker .

----------------------
Building the processor
----------------------

The processor files citeproc.js` and citeproc_commonjs.js are built
automatically when tests are run (see below).

-------------
Running Tests
-------------

The processor is supported by a little over 1,300 test fixtures, which
can be run from a git clone of this repository after installing the
Citeproc Test Runner_. The system requirements (apart from git itself) are:

git
Needed to fetch a clone of the citeproc-js repository on GitHub.
node.js
Any recent-ish version should work. Version 7 is used for automated testing.
mocha
Install Mocha globally with npm install --global mocha.
java
This is used to perform schema validation. Browser extension is not
required, a basic command-line install is all you need.

Once the system requirements are set up, install the test runner
with the following command::

npm install -g citeproc-test-runner

You can now run the full suite of integration tests from the citeproc-js directory
with the following command:

cslrun -a

You can review the full set of options by runningcslrun -h. For
more information on running tests, see the citeproc-js Manual_ or
the README of the Citeproc Test Runner_

------------------
Repository Content
------------------

The processor itself is contained in a single file. Two copies are in
the repository: citeproc_commonjs.js (an ES6 module); and
citeproc.js (a raw bundle of JavaScript). The former is
probably what you will want for most purposes today.

The following command will pull the sources of the processor and
supporting files::

git clone --recursive https://github.com/Juris-M/citeproc-js.git

Directories of the repository contain a number of tools used for
development and testing:

src
Processor source files. These are bundled into the two processor
copies by the test script cslrun, distributed separately in
the citeproc-test-runner package via npm (see below
for details).

csl-schemata
The RelaxNG schemata for CSL and CSL-M. These are used to
validate style code. The schemata are not used directly
by the processor at runtime.

demo
Contains a simple example of processor configuration in a Web
environment. Can be viewed by running a local webserver in the
directory.

docs
Source files for the citeproc-js manual on ReadTheDocs
_.

fixtures/local
Integration test fixtures specific to the citeproc-js processor or to
the CSL-M grammar variant.

fixtures/std
Standard CSL integration tests from the Citation Style Language_ repository.

fixtures/styles
Style-level tests. For more information, see the citeproc-js Manual_ or the README of
the Citeproc Test Runner_

juris-modules
Jurisdiction modules. These are used to CSL-M mode to render legal
citations in country-specific forms.

locale
The standard locale files _ from the CSL project.

tools
An assortment of scripts that are used, or have been used at some point,
in the maintenance of citeproc-js.

---------------------------

.. [1] CSL-M is set of private extensions to official CSL used by the
Jurism _ reference manager, a
variant of Zotero. For more information, see the citeproc-js Manual`_

---------------------------

| 2019.03.27
| FB

.. _csl processor: https://citationstyles.org/developers/#csl-processors
.. _mendeley: https://www.mendeley.com
.. _zotero: https://www.zotero.org
.. _csl specification: http://docs.citationstyles.org/en/1.0.1/specification.html
.. _other processors: https://citationstyles.org/developers/#csl-processors
.. _citeproc-js Manual: https://citeproc-js.readthedocs.io/en/latest/
.. _citation style language: https://github.com/citation-style-language/test-suite

.. _citeproc test runner: https://github.com/juris-m/citeproc-test-runner>