Re: wip-cite status question and feedback

[Bruce D'Arcus]

Thank you for this thorough reply, Nicholas!

See below.

On Tue, Apr 7, 2020 at 1:51 PM Nicolas Goaziou <address@hidden> wrote:
>
> Hello,
>
> "Bruce D'Arcus" <address@hidden> 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.

OK, gotcha. That does explain the "hold up."

I'll come back to this below, but for now simply say that ideal would
probably be a default formatting library and database, with room to
replace with other options.

For the database, it would make to do as existing tools do; allow
users to define default bib(la)tex files.

[snip]

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

OK, that's good.

Note that in CSL processors, the locators are meaningful key-values,
basically; not plain text strings.

This is because different citation styles have different requirements
for rendering them.

Description from the spec:

a cite-specific pinpointer within the item (e.g. a page number within
a book, or a volume in a multi-volume work). Must be accompanied in
the input data by a label indicating the locator type (see the
Locators term list), which determines which term is rendered by
cs:label when the “locator” variable is selected.

And this is the list of CSL locators keys:

http://docs.citationstyles.org/en/stable/specification.html#locators

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

While I of course can't speak for John, I would hope and expect org
ref to support the new syntax.

I would hope and expect the same of other packages (like ebib) that
use their own custom syntax.

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

I hadn't considered that.

I'm thinking two options:

1. just have a super simple citation export formatter, with (per
above) room to configure an external one

2. while I don't know its status, include citeproc-org in org and emacs

I'd say if citeproc-org is far along and free of substantial bugs, 2
might make sense. I am, of course, biased, but CSL's been widely
deployed in the wild for more than a decade, and there are thousands
of available styles.

Otherwise, and more likely, 1 would be the best path; users get basic
output formatting for citations, but then can plug in more elaborate
tools (citeproc-org, citeproc-hs*, etc.) if they need them.

Obviously, if a user is exporting to LaTeX, the formatting is
straightforward, because you're just exporting to the latex cite code,
as pandoc does (though it also has an option to use citeproc to
produce "cooked" formatted output in latex).

For HTML, the output doesn't need to be anything fancy.

So the #1 path is the more iterative approach to implementing the functionality.

WDY about that?

Bruce

* citeproc-hs is a newer effort, funded by zotero, to create a very
high performance, fully compliant, CSL implementation, that is easy to
embed and use pretty much anywhere; I haven't checked on the status
recently, but I'm optimistic this will be the best option long-term

Bruce