Re: [O] Citations, continued

[John Kitchin]

 

Here's my personal opinion about how we might solve them.

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. Links already have a type, so they are easily differentiable from other links and elements. The only limitation I can see is your example below where I couldn't put two pre/post text citations in one link. I would write that as:

See cite:Doe1999 for an overview; a more extensive discussion is in cite:Foobar2000

if the pre/post text is really critical somehow, you can do this.

[[cite:Doe1999][See::for an overview]]; a more extensive discussion is in cite:Foobar2000

I guess this would also be ok in orgref:

[[cite:Doe1999][See::for an overview]][[cite:Foobar2000][; a more extensive discussion is in]]

Depending on your backend and citation style, it might be necessary to use Ref. citenum:Foobar2000 for it to look right on export.

Either way, none of these are more readable than the first one I think, and they would probably all render the same in any backend. 

Here's why.  Citations are complicated, and it's clear that some sort of
new syntax is needed to represent them.  Even link-based solutions
introduce new syntax `inside' the link syntax, such as using `::' to
separate pre-text and post-text in a link description, as org-ref does.
Thus, the issue is not *whether* there should be additional syntax, but
just *how constrained* it should be.  In particular, the question is
whether we want to make citation syntax a subset of link syntax, or
whether citations and links should be distinct types of syntactic
elements.

It seems to me that the needs of citation users are wide enough and
complicated enough that it is worth shedding the constraints imposed by
the link syntax.  Eventually, packing all the representations we need
for a general solution (citation type, pre- and post-text, suppressing
author name, etc. etc.) into the link syntax will tend to make citations
unreadable.

 

Making anything unreadable should be avoided at all cost!

 

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.

 

Finally, it seems to me that Org strives to be a document format which
is usable independently of any particular export format.  This counts in
favor of having citation syntax as a first-class citizen in Org; at
present, Org documents can only contain citations through a combination
of extensions and external tools.

For these reasons, I would support a separate citation syntax, but one
that can behave like a link when useful.  For example, suppose we
borrowed the Pandoc [ ... @key1 ...; ... @key2 ...] syntax.  When point
is on address@hidden', C-c C-o could be bound to find the key in the reference
database, or another useful action, depending on the reference database
format.

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. 

  '("cite" "nocite" ;; the default latex cite commands
    ;; natbib cite commands, http://ctan.unixbrain.com/macros/latex/contrib/natbib/natnotes.pdf
    "citet" "citet*" "citep" "citep*"
    "citealt" "citealt*" "citealp" "citealp*"
    "citenum" "citetext"
    "citeauthor" "citeauthor*"
    "citeyear" "citeyear*"
    "Citet" "Citep" "Citealt" "Citealp" "Citeauthor"
    ;; biblatex commands
    ;; http://ctan.mirrorcatalogs.com/macros/latex/contrib/biblatex/doc/biblatex.pdf
    "Cite"
    "parencite" "Parencite"
    "footcite" "footcitetext"
    "textcite" "Textcite"
    "smartcite" "Smartcite"
    "cite*" "parencite*" "supercite"
    "autocite" "Autocite" "autocite*" "Autocite*"
    "Citeauthor*"
    "citetitle" "citetitle*"
    "citedate" "citedate*"
    "citeurl"
    "fullcite" "footfullcite"
    ;; "volcite" "Volcite" cannot support the syntax
    "notecite" "Notecite"
    "pnotecite" "Pnotecite"
    "fnotecite"
    ;; multicites. Very limited support for these.
    "cites" "Cites" "parencites" "Parencites"
    "footcites" "footcitetexts"
    "smartcites" "Smartcites" "textcites" "Textcites"
    "supercites" "autocites" "Autocites"
    ;; for the bibentry package
    "bibentry"
    )

 

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. For a pandoc like link you could consider (adapted from the pandoc examples):

address@hidden,key2,key3

[optional pre text address@hidden optional post text]

or a group like this

[see address@hidden p. 34-35; also address@hidden chap. 3].

where optional text might include additional citations

address@hidden@key2, p. 30; see also Ref. address@hidden)]

I can't say I look forward to figuring out how to convert that to latex (or what the latex equivalent even is!)). There would have to be some mechanism to define new citation types, analogous to adding new link types. I suppose if org-element-map parsed these into data structures it might not be too bad.

These look alot like replacing : with @ in a link to me, but maybe the added flexibility is worth it. The simplest cases would act like links. Looking back at this, I am not seeing a critical advantage over the links, other than eliminating the :: separator in the description. Except for the last example. I would never dream of  writing a citation like that though! We never use pre/post text in citations in our work, and they don't even make sense with all citation formats, e.g. superscripted numbers. Maybe someone could provide some real life citation examples that links can't handle?

I suspect a lot of pre/post text issues can be solved manually as:

(see cite:key1, pg33-4; also cite:key2, chapter 3)

and you will get what you want in the output. 

I have no idea how hard it would be to implement something like that syntax. 

As I mentioned in the earlier thread, I think the Pandoc syntax is a
good place to start, and I think it would be valuable to have the two
syntaxes be compatible.  But even Pandoc's citation syntax might not be
general enough to satisfy everyone's needs, so the first step for
introducing citation syntax to Org should be compiling a list of all the
things such a syntax should represent.

The backend responsible for rendering the citation needs:

1. how to render the citation in the text (some hint about a type, pre and post text)

2. how to render the citation in the bibliography (it will get all the information from somewhere, based on the key of the citation, and prepare the citation).

In Latex, you specify a style somewhere that says how to format a cite, cite*, citenum, etc... and what the bibliography entries look like (unless you use thebibliography, in which case you do that work yourself).

in org-ref, it gets the type from a link, the key from the link, and pre/post text from the link, and converts that to the latex form needed by the latex bibliography backend. Something similar happens in the html export, except I build the bibliography from the bibtex file, and then go back and put html links in place for citations. nothing fancy.

In word, I suppose there are little fields in the main document, and you run some function that fires up zotero/endnote/mendeley, etc... that does the formatting.

 

The other problems, I think, must wait until a stable citation syntax
emerges -- export support in particular.  (Using an existing syntax from
another project could help ease the transition here: if people can
export citations using an existing tool, they'll be able to switch to
that syntax immediately, and use the external tool in the meantime while
Org-internal support for it catches up.)

I hope this is a useful starting point for further discussion!

So, after working through all that, I still think links are good enough for a large portion of citations. org should not try to solve all of these problems. That said, I would be interested again to see real life citation needs that links are too awkward to handle.

 

Best,
Richard