[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

wip-cite status question and feedback

From: Bruce D'Arcus
Subject: wip-cite status question and feedback
Date: Tue, 7 Apr 2020 11:15:15 -0400

Hi everyone; first post.

From what I can tell, there was a lot of activity here a few years back to define org citation link support, which was reflected in what seems to be a fairly developed wip-cite branch of the git repo.

But that stalled somewhere, and we still have diverse tools, using diverse and incompatible methods to define citation links. 

I see from the archive there was an encouraging thread from April of 2018 (so, two years ago) that seemed to suggest merging to master was close, with perhaps some uncertainty around syntax being the primary hold up?

My main question: how do we get this done?

I'm happy to help resolve any syntax questions, if that's the primary hold up, though my coding skills in general are minimal.

While I’m here, some feedback and thoughts below. I think the proposed syntax is basically sound, but maybe could be simplified.

For background, I created the Citation Style Language (CSL), and the initial XSLT-based proof-of-concept formatter, which I used to format the citations and bibliography in my first book.

I work in a field that has pretty diverse citation practices, and myself work at the borders of the social sciences and humanities, which influences my thinking on design priorities around citation technology.

I also had a hand in the pandoc citation syntax, which is consistent with the basic design goals I had, including:

  1. simple as possible plain-text format, consistent with markdown

  2. prefix and suffix free text, page number locators, etc.

  3. ability to radically change output style (for example, from author-date to footnote-based), without changing source.

I believe the pandoc syntax achieves all of these goals.

Which brings me to the org proposal. 

The only documentation I can find on the proposal is at the citeproc org project.


If the above is correct, then:

  1. There are two forms of citations: short and long.

  2. Short is of this syntax, and can only have a single citekey as content: [@doe2019].

  3. Anything else (multiple citations, locators, prefixes and/or suffixes) requires the long form.

  4. In addition, there is a standard long form, and what the doc above calls “parenthetical” form of the long form.

So do I have all that right?

First question: 

Why #4 above; a distinction between two different long forms?

Moving on, assuming the above is correct, let’s borrow these examples from the pandoc citation syntax for markdown (which it also supports in org):

Blah blah [see @doe99, pp. 33-35; also @smith04, chap. 1].

Blah blah [@doe99, pp. 33-35, 38-39 and *passim*].

Blah blah [@smith04; @doe99].

So from a model perspective, a citation in pandoc is a list of one-or-more cites (or whatever we want to call them), each of which has optional:

I believe this is similar to the proposed org model, with one difference: the org proposal adds prefix and suffix for the list (the citation) as a whole. 

So the pandoc version is a flat list, and the org version has two levels.

Am I still understanding everything correctly?

So ... am I correct that in none of these cases can one use the “short” form, and that the above would look like this converted to the proposed org syntax?

Blah blah [cite:see @doe99 pp. 33-35; also @smith04 chap. 1].

Blah blah [cite:@doe99 pp. 33-35, 38-39 and *passim*].

Blah blah [cite:@smith04; @doe99].

Or the first one might treat the “see” as a prefix for the list, though I’m not sure what the practical benefit of that more hierarchical modelling is.

While I do wonder if the syntax could be simplified, my main hope is that it actually gets merged to master and deployed, to harmonize the variety of different ways emacs tools (org-ref, ebib, pandoc, etc.) are dealing with citation links in org currently.

reply via email to

[Prev in Thread] Current Thread [Next in Thread]