emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
* [wip-cite-new] Initial implementation of `csl' citation processor
@ 2021-05-26 20:33 Nicolas Goaziou
  2021-05-26 21:11 ` Bruce D'Arcus
                   ` (2 more replies)
  0 siblings, 3 replies; 43+ messages in thread
From: Nicolas Goaziou @ 2021-05-26 20:33 UTC (permalink / raw)
  To: Org Mode List; +Cc: András Simonyi

Hello,

I just pushed a Citeproc-based citation processor. As such, Citeproc
library must be available in the load path. For a better experience,
your also need to download styles, and possibly locales definitions, as
pointed in the commentary section pasted below.

I called it `csl' instead of `citeproc'. It is a bit ambiguous, but it
is shorter, and "org-cite-csl" prefix sounds less redudant than
"org-cite-citeproc...". Also, I don't expect a different CSL-based
citation processor any time soon, so it should be fine. But I know this
is a weak argument, so if you think "citeproc" is still more
appropriate, I can revisit this.

As pointed out in the commentary section, this is, for a large part,
a port of András Simonyi's Citeproc Org library. Thanks!

There are some differences between the two libraries, however. For
example, Org Cite CSL does not support Org Ref links. It also provides
less customization options. OTOH, it supports ".bib", ".bibtex" and
".json" bibliography files. It also handles author suppression and
global affixes in citations.

This patch adds two files in a new "etc/csl/" directory. They are both
licensed under CC BY-SA 3.0 terms. So I assume this is fine to
distribute them with Org.

Here is the full commentary. Feedback welcome!

--8<---------------cut here---------------start------------->8---
This library registers the `csl' citation processor, which provides
the "export" capability for citations.  You may activate it globally with

   (setq org-cite-export-processor '(csl))

or at the document level, with

   #+cite_export: csl

The processor relies on the external Citeproc Emacs library, which must be
available prior to loading this library.

By default, citations are rendered in Chicago author-date CSL style.  You can
use another style file by specifying it in `org-cite-export-processor'

   (setq org-cite-export-processor '(csl "/path/to/style-file.csl")

or from within the document by adding the file name to "cite_export" keyword

   #+cite_export: csl /path/to/style-file.csl
   #+cite_export: csl "/path/to/style-file.csl"

Styles can be downloaded, for instance, from the Zotero Style Repository
(<https://www.zotero.org/styles>).  Dependent styles (which are not "unique"
in the Zotero Style Repository terminology) are not supported.

The processor uses the "en-US" CSL locale file shipped with Org for rendering
localized dates and terms in the references, independently of the language
settings of the Org document.  Additional CSL locales can be made available
by setting `org-cite-csl-locales-dir' to a directory containing the locale
files in question (see <https://github.com/citation-style-language/locales>
for such files).  The directory must contain at least the "en-US" CSL locale.

Bibliography is defined with the "bibliography" keyword.  It supports files
with ".bib", ".bibtex", and ".json" extensions.  References are exported using
the "print_bibliography" keyword.

The library supports the following citation styles:

- noauthor (na), including bare (b) variant,
- default style, including bare (b) variant.

CSL styles recognize "locator" in citation references' suffix.  For example,
in the citation

    [cite:see @Tarski-1965 chapter 1, for an example]

"chapter 1" is the locator.  The whole citation is rendered as

    (see Tarski 1965, chap. 1 for an example)

in the default CSL style.

The locator starts with a locator term, among "bk.", "bks.", "book", "chap.",
"chaps.", "chapter", "col.", "cols.", "column", "figure", "fig.", "figs.",
"folio", "fol.", "fols.", "number", "no.", "nos.", "line", "l.", "ll.",
"note", "n.", "nn.", "opus", "op.", "opp.", "page", "p.", "pp.", "paragraph",
"para.", "paras.", "¶", "¶¶", "§", "§§", "part", "pt.", "pts.", "section",
"sec.", "secs.", "sub verbo", "s.v.", "s.vv.", "verse", "v.", "vv.",
"volume", "vol.", and "vols.".  It ends with the last comma or digit in the
suffix, whichever comes last, or runs till the end of the suffix.

The part of the suffix before the locator is appended to reference's prefix.
If no locator term is used, but a number is present, then "page" is assumed.

This library was heavily inspired by and borrows from András Simonyi's
Citeproc Org (<https://github.com/andras-simonyi/citeproc-org>) library.
Many thanks to him!
--8<---------------cut here---------------end--------------->8---

Regards,
-- 
Nicolas Goaziou


^ permalink raw reply	[flat|nested] 43+ messages in thread

end of thread, other threads:[~2021-06-05 17:16 UTC | newest]

Thread overview: 43+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-05-26 20:33 [wip-cite-new] Initial implementation of `csl' citation processor Nicolas Goaziou
2021-05-26 21:11 ` Bruce D'Arcus
2021-05-26 22:07   ` Nicolas Goaziou
2021-05-27  0:47     ` Bruce D'Arcus
2021-05-27  1:58       ` Bruce D'Arcus
2021-05-27  8:01         ` Denis Maier
2021-05-27 12:45           ` Bruce D'Arcus
2021-05-27 13:12             ` Nicolas Goaziou
2021-05-27 14:18               ` Bruce D'Arcus
2021-05-27 14:34                 ` Bruce D'Arcus
2021-05-27 15:02                   ` Bruce D'Arcus
2021-05-27 16:13                     ` Bruce D'Arcus
2021-05-27 17:49                       ` Matt Price
2021-05-28 13:05                       ` Bruce D'Arcus
2021-05-28 13:52                         ` Nicolas Goaziou
2021-05-28 21:37                           ` Bruce D'Arcus
2021-05-29 16:34                     ` Nicolas Goaziou
2021-05-29 17:25                       ` Bruce D'Arcus
2021-05-29 17:56                         ` Bruce D'Arcus
2021-05-29 20:07                         ` Nicolas Goaziou
2021-05-27 12:59           ` Nicolas Goaziou
2021-05-27  9:15 ` Denis Maier
2021-05-27 12:24   ` Nicolas Goaziou
2021-05-27 12:59 ` Bruce D'Arcus
2021-05-28 15:54   ` Nicolas Goaziou
2021-05-28 16:13     ` Bruce D'Arcus
2021-05-28 16:14     ` Timothy
2021-05-28 17:11       ` Nicolas Goaziou
2021-05-28 17:32         ` Timothy
2021-05-28 17:38           ` Nicolas Goaziou
2021-05-28 17:54             ` Timothy
2021-05-28 18:26               ` Bruce D'Arcus
2021-05-28 19:40                 ` Nicolas Goaziou
2021-05-28 20:31                   ` András Simonyi
2021-05-29 13:52                     ` Bruce D'Arcus
2021-05-29 16:22                       ` Nicolas Goaziou
2021-05-30 13:17                         ` Bruce D'Arcus
2021-05-30 20:20                           ` Nicolas Goaziou
2021-05-31 23:44                             ` Bruce D'Arcus
2021-05-31 17:46                         ` András Simonyi
2021-06-05 17:16                         ` Nicolas Goaziou
2021-05-29  7:51                   ` Stefan Nobis
2021-05-29 14:08                     ` Bruce D'Arcus

Code repositories for project(s) associated with this inbox:

	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).