============= `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 running``cslrun -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>