Thank you for this thorough reply, Nicholas! See below.
On Tue, Apr 7, 2020 at 1:51 PM Nicolas Goaziou <m...@nicolasgoaziou.fr> wrote: > > Hello, > > "Bruce D'Arcus" <bdar...@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. 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
