Re: Citation syntax and ODT

[Richard Lawrence <richard.lawrence@berkeley.edu>]

Vaidheeswaran <kjambunathan@gmail.com> writes:

>> We haven't really discussed how styles should be specified (yet), or the
>> formatting of bibliographies.  But we have been discussing a syntax that
>> lets you specify those formatting properties which commonly differ
>> between individual citations.
>
> IMO, it is better to roll out the citation feature WITHOUT any
> formatting properties.  The specific formatting chosen is at the mercy
> of capabilities of the export backend or citation engine it works
> with.

I still don't understand what it would mean for an exported citation not
to have any formatting properties.  If I write a citation like

  [cite: See @Doe99 p. 43]

how should that be represented in an ODT/HTML/etc. document without any
formatting?  Just copy the text verbatim into the output...?  

According to the proposal we've been discussing, a citation like this is
an in-text (as opposed to parenthetical) citation with a prefix and a
suffix, and thus should render something like

  See Doe (1999, p. 43)

or 

  See Doe [1, p. 43] 

etc.

where the choice between those options would depend on the citation
style.  I agree that there is an issue about those styles; it seems
likely that Org will have to be fairly flexible about those, perhaps
falling back to a default if the requested style is not available on a
particular backend.  (Probably it would be useful, too, to be able to
separately specify styles for LaTeX vs. non-LaTeX backends.)

But whatever style is chosen, I would still think that the fact that the
citation is in-text rather than parenthetical, and that it has a prefix
and suffix, should be represented in the output.  Perhaps not all
backends will be able to do even that at first -- that's fine -- but I
think that should be treated as a bug to be fixed at some point, not as
acceptable behavior.  Do you disagree?  

> Do you think of a scenario where:
>
> 1. Org acts like a citation engine.  (A self-contained Org-ecosystem)
>
> 2. Org-backends interfaces with a 3rd-party engine (like pandoc,
>    zotero, JabRef)
>
> If the current effort is to build (1), ODT backend will have no reason
> to complain.
>
> If the effort is geared more towards (2), the ground reality is that
> JabRef's style catalog is not as extensive or mature as, say Zotero's
> or LaTeXs.  The implication is that the PDF document produced via the
> LaTeX document WILL DIFFER IN STYLE from the PDF document produced via
> the ODT backend.

Yes, that is inevitable, and fine, I think.  But as far as I can tell,
this is an issue of the document-level style selection (Chicago vs. APA
vs. ACM...), not an issue of the more fine-grained differences between
e.g. parenthetical and in-text, or having a prefix or not; these
fine-grained differences are (mostly) independent of the style, and I
think they should be represented in the output.

> I am imagining something along a mix of (1) and (2), with more initial
> thrust in favor of (2).

Me too.  I am guessing we will want to `bless' one or two external
tools, both on the side of reference databases (perhaps Bib(La)TeX and
Zotero, in addition to Org-bibtex) and on the side of formatting
processors (perhaps Bib(La)TeX and citeproc-js or zotxt).  We can then
make it clear that exporting citations to a particular format requires
these tools, much like exporting an Org document to PDF requires a TeX
installation.

> I am only saying that the people who work on the specification take
> sufficient care to TEMPER what a user can reasonably expect when he
> moves between different backends.
>
> My primary motivation is to draw the attention of people like you (who
> are hammering out the syntax) to factor the case of a backend-like
> ODT.

I agree, this is important.  Unfortunately, like I said, I don't
personally know much about ODT, so I need to rely on people who know
more about it (like you) in order to factor in the details.  

> My focus in not so much on syntax-richness but on quick roll-out of
> citation support. ... My only suggestion is to MERELY TO TAKE
> COGNIZANCE of the need for bells-and-whistles without the current
> momentum being dragged down by an attempt to arrive at a consensus
> that will keep all parties happy.

That is fair enough, and I agree.  I would just add that we've worked
pretty hard to come up with a list of features that are important enough
that they should be supported by all backends.  While we might not be
able to implement them all on all backends right away, my hope is that
they eventually will be fully supported.  But you're right, let's not
have the perfect be the enemy of the good in the meantime.
 
Best,
Richard