all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
From: Nicolas Goaziou <mail@nicolasgoaziou.fr>
To: Org Mode List <emacs-orgmode@gnu.org>
Cc: "András Simonyi" <andras.simonyi@gmail.com>
Subject: [wip-cite-new] Initial implementation of `csl' citation processor
Date: Wed, 26 May 2021 22:33:02 +0200	[thread overview]
Message-ID: <87y2c1dym9.fsf@nicolasgoaziou.fr> (raw)

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


             reply	other threads:[~2021-05-26 20:40 UTC|newest]

Thread overview: 43+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-05-26 20:33 Nicolas Goaziou [this message]
2021-05-26 21:11 ` [wip-cite-new] Initial implementation of `csl' citation processor 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

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=87y2c1dym9.fsf@nicolasgoaziou.fr \
    --to=mail@nicolasgoaziou.fr \
    --cc=andras.simonyi@gmail.com \
    --cc=emacs-orgmode@gnu.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this external index

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

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.