@hackage citeproc-hs0.2

A Citation Style Language implementation in Haskell

% 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 only read MODS XML formattted bibliographic databases. 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.

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)

pandoc is a Haskell library for converting from one markup format to another, and a command-line tool that uses this library. It can read markdown and (subsets of) reStructuredText, HTML, and LaTeX; and it can write markdown, reStructuredText, HTML, LaTeX, ConTeXt, RTF, DocBook XML, OpenDocument XML, ODT, GNU Texinfo, MediaWiki markup, groff man pages, and S5 HTML slide shows.

Download

citeproc-hs can be downloaded from Hackage:

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

To get the darcs source run:

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

Installation

Installing without bibutils support

citeproc-hs depends on hxt, the Haskell XML Tool Box.

In order to install citeproc-hs you need to install hxt and its dependencies. You can download 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

Installing with bibutils support

Since bibutils doesn't build a shared object and doesn't install the library, which is a static object used to compile the single bibutils utilities, by default citeproc-hs is not built with bibutils support.

If you succeeded in installing bibutils and hs-bibutils, you can enable bibutils by configuring with the -fbibutils flag:

    runhaskell Setup.lhs configure -fbibutils

and then build and install with:

    runhaskell Setup.lhs build
    runhaskell Setup.lhs install

Using citeproc-hs with Pandoc

If you want to use citeproc-hs with pandoc you need to install citeproc-hs first, get the pandoc source code and compile it with the -f citeproc flag:

    runhaskell Setup.hs configure -f citeproc
    runhaskell Setup.hs build
    runhaskell Setup.hs install

Citations are inserted like simple reference links:

[Rossato2006]

where Rossato2006 is the reference id (or citation key) used in the bibliographic database.

Citation groups are also possible. Each citation is separated by a semicolon:

[Rossato2006; Pascuzzi2002]

The use of locators is also possible:

[Rossato2006@ p. 10; Pascuzzi2002@ cap. 12]

To automatically format citations and generate the bibliography, run pandoc with the --csl and --biblio flags:

pandoc --csl cslStyle.csl --biblio modsCollection.mods text.markdown > text.html

Obviously you can export the text into any of the formats supported by pandoc.

Some examples can be found in the test directory of the source tree.

You can try them with:

pandoc --csl apa.csl --biblio modsCollection.xml --biblio-format mods test.markdown
pandoc --csl apa.csl --biblio modsCollection.xml --biblio-format mods test_note.markdown

Documentation

Haddock documentation for the exported API is available at the following address:

http://code.haskell.org/citeproc-hs/docs/

Generating the Haddock documentation is troublesome with Cabal < 1.6.0.2 (GHC-6.10.1 comes with Cabal-1.6.0.1), because of this:

http://hackage.haskell.org/trac/hackage/ticket/396

Known Issues

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

Specifically the following options are not implemented:

  • "hanging-indent"
  • "second-field-align"
  • "line-spacing"
  • "entry-spacing"

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 author of CSL, has been very kind and patient with me when I was trying to understand the CSL schema, and provided me with ideas, comments and suggestions that made it possible to come to something usable.

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 ing.unitn.it

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

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

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

Zotero : http://www.zotero.org

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

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 Andrea Rossato