Re: [O] Citation syntax: a revised proposal

[Richard Lawrence]

Hi Tom,

address@hidden (Thomas S. Dye) writes:

> I want a syntax that recognizes arbitrary citation commands because I
> write in Org mode for publication.  You want a syntax that recognizes a
> few commands that it might be possible to support in Org mode backends,
> some of which are tied loosely, if at all, to publication.  Yours might
> be a noble goal that many Org mode users will find useful (I hope it
> is!), but I don't think it is (or will be) a syntax useful in my work,
> for the following reasons:
>
> 1) It is easier for me to have the citation command in one place.  The
> decision to represent selected aspects of the citation command in the
> syntax and other parts in extensions means that I'd have to learn the
> syntax and then remember which aspects were chosen for representation
> and which I'd need to develop through extensions of my own.  This is a
> lot more work than I do now to get exactly what I want through links.
> I'm keen to simplify the authoring process, not make it more complex.
>
> 2) Treating footnote citations differently from author-date citations is
> a non-starter for me.  When Science turns me away and the editor
> suggests that my rant is well suited for another journal, one that
> happens to use author-date citations, I'll just search all my citation
> links and replace footcite with parencite before exporting the rant to
> the suggested journal.  IIUC, with the official Org mode syntax, I'd be
> faced with the tedious process of cutting and pasting footnote text back
> into the document body.

I do think it is important to support these kinds of uses, and I think
it would be a shame if the official Org syntax did not make them
relatively straightforward.  You are surely not the only person using
Org to prepare documents for publication, and I'm sure this kind of
per-journal `refactoring' is common and important to make easy.

(You're right that our goals differ to some extent.  I am still in grad
school.  Preparing documents for academic publication is a privilege I
hope to have one day; but I am not presently one of the people using Org
for this on a regular basis, though I hope I can in the future.  One
reason I am concerned to have a citation syntax that can be exported by
other backends is this: I am anxious that, unless I can also export my
dissertation to HTML, the final document may never be read by anyone
except backup programs on the library servers.  Another, more serious
reason is that I work in a field where some journals do not accept LaTeX
submissions, or disprefer them; so having some citation support in ODT
export is important.)

I *think* it should be possible to do the kinds of things you've
described here using the syntax I proposed, but I may not understand
everything you'd like to do.  If not, let's figure out what the other
things are, and how to accommodate them.

Basically, I think you could ignore the distinctions that the [cite:
...] syntax is capable of expressing, and just write all your citations
like:

  [cite: See @Doe99 for more on this point.] %%(:type footnoted)

or, in the syntax Nicolas proposed, something like:

  [cite: See @Doe99 for more on this point.]{:type footnoted}

You would then use an export filter to transform citations with this
:type into the appropriate command, something along the lines of:

(defun footnoted-citation (citation backend info)
  (let ((type (get-citation-type citation)
        (pre (get-citation-prefix citation))
        (post (get-citation-suffix citation))
        (key (get-citation-key citation)))
     (when (and (org-export-derived-backend-p backend 'latex)
                (eq type 'footnoted))
       (format "\footcite[%s][%s]{%s}" pre post key))))

(It would be more complicated than this in the general case, since a
citation can contain more than one reference as well as common prefix
and suffix text, but hopefully that illustrates the idea.)

Then, when Science sends you elsewhere, you can just query-replace
":type footnoted" with ":type author-date", or whatever the appropriate
type for the new journal is, which will have a different export filter
(or a different clause in the same filter).

That is more work than letting Org export citations for you, because it
means manually processing every :type you use.  But maybe it is about
the same amount of work as what you are doing now with custom links.

This way, although you wouldn't be relying much on the default export
behavior of citations, you could still get the other advantages of
having them represented in Org syntax.  Those are things like having
prefix/suffix text stand in a more readable relation to the key, having
Org parse the different parts out for you, and having individual keys be
clickable so you can look up the reference in your reference database or
find an associated PDF.

Would that be sufficient?  And are there other kinds of situation where
you don't think the proposed syntax would work well?

Best,
Richard