README.md
1# citeproc
2
3[](LICENSE)
4[](https://github.com/jgm/citeproc/actions)
6[](https://hackage.haskell.org/package/citeproc)
7
8This library generates citations and bibliography formatted
9according to a [CSL] style. Currently version 1.0.2 of the CSL
10spec is targeted.
11
12This library is a successor to pandoc-citeproc, which was a fork
13of Andrea Rossato's citeproc-hs. I always found it difficult to
14fix bugs in pandoc-citeproc and decided that implementing
15citeproc from scratch would give me a better basis for
16understanding. This library has a number of other advantages
17over pandoc-citeproc:
18
19- it is much faster (as a rough benchmark, running the CSL
20 test suite takes less than 4 seconds with this library,
21 compared to 12 seconds with pandoc-citeproc)
22
23- it interprets CSL more faithfully, passing more of the CSL
24 tests
25
26- it has fewer dependencies (in particular, it does not depend
27 on pandoc)
28
29- it is more flexible, not being tied to pandoc's types.
30
31Unlike pandoc-citeproc, this library does not provide an
32executable. It will be used in pandoc itself to provide
33integrated citation support and bibliography format conversion
34(so the pandoc-citeproc filter will no longer be necessary).
35
36[CSL]: https://docs.citationstyles.org/en/stable/specification.html
37
38## How to use it
39
40The main point of entry is the function `citeproc` from the
41module `Citeproc`. This takes as arguments:
42
43- a `CiteprocOptions` structure (which currently just allows you
44 to set whether citations are hyperlinked to the bibliography)
45
46- a `Style`, which you will want to produce by parsing a CSL
47 style file using `parseStyle` from `Citeproc.Style`.
48
49- Optionally a `Lang`, which allows you to override a default locale,
50
51- a list of `Reference`s, which you can produce from a CSL JSON
52 bibliography using aeson's `decode`,
53
54- a list of `Citation`s (each of which may have multiple
55 `CitationItems`).
56
57It yields a `Result`, which includes a list of formatted
58citations and a formatted bibliography, as well any warnings
59produced in evaluating the style.
60
61The types are parameterized on a `CiteprocOutput` instance `a`,
62which represents formatted content in your bibliographic
63fields (e.g. the title). If you want a classic CSL processor,
64you can use `CslJson Text`. But you can also use another type,
65such as a pandoc `Inlines`. All you need to do is define
66an instance of `CiteprocOutput` for your type.
67
68The signature of `parseStyle` may not be self-evident:
69the first argument is a function that takes a URL and
70retrieves the text from that URL. This is used to fetch
71the "indendent parent" of a dependent style. You can supply
72whatever function you like: it can search your local file
73system or fetch the content via HTTP. If you're not using
74dependent styles, you can get by with `\_ -> return mempty`.
75
76## The citeproc executable
77
78If the package is compiled with the `executable` flag, an
79executable `citeproc` will be built. `citeproc` reads
80a JSON-encoded `Inputs` object from `stdin` (or from
81a file if a filename is provided) and writes
82a JSON-encoded `Result` object to `stdout`. This executable
83can be used to add citation processing to non-Haskell projects.
84
85`citeproc --help` will summarize usage information. See
86the [man page](man/citeproc.1.md) for more information.
87
88## Known bugs and limitations
89
90Although this library is much more accurate in implementing the
91CSL spec than pandoc-citeproc was, it still fails some of the
92tests from the CSL test suite (67/862). However, most of the
93failures are on minor corner cases, and in many cases the
94expected behavior goes beyond what is required by the CSL spec.
95(For example, we intentionally refrain from capitalizing
96terms in initial position in note styles. It makes more sense
97for the calling program, e.g. pandoc, to do the capitalization
98when it puts the citations in notes, since some citations
99in note styles may already be in notes and in this case
100their rendering may not require capitalization. It is easy
101to capitalize reliably, hard to uncapitalize reliably.)
102
103
){kind=link}
){kind=link}
){kind=link}