Re: [O] Citation syntax: a revised proposal

[Richard Lawrence]

Hi Aaron and all,

Richard Lawrence <address@hidden> writes:

> I'll take some time this weekend to see if I can wire this together with
> the Elisp Aaron wrote for the Org exporter side.

I've had some success with this.  I would not say that my efforts are
complete yet, but I thought I should send an update to let everyone
know.  I've published a branch here:

https://github.com/wyleyr/org-mode

which derives from Aaron's wip-cite-awe branch.  Basically, what I've
been able to do so far is process citations in a document via
org-citeproc, using a bibtex database file, then insert the processed
citations and bibliography in the document during export.  (In theory,
this should work with org-bibtex too, though I think I may have
introduced a bug...the library is not producing well-formed bibtex from
org-bibtex entries for me at the moment.)  It works pretty slick, at
least for the simple cases I've tested.
 
Aaron, now that I've had time to go through your code a bit more
carefully, here are a few comments:

In general, I like the design of the org-cite library!  It was pretty
easy for me to understand what's going on, and it was also pretty easy
for me to make it use org-citeproc, just by plugging in different helper
functions.  This speaks to the modularity of the code and a
well-designed API.  I like the general approach of pre-processing
citations via org-cite-export-prepare and stashing the information on
the info plist.  I also like the extensibility of the lookup types
mechanism.

I didn't quite understand all the code surrounding citation modes and
styles.  I didn't dive into this too much, because I just wanted to get
org-citeproc to process citations and produce a bibliography using a CSL
file.  Rather than figure out how to infer a CSL file from
CITATION_STYLE and CITATION_MODE, I just added a new keyword (CSL_FILE)
to allow specifying it directly.  I am not sure which approach is
better, but I certainly found it simpler to use CSL_FILE and let
org-citeproc deal with formatting.

(One relevant issue here, as you mentioned in an earlier post, is how
much we want to worry about keeping LaTeX and non-LaTeX backends in
sync.  If it's important that they stay very close, the high-level way
of specifying citation formatting via CITATION_STYLE and _MODE is
probably the way to go.  These can be mapped to a BibLaTeX style on the
LaTeX side, and a CSL file elsewhere.  It might still be good to have
low-level keywords like CSL_FILE and, e.g., LATEX_BIB_STYLE too.  The
LaTeX vs. non-LaTeX issue is also important for dealing with
multi-cites, which are not handled in this branch.  I am waiting to hear
back about the right way to get the list of references associated with a
citation before I tackle that.)

As for the lookup types mechanism, I think this works pretty well,
though I have one suggestion: lookup functions should just be
responsible for jumping to the entry referenced by a citation in a
BIBDB, not for returning data about it.  Returning data only really
makes sense if we need to produce a new bibliography file, as in
org-cite--make-bibtex, but there are better mechanisms for that case
(see org-bibtex-export-to-kill-ring).  Jumping to the referenced entry
enables this, and makes lookup functions useful interactively.

In general, I did find that the cl-lib idioms and other stuff from
external libraries made the code more difficult for me to understand
(though that's on me), and in at least one case, I had to do without one
of the libraries you are loading (namely, let-alist) to get the code to
run in a vanilla Emacs 24.  I would personally prefer it if this library
could stay away from bleeding-edge Emacs features, as I run Org from
master, but generally on an older Emacs (my main Emacs is the one in
Debian stable).

There are just a few points where I had to modify your code, or comment
it out, to get it to run in my setup.  As a result, I might have broken
some things due to lack of understanding.  In all cases, my intent was
just to make my new code run alongside the existing code via whatever
minimal change was necessary, not to remove what was working for you.

Best,
Richard