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

[Bruce D'Arcus]

On Sun, Mar 27, 2022 at 3:41 PM John Kitchin <jkitchin@andrew.cmu.edu> wrote:

...

> Regarding that org-cite adds an abstraction layer, how else could one
> interpret this (from
> https://blog.tecosaur.com/tmio/2021-07-31-citations.html#cite-syntax)
> other than abstraction:
>
> [cite/na/b:@key] or [cite/noauthor/bare:@key] to mean \citeyear{key}?
>
> Why wouldn't it be \citetitle? or \citeurl, or \citedate? or even,
> \citenum?

You mean why shouldn't we privilege natbib, as you have in org-ref?

And let me turn the question around: how would you propose to
translate those natbib-derived commands to biblatex, or CSL, so it
works reliably across users and documents? The mapping has to happen
someplace, after all.

And from a UX POV, how well would that work for users who have no
previous experience with natbib or even latex?

...

> It might be a social problem, and I do not think it is trivial to solve.
> It is not just about having a syntax that works. I wrote and shared a
> whole set of processors for org-cite that did or tried to do all those
> things above. It was fine to use, but it was very difficult code to
> write for me. I don't personally want to support it in part because it
> was so difficult to write.

I think what Nicolas is asking is when you have time, to itemize the
pain points that made development difficult for you, so that we might
figure out how to improve them (perhaps new helper functions, etc.).

As another data point, one of the things I've loved about org-cite is
how easy I found it to develop pretty functional processors for citar
with minimal code. Total LOC for citar is just under 2000, with just
under 400 specific to org.

But I'm deliberately developing a small, focused, modular, package.

...

> Some motivation for org-cite stemmed from at least perceived limitations
> in org-ref, especially related to pre/post notes and CSL support. I
> think it is totally reasonable to learn if those were real limitations
> or not.

The org-cite citation syntax and model, I hope you would agree, is
unambiguously better than natbib or the original org-ref syntax. It's
simpler than biblatex in the sense of no difference between single and
multicite citations, but can easily and losslessly map to and from
either.

Org-ref 3.0 adds essentially a copy of that syntax and model, with a
trivial difference.

To me, that's the biggest problem. Aside from users having
incompatible documents, it forces other developers either to dedicate
additional development and maintenance time to supporting both
syntaxes, or to choose one.

Pandoc only supports org-cite.

In the case of citar, I have also decided to only support org-cite
(though I leave the function to generate citations configurable, so
it's easy enough for a user to configure this themselves; but I don't
include this by default because I have other processor code that
relies on parsed citations).

Org-roam supports all three.

It sounds like the biggest hold up was with reconciling the org-ref
command model with more general approach of the oc style and variants.

But as a first step, you could do as you originally planned to: simply
use the same names for styles. If Nicolas were to allow the mapping in
natbib to be handled via the defcustom, you could even do this without
having to write and maintain your own export processor.

And then you could save the other part (how to map those to other
export processors) for another step, if and when you or your users
need it or want it.

Certainly that would address the most fundamental incompatibility.

I guess to be direct: what value does the v3 syntax provide you, your
users, or the org ecosystem in general?

Bruce