@hackage citeproc-hs0.1

A Citation Style Language implementation in Haskell

  • Installation

  • Dependencies (0)

  • Dependents (0)

    • Package Flags

      small_base
       (on by default)

      Choose the new smaller, split-up base package.

      test
       (on by default)

      Run the textsuite.

% 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 MODS collection of references.

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 a future plan is to use that library for providing native support for the most widely used bibliographic databases in citeproc-hs.

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

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

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.lhs configure -f citeproc
    runhaskell Setup.lhs build
    runhaskell Setup.lhs 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 --mods flags:

pandoc --csl cslStyle.csl --mods modsCollection.xml 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 --mods modsCollection.xml test.markdown
pandoc --csl apa.csl --mods modsCollection.xml test_note.markdown

Documentation

No further documentation is so far available and even haddock generated documentation is at a very early stage.

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

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:

  • "collapse" (citation collapsing)
  • "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