Re: wip-cite status question and feedback

[Nicolas Goaziou <mail@nicolasgoaziou.fr>]

Hello,

András Simonyi <andras.simonyi@gmail.com> writes:

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

No, I removed them in last year's iteration, because they are prone to
false positives. I didn't want to repeat the footnote syntax mistake,
when "[1]" was equivalent to "[fn:1]".

I am also leaning towards removing the possibility to include Org syntax
(e.g., bold) in prefixes/suffixes. Indeed, this doesn't sound terribly
useful (you can move the bold part outside of the citation object), and
yet, adds a layer of complexity on top of the citation object.

Can we assume (global)prefix/suffix are just plain text?

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

In my mind, "opening" leads to the bibliography reference, not to the
original document. IIUC, in this situation, the location does not matter
much, does it?

In any case, Org has no clue about the "location" of the citation. It
can provide the suffix associated to the citation key, but it is up to
the citation processor to extract page information out of it. If this is
desirable, we need to provide the full citation object instead of the
key. I don't know if it is worth the trouble.

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

I had a quick glance at citeproc-org for inspiration. I agree this is
a sane way to proceed.

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

I think it should be rendered as target format, to be on par with
citation handling.

You may, however, use Org format as an intermediate step, and then, call
`org-export-data-with-backend' (from "ox.el") on it. If this is
desirable, I need to also provide a fifth `info' argument to the list
above.

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

I don't think any addition to the suggested API is required. If you
cannot split citation processing, you may fill a temporary cache holding
all exports on first citation (the full list of citations objects is
provided right from the start), then read from that cache on subsequent
citations.

WDYT?

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

Noted.

IIRC, `org-export--footnote-reference-map' deals with a similar issue,
i.e., how to apply a function on footnote references _in order_.

Situation in nested footnotes can be ambiguous, tho. In the following
example, is the expected order @a then @b then @c?

--8<---------------cut here---------------start------------->8---
Text[fn:1] [@cite:@c]

[fn:1] This[fn:2] is [cite:@b].

[fn:2] [cite:@a]
--8<---------------cut here---------------end--------------->8---

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

I don't understand what you call the "identity of the notes". Could you
provide an example?

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

OK. Citation object and list of bibliography files as arguments are
a starting point.

>> 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?)

I don't have an idea about it either. This is not a blocker, tho. We can
revisit it later, once we have "something" working.

Thanks for your feedback.

Regards,
-- 
Nicolas Goaziou