Re: [O] Should wip-cite branch be merged to master?

[András Simonyi]

Dear All,

thanks for your responses. I find John's list of the most important
capabilities of org-ref very useful and agree that in the long run we
should aim at providing all of these functionality for the new syntax as
well. One point where this might prove to be difficult is precisely the
set of provided citation commands since org-ref, being bib(la)tex
focused, can support all BibTeX/biblatex commands via its citation
links. This leads to Richard's comments on this topic:

  > one of the fundamental problems with citations, namely, they resist
  > attempts to separate 'content' from 'style'. It is hard to insert
  > citations into a document without making any assumptions about how they
  > will be rendered by the citation processor. And so it is hard to come up
  > with a syntax that is general enough to represent widely different
  > citation styles, in a way that makes those assumptions explicit in the
  > syntax of the unprocessed citation, so that the content of the citation
  > can be separated from how it will be rendered. Thus we see the huge
  > proliferation of different citation commands in e.g. BibLaTeX, natbib,
  > and similar packages. András' proposal would reintroduce some of the
  > complexity of BibLaTeX citation commands at the level of Org syntax.

These are very good points and I agree that the used citation style can
influence the way of writing to a large extent, which makes it virtually
impossible to devise a citation syntax using which one could switch any
document to a totally different style (say from author-date to footnote)
without any rewrites. I suppose in this respect (i.e., 'separating
content and style') our aim can only be to provide those few
style-independent abstractions that are possible to minimize the amount
of changes needed, plus perhaps some style-dependent constructs.

  > I want to point out that one of the goals of the original discussion
  > to come up with an Org syntax that is simpler and does a better job
  > of separating content and style.

  > I think we should try to avoid proliferation of citation commands.

  > If that is a reasonable goal, then I think there is really just
  > one distinction that deserves to be represented at the level of
  > citation commands: the distinction between 'in text' and
  > 'parenthetical' citations, that is, the distinction between
  > 'cite:' and '(cite):' in the current syntax in wip-cite.  That
  > brings me to this point:

I agree both that we should avoid having too many citation commands and
that the most important distinction is that of between 'parenthetical'
and '(partly) in main text'. As for the concrete choice of these two
commands, it seems that I misunderstood the intended semantics of the
commands in the current wip-cite syntax because I thought that 'cite'
isn't supposed to produce an 'in main text' citation but a
'bare'/bracketless one, i.e., in the case of author-date styles, 'Smith
2018' instead of '(Smith 2018)'. If, on the contrary, 'cite' was
intended to stand for 'in text' citations then it is indeed a question
which part of the citation should be part of the main text -- e.g., how
should [cite: @Smith2018] be rendered by an author-date style? Since the
typical choice is the author's name, this would probably be a good
default.

  > we should just stick to one command for the in-text case, and have some
  > extensible way to represent the data that should be rendered, e.g. maybe
  > like

  > [cite: @Jones2018 :year]

  > or (as I think was proposed at one point):

  > [cite:author @Jones2018]

  > Again, maybe it's worth having some shortcuts here for the common cases,
  > but I think in general we want to try to avoid proliferation of basic
  > citation commands. So for that reason I think we should just stick with
  > the 'cite'/'(cite)' distinction as the two basic commands, perhaps with
  > a more extensible/compositional syntax in each case for expressing the
  > variations on these two basic types of citation.

Again, I very much agree with the general direction of these proposals,
but doesn't this mean that the citation element should have an attribute
to represent which parts of an 'in text' citation are meant to be in the
main text? (I think currently the only citation-specific attributes in
the wip-cite branch are 'prefix', 'suffix' and 'parenthetical'.)

Finally, to (at least roughly) conform with Wadler's law of language
design :-), just for the record, a few words about the choice of the
concrete commands for 'parenthetical' and 'in main text' citations.
Although Richard is right that the ratio of 'parenthetical' vs '(partly)
in main text' citations

  > depends completely on one's field, writing style, etc. (In my
  > dissertation, for example, in-text citations outnumber parenthetical
  > citations roughly 3:2.)

I still think a case can be made for making the 'parenthetical' one the
default/basic (and, consequently, interpreting the simplest/shortest
citation command as 'parenthetical').

First, I suspect that in documents using a note citation style 'partly
in main text' citations are quite rare. Second, although I couldn't find
any general frequency data on this, it seems that well established style
guides such as the Chicago Manual of Style consider 'parenthetical'
citations the basic/usual ones even in the case of author-date
citations. E.g., the CMS (16th ed.) writes that

'In the author-date system, a citation in the text usually appears in
parentheses and includes only the first elements in a reference list --
the author and the year of publication (15.7) [...] 15.21 *Text citatons --
basic form.* An author-date citation in running text or at the end of a
block quotation consists of the last (family) name of the author
followed by the year of publication'

Of course, it can be argued that this indicates only conceptual priority
and not frequency but I think this conceptual priority in itself is a
good argument for associating this type of citation with the basic
command, especially in view of the fact that 'partly in main text'
variants need the additional specification of what goes into the main
text.

Last but not least an 'argument from authority': the CSL plugins I know
of all default to inserting 'parenthetical' citations regardless of the
used style, and biblatex's basic high-level/style-independent command,
'autocite' also behaves that way.

I'd like to add that I don't consider the choice of the two citation
commands a crucial one, 'cite' as 'in main text' and '(cite)' as
'parenthetical' could also be a perfectly usable syntax/semantics,
especially if -- as Richard suggests -- we provide extension points to
cover more complex use cases.

best wishes,

András