Re: [O] Citation syntax: a revised proposal

[Aaron Ecay]

Hi Nicolas,

Thanks for implementing the parser support.  I decided to go ahead and
see what I could make of it.  The result has been pushed to the org mode
repo to the branch wip-cite-awe.  (I didn’t want to push to your branch
without asking, but if you prefer I’ll do that and delete my own.)

First I’ll describe two minor issues with the parser support I
uncovered.  Then I’ll go on to describe what the code I’ve written does.

The first issue is that the parser includes trailing punctuation in
“bare” @key citations.  So the following does not work as expected (the
:key includes the period): “This was demonstrated most recently by
@Smith2015.”  I’m not sure what the right approach is – one option
would be to say that keys can contain punctuation, but must end (and
begin) with an alphanumeric character.

The second issue is that the :key property of the citation element
includes the @.  This is not right IMO: it’s a detail of the syntax.
And it means that consumers of the syntax, who might want to look up
the key in a database, will always have to remember to strip the @.
I’ve pushed a provisional fix for this in my branch.

=====

The code I have pushed introduces three document-level keywords: BIBDB,
CITATION_MODE, and CITATION_STYLE.  Each of these has a corresponding
extension point in the code: org-export-cite-add-lookup-type,
org-export-cite-add-citation-mode, and
org-export-cite-add-citation-style.

Lookup types are concerned with mapping from a key to bibliographic
information.  Currently an org-bibtex lookup is implemented.  Others
that could be added straightforwardly are bibtex and the internet DOI
resolver as described here:
https://tex.stackexchange.com/questions/6848/automatically-dereference-doi-to-bib

Citation modes are responsible for formatting the in-text citation
(usually, a reference to a full citation stored elsewhere).  Currently a
crude author-year style is implemented.  Footnote and numbered citations
could both be added with relatively little effort (I think), though
they’d be a bit more complicated because they require keeping track of a
counter.

Citation styles are responsible for formatting the citation in the
bibliography (or footnote, or wherever the “full” citation lands).
Currently a hyper-simple one is implemented that just outputs the
author, year, and title.

I’ve attached a zip file to this email which contains a very simple org
document, a very simple bibliography, and the results of exporting it to
HTML (body only), plain text, and Latex.  (These are the only three
supported backends so far).

The code is very rough and ready, has lots of TODO comments in it, is
missing tests, documentation in the manual, etc.  Nonetheless, I want to
get feedback on it early, given that many people have already contributed
so much useful information to this discussion.

The two main questions that arise for me at this point are:

-> How much is it worth trying to keep latex and the other backends
together.

The current implementation uses some common functions (in ox-cite.el)
for all backends, including latex.  However, latex basically does its
own thing.  So it would be possible to include in ox-cite only code for
non-latex backends, and then implement latex citations solely in
ox-latex.  Separation would make the initial implementation very
simple.  On the other hand, I worry that it would perpetuate the present
situation where latex and non-latex citations are two separate
universes.  On the third hand, serious latex users will probably just
say you should use latex of you want nice citations, since latex is so
much better.  ;)

-> How much of the non-latex citation code is it worth implementing in
elisp.

One quick strategy would be to depend on citeproc-java
<https://github.com/michel-kraemer/citeproc-java>.  This can generate
bibliographies in HTML format from a bibtex file, which can be parsed,
turned into org syntax, and used wherever they are needed.  However, it
introduces a hard dependency on this program.  Is it worth trying to put
together a bare-bones elisp implementation, so people can have
dependency-free bibliographies?  My inclination is to say “no,” to avoid
duplicating the considerable effort put into the CSL universe (over
7,000 citation styles available!).  However, it also seems a bit wrong
to have a core feature depend on a third party executable.

(How much it would slow down export to continually shell out to an
external program is also an open question.)

=====

I didn’t try to do anything about support for editing/inserting citations
within org mode.  It would be good to know whether John Kitchin is willing
to contribute bits of his org-ref code for that.  (I see on Worg that he
has an FSF assignment on file, but I don’t want to take without asking –
or do porting/integration work that he’s happy to do himself!)

Thanks,
Aaron

PS the code uses relatively new functions from the subr-x and let-alist
libraries, so it probably works best on a recent-ish (past few months)
trunk version of emacs.

org-citations.zip
Description: Zip archive

-- 
Aaron Ecay