citeproc: Generates citations and bibliography from CSL styles.

[ bsd2, library, text ] [ Propose Tags ]

citeproc parses CSL style files and uses them to generate a list of formatted citations and bibliography entries. For more information about CSL, see https://citationstyles.org/.


[Skip to Readme]

Flags

Automatic Flags
NameDescriptionDefault
icu

Use Haskell bindings to the ICU library

Disabled
executable

Build citeproc executable

Disabled

Use -f <flag> to enable a flag, or -f -<flag> to disable that flag. More info

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

  • No Candidates
Versions [RSS] 0.1, 0.1.0.1, 0.1.0.2, 0.1.0.3, 0.1.1, 0.1.1.1, 0.2, 0.2.0.1, 0.3, 0.3.0.1, 0.3.0.2, 0.3.0.3, 0.3.0.4, 0.3.0.5, 0.3.0.6, 0.3.0.7, 0.3.0.8, 0.3.0.9, 0.4, 0.4.0.1, 0.4.1, 0.5, 0.6, 0.6.0.1, 0.7, 0.8, 0.8.0.1, 0.8.0.2, 0.8.1
Change log CHANGELOG.md
Dependencies aeson, aeson-pretty, attoparsec, base (>=4.8 && <5), bytestring, case-insensitive (>=1.2 && <1.3), citeproc, containers (>=0.6.0.1 && <0.7), data-default, file-embed, filepath, pandoc-types (>=1.22 && <1.23), rfc5051 (>=0.2 && <0.3), safe, scientific, text, text-icu, transformers (>=0.5.6 && <0.6), uniplate, vector, xml-conduit [details]
License BSD-2-Clause
Copyright 2020 John MacFarlane
Author John MacFarlane
Maintainer jgm@berkeley.edu
Category Text
Source repo head: git clone https://github.com/jgm/citeproc.git
Uploaded by JohnMacFarlane at 2020-10-09T23:32:01Z
Distributions Arch:0.8.1, Fedora:0.8.1, LTSHaskell:0.8.1, NixOS:0.8.1, Stackage:0.8.1, openSUSE:0.8.1
Reverse Dependencies 3 direct, 165 indirect [details]
Executables citeproc
Downloads 23413 total (228 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs uploaded by user
Build status unknown [no reports yet]

Readme for citeproc-0.1

[back to package description]

citeproc

BSD2 license CItests

This library generates citations and bibliography formatted according to a CSL style. Currently version 1.0.2 of the CSL spec is targeted.

This library is a successor to pandoc-citeproc, which was a fork of Andrea Rossato's citeproc-hs. I always found it difficult to fix bugs in pandoc-citeproc and decided that implementing citeproc from scratch would give me a better basis for understanding. This library has a number of other advantages over pandoc-citeproc:

  • it is much faster (as a rough benchmark, running the CSL test suite takes less than 4 seconds with this library, compared to 12 seconds with pandoc-citeproc)

  • it interprets CSL more faithfully, passing more of the CSL tests

  • it has fewer dependencies (in particular, it does not depend on pandoc)

  • it is more flexible, not being tied to pandoc's types.

Unlike pandoc-citeproc, this library does not provide an executable. It will be used in pandoc itself to provide integrated citation support and bibliography format conversion (so the pandoc-citeproc filter will no longer be necessary).

How to use it

The main point of entry is the function citeproc from the module Citeproc. This takes as arguments:

  • a CiteprocOptions structure (which currently just allows you to set whether citations are hyperlinked to the bibliography)

  • a Style, which you will want to produce by parsing a CSL style file using parseStyle from Citeproc.Style.

  • Optionally a Lang, which allows you to override a default locale,

  • a list of References, which you can produce from a CSL JSON bibliography using aeson's decode,

  • a list of Citations (each of which may have multiple CitationItems).

It yields a Result, which includes a list of formatted citations and a formatted bibliography, as well any warnings produced in evaluating the style.

The types are parameterized on a CiteprocOutput instance a, which represents formatted content in your bibliographic fields (e.g. the title). If you want a classic CSL processor, you can use CslJson Text. But you can also use another type, such as a pandoc Inlines. All you need to do is define an instance of CiteprocOutput for your type.

The signature of parseStyle may not be self-evident: the first argument is a function that takes a URL and retrieves the text from that URL. This is used to fetch the "indendent parent" of a dependent style. You can supply whatever function you like: it can search your local file system or fetch the content via HTTP. If you're not using dependent styles, you can get by with \_ -> return mempty.

The citeproc executable

If the package is compiled with the executable flag, an executable citeproc will be built. citeproc reads a JSON-encoded Inputs object from stdin (or from a file if a filename is provided) and writes a JSON-encoded Result object to stdout. This executable can be used to add citation processing to non-Haskell projects.

citeproc --help will summarize usage information. See the man page for more information.

Known bugs and limitations

Although this library is much more accurate in implementing the CSL spec than pandoc-citeproc was, it still fails some of the tests from the CSL test suite (59/845). However, most of the failures are on minor corner cases, and in many cases the expected behavior goes beyond what is required by the CSL spec.