content: {-# LANGUAGE NoImplicitPrelude #-}
  -----------------------------------------------------------------------------
  -- |
  -- 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.Input.Bibutils
  import           Text.CSL.Output.Pandoc
  import           Text.CSL.Output.Plain
  import           Text.CSL.Parser
  import           Text.CSL.Proc
  import           Text.CSL.Reference
  import           Text.CSL.Style
  
  
  -- $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)
  