citeproc-el

A CSL 1.0.2 Citation Processor for Emacs.

Table of Contents

• Introduction
• Requirements
• Installation
• Usage
  • Creating a citation processor
  • Creating citation structures
  • Managing a processor’s citation list and bibliography items
  • Rendering citations and bibliographies
  • Rendering isolated references
  • Supported output formats
  • Hooks
• Acknowledgements
• License

Introduction

citeproc-el is an Emacs Lisp library for rendering citations and bibliographies in styles described in the Citation Style Language (CSL), an XML-based, open format to describe the formatting of bibliographic references (see http://citationstyles.org/ for further information on CSL).

The library implements most of the CSL 1.0.2 specification, including such features as citation disambiguation, cite collapsing and subsequent author substitution, and passes more than 70% of the tests in the CSL Test Suite. In addition to the standard CSL-JSON data format, citeproc-el has rudimentary support for reading bibliographic data from BibTeX, biblatex and org-bibtex bibliographies and can produce output in several formats including HTML and org-mode markup (see Supported output formats for the full list).

Requirements

Emacs 26 or later compiled with libxml2 support. (The library is regularly tested on Emacs 27.2, 28.1 and 29.1.)

Installation

citeproc-el is available in the MELPA package repository and can be installed using Emacs’s built-in package manager, package.el.

Usage

The central use-case of citeproc-el is that of feeding all citations occurring in a document into a citation processor and rendering the complete list of references and bibliography with it. This requires

1. creating a citation processor object,
2. collecting the document’s citations into a list of citation structures,
3. loading this list into the processor, and
4. rendering the loaded citations and the corresponding bibliography with the processor in one of the supported formats.

Creating a citation processor

Citation processor objects are created using the citeproc-create function (the signature of which was inspired by the citeproc-js API):

citeproc-create (style item-getter locale-getter &optional locale force-locale)

• style is a CSL style file (e.g., "/usr/local/csl_styles/chicago-author-date.csl") to use for rendering the references;
• item-getter is function that takes a list of bibliographic item id strings as its sole argument and returns an alist in which the given item ids are the keys and the values are the CSL-JSON descriptions of the corresponding bibliography items as parsed by Emacs’s built in JSON parser (keys are symbols, arrays and hashes should be represented as lists and alists, respectively);
• locale-getter is a function that takes a CSL locale tag (e.g., "fr-FR") as an argument and returns a corresponding CSL locale as parsed by Emacs’s libxml-parse-xml-regionfunction or nil, with the exception of the default "en-US" argument for which it must return the corresponding parsed locale (nil is not allowed);
• the optional locale is the CSL locale tag to use if the style doesn’t specify a default one (defaults to "en-US"); and
• if the optional force-locale is non-nil then the specified locale is used even if the given style specifies a different one as default.
• Returns a citation processor with an empty citation list.

citeproc-el integrators are free to implement their own special item-getter and locale-getter functions (e.g., to provide item descriptions and locales from a centralized source on a network) but citeproc-el provides some convenience functions to create typical item- and locale-getters:

citeproc-itemgetter-from-csl-json (file)

citeproc-hash-itemgetter-from-csl-json (file)

Both functions return an item-getter function getting bibliography item descriptions from a CSL-JSON file. The difference between them is that an item-getter produced by citeproc-itemgetter-from-csl-json opens and reads directly from file each time it is called, while citeproc-hash-itemgetter-from-csl-json reads the content of file into a hash-table and the created function reads item descriptions from this hash-table when called. As a consequence, functions created with citeproc-hash-itemgetter-from-csl-json can perform better but ignore changes in file between calls.

citeproc-itemgetter-from-bibtex (file-or-files)

citeproc-itemgetter-from-org-bibtex (file-or-files)

Return an item-getter function getting bibliography item descriptions from BibTeX/org-bibtex files. Similarly to citeproc-itemgetter-from-csl-json, these functions open and read directly from the specified files each time they are called.

citeproc-hash-itemgetter-from-any (file-or-files &optional no-sentcase-wo-langid)

Return a getter for file-or-files in any supported format. The format is determined on the basis of file extensions. Supported formats:

• CSL-JSON (.json extension) the recommended native format;
• BibTeX/biblatex (.bib or .bibtex extension),
• org-bibtex (.org extension).

If no-sentcase-wo-langid is non-nil then title fields in items without a `langid' field are not converted to sentence-case.

citeproc-locale-getter-from-dir (directory)

Return a locale-getter function getting CSL locales from directory. The directory must contain the CSL locale files under their canonical names (as found at the Official CSL locale repository), and must contain at least the default en-US locale file.

Creating citation structures

Citation structures are created with

citeproc-citation-create (&key cites note-index mode suppress-affixes capitalize-first ignore-et-al)

• cites is a list of alists describing cites. Each alist must contain the id symbol as key coupled with an item id string as value, and can optionally contain additional information with the symbol keys prefix, suffix, locator, label (all with string values);
• note-index is the note index of the citation if it occurs in a note and nil otherwise;
• mode is either nil (for the default citation mode) or one of the symbols suppress-author, textual, author-only, year-only, title-only, locator-only, bib-entry;
• suppress-affixes is non-nil if the prefix and the suffix of the citation (e.g., opening and closing brackets) have to be suppressed;
• capitalize-first is non-nil if the first word of the citation has to be capitalized;
• ignore-et-al is non-nil if et-al settings should be ignored for the first cite.

Managing a processor’s citation list and bibliography items

Processor objects maintain lists of citations and bibliography items, which can be manipulated with the following functions:

citeproc-append-citations (citations proc)

Append citations, a list of citation structures, to the citation list of citation processor proc.

citeproc-add-uncited (itemids proc)

Add uncited bib items with itemids to proc. As an extension, an itemid can be the string "*" which has the effect of adding all items available in the itemgetter.

citeproc-add-subbib-filters (filters proc)

Add sub-bibliography filters to proc. filters should be a list of alists containing symbol keys and string values, each pair describing an atomic condition to be satisified by the printed entries. The following keys are supported:

• type: print only entries of the given type. Type is the bib(la)tex entry type if available, otherwise the CSL type is used as fallback;
• nottype: print only entries not of the given type. Type is the bib(la)tex entry type if available, otherwise the CSL type is used as fallback;
• csltype, notcsltype: same as type and nottype but uses the entries' CSL type even if the bib(la)tex type is also available;
• keyword: print only entries with the given keyword;
• notkeyword: print only entries without the given keyword;
• filter: print only entries for which the function named by the key returns a non-nil value.

citeproc-clear (proc)

Clear the citation and bibliography lists of citation processor proc.

Rendering citations and bibliographies

citeproc-render-citations (proc format &optional internal-links)

Render all citations in citation processor proc in the given format. Return a list of formatted citations. format is one of the supported output formats as a symbol.

If the optional internal-links is bib-links then link cites to the bibliography regardless of the style type, if no-links then don't add internal links, if nil or auto then add internal links based on the style type (cite-cite links for note styles and cite-bib links else). For legacy reasons, any other value is treated as no-links.

citeproc-render-bib (proc format &optional internal-links no-external-links bib-formatter-fun)

Render a bibliography of the citations in citation processor proc in the givenformat. format is one of the supported output formats as a symbol.

For the optional internal-links argument see citeproc-render-citations. If the optional no-external-links is non-nil then don't generate external links. If the optional bib-formatter-fun is given then it will be used to join the bibliography items instead of the content of the chosen formatter’s bib slot (see the documentation of the citeproc-formatter structure type for details).

Returns a (FORMATTED-BIBLIOGRAPHY . FORMATTING-PARAMETERS) pair, in which FORMATTED-BIBLIOGRAPHY is either a single bibliography or a list of sub-bibliograhies if filters were added to the processor, and FORMATTING-PARAMETERS is an alist containing the values of the following formatting parameters keyed to the parameter names as symbols:

• max-offset (integer): The width of the widest first field in the bibliography, measured in characters.
• line-spacing (integer): Vertical line distance specified as a multiple of standard line height.
• entry-spacing (integer): Vertical distance between bibliographic entries, specified as a multiple of standard line height.
• second-field-align (flush or margin): The position of second-field alignment.
• hanging-indent (boolean): Whether the bibliography items should be rendered with hanging-indents.

Rendering isolated references

Reference rendering is typically context-dependent, as the rendered form can depend on the position of the reference and the presence of other references may make it necessary to add disambiguating information. Since computing the context-dependent form might be too time-consuming or unnecessary for some applications (e.g., for generating previews), citeproc-el provides functions to render isolated references.

Isolated rendering requires only the creation of a citeproc-style object (as opposed to a full-blown citation processor) with the function

citeproc-create-style (style locale-getter &optional locale force-locale)

Return a newly created citeproc-style object. See the documentation of citeproc-create for the description of the arguments.

After the creation of a style object references can be rendered by

citeproc-render-item (item-data style mode format &optional no-external-links)

Render an item described by item-data with style. item-data is the parsed form of a bibliographic item description in CSL-JSON format, style is a citeproc-style style object, mode is one of the symbols bib or cite, format is a supported output format (see next section) as a symbol. If the optional no-external-links is non-nil then don't generate external links in the item.

See the Wiki page Rendering isolated references with a modified html formatter for a worked-out example.

Supported output formats

Currently html, org, plain (plain text), latex, org-odt, org-latex (for Org ODT and LaTeX export), csl-test (for the CSL test suite) and raw (internal rich-text format, for debugging) are supported as output formats. New ones can easily be added — see citeproc-formatters.el for examples.

Hooks

citeproc-el provides the following hook variables:

citeproc-citation-postprocess-functions

A list of functions to postprocess rendered citations. Each function takes a single argument, a rich-text, and returns a post-processed rich-text value. The functions are applied in the order they appear in the list.

citeproc-name-postprocess-functions

A list of functions to postprocess rendered names. Each function takes three arguments:

• the rich-text rendering of a name to be postprocessed,
• the rendered name as an alist with CSL name-part keys (family, given etc.), and
• the rendering context, as a citeproc-context structure.

The output of each function should be the postprocessed rich-text, and the functions are applied in the order they appear in the list.

Acknowledgements

Code contributions

• Marvin Gülker
• Matt Price
• Alexey Shiklomanov

Advice, discussion

• Rudolf Adamkovič
• Bruce D'Arcus
• Marvin Gülker
• Denis Maier
• Matt Price

License

Copyright (C) 2018-2022 András Simonyi

Authors: András Simonyi

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.