% 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](http://bibliographic.openoffice.org/). [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` Links to Related Projects ---------------- 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/> 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 &copy; 2008 Andrea Rossato [citeproc-hs]: http://code.haskell.org/cioteproc-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/ [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/ [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/