% 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 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`
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 © 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/
