wip-cite status question and feedback

["Bruce D'Arcus" <bdarcus@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 4215 bytes --]

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
<https://lists.gnu.org/archive/html/emacs-orgmode/2018-04/msg00336.html>
(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.

https://github.com/andras-simonyi/citeproc-org#citations

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
<https://pandoc.org/MANUAL.html#citations> (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:

   -

   prefix
   -

   Locators (page numbers and such)
   -

   suffix


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.

[-- Attachment #2: Type: text/html, Size: 20288 bytes --]