% 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 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]: 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]: 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: 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: 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: 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` Links to Related Projects ---------------- Pandoc : Bibutils : CSL : Zotero : 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 Andrea Rossato [citeproc-hs]: http://code.haskell.org/citeproc-hs [CSL]: http://xbiblio.sourceforge.net/csl/ [pandoc]: http://johnmacfarlane.net/pandoc/ [Zotero]: http://www.zotero.org [MODS]: http://www.loc.gov/mods/ [bibutils]: http://www.scripps.edu/~cdputnam/software/bibutils/ [hs-bibutils]: http://code.haskell.org/hs-bibutils/ [Hackage]: http://hackage.haskell.org/cgi-bin/hackage-scripts/package/citeproc-hs [hxt]: http://www.fh-wedel.de/~si/HXmlToolbox/ [Bruce D'Arcus]: http://community.muohio.edu/blogs/darcusb/ [John MacFarlane]: http://johnmacfarlane.net/ [Haddock]: http://www.haskell.org/haddock/ [markdown]: http://daringfireball.net/projects/markdown/ [reStructuredText]: http://docutils.sourceforge.net/docs/ref/rst/introduction.html [S5]: http://meyerweb.com/eric/tools/s5/ [HTML]: http://www.w3.org/TR/html40/ [LaTeX]: http://www.latex-project.org/ [ConTeXt]: http://www.pragma-ade.nl/ [RTF]: http://en.wikipedia.org/wiki/Rich_Text_Format [DocBook XML]: http://www.docbook.org/ [OpenDocument XML]: http://opendocument.xml.org/ [ODT]: http://en.wikipedia.org/wiki/OpenDocument [MediaWiki markup]: http://www.mediawiki.org/wiki/Help:Formatting [groff man]: http://developer.apple.com/DOCUMENTATION/Darwin/Reference/ManPages/man7/groff_man.7.html [Haskell]: http://www.haskell.org/ [GNU Texinfo]: http://www.gnu.org/software/texinfo/