% 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: There are plans to use CSL for adding bibliographic support to future releases of [OpenOffice](http://bibliographic.openoffice.org/). [citeproc-hs] can process and format citations according to a [CSL] style, given a collection of references. Natively [citeproc-hs] can read [JSON][^1] and [MODS][^2] XML formatted 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]: To get the darcs source run: darcs get 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]: 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]: ### 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: ### Date parsing The [MODS] parser, which is used to read all bibliograhic databases supported by [bibutils], tries to parse dates, including seasons (expressed in English). An example of supported formats: 2010-01-31 (January 31, 2010) 2004-05 (May, 2004) 2001 (the year only) Summer, 2001 (the season) ### 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 or a single test in a group: runhaskell test/test.hs date IgnoreNonexistentSort To increase the debug messages edit *test/test.hs* and increase the *Int* parameter of *runTS*: runTS args 1 testDir Known Issues ------------ The [CSL] implementation is mostly but not entirely complete. Some of the 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.5 release passes 504 out of 693 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 [MODS] parser may need some refinement. Bug Reports ----------- To submit bug reports you can use the Google code bug tracking system available at the following address: 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 : citeproc-js : citeproc-test : Zotero : Pandoc : Bibutils : 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--2012 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: [^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. [citeproc-hs]: http://code.haskell.org/citeproc-hs [citeproc-js]: https://bitbucket.org/fbennett/citeproc-js/wiki/Home [CSL]: http://citationstyles.org/ [pandoc]: http://johnmacfarlane.net/pandoc/ [Zotero]: http://www.zotero.org [JSON]: http://www.json.org/ [MODS]: http://www.loc.gov/mods/ [bibutils]: http://www.scripps.edu/~cdputnam/software/bibutils/ [hs-bibutils]: http://code.haskell.org/hs-bibutils/ [Haskell Platform]: http://hackage.haskell.org/platform/ [Hackage]: http://hackage.haskell.org/cgi-bin/hackage-scripts/package/citeproc-hs [cabal-install]: http://hackage.haskell.org/trac/hackage/wiki/CabalInstall [Bruce D'Arcus]: http://community.muohio.edu/blogs/darcusb/ [John MacFarlane]: http://johnmacfarlane.net/ [Haddock]: http://www.haskell.org/haddock/ [display]: http://citationstyles.org/downloads/specification.html#display [citeproc-test]: http://bitbucket.org/bdarcus/citeproc-test/ [Frank Bennett]: http://gsl-nagoya-u.net/faculty/cache/gsliF_Bennett.html [mercurial]: http://mercurial.selenic.com/ [Haskell]: http://www.haskell.org