-----------------------------------------------------------------------------
-- |
-- Module : Text.CSL
-- Copyright : (c) Andrea Rossato
-- License : BSD-style (see LICENSE)
--
-- Maintainer : Andrea Rossato <andrea.rossato@unitn.it>
-- Stability : unstable
-- Portability : unportable
--
-- /citeproc-hs/ is a library for automatically formatting
-- 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: <http://xbiblio.sourceforge.net/>.
--
-- This module documents and exports the library API.
--
-----------------------------------------------------------------------------
module Text.CSL
( -- * Introduction
-- $intro
-- * Overview: A Simple Example
-- $overview
-- * Reading Bibliographic Databases
readBiblioFile
, readModsFile
, readModsColletionFile
-- ** Reference Representation
, Reference (..)
, getReference
-- * CSL Parser, Representation, and Processing
, readCSLFile
-- ** The Style Types
, Style (..)
, Citation (..)
, Bibliography (..)
-- ** High Level Processing
, citeproc
, processCitations
, processBibliography
, BiblioData (..)
-- * The output and the rendering functions
, FormattedOutput (..)
, renderPlain
, renderPlainStrict
, renderPandoc
, renderPandoc'
, renderPandocStrict
) where
import Text.CSL.Parser
import Text.CSL.Proc
import Text.CSL.Reference
import Text.CSL.Style
import Text.CSL.Input.Bibutils
import Text.CSL.Input.MODS
import Text.CSL.Output.Pandoc
import Text.CSL.Output.Plain
-- $intro
--
-- /citeproc-hs/ provides functions for reading bibliographic
-- databases, for reading and parsing CSL files and for generating
-- citations in an internal format, 'FormattedOutput', that can be
-- easily rendered into different final formats. At the present time
-- only 'Pandoc' and plain text rendering functions are provided by
-- the library.
--
-- The library also provides a wrapper around hs-bibutils, the Haskell
-- bindings to Chris Putnam's bibutils, a library that interconverts
-- between various bibliography formats using a common MODS-format XML
-- intermediate.
--
-- For more information about hs-bibutils see here:
-- <http://code.haskell.org/hs-bibutils/>.
--
-- /citeproc-hs/ can natively read MODS formatted bibliographic
-- databases.
-- $overview
--
-- The following example assumes you have properly installed
-- hs-bibutils. If not you can use bibutils to convert the following
-- bibtex bibliographic database into a MODS collection.
--
-- Suppose you have a small bibliographic database, like this one:
--
-- > @Book{Rossato2005,
-- > author="Andrea Rossato",
-- > title="My First Book",
-- > year="2005"
-- > }
-- >
-- > @Book{Rossato2006,
-- > author="Andrea Rossato",
-- > title="My Second Book",
-- > year="2006"
-- > }
-- >
-- > @Book{Caso2007,
-- > author="Roberto Caso",
-- > title="Roberto's Book",
-- > year="2007"
-- > }
--
-- Save it as @mybibdb.bib@.
--
-- Then you can grab one of the CSL style developed by the Zotero
-- community. Suppose this one:
--
-- <http://www.zotero.org/styles/apa>
--
-- saved locally as @apa.csl@.
--
-- This would be a simple program that formats a list of citations
-- according to that style:
--
-- > import Text.CSL
-- >
-- > main :: IO ()
-- > main = do
-- > m <- readBiblioFile "mybibdb.bib" "bibtex"
-- > s <- readCSLFile "apa.csl"
-- > let result = citeproc s m $ [[("Caso2007","p. 10"),("Rossato2005","p. 10"),("Rossato2006","p. 15")]]
-- > putStrLn . unlines . map (renderPlainStrict) . citations $ result
--
-- The result would be:
--
-- > (Caso, 2007, p. 10; Rossato, 2005, p. 10, 2006, p. 15)