[Docutils-develop] Citation support

[Guenter M. <mi...@us...>]

On 2011-11-11, Alan G Isaac wrote:

> I am simply interested in addressing a common need:
> the need to be able to add instance-specific data to a citation.

This need does not arise with the current state of citation support - you
can just put this data behind the citation (as you do with all numbered
citation styles). Examples::

  see also [foo]_ page 3
  as proven by `Müller (1980)`_ p. 37

> Comparing with BibTeX, I am just asking for the equivalent
> of the optional argument in a BibTeX citation.

BibTeX itself does not support optional arguments to a \cite command and
its author strongly advises against styles that require them:

  ... the logical deficiencies of the author-date style are quite evident
  once you’ve written a program to implement it.

  --- BibTeXing_, Chapter 4

(For those "saddled with an unenlightened publisher" [BibTeXing]_, there
are several contributed LaTeX packages to handle the author-year style.)

> Once an reST writer has access to this, it can do *anything it wants*
> with this information.  What it will do does not need to be "thought out"
> before hand.

There is no need to change the rst syntax to accomodate a special writer.
reStructuredText has established "hooks" for extensions: class arguments,
custom directives and roles.

A custom role can be easily added by an extension without the need to
change the Docutils core - as the zotero-plain extension proved.

...

> iii. citation references should also have instance-specific
>       information (comparable to the optional argument in a
>       BibTeX citation).

...

> Can you suggest a bibliographic solution that will not require (iii)?

BibTeX with `plain` or `unsrt` styles. Again from BiBTeXing:

  I strongly recommend that you choose something like the *plain*
  standard style. Such a style, van Leunen [4]_ argues convincingly,
  encourages better writing than the alternatives—more concrete, more
  vivid.


For ideas on improved citation support in Docutils, see todo.txt and the
old threads referenced there.


Günter


References:

.. [4] Mary-Claire van Leunen. `A Handbook for Scholars`. Knopf, 1979.
.. _BiBTeXing: btxdoc.pdf