Re: Citations, continued

[John Kitchin <jkitchin@andrew.cmu.edu>]

Richard Lawrence writes:

> Hi Tom and all,
>
> tsd@tsdye.com (Thomas S. Dye) writes:
>
>> IIUC, Org mode citation syntax needs to capture four pieces of
>> information for an *individual* citation: a =key= into one or more
>> stores of bibliographic information; a =citation-command= that is
>> understood by the =citation-style= specified for the document; a
>> =pre-note= of arbitrary text in any language; and a =post-note= of
>> arbitrary text in any language.  At least, this is how the LaTeX world
>> accommodates the almost unconstrained and ever-growing variability in
>> bibliographic styles in the wild.
>
> I think the key, pre-note and post-note are common ground, and everyone
> agrees that they need to be represented in a citation syntax.
>
> I am a bit more hesitant about the citation command, though.  My reasons
> for hestitation are the same as other people have expressed here, but I
> think it might be useful to summarize.

I think the critical point is that the syntax must be user
extendable. It should be possible to add these different types, even if
most people do not use them. Otherwise, links will continue to be used
anyway.

>
> As Tom notes, there is basically unlimited complexity in the LaTeX world
> for citation commands.  There's a different subset of commands for every
> distinction you might want to express in a given style.
>
> The trouble is that there is close to zero support for this complexity
> in the other export formats that Org supports.  As far as I am aware
> (though I could be wrong), HTML, ODT, and other document formats barely
> even have a way of indicating that a piece of text is a citation.
> (HTML5 does have a "cite" element, but it seems to be basically an
> unconstrained semantic element.)

This should not prevent us from making a syntax that can be simple for
these backends, and functional for Latex.

>
> Many of us (including me) are exporting to LaTeX, and if that is what
> you are doing, it is natural to want to have access to all the
> distinctions that LaTeX provides.  But if we try to capture those
> distinctions in a high-level Org citation syntax, then we have two
> problems: (a) finding the right syntax to express those distinctions,
> and (b) exporting citations that make use of those distinctions to
> non-LaTeX formats, which provide little support for them.  The more
> distinctions we try to capture, the more difficult these problems will
> be to solve.

Again, user extendability is the key to this. You would not use these
for export to other formats, and you do not want to have to use one
notation for some backends, and another for latex. One also does not use
the sophisticated machinery of latex by accident. So I don't think we
lose anything by making it possible.

>
> Thus, I think the right question to ask is: which distinctions are both
> *simple enough* and *important enough* that they are worth encoding in
> Org syntax and supporting in non-LaTeX backends?  I think that is the
> right place to draw the line between features of citations that are
> encoded in `citation syntax proper' vs. `escape hatches' that give more
> information about how to format a citation in a particular backend.

I think the new citations should support an export mechanism like links
do. Each backend whould be responsible to take the information it gets,
and use it to create what it needs. Syntax like [see cite@Doe99 for
example] contains all that information, and is pretty readable.

>
> My sense is that a lot of the complexity in LaTeX citations should fall
> in the latter category, but we need to think more about what falls in
> the first category.
>
> One clear candidate for the first category that I think everyone agrees
> on is the distinction between in-text vs. parenthetical citations
> (\citet vs. \citep and similar in LaTeX).  For my own case, this is the
> only distinction I need to be directly expressed in syntax.

If these are the default types, I think it is fine. It should be
possible to define new types though. It should be possible to define
this: [citeauthor@Doe99] showed in [citeyear@Doe99] that this was
possible. An alternative approach is illustrated in
Ref. [citenum@Doe100].

>
> Nicolas expressed a similar opinion:
>
>> It seems to me that :type is a LaTeX-only feature and, as such, should
>> be handled in "ox-latex". In the general case, I think that Org should
>> only support inline and parenthesized citations.

I don't think it is a latex only feature. Word could have this feature
too where you differentiate between types, and html, and ascii,
etc... This is handled by the backend.

>
> But in response to a question from Rasmus, Tom also suggested that
> multi-cites are a candidate, in addition to the in-text/parenthetical
> distinction:
>
>> Yes, I typically use what I call a multicite to get multiple citations
>> with biblatex.

If a multicite is something that might render as [1-3] or [1,6,9] in a
backend then yes, multicite is a necessary capability for most
scientific publications.

These could look like (I am mixing :/@ below just to see what it looks like):

[cite:key1,key2] or [cite:key1; cite:key2]

[cite@key1,key2] or [cite@key1; cite@key2]

[cite@key1; see also cite@key2]

>
> I myself never use these, so I don't understand exactly what would be
> required to support them properly in non-LaTeX backends, and I can't
> speak to which category they belong to.
>
> Are there other candidates we should discuss?  What other distinctions
> are so important that they are worth figuring out how to express in
> syntax that can be exported by all backends?

I think the examples above cover a lot of the use cases we have
considered. Maybe there is some subtle issues of a citation in a
citation, or of other markup in a citation, e.g. bold/italics, that I
overlooked.

I am pretty sure all those formats can be integrated pretty easily into
something like org-ref for inserting citations. As long as some part of
them is clickable, with a user-defined action, e.g. the cite@key part,
then functionally this would be the same as what we have with links in
org-ref.

converting multicites this way to latex might be a little tricky, but I
think it is doable.

>
> As for supporting the `escape hatch' category, it seems that more
> thought is needed here, too.  Right now, the #+ATTR_BACKEND syntax is
> the only way I know of to specify arbitrary export properties for a
> piece of Org syntax.  But it only applies to greater elements, and Tom
> at least does not think it is sufficient to only allow specifying the
> citation command, in particular, in an out-of-line (because greater
> element) citation definition.
>
> So maybe we need some kind of inline syntax for backend-specific
> properties of citations, perhaps along the lines that Rasmus has
> suggested.  I think this could be a good idea; my only concern is that
> we make a clear separation between this syntax and the main syntax for
> citations.  There are two reasons for this: if we don't clearly make
> this separation, then (1) it becomes much harder to figure out and agree
> on which distinctions should be expressed in `the' citation syntax; and
> (2) there is a danger that the complexity of backend-specific properties
> will bleed over into the main citation syntax, which all backends have
> to support.
>
> Best,
> Richard

--
Professor John Kitchin
Doherty Hall A207F
Department of Chemical Engineering
Carnegie Mellon University
Pittsburgh, PA 15213
412-268-7803
@johnkitchin
http://kitchingroup.cheme.cmu.edu