Re: [O] Citations, continued

[John Kitchin]

Richard Lawrence writes:

>
> My concern is just that we clearly distinguish the `main' or `proper'
> citation syntax from the user-extensible part, as I said here:
>

> Rasmus has also expressed support for something like this, and I can see
> that it is important for a user to be able to define types which are
> backend-independent (and can thus be exported differently for different
> backends by some user-supplied function), much like links.
>
> On the other hand, before we adopt such a facility, it's important to
> think about what the interface would look like.  What can reasonably be
> expected of the user function?  What information needs to be given to it?
> (Just the citation and its properties? a reference to the bibligraphy
> file? a data structure representing the referenced work?)  What happens
> when the user doesn't define behavior for a particular backend?

The pieces of information we have converged on (I think) are key, pre
text, post text, command, and that could be packaged in some data
structure. You also need the backend, and there is a final piece that is
important and that is the bibliography database(s). In org-ref we use a
bibliography link or rely on a default variable setting if that is not
found. Another option is #+BIBLIOGRAPHY: information.

The user function should take that information, and provide the
formatted string to replace the citation. As with latex, the function
may have to run a few times, e.g. to get the citations, construct the
bibliography, and then go back through the text to put in the formatted
numbers, author-year, etc... in latex we have the convenience to let
latex/bibtex handle that, and other backends would need to duplicate at
least some of that capability.

This can also be used to specify where a bibliography should be placed
in the document.

For undefined behavior, the only thing that can happen is the the same
thing that happens with links. Nothing.


> I don't quite like the examples you have illustrated here because they
> don't make the distinction I was urging above, between the `main'
> citation syntax and the user-extensible part.  As a result it's really
> unclear to an author/editor, when reading the document, which backends
> can be expected to support which citations, and which citations can be
> expected to break if all you have is a default setup.  (Imagine you
> didn't write the document or the custom citation type!) From the
> exporter's perspective, it's also really unclear what should happen when
> there's no behavior defined for, say, the "citeauthor" type for the HTML
> backend.  If it defaults to just a "normal" citation, the output is very
> likely to be unreadable in the general case, but what other option is
> there?

That is true enough. That is already the case for every custom link
anyone makes in org-mode. the default behavior there is that the link is
dead and exports as plain text. This is also the case in Latex, if you
do not use the right package, sometimes you cannot get the right format
out.

>
> It's easy (and correct) to say: "These are the user's problems."  But
> we're all users, so let's think some more about how to make things easy
> for ourselves. :)
>
> For these reasons, I'd prefer something like Rasmus' suggestion; maybe
> syntax like
>
> address@hidden :custom-type author-only] showed in address@hidden 
> :custom-type year-only]
> that this was possible. An alternative approach is illustrated in
> address@hidden :custom-type refnum].
>
> where, basically, ":custom-type" is a nice big flag that says: "Here be
> dragons: you are responsible for exporting this citation yourself."
>
>> 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.
>
> Can you (or Tom, or someone else) make the case that it is important
> enough to have multicites that non-LaTeX backends should support them
> out of the box?  (I'm not doubting it, I just don't have any idea why
> since I don't use them myself.)

My case is that if this is not supported out of the box, we could not
use the citation syntax for any of our scientific publishing needs.  In
a recently published paper we had four citations with 4 references in
it, four with three references, 10 with two references and 15 single
citations. That is probably typical in our work, and in review work it
is common to have even more than four references in a citation. This is
a feature of modern publications because of tools like Endnote, zotero,
etc... which make it trivial to add citations, and independent of the
ultimate format (which is usually pdf, but sometimes html, and sometimes
Word).

If the new syntax allows us to handle citations the way links do today,
I can see a transition pathway to the new syntax. If not, I doubt it can
be adopted for scientific writing if you need two syntaxes for
citations. There are other, important types of writing this may support,
and maybe it makes sense to have separate approaches.


>
> 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