Re: citations: org-cite vs org-ref 3.0

[Max Nikulin]

On 23/03/2022 06:52, Nicolas Goaziou wrote:
> Max Nikulin writes:
>
> > Another point is more serious. Besides citations there are internal
> > cross-references. Org supports them but only in a rudimentary form.
> > Actually cross-references are similar to citations in the sense that
> > they can have style, prefixes and suffixes, and their appearance
> > depends on target properties. Another feature is grouping. However
> > cross-references should not be handled by citation backends, they
> > require different handlers. Unfortunately there is no way to define
> > custom "citation" type e.g. "[ref:...]" in addition to "[cite:...]".
>
> There is too little information here for me to understand what
> cross-references (or grouping) are, or why they would require different
> handlers. In any case, if such thing are deemed necessary in Org Cite,
> one can always start a new thread.

Frankly speaking, for me it was enough just to use available LaTeX 
commands. I never thought about corner cases, but feature request 
requires such analysis.

By grouping I mean the existing feature of org-cite: several keys with 
common prefix and suffix, items within such group may be sorted.

Citation handlers obtain information necessary for formatting from a 
bibliography database. For cross-references such additional info should 
be pulled from other parts of the same document. There is no point to 
mix the code for both cases withing the same handler, it is better to 
combine independent handlers and to allow each type to have alternative 
implementations. I agree with those who say that cross-references and 
citations are rather independent when implementation is considered.

Judging from the description, org-ref (with org-refproc as an optional 
addition) does the job taking advantage of multiple custom link types 
for the same actual standard internal link target.

Sphinx has a feature that is an interesting border case between internal 
cross-references and external links (almost citations). Readthedocs 
sites host mapping tables for python packages. It is possible to fetch a 
file that associates e.g. anchors and section names. In generated docs 
anchors (similar to custom_id values) are replaced by section names and 
link target points to particular location in the external file.

Nicolas, concerning a new thread, I have an impression that you are busy 
with over activities since you are participating in discussions not so 
frequently. So I am unsure at which moment it is appropriate to raise 
such question that otherwise may just be buried in the list archive. 
Sometimes I am in doubts if an idea deserves a dedicated thread or 
initial feedback may be received from a related rather generic topic.

> > To assign additional properties, info "(org) Links in HTML export"
> > https://orgmode.org/manual/Links-in-HTML-export.html recommends usage
> > of "#+ATTR_HTML", but such technique has several issues:
>
> This is a different issue. Citations are not link, and have a fixed set
> of properties.

Outside of Org, citations are links. Along with cross-references they 
worked before appearance of the web. To be recognizable on paper they 
may have a bit special form. An author may choose what will appear in 
the text: page number, section number, or section text. For HTML links 
page number option is not meaningful.

Within Org citations look like generalized links: a citation may have 
multiple targets, they have more properties: prefixes, suffixes 
(including common ones), style, and locators. However there is no 
description.

Internal links in Org (built-in ones without additional packages) are 
more limited than full-fledged cross-references. When exported they have 
the same form.

I consider fixed set of properties as a problem. At first I tried to 
draw attention to additional link attributes. Then I realized that 
block-level elements may have arbitrary attributes. It would be a great 
feature to have some syntax construct to assign attributes for 
particular inline object. People actively use link types as an 
additional property, but it gives just one degree of freedom. Sometimes 
more parameters are required and abusing link types means combinatorics 
explosion. Encoding extra properties inside link targets sometimes is 
enough (as in org-ref) but some times it is inconvenient.

Advantages of arbitrary attributes for inline objects for links:
- Within the same paragraph only part of links may be marked as 
"nofollow noopener" during exporting to HTML.
- Each link may have its own title.
- Link types similar to org-ref cross-references ("pageref", "nameref", 
"eqref", etc.) becomes an extra attribute while link type and link 
target remains the standard one for Org (heading text, custom id, name 
attribute).

For citations some values may be passed to specific citation backend 
overriding default value derived from style. It should be similar to 
babel header arguments specific to particular language or export options 
for particular format.

Leaving groups aside, attributes for inline objects may be a convenient 
extension.