@hackage citeproc-hs0.3.2

% citeproc-hs - A Haskell Implementation of the Citation Style Language % Andrea Rossato

About

citeproc-hs is a Haskell implementation of the Citation Style Language (CSL).

citeproc-hs adds to pandoc, the famous Haskell text processing tool, a Bibtex like citation and bibliographic formatting and generation facility.

CSL is an XML language for specifying citation and bibliographic formatting, similar in principle to BibTeX .bst files or the binary style files in commercial products like Endnote or Reference Manager.

CSL is used by Zotero for bibliographic style formatting, and the huge number of CSL styles developed by the Zotero community can can be downloaded from here:

http://www.zotero.org/styles

There are plans to use CSL for adding bibliographic support to future releases of OpenOffice.

citeproc-hs can process and format citations according to a CSL style, given a collection of references.

Natively citeproc-hs can read [JSON]¹ and [MODS]² XML formattted bibliographic databases.

bibutils can be used to convert Bibtex and other bibliographic databases to MODS collections, which can be thus read by citeproc-hs.

bibutils also exports a library and this library can be used by citeproc-hs for reading the most widely used bibliographic databases. This requires the installation of hs-bibutils, the Haskell bindings to bibutils.

citeproc-hs is a library that exports functions to parse CSL styles and MODS collections, to process lists of citation groups and to format the processed output. The output is a Haskell data type that can be further processed for conversion to any kind of formats (at the present time plain ASCII and the pandoc native format)

Download

citeproc-hs can be downloaded from Hackage:

http://hackage.haskell.org/package/citeproc-hs

To get the darcs source run:

    darcs get http://code.haskell.org/citeproc-hs/

NOTE: http://code.haskell.org is presently down. The darcs repository may be accessed at: http://gorgias.mine.nu/repos/citeproc-hs/

Installation

citeproc-hs depends on a few Haskell packages. Most of them come with the Haskell Platform and are usually included in every Haskell tool-chain.

In order to install citeproc-hs you need to install its dependencies. You can choose to manually download and install everything from Hackage:

http://hackage.haskell.org/cgi-bin/hackage-scripts/package/hxt

Every package downloaded form Hackage can be installed with these simple commands:

    runhaskell Setup.lhs configure
    runhaskell Setup.lhs build
    runhaskell Setup.lhs install

This last step requires root privileges.

If you don't have root privileges you can install citeproc-hs and all its dependencies locally with these commands:

    runhaskell Setup.lhs configure --user --prefix=$HOME
    runhaskell Setup.lhs build
    runhaskell Setup.lhs install --user

Alternatively you can use cabal-install to install citeproc-hs and all the needed dependencies:

    cabal update
    cabal install citeproc-hs

Installing without bibutils or network support

bibutils and network support may be suppressed with cabal flags:

    runhaskell Setup.lhs configure -f'-bibutils'

or

    runhaskell Setup.lhs configure -f'-bibutils -network'

and then build and install with:

    runhaskell Setup.lhs build
    runhaskell Setup.lhs install

It is possible to pass the flags also too cabal-install.

Using citeproc-hs with Pandoc

Future releases of pandoc will depend on citeproc-hs and no specific step will be required to activate citeproc support.

Please refer to pandoc's documentation for more information on inserting citations in pandoc's documents.

Documentation

Haddock documentation for the exported API is available on Hackage:

http://hackage.haskell.org/package/citeproc-hs

Some notes about name parsing

The MODS parser has been optimized for bibtex input, especially for parsing names with affixes , dropping and non-dropping particles.

Suffixes should come after the family name:

    Brown, Jr., John W.

If a comma is needed before the suffix, an exclamation mark may be used:

    Brown,! Jr., John W.

Non-dropping particles are placed before the family name:

    von Hicks,! Jr., Michael

Dropping particles are placed after the given name:

    la Martine,! III, Martin B. de

See also the CSL specification:

http://citationstyles.org/downloads/specification.html#name-particles

Running the test-suite

To run the test suite, you first need to grab it with mercurial by running, from the root directory of the citeproc-hs source tree:

    hg clone https://bitbucket.org/bdarcus/citeproc-test

You then need to grind human-readable test code into machine-readable form by running, in the citeproc-test directory, the following commands:

    cd citeproc-test
    ./processor.py -g
    cd ..

Then, from the root directory of citeproc-hs source tree, run:

    runhaskell test/test.hs

You may also specify a test group:

    runhaskell test/test.hs date

To increase the debug messages edit test/test.hs and increase the Int parameter of runTS:

    runTS args 1 testDir

Known Issues

citeproc-hs is in an early stage of development and the CSL implementation is not complete.

Most of CSL-1.0 features are implemented. Some missing features are meaningless in pandoc, the main target of citeproc-hs at the present time. Specifically the display attribute has not been implemented yet.

The citeproc-hs-0.3.2 release passes 411 out of 537 tests of the citeproc-test suite. The test-suite has been developed along with citeproc-js, and the failure of some of those tests is not meaningful for citeproc-hs. The major missing bits are related to multi-language names.

The MODS parser needs some refinement too.

Bug Reports

To submit bug reports you can use the Google code bug tracking system available at the following address:

http://code.google.com/p/citeproc-hs/issues

Credits

Bruce D'Arcus, the man behind CSL, Rintze Zelle, one of the main CSL developer, and Frank Bennett, the citeproc-js author, have been very kind and provided ideas, comments and suggestions that made it easier coding citeproc-hs.

John MacFarlane, the author of pandoc, has been very supportive of the project and provided a lot of useful feed back, comments and suggestions.

Author

Andrea Rossato

andrea.rossato at unitn.it

Links to Related Projects

CSL : http://xbiblio.sourceforge.net/csl/

citeproc-js : https://bitbucket.org/fbennett/citeproc-js/wiki/Home

citeproc-test : http://bitbucket.org/bdarcus/citeproc-test

Zotero : http://www.zotero.org

Pandoc : http://johnmacfarlane.net/pandoc/

Bibutils : http://www.scripps.edu/~cdputnam/software/bibutils/

MODS : http://www.loc.gov/mods/

Legal

This software is released under a BSD-style license. See LICENSE for more details.

This is an early, "alpha" release. It carries no warranties of any kind.

Copyright © 2008--2011 Andrea Rossato

1

The JSON format is basically documented by citeproc implementations and is derived by the CSL scheme. More information can be read in the citeproc-js documentation:

http://gsl-nagoya-u.net/http/pub/citeproc-doc.html#data-input

2

The Metadata Object Description Schema (MODS) is an XML format which is used by bibutils to interconvert many different bibliographic database formats, like Bibtex, Endnote, and others.