emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
From: Nicolas Goaziou <mail@nicolasgoaziou.fr>
To: "Bruce D'Arcus" <bdarcus@gmail.com>
Cc: emacs-orgmode@gnu.org
Subject: Re: wip-cite status question and feedback
Date: Tue, 07 Apr 2020 19:51:31 +0200	[thread overview]
Message-ID: <87o8s389r0.fsf@nicolasgoaziou.fr> (raw)
In-Reply-To: <CAF-FPGOkFoduNuNyN-Atsg21emqcVj2SXEkYp1XCfqum5y0MBg@mail.gmail.com> (Bruce D'Arcus's message of "Tue, 7 Apr 2020 11:15:15 -0400")

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


  reply	other threads:[~2020-04-07 18:04 UTC|newest]

Thread overview: 139+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-04-07 15:15 Bruce D'Arcus
2020-04-07 17:51 ` Nicolas Goaziou [this message]
2020-04-07 18:27   ` Bruce D'Arcus
2020-04-07 18:31     ` Bruce D'Arcus
2020-04-07 21:13     ` Joost Kremers
2020-04-08  0:01       ` Bruce D'Arcus
2020-04-08  9:16         ` Joost Kremers
2020-04-08  9:32     ` Nicolas Goaziou
2020-04-08 12:19       ` Bruce D'Arcus
2020-04-08 13:39         ` John Kitchin
2020-04-08 16:12           ` Bruce D'Arcus
2020-04-09  7:38         ` Albert Krewinkel
2020-04-09  9:30           ` Bruce D'Arcus
2020-04-09  9:46             ` Bruce D'Arcus
2020-04-09 10:05               ` Bruce D'Arcus
2020-04-09 23:17                 ` Nicolas Goaziou
2020-04-10  1:17                   ` Bruce D'Arcus
2020-04-10  5:38             ` Albert Krewinkel
2020-04-11 11:41       ` Bruce D'Arcus
2020-04-13 12:05       ` Gustav Wikström
2020-04-13 12:33         ` Bruce D'Arcus
2020-05-24 12:12           ` Bastien
2020-05-24 13:17             ` Bruce D'Arcus
2020-05-29 21:59               ` András Simonyi
2020-05-29 22:24                 ` Bruce D'Arcus
2020-05-29 22:58                 ` Bruce D'Arcus
2020-06-03 14:40                   ` Bastien
2020-06-03 14:53                     ` Bruce D'Arcus
2020-12-14 21:24                       ` Bruce D'Arcus
2021-03-24 13:22                       ` Bruce D'Arcus
2021-03-24 18:27                         ` M. ‘quintus’ Gülker
2021-04-11 23:15                           ` Bruce D'Arcus
2021-04-12 13:19                             ` Nicolas Goaziou
2021-04-12 18:53                               ` András Simonyi
2021-04-16 17:05                               ` András Simonyi
2021-04-16 17:23                                 ` Bruce D'Arcus
2021-04-18 13:11                                 ` Nicolas Goaziou
2021-04-18 13:35                                   ` Ihor Radchenko
2021-04-18 13:37                                     ` Bruce D'Arcus
2021-04-21 19:57                                     ` John Kitchin
2021-04-21 20:09                                       ` Bruce D'Arcus
2021-04-21 20:57                                         ` John Kitchin
2021-04-21 20:26                                   ` John Kitchin
2021-04-21 20:54                                     ` Bruce D'Arcus
2021-04-22  2:47                                     ` Timothy
2021-04-22 12:07                                       ` Bruce D'Arcus
2021-04-22 12:34                                         ` Timothy
2021-04-21 21:47                                   ` András Simonyi
2021-04-21 23:51                                     ` Nicolas Goaziou
2021-04-22  0:01                                       ` Bruce D'Arcus
2021-04-22  0:15                                         ` Nicolas Goaziou
2021-04-23 11:49                                           ` Nicolas Goaziou
2021-04-23 12:55                                             ` András Simonyi
2021-04-23 13:10                                               ` Bruce D'Arcus
2021-04-23 13:24                                                 ` Bruce D'Arcus
2021-04-23 14:50                                                   ` András Simonyi
2021-04-23 22:08                                                   ` Bruce D'Arcus
2021-04-24 17:37                                                   ` M. ‘quintus’ Gülker
2021-04-24 17:47                                                   ` Nicolas Goaziou
2021-04-24 18:39                                                     ` Bruce D'Arcus
2021-04-26 14:54                                                       ` Bruce D'Arcus
2021-04-26 20:35                                                         ` Denis Maier
2021-04-27 10:12                                                           ` Bruce D'Arcus
2021-04-27 10:20                                                             ` Timothy
2021-04-27 11:44                                                             ` Denis Maier
2021-04-27 12:32                                                               ` Bruce D'Arcus
2021-04-27 13:58                                                                 ` Denis Maier
2021-04-27 14:07                                                                   ` Bruce D'Arcus
2021-04-27 14:50                                                                     ` Denis Maier
2021-04-30 13:28                                                       ` Nicolas Goaziou
2021-04-30 21:47                                                         ` Denis Maier
2021-05-01 11:09                                                           ` Nicolas Goaziou
2021-05-01 13:26                                                           ` Bruce D'Arcus
2021-05-02 21:58                                                             ` Denis Maier
2021-05-02 22:18                                                               ` Bruce D'Arcus
2021-05-02 23:30                                                                 ` Bruce D'Arcus
2021-05-05 13:46                                                                 ` Bruce D'Arcus
2021-05-05 18:14                                                                   ` M. ‘quintus’ Gülker
2021-05-05 18:27                                                                     ` Bruce D'Arcus
2021-05-06 17:05                                                                       ` M. ‘quintus’ Gülker
2021-05-06  8:08                                                                     ` Denis Maier
2021-04-24 13:14                                               ` Nicolas Goaziou
2021-04-23 12:03                                     ` Nicolas Goaziou
2021-04-23 13:34                                       ` András Simonyi
2021-04-17 19:13                               ` M. ‘quintus’ Gülker
2021-04-18 16:17                                 ` Nicolas Goaziou
2021-04-20 13:32                                   ` Matt Price
2021-04-21 17:07                                     ` Nicolas Goaziou
2021-04-21 17:53                                       ` Bruce D'Arcus
2020-04-10  9:29 denis.maier.lists
2020-04-10 12:22 ` Bruce D'Arcus
2020-04-10 22:56 ` Nicolas Goaziou
2020-04-11 21:42   ` denis.maier.lists
2020-04-11 22:05     ` Bruce D'Arcus
2020-04-12 10:38       ` Nicolas Goaziou
2020-04-12 11:15         ` Bruce D'Arcus
2020-04-12 14:02           ` Nicolas Goaziou
2020-04-12 14:25             ` Bruce D'Arcus
2020-04-12 15:32               ` Nicolas Goaziou
2020-04-12 15:44                 ` Bruce D'Arcus
2020-04-12 15:57                   ` Nicolas Goaziou
2020-04-12 17:17                     ` Bruce D'Arcus
2020-04-12 20:49                 ` denis.maier.lists
2020-04-12 22:19                   ` Nicolas Goaziou
2020-04-13  8:33                     ` Stefan Nobis
2020-04-13 10:02                       ` Denis Maier
2020-04-13 10:11                         ` denis.maier.lists
2020-04-13 10:05                       ` Bruce D'Arcus
2020-04-13 10:14                       ` denis.maier.lists
2020-04-13  9:58                     ` Bruce D'Arcus
2020-04-13 10:09                     ` denis.maier.lists
2020-04-13 10:10                     ` Joost Kremers
2020-04-13 10:46                       ` Stefan Nobis
2020-04-15  5:54                       ` Richard Lawrence
2020-04-15 10:07                         ` Joost Kremers
2020-04-18  9:34                           ` Richard Lawrence
2020-04-18 10:56                         ` Bruce D'Arcus
2020-04-18 12:48                           ` Richard Lawrence
2020-04-18 13:17                             ` Bruce D'Arcus
2020-04-18 13:22                               ` Bruce D'Arcus
2020-04-18 20:23                                 ` Denis Maier
2020-04-18 20:28                                 ` denis.maier.lists
2020-04-19  9:11                               ` Richard Lawrence
2020-04-25 16:19                                 ` Nicolas Goaziou
2020-04-25 17:00                                   ` Bruce D'Arcus
2020-04-25 20:03                                     ` Nicolas Goaziou
2020-04-25 21:18                                       ` Bruce D'Arcus
2020-05-01 17:38                                         ` Richard Lawrence
2020-05-01 17:54                                           ` Bruce D'Arcus
2020-05-02 14:06                                             ` Nicolas Goaziou
     [not found]                                               ` <2fbf14cf-ae8c-4f7c-27f7-33771aa99492@mailbox.org>
2020-05-02 16:34                                                 ` Nicolas Goaziou
2020-05-02 17:24                                                   ` Denis Maier
2020-05-02 13:13                                           ` Nicolas Goaziou
2020-05-02 13:45                                             ` Bruce D'Arcus
2020-05-02 20:45                                             ` Richard Lawrence
2020-04-29  9:14                                   ` Denis Maier
2020-05-02  9:51                                     ` Nicolas Goaziou
2020-05-02 11:53                                       ` Bruce D'Arcus
2020-04-18 20:38                           ` Joost Kremers

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

  List information: https://www.orgmode.org/

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

  git send-email \
    --in-reply-to=87o8s389r0.fsf@nicolasgoaziou.fr \
    --to=mail@nicolasgoaziou.fr \
    --cc=bdarcus@gmail.com \
    --cc=emacs-orgmode@gnu.org \
    --subject='Re: wip-cite status question and feedback' \
    /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

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