citeproc-hs: A Citation Style Language implementation in Haskell

[ bsd3, library, text ] [ Propose Tags ]

citeproc-hs is a library for rendering bibliographic reference citations into a variety of styles using a macro language called Citation Style Language (CSL). More details on CSL can be found here:

For the API documentation please see Text.CSL.

[Skip to Readme]


Automatic Flags

Choose the new smaller, split-up base package.


Use Chris Putnam's Bibutils.


Use network and HTTP to retrieve csl file from URIs.


Embed locale files into the library (needed for windows packaging)


Use -f <flag> to enable a flag, or -f -<flag> to disable that flag. More info


Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees


Versions [RSS] 0.1, 0.2, 0.3.0, 0.3.1, 0.3.2, 0.3.3, 0.3.4, 0.3.5, 0.3.6, 0.3.7, 0.3.8, 0.3.9, 0.3.10
Dependencies base (>=3), bytestring, containers, directory, file-embed, filepath, hs-bibutils (>=0.3), HTTP (>=4000.0.9), json, mtl, network (>=2), old-locale, pandoc-types (>=1.8 && <1.11), parsec, syb, template-haskell, time, utf8-string, xml [details]
License BSD-3-Clause
Author Andrea Rossato
Category Text
Home page
Bug tracker
Uploaded by AndreaRossato at 2012-09-28T16:43:28Z
Distributions FreeBSD:0.3.10
Reverse Dependencies 5 direct, 166 indirect [details]
Downloads 18525 total (42 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs uploaded by user
Build status unknown [no reports yet]

Readme for citeproc-hs-0.3.5

[back to package description]
% citeproc-hs - A Haskell Implementation of the Citation Style Language
% Andrea Rossato


[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](

[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

[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)


[citeproc-hs] can be downloaded from [Hackage]:


To get the darcs source run:

        darcs get


[citeproc-hs] depends on a few Haskell packages. Most of them come
with the [Haskell Platform] and are usually included in every Haskell

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'


        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.


[Haddock] documentation for the exported API is available on


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

        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

You then need to grind human-readable test code into machine-readable
form by running, in the citeproc-test directory, the following

        cd citeproc-test
        ./ -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:



[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


Andrea Rossato

`andrea.rossato at`

Links to Related Projects

:    <>

:    <>

:    <>

:    <>

:    <>

:    <>

:    <>


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

[Haskell Platform]:
[Bruce D'Arcus]:
[John MacFarlane]:
[Frank Bennett]: