Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/Juris-M/citeproc-js

A JavaScript implementation of the Citation Style Language (CSL) https://citeproc-js.readthedocs.io
https://github.com/Juris-M/citeproc-js

Last synced: 3 months ago
JSON representation

A JavaScript implementation of the Citation Style Language (CSL) https://citeproc-js.readthedocs.io

Awesome Lists containing this project

README 

        
=============

`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>