hs-bibutils: Haskell bindings to bibutils, the bibliography conversion utilities.

% Haskell Bindings to Bibutils, the Bibliography Conversion Utilities
% Andrea Rossato

About
-----

[hs-bibutils] is library with Haskell bindings to Chris Putnam's
[bibutils], a library that interconverts between various bibliography
formats using a common MODS-format XML intermediate.

[hs-bibutils] can be used with [citeproc-hs] and [pandoc] to read and
use various bibliographic database formats for processing and
automatically formatting citations andreferences according to a [CSL]
style.

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

Download
--------

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

<http://hackage.haskell.org/cgi-bin/hackage-scripts/package/hs-bibutils>

To get the darcs source run:

        darcs get http://code.haskell.org/hs-bibutils/

Installation
------------

[hs-bibutils] requires [bibutils] version 4.0 or higher. Moreover, it
requires the [bibutils] library to be installed on your system as a
share object. This is necessary if you want to use the library with
GHCi or [andoc].

At the present time, though, [bibutils] default compilation and
installation scripts only build a static library to be used for
building the various [bibutils]' binaries, the only ones being
installed.

In other words you need to either patch or download a patched version
of [bibutils] in order to build and install the library as a share
object.[^1]

### Obtaining a patched version of bibutils

You can download a patched version of [bibutils] here:

<http://code.haskell.org/hs-bibutils/bibutils-4.1-ar.tar.gz>

To install it run:

        tar xvfz bibutils-4.1-ar.tar.gz
        cd bibutils-4.1-ar
        ./configure
        make

And now install it with, as root:

        make installlib

### Patching bibutils

You can patch [bibutils] by yourself.

Download version 4.1 from here:

<http://www.scripps.edu/~cdputnam/software/bibutils/bibutils_4.1_src.tgz>

and apply the patch that comes with the [hs-bibutils] source code,
`bibutils.patch`.

        tar xvfz bibutils-4.1.tar.gz
        cd bibutils-4.1
        patch -p0 < bibutils.patch

Now you can configure and build:

        ./configure
        make

And now as root:

        make installlib

### Installing hs-bibutils

Now you need install [hs-bibutils]. After unpacking the source code
run:

        runhaskell Setup.lhs configure --extra-include-dirs=/path/to/bibutils_4.1/lib

Change `/path/to/bibutils_4.1/lib` to point to the `lib` sub-directory
of the [bibutils] source code.

`--extra-include-dirs=/path/to/bibutils_4.1/lib` will tell the
compiler where to find the library header files needed to compile the
bindings.

Now you can build and install:

        runhaskell Setup.lhs build
        runhaskell Setup.lhs install

This last step requires `root` privileges.

If you don't have `root` privileges you can install [hs-bibutils]
locally with these commands:

        runhaskell Setup.lhs configure --extra-include-dirs=/path/to/bibutils_4.1/lib --user --prefix=$HOME
        runhaskell Setup.lhs build
        runhaskell Setup.lhs install --user

Documentation
-------------

The [Haddock] generated documentation is available here:

<http://code.haskell.org/hs-bibutils/docs/>

The original API documentation is available here:

<http://www.scripps.edu/~cdputnam/software/bibutils/library_specs.html>

Bug Reports
-----------

To submit bug reports you can use the [citeproc-hs] bug tracking
system available at the following address:

<http://code.google.com/p/citeproc-hs/issues>

Credits
-------

Thanks to [Chris Putnam] for his help.

Author
------

Andrea Rossato

`andrea.rossato at unitn.it`

Links to Related Projects
----------------

Bibutils
:    <http://www.scripps.edu/~cdputnam/software/bibutils/>

Pandoc
:    <http://johnmacfarlane.net/pandoc/>

Citeproc-hs:
:    <http://code.haskell.org/citeproc-hs/>

CSL
:    <http://xbiblio.sourceforge.net/csl/>

Legal
-----

This software is released under a BSD-style license. See LICENSE for
more details.

Be aware, however, that bibutils itself is licensed under the GPL. If
you wish to use the hs-bibutils bindings, your project will need to be
GPL compatible.

This is an early, "alpha" release. It carries no warranties of any kind.

Copyright &copy; 2008 Andrea Rossato

[^1]: The library must be a shared object and must be installed in
order to build [pandoc] because [pandoc] uses the Template Haskell
extension to produce some source code at compilation time. This
extension requires running the GHCi interpreter which can only deal
with shared objects. If the library is a static object
(`libbibutils.a`) the compilation of [pandoc] or the use of the
library with GHCi will fail.

[hs-bibutils]: http://code.haskell.org/hs-bibutils
[bibutils]: http://www.scripps.edu/~cdputnam/software/bibutils/
[Hackage]: http://hackage.haskell.org/cgi-bin/hackage-scripts/package/hs-bibutils
[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/
[Bruce D'Arcus]: http://community.muohio.edu/blogs/darcusb/
[John MacFarlane]: http://johnmacfarlane.net/
[Chris Putnam]: http://www.scripps.edu/~cdputnam/
[Haskell]:  http://www.haskell.org/
[Haddock]:  http://www.haskell.org/haddock/