-----------------------------------------------------------------------------
-- |
-- 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://citationstyles.org/>.
--
-- This module documents and exports the library API.
--
-----------------------------------------------------------------------------
module Text.CSL
( -- * Introduction
-- $intro
-- * Overview: A Simple Example
-- $overview
-- * Reading Bibliographic Databases
readBiblioFile
, BibFormat (..)
, readBiblioString
-- ** Reference Representation
, Reference (..)
, getReference
, setNearNote
-- * CSL Parser, Representation, and Processing
, readCSLFile
, parseCSL
, parseCSL'
, localizeCSL
-- ** The Style Types
, Style (..)
, Citation (..)
, Bibliography (..)
, Cite (..)
, Abbreviations (..)
, emptyCite
-- ** High Level Processing
, ProcOpts (..)
, procOpts
, BibOpts (..)
, citeproc
, processCitations
, processBibliography
, BiblioData (..)
-- * The output and the rendering functions
, renderPlain
, renderPandoc
, renderPandoc'
) where
import Text.CSL.Proc
import Text.CSL.Reference
import Text.CSL.Style
import Text.CSL.Parser
import Text.CSL.Input.Bibutils
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, 'Formatted', 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://hackage.haskell.org/package/hs-bibutils>.
--
-- /citeproc-hs/ can natively read MODS and JSON formatted
-- bibliographic databases. The JSON format is only partially
-- documented. It is used by citeproc-js, by the CSL processor
-- test-suite and is derived by the CSL scheme. More information can
-- be read here:
-- <http://citationstyles.org/>.
--
-- A (git) repository of styles can be found here:
-- <https://github.com/citation-style-language/styles>.
-- $overview
--
-- The following example assumes you have installed citeproc-hs with
-- hs-bibutils support (which is the default).
--
-- Suppose you have a small bibliographic database, like this one:
--
-- > @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 styles that come with the
-- test-suite for CSL processors. Suppose this one:
--
-- <https://bitbucket.org/bdarcus/citeproc-test/raw/18141149d1d3/styles/apa-x.csl>
--
-- saved locally as @apa-x.csl@.
--
-- This would be a simple program that formats a list of citations
-- according to that style:
--
-- > import Text.CSL
-- >
-- > cites :: [Cite]
-- > cites = [emptyCite { citeId = "Caso2007"
-- > , citeLabel = "page"
-- > , citeLocator = "15"}
-- > ,emptyCite { citeId = "Rossato2006"
-- > , citeLabel = "page"
-- > , citeLocator = "10"}
-- > ]
-- >
-- > main :: IO ()
-- > main = do
-- > m <- readBiblioFile "mybibdb.bib"
-- > s <- readCSLFile Nothing "apa-x.csl"
-- > let result = citeproc procOpts s m $ [cites]
-- > putStrLn . unlines . map renderPlain . citations $ result
--
-- The result would be:
--
-- > (Caso, 2007, p. 15; Rossato, 2006, p. 10)