Re: wip-cite status question and feedback

[Nicolas Goaziou <mail@nicolasgoaziou.fr>]

Hello,

"Bruce D'Arcus" <bdarcus@gmail.com> writes:

> Hi everyone; first post.

Welcome!

> 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?

Good question. I don't think syntax is the primary hold up. It seems to
me that the glue part between the parser and the export back-ends is
missing. If we merge wip-cite branch in master, where do we plug it? How
do Org folks use it, out of the box? It also need tooling. For example,
citations could be a link to a database.

Of course, that doesn't mean the syntax is perfect, but as it is,
I assume it theoretically goes a long way towards solving most citation
needs.

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

Actually, the coding part is the easiest one. I can help on that part.
Unfortunately, I do not use citations, so I cannot speak for the people
who would make use of them in Org.

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

Great!

> 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?

You do.

> First question:
>
> Why #4 above; a distinction between two different long forms?

I think this is because you may want to mix two styles in the same
document: inline and parenthesised. I think the idea comes from BibTeX.

> 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?

Org syntax has no notion of locators. Is that an issue for later
interpretation?

It just uses optional prefix and suffix around keys. The "(prefix) key
(suffix)" is called a citation reference. A full citation may contain
one ore more citation references, separated by semicolons.

You are right about the global prefix and suffix. I'm not sure why they
are here, but were probably suggested at some point.

If there is no practical use for them, we can also drop them.

> 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?

True. I think the short form is just a quick reference that should be
expanded in a predefined style, e.g., "(author, year)".

> 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].

Actually, barring the "cite:" prefix, you can use the exact same syntax
as Pandoc, i.e.:

  [cite:see @doe99, pp. 33-35; also @smith04, chap. 1]
  [cite:@doe99, pp. 33-35, 38-39 and *passim*]
  [cite:@smith04; @doe99]

Only the semicolon is meaningful in there, not the commas. Also, for
readability, spacing after the "cite:" prefix is ignored, so one can
write, e.g.,

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

> 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.

No, IIRC, the common prefix is the part before the first semicolon, but
only if that part contains no citation key. IOW, in the example above,
"see " is the prefix of the first citation reference, not a global
prefix.

> 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.

If the syntax is practical, we could merge it, yes. Maybe that's the way
forward, after all. But then? What library is going to use it?

Org Ref is well established and is unlikely to switch to the new syntax.
It would be nice if both syntax could converge at some point, though.
The point of the new syntax is to make it easier for this kind of
extension.

"citeproc-el" is not included in Emacs, so integrating "citeproc-org" in
Org may not be helpful at this point. Since Org is bundled with Emacs,
it cannot use external libraries.

WDYT?

Regards,

-- 
Nicolas Goaziou