Re: [O] Citations, continued

[Richard Lawrence]

Hi John and all,

John Kitchin <address@hidden> writes:

>> As for the first problem, I think a good case can be made for adding new
>> syntax to Org to represent citations, instead of repurposing/extending
>> existing syntax (most notably, the link syntax).
>>
>
> I think links are remarkable flexible, and solve most of the pre/post text
> issue. You can use literal links if you don't want to see them collapsed.

I agree; links *are* remarkably flexible.  But I think that's actually
sort of the problem in this case.  It's easy to use the link syntax to
implement a solution for citations that is `good enough' for 80+% of the
use cases.  That becomes a barrier to adopting something which better
advances the goals of Org and its users.

If I was implementing a citations solution just for my own Org
documents, I would do it exactly the way org-ref does: use the link
syntax, and put the pre- and post-text in the description, with a
separator that's easy to remember, like

[[cite:Doe1999][See::for an overview]] 

or more realistically: 

[[cite:Doe1999][Cf. a recent discussion in::, on sluicing.]]

Does this work?  Yes.  Is it easy to implement on top of the existing
features?  Yes.  Again, for my own personal use, this is exactly what I
would do.

But I would not want to see this syntax canonized as the official Org
citation syntax.  It feels like a hack, not a proper solution, and it
definitely strikes me as less readable than

[Cf. a recent discussion in @Doe1999, on sluicing.] 

especially if you have the default setup, where the URLS of links that
have a description part are hidden.

My point is not that the link syntax *can't* do enough.  Rather, my
point is that citations are conceptually distinct from links, and if we
are going to adopt an official syntax for them, that syntax should
reflect this conceptual distinction.  This is better for document
authors, because it is less work for us.  It gives us the right tool for
this particular job, instead of re-purposing a tool that, despite its
power, is designed for a different job.  It is thus better for the Org
community as a whole.

>> Moreover, citations are not really links, even though it is often useful
>> to treat them (or parts of them) as links.  For example, a link can only
>> point to one target; yet a single citation often points to multiple
>> sources.  And what if you need different pre- or post-text for different
>> sources within the same citation, like ``See @Doe1999 for an overview; a
>> more extensive discussion is in @Foobar2000''?
>>
>
> An org link can point to many targets. An org-mode link executes code,
> which can give you many options to consider. In your example, I would
> consider that two citations. Even a single cite link in org-ref considers
> each comma-separated key a separate clickable entity; the code figures out
> which key you clicked on, and gives you several options of what to do with
> it, like open the entry, the pdf, etc... which it figures out how to do
> based on the key.

This is a good example of how extending the link syntax to citations
will end up obscuring important conceptual distinctions, which makes
more work for the user.  

Normally, when you click on a link (or follow it with C-c C-o), you
don't have to pay attention to /where/ on the link you click.  By making
citation keys significant sub-parts of a link, you force the user to
always pay attention to this for every link, at least until he or she
determines whether the link is a citation link or a `real' link.  (If
that doesn't seem like a big deal, consider how it would affect someone
who edits Org documents using a screen reader.)

A link has two significant parts: a URL, and a description.  A citation
potentially has at least three significant parts for each work it
references (key, pre-text and post-text).  

I am certainly not opposed to having parts of citations exhibit
link-like behavior, though.  I think it would be great if one could
`follow' each reference key within a citation to do something useful
with it, as org-ref does.  I just think the link syntax is not the right
underlying syntax to express this.  It does not contain enough
significant parts -- and giving it more significant parts makes links
into something else.

> How does the pandoc syntax handle different link types. e.g. the 40ish
> different types supported by biblatex? Links manage this easily, and with
> the export framework, you can convert them to all kinds of other formats.
> It looks to me like the pandoc syntax is too simple for that.
> ...
> I think you need a citation type for the backend, because you often need
> more than one type in a document, e.g. the regular citations, sometimes a
> citation number, author or year.

Yes, I agree here.  As far as I can tell, the Pandoc syntax does not
handle different types of citations within the same document, except
in a limited way, via the distinctions between

Smith says blah address@hidden, p. 3].
@Smith99 [p. 3] say blah.
Smith once thought foo address@hidden, but now thinks bar address@hidden

which basically correspond in the LaTeX world to natbib's \citep,
\citet, and \citeyear in the default (Chicago) citation styling.  Pandoc
does not map these different citation types to LaTeX commands directly,
though.  Instead, it formats citations using citeproc-hs' implmentation
of the Citation Style Language, then inserts the resulting text into the
document where the citation is supposed to appear.

I agree that some sort of fallback may be needed so that you can
instruct the LaTeX exporter, in particular, which command to use for a
given citation.  

But Org is a document format, not a nicer-looking frontend for LaTeX (as
other people on this list have had to remind me in the past!).  The
official syntax should distinguish between citations, on the one hand,
and instructions to particular backends for formatting them, on the
other.  Users should not have to learn the vagaries of LaTeX citation
commands in order to represent citations in an Org document. 

There is existing syntax for giving instructions to particular export
backends about how to format Org elements: the #+ATTR_BACKEND syntax.
Something like this is the right way to pass citation formatting
information to LaTeX when needed.  Unfortunately, this can't be applied
to inline citations directly, so something else is required.  I have an
idea about how to do this, which I will post when I finish writing it
up.

Best,
Richard