{"id":13646409,"url":"https://github.com/andras-simonyi/citeproc-el","last_synced_at":"2025-04-21T18:31:00.568Z","repository":{"id":37548225,"uuid":"114693307","full_name":"andras-simonyi/citeproc-el","owner":"andras-simonyi","description":"A  CSL 1.0.2 Citation Processor for Emacs.","archived":false,"fork":false,"pushed_at":"2024-05-13T13:13:18.000Z","size":530,"stargazers_count":82,"open_issues_count":14,"forks_count":7,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-05-13T14:36:05.191Z","etag":null,"topics":["bibliography","bibtex","citation","citation-processor","citation-style-language","citeproc","csl","emacs","rendering-citations"],"latest_commit_sha":null,"homepage":"","language":"Emacs Lisp","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/andras-simonyi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-12-18T22:18:54.000Z","updated_at":"2024-05-13T14:36:07.029Z","dependencies_parsed_at":"2023-11-26T08:23:39.890Z","dependency_job_id":"813277ba-b39b-4cf1-bb75-c1614c260dee","html_url":"https://github.com/andras-simonyi/citeproc-el","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andras-simonyi%2Fciteproc-el","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andras-simonyi%2Fciteproc-el/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andras-simonyi%2Fciteproc-el/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andras-simonyi%2Fciteproc-el/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andras-simonyi","download_url":"https://codeload.github.com/andras-simonyi/citeproc-el/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250110837,"owners_count":21376544,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bibliography","bibtex","citation","citation-processor","citation-style-language","citeproc","csl","emacs","rendering-citations"],"created_at":"2024-08-02T01:02:54.904Z","updated_at":"2025-04-21T18:31:00.211Z","avatar_url":"https://github.com/andras-simonyi.png","language":"Emacs Lisp","funding_links":[],"categories":["Emacs Lisp"],"sub_categories":[],"readme":"# citeproc-el\n\n[![Build Status](https://github.com/andras-simonyi/citeproc-el/actions/workflows/ci.yml/badge.svg)](https://github.com/andras-simonyi/citeproc-el/actions/workflows/ci.yml)\n[![License: GPL\nv3](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)\n[![MELPA](http://melpa.org/packages/citeproc-badge.svg)](http://melpa.org/#/citeproc)\n[![MELPA Stable](http://stable.melpa.org/packages/citeproc-badge.svg)](http://stable.melpa.org/#/citeproc)\n\n\nA CSL 1.0.2 Citation Processor for Emacs.\n\n**Table of Contents**\n\n- [Introduction](#introduction)\n- [Requirements](#requirements)\n- [Installation](#installation)\n- [Usage](#usage)\n    - [Creating a citation processor](#creating-a-citation-processor)\n    - [Creating citation structures](#creating-citation-structures)\n    - [Managing a processor’s citation list and bibliography items](#managing-a-processors-citation-list-and-bibliography-items)\n    - [Rendering citations and bibliographies](#rendering-citations-and-bibliographies)\n\t- [Rendering isolated references](#rendering-isolated-references)\n\t- [Supported output formats](#supported-output-formats)\n\t- [Hooks](#hooks)\n- [Acknowledgements](#acknowledgements)\n- [License](#license)\n\n## Introduction\n\nciteproc-el is an Emacs Lisp library for rendering citations and\nbibliographies in styles described in the Citation Style Language (CSL), an\nXML-based, open format to describe the formatting of bibliographic references\n(see http://citationstyles.org/ for further information on CSL).\n\nThe library implements most of the [CSL 1.0.2\nspecification](http://docs.citationstyles.org/en/stable/specification.html),\nincluding such features as citation disambiguation, cite collapsing and\nsubsequent author substitution, and passes more than 70% of the tests in the\n[CSL Test Suite](https://github.com/citation-style-language/test-suite). In\naddition to the standard\n[CSL-JSON](https://github.com/citation-style-language/schema/blob/master/csl-data.json)\ndata format, citeproc-el has rudimentary support for reading bibliographic data\nfrom BibTeX, biblatex and org-bibtex bibliographies and can produce output in several\nformats including HTML and org-mode markup (see [Supported output\nformats](#supported-output-formats) for the full list).\n\n## Requirements\n\nEmacs 26 or later compiled with libxml2 support. (The library is regularly\ntested on Emacs  27.2, 28.1 and 29.1.)\n\n## Installation\n\nciteproc-el is available in the [MELPA package repository](https://melpa.org)\nand can be installed using Emacs’s built-in package manager, `package.el`.\n\n-------------------------------------------------------------------------------\n\n## Usage\n\nThe central use-case of citeproc-el is that of feeding all citations occurring\nin a document into a citation processor and rendering the complete list of\nreferences and bibliography with it. This requires\n\n  1. creating a citation processor object,\n  2. collecting the document’s citations into a list of citation structures,\n  3. loading this list into the processor, and\n  3. rendering the loaded citations and the corresponding bibliography with the\n     processor in one of the supported formats.\n\n### Creating a citation processor\n\nCitation processor objects are created using the `citeproc-create` function (the\nsignature of which was inspired by the\n[citeproc-js](https://github.com/Juris-M/citeproc-js) API):\n\n#### citeproc-create `(style item-getter locale-getter \u0026optional locale force-locale)`\n\n  * `style` is a CSL style file (e.g.,\n    `\"/usr/local/csl_styles/chicago-author-date.csl\"`) to use for rendering the\n    references;\n  * `item-getter` is function that takes a list of bibliographic item id strings\n    as its sole argument and returns an alist in which the given item ids are\n    the keys and the values are the\n    [CSL-JSON](https://github.com/citation-style-language/schema/blob/master/csl-data.json)\n    descriptions of the corresponding bibliography items as parsed by Emacs’s\n    built in JSON parser (keys are symbols, arrays and hashes should be\n    represented as lists and alists, respectively);\n  * `locale-getter` is a function that takes a CSL locale tag (e.g., `\"fr-FR\"`)\n\tas an argument and returns a corresponding CSL locale as parsed by Emacs’s\n\t`libxml-parse-xml-region`function or `nil`, with the exception of the\n\tdefault `\"en-US\"` argument for which it must return the corresponding parsed\n\tlocale (`nil` is not allowed);\n  * the optional `locale` is the CSL locale tag to use if the style doesn’t\n\tspecify a default one (defaults to `\"en-US\"`); and\n  * if the optional `force-locale` is non-nil then the specified `locale` is\n    used even if the given `style` specifies a different one as default.\n  * Returns a citation processor with an empty citation list.\n\nciteproc-el integrators are free to implement their own special item-getter\nand locale-getter functions (e.g., to provide item descriptions and locales from\na centralized source on a network) but citeproc-el provides some convenience\nfunctions to create typical item- and locale-getters:\n\n#### citeproc-itemgetter-from-csl-json `(file)`\n\n#### citeproc-hash-itemgetter-from-csl-json `(file)`\n\nBoth functions return an item-getter function getting bibliography item\ndescriptions from a\n[CSL-JSON](https://github.com/citation-style-language/schema/blob/master/csl-data.json)\nfile. The difference between them is that an item-getter produced by\n`citeproc-itemgetter-from-csl-json` opens and reads directly from `file` each\ntime it is called, while `citeproc-hash-itemgetter-from-csl-json` reads the\ncontent of `file` into a hash-table and the created function reads item\ndescriptions from this hash-table when called. As a consequence, functions\ncreated with `citeproc-hash-itemgetter-from-csl-json` can perform better but\nignore changes in `file` between calls.\n\n#### citeproc-itemgetter-from-bibtex `(file-or-files)`\n\n#### citeproc-itemgetter-from-org-bibtex `(file-or-files)`\n\nReturn an item-getter function getting bibliography item descriptions from\nBibTeX/org-bibtex files. Similarly to `citeproc-itemgetter-from-csl-json`, these\nfunctions open and read directly from the specified files each time they are\ncalled.\n\n#### citeproc-hash-itemgetter-from-any `(file-or-files \u0026optional no-sentcase-wo-langid)`\nReturn a getter for `file-or-files` in any supported format.\nThe format is determined on the basis of file extensions.\nSupported formats:\n\n- CSL-JSON (.json extension) the recommended native format;\n- BibTeX/biblatex (.bib or .bibtex extension),\n- org-bibtex (.org extension). \n\nIf `no-sentcase-wo-langid` is non-nil then title fields in items without a\n`langid' field are not converted to sentence-case.\n\n#### citeproc-locale-getter-from-dir `(directory)`\n\nReturn a locale-getter function getting CSL locales from `directory`. The\ndirectory must contain the CSL locale files under their canonical names (as\nfound at the [Official CSL locale\nrepository](https://github.com/citation-style-language/locales)), and must\ncontain at least the default `en-US` locale file.\n\n### Creating citation structures\n\nCitation structures are created with\n\n#### citeproc-citation-create `(\u0026key cites note-index mode suppress-affixes capitalize-first ignore-et-al) `\n\n\n  * `cites` is a list of alists describing cites. Each alist must contain the\n     `id` symbol as key coupled with an item id string as value, and can\n     optionally contain additional information with the symbol keys `prefix`,\n     `suffix`, `locator`, `label` (all with string values);\n  * `note-index` is the note index of the citation if it occurs in a note and\n     `nil` otherwise;\n  * `mode` is either nil (for the default citation mode) or one\n    of the symbols `suppress-author`, `textual`, `author-only`,\n    `year-only`, `title-only`, `locator-only`, `bib-entry`;\n  * `suppress-affixes` is non-nil if the prefix and the suffix of the citation\n    (e.g., opening and closing brackets) have to be suppressed;\n  * `capitalize-first` is non-nil if the first word of the citation has to be\n    capitalized;\n  * `ignore-et-al` is non-nil if et-al settings should be ignored for the first\n    cite.\n  \n### Managing a processor’s citation list and bibliography items\n\nProcessor objects maintain lists of citations and bibliography items,\nwhich can be manipulated with the following functions:\n\n#### citeproc-append-citations `(citations proc)`\n\nAppend `citations`, a list of citation structures, to the citation list of\ncitation processor `proc`.\n\n#### citeproc-add-uncited `(itemids proc)`\n\nAdd uncited bib items with `itemids` to `proc`. As an extension, an itemid can\nbe the string \"*\" which has the effect of adding all items available in the\nitemgetter.\n\n#### citeproc-add-subbib-filters `(filters proc)`\n\nAdd sub-bibliography `filters` to `proc`. `filters` \nshould be a list of alists containing symbol keys and\nstring values, each pair describing an atomic condition to be\nsatisified by the printed entries. The following keys are\nsupported:\n\n- `type`: print only entries of the given type. Type is the\n  bib(la)tex entry type if available, otherwise the CSL type is\n  used as fallback;\n- `nottype`: print only entries not of the given type. Type is\n  the bib(la)tex entry type if available, otherwise the CSL type\n  is used as fallback;\n- `csltype`, `notcsltype`: same as `type` and `nottype` but uses\n  the entries' CSL type even if the bib(la)tex type is also\n  available;\n- `keyword`: print only entries with the given keyword;\n- `notkeyword`: print only entries without the given keyword;\n- `filter`: print only entries for which the function named by\n  the key returns a non-nil value.\n\n#### citeproc-clear `(proc)`\n\nClear the citation and bibliography lists of citation processor `proc`.\n\n### Rendering citations and bibliographies\n\n#### citeproc-render-citations `(proc format \u0026optional internal-links)`\n\nRender all citations in citation processor `proc` in the given `format`. Return\na list of formatted citations. `format` is one of the [supported output\nformats](#supported-output-formats) as a symbol. \n\nIf the optional `internal-links` is `bib-links` then link cites\nto the bibliography regardless of the style type, if `no-links`\nthen don't add internal links, if nil or `auto` then add internal\nlinks based on the style type (cite-cite links for note styles\nand cite-bib links else). For legacy reasons, any other value is\ntreated as `no-links`.\n\n#### citeproc-render-bib `(proc format \u0026optional internal-links no-external-links bib-formatter-fun)`\n\nRender a bibliography of the citations in citation processor `proc` in the\ngiven`format`. `format` is one of the [supported output\nformats](#supported-output-formats) as a symbol. \n\nFor the optional `internal-links` argument see `citeproc-render-citations`. If\nthe optional `no-external-links` is non-nil then don't generate external links.\nIf the optional `bib-formatter-fun` is given then it will be used to join the\nbibliography items instead of the content of the chosen formatter’s `bib` slot\n(see the documentation of the `citeproc-formatter` structure type for details).\n\nReturns a `(FORMATTED-BIBLIOGRAPHY . FORMATTING-PARAMETERS)` pair, in which\n`FORMATTED-BIBLIOGRAPHY` is either a single bibliography or a list of\nsub-bibliograhies if filters were added to the processor, and\n`FORMATTING-PARAMETERS` is an alist containing the values of the following\nformatting parameters keyed to the parameter names as symbols:\n\n  * `max-offset` (integer): The width of the widest first field in the\n    bibliography, measured in characters.\n  * `line-spacing` (integer): Vertical line distance specified as a multiple of\n    standard line height.\n  * `entry-spacing` (integer): Vertical distance between bibliographic entries,\n    specified as a multiple of standard line height.\n  * `second-field-align` (`flush` or `margin`): The position of second-field\n    alignment.\n  * `hanging-indent` (boolean): Whether the bibliography items should\n    be rendered with hanging-indents.\n\n### Rendering isolated references\n\nReference rendering is typically context-dependent, as the rendered form can\ndepend on the position of the reference and the presence of other references may\nmake it necessary to add disambiguating information. Since computing the\ncontext-dependent form might be too time-consuming or unnecessary for some\napplications (e.g., for generating previews), citeproc-el provides functions\nto render isolated references.\n\nIsolated rendering requires only the creation of a `citeproc-style` object (as\nopposed to a full-blown citation processor) with the function\n\n#### citeproc-create-style `(style locale-getter \u0026optional locale force-locale)`\n\nReturn a newly created `citeproc-style` object. See the documentation of\n[citeproc-create](#citeproc-create-style-item-getter-locale-getter-optional-locale-force-locale)\nfor the description of the arguments.\n\nAfter the creation of a style object references can be rendered by\n\n#### citeproc-render-item `(item-data style mode format \u0026optional no-external-links)`\nRender an item described by `item-data` with `style`. `item-data` is the parsed\nform of a bibliographic item description in\n[CSL-JSON](https://github.com/citation-style-language/schema/blob/master/csl-data.json)\nformat, `style` is a `citeproc-style` style object, `mode` is one of the symbols\n`bib` or `cite`, `format` is a supported output format (see next section) as a\nsymbol. If the optional `no-external-links` is non-nil then don't generate\nexternal links in the item.\n\nSee the Wiki page [Rendering isolated references with a modified html\nformatter](https://github.com/andras-simonyi/citeproc-el/wiki/Rendering-isolated-references-with-a-modified-html-formatter) for a worked-out example.\n\n### Supported output formats\n\nCurrently `html`, `org`, `plain` (plain text), `latex`, `org-odt`, `org-latex`\n(for Org ODT and LaTeX export), `csl-test` (for the CSL test suite) and `raw`\n(internal rich-text format, for debugging) are supported as output formats. New\nones can easily be added — see `citeproc-formatters.el` for examples.\n\n### Hooks\n\nciteproc-el provides the following hook variables:\n\n#### citeproc-citation-postprocess-functions\nA list of functions to postprocess rendered citations. Each function takes a\nsingle argument, a rich-text, and returns a post-processed rich-text value. The\nfunctions are applied in the order they appear in the list.\n\n#### citeproc-name-postprocess-functions\nA list of functions to postprocess rendered names.\nEach function takes three arguments:\n\n- the rich-text rendering of a name to be postprocessed,\n- the rendered name as an alist with CSL name-part\n  keys (`family`, `given` etc.), and\n- the rendering context, as a `citeproc-context` structure.\n\nThe output of each function should be the postprocessed rich-text, and\nthe functions are applied in the order they appear in the list.\n\n-------------------------------------------------------------------------------\n\n## Acknowledgements\n\n### Code contributions\n\n- [Marvin Gülker](https://github.com/Quintus)\n- [Matt Price](https://github.com/titaniumbones)\n- [Alexey Shiklomanov](https://github.com/ashiklom)\n\n### Advice, discussion\n\n- [Rudolf Adamkovič](https://github.com/salutis)\n- [Bruce D'Arcus](https://github.com/bdarcus)\n- [Marvin Gülker](https://github.com/Quintus)\n- [Denis Maier](https://github.com/denismaier)\n- [Matt Price](https://github.com/titaniumbones)\n\n-------------------------------------------------------------------------------\n\n## License\n\nCopyright (C) 2018-2022 András Simonyi\n\nAuthors: András Simonyi\n\nThis program is free software; you can redistribute it and/or modify it under\nthe terms of the GNU General Public License as published by the Free Software\nFoundation, either version 3 of the License, or (at your option) any later\nversion.\n\nThis program is distributed in the hope that it will be useful, but WITHOUT ANY\nWARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A\nPARTICULAR PURPOSE. See the GNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License along with\nthis program. If not, see http://www.gnu.org/licenses/.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandras-simonyi%2Fciteproc-el","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandras-simonyi%2Fciteproc-el","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandras-simonyi%2Fciteproc-el/lists"}