scholdoc-citeproc-0.6: Scholdoc fork of pandoc-citeproc

Copyright(c) Andrea Rossato
LicenseBSD-style (see LICENSE)
MaintainerAndrea Rossato <andrea.rossato@unitn.it>
Stabilityunstable
Portabilityunportable
Safe HaskellNone
LanguageHaskell98

Text.CSL

Contents

Description

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.

Synopsis

Introduction

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: A Simple Example

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)

Reading Bibliographic Databases

readBiblioFile :: FilePath -> IO [Reference] Source

Read a file with a bibliographic database. The database format is recognized by the file extension.

Supported formats are: json, mods, bibtex, biblatex, ris, endnote, endnotexml, isi, medline, and copac.

Reference Representation

data Reference Source

The Reference record.

Constructors

Reference 

Fields

refId :: Literal
 
refType :: RefType
 
author :: [Agent]
 
editor :: [Agent]
 
translator :: [Agent]
 
recipient :: [Agent]
 
interviewer :: [Agent]
 
composer :: [Agent]
 
director :: [Agent]
 
illustrator :: [Agent]
 
originalAuthor :: [Agent]
 
containerAuthor :: [Agent]
 
collectionEditor :: [Agent]
 
editorialDirector :: [Agent]
 
reviewedAuthor :: [Agent]
 
issued :: [RefDate]
 
eventDate :: [RefDate]
 
accessed :: [RefDate]
 
container :: [RefDate]
 
originalDate :: [RefDate]
 
submitted :: [RefDate]
 
title :: Formatted
 
titleShort :: Formatted
 
reviewedTitle :: Formatted
 
containerTitle :: Formatted
 
volumeTitle :: Formatted
 
collectionTitle :: Formatted
 
containerTitleShort :: Formatted
 
collectionNumber :: Formatted
 
originalTitle :: Formatted
 
publisher :: Formatted
 
originalPublisher :: Formatted
 
publisherPlace :: Formatted
 
originalPublisherPlace :: Formatted
 
authority :: Formatted
 
jurisdiction :: Formatted
 
archive :: Formatted
 
archivePlace :: Formatted
 
archiveLocation :: Formatted
 
event :: Formatted
 
eventPlace :: Formatted
 
page :: Formatted
 
pageFirst :: Formatted
 
numberOfPages :: Formatted
 
version :: Formatted
 
volume :: Formatted
 
numberOfVolumes :: Formatted
 
issue :: Formatted
 
chapterNumber :: Formatted
 
medium :: Formatted
 
status :: Formatted
 
edition :: Formatted
 
section :: Formatted
 
source :: Formatted
 
genre :: Formatted
 
note :: Formatted
 
annote :: Formatted
 
abstract :: Formatted
 
keyword :: Formatted
 
number :: Formatted
 
references :: Formatted
 
url :: Literal
 
doi :: Literal
 
isbn :: Literal
 
issn :: Literal
 
pmcid :: Literal
 
pmid :: Literal
 
callNumber :: Literal
 
dimensions :: Literal
 
scale :: Literal
 
categories :: [Literal]
 
language :: Literal
 
citationNumber :: CNum
 
firstReferenceNoteNumber :: Int
 
citationLabel :: Literal
 

setNearNote :: Style -> [[Cite]] -> [[Cite]] Source

CSL Parser, Representation, and Processing

readCSLFile :: Maybe String -> FilePath -> IO Style Source

Read and parse a CSL style file into a localized sytle.

parseCSL :: String -> Style Source

Parse a String into a Style (with default locale).

localizeCSL :: Maybe String -> Style -> IO Style Source

Merge locale into a CSL style.

The Style Types

High Level Processing

data ProcOpts Source

Constructors

ProcOpts 

Fields

bibOpts :: BibOpts
 

citeproc :: ProcOpts -> Style -> [Reference] -> Citations -> BiblioData Source

With a Style, a list of References and the list of Citations, produce the Formatted for each citation group and the bibliography.

processCitations :: ProcOpts -> Style -> [Reference] -> Citations -> [Formatted] Source

With a Style, a list of References and the list of citation groups (the list of citations with their locator), produce the Formatted for each citation group.

processBibliography :: ProcOpts -> Style -> [Reference] -> [Formatted] Source

With a Style and the list of References produce the Formatted for the bibliography.

The output and the rendering functions

renderPlain :: Formatted -> String Source

Render the Formatted into a plain text string.