Re: wip-cite status question and feedback

["András Simonyi" <andras.simonyi@gmail.com>]

Dear All,

apologies for being this late with my reaction --  here  are some
comments/questions on Nicolas's summary:

On Mon, 12 Apr 2021 at 15:19, Nicolas Goaziou <mail@nicolasgoaziou.fr> wrote:

> suffix" are all optional. So, in its minimal form, it can be as simple
> as:
>
>   [cite:@Doe:1995a]

are short-form citations like @doe2018 or  [@doe2018] also supported?

> Now about the API, which is partly implemented on a local branch.

>   - "opening" action is straightforward. All is needed for the processor
>     is to provide a function accepting two arguments: the citation key,
>     as a string, and possibly a universal argument, which it may ignore,
>     or not.
>
>     All this is already implemented locally.

I can imagine situations in which the location (e.g. page range) of
the citation is also important, e.g., when the
processor opens the cited document, so it'd be nice to pass this
information (when available) as well.

>     First, export happens as pre-process, before export back-ends are
>     introduced. IOW, export back-ends are never going to see a citation
>     object, which means no support whatsoever is needed on their end.

This is pretty close to how citeproc-org operates right now.

>     Support export requires two functions. The first function is
>     responsible for rendering a bibliography. Its arguments are the list
>     of citations in the document, the list of bibliography files, the
>     style, if any, and the export back-end. It should return a string.

Am I correct in assuming that the returned bibliography should be
rendered as a legitimate Org fragment regardless of the back-end?

>     The second mandatory function is obviously responsible for rendering
>     citations. It is called with a citation object, the desired style,
>     if any, and the export back-end, the full list of citations objets
>     in the document, and the list of bibliography files. It should also
>     return a string. Org provides a helper function to determine the
>     footnote containing a citation (and its label, or number) from
>     a citation object.

This might not be an important point, but citeproc-el is rather
citation list oriented in the sense that it processes the list of all
citations and returns a list of their formatted counterparts, so it
might be useful to provide this "bulk" API as well, at least as an
optional addition.

What is very important and was rather tricky to implement as I recall
is that the list of citations should be in the order they actually
appear in the exported document even for citations in footnotes,
because certain styles format citations differently if another
reference to the same work occurred in a nearby, earlier note. In
addition to the precise order of the citations and whether they are in
a footnote or not, the concrete identity  of the notes is also
important, because formatting can differ depending on whether two
citations are in the same note or in different ones.

>   - "fontification" is meant to give full access to face selection, what
>     is really displayed, additional keymaps, all using a single
>     function.

>     At the moment, I have no idea about what arguments would be useful.
>     I think John Kitchin gave ideas about this already on this ML.
>     I have to re-read his posts on the subject. In any case, feedback
>     welcome.

I'm thinking about implementing a "fontification" solution which would
use citeproc-el with a standard style to produce nice preview-like
representations of the citations in the buffer. This would require
basically the same pieces of information as citation export I think,
although it might be made strictly  local, working only with the
single citation object plus the bibliography information. Providing
really precise previews is probably out of scope here,because some
details depend on global information about other citations which can
frequently change and would be difficult to keep up-to-date.

> A citation processor does not need to provide integration in all these
> areas. Users may be able to mix and match processors. This is another
> (minor) point which is yet to be designed. How is a user supposed to
> select a processor for each integration area? It could be done through
> three variables, e.g.,
>
>   (setq org-cite-display-processor 'org-ref)
>   (setq org-cite-export-processor 'citeproc)
>   (setq org-cite-follow-processor 'default)
>
> I think it is unlikely for a user to locally select "display" and
> "follow" processors. However, we need a way to use a local export
> processor for a given document. I may need to introduce
> a #+citation_processor keyword during export. Any other idea?

All of these solutions seem to be good starting points.  As for
setting the "display" and "follow" processors locally, this leads to a
question which probably has to be addressed at a certain point: that
of bibliography formats. The Emacs world is currently rather BibTeX
centered, but biblatex is an important (and rather different)
alternative, and there is CSL as well which I expect to become more
and more relevant (it's citeproc-el's native format). Moreover, these
formats have some variants, e.g., for BibTeX there is also org-bibtex,
for CSL there is CSL-JSON and a CSL-YAML etc. If different "display"
and "follow" processors will be able to handle different formats then
the users might want to change those settings locally as well, based
on the bibliography format, but I'm not sure what kind of
infrastructure would be the best way of supporting this. (E.g.,
registering format support information about the processors and
choosing on this basis?)

> The last step is implementing a default processor. The point is to
> provide a self-contained, very basic processor handling all three areas
> described above.
>
> I started implementing one. It relies on built-in bibtex.el library, so
> it assumes bibliography is written as a BibTex file. At the moment it
> properly "follows" citations. It also exports citations as (Name, date).
> However, it doesn't export bibliographies yet. It does not fontify
> either.
>
> As a conclusion, besides the syntax, the branch is not ready for
> inclusion yet. There are a few design questions about the API to answer.
> Once done, and as long as no one has high expectations about the default
> processor, this last part should not be too hard to complete.
>
>
> Regards,
> --
> Nicolas Goaziou

Thanks again for working on this and best regards,
András