Re: [Docutils-users] citation enhancement?

[G. M. <g....@we...>]

On 12.07.06, David Goodger wrote:
> [Alan G Isaac]
> > I proposed a mechanism that will allow convenient
> > interaction with preprocessors:
> 
> A preprocessor could handle everything, with no change to reST.

However, a small change to reST could facilitate a far simpler
preprocessor and "nice", easy to understand preprocessed restructured
text.

> > So more people than just me will need to
> > indicate that this enhancement will be useful to them.
> 
> No matter how many people indicate usefulness, some proposals are
> unacceptable and will be rejected.  I believe this proposal to be one
> of these.  Please consider this a pronouncement, and give it a rest.

Could we separate "enhanced citation support" from the implementation
proposal? 

* I believe reST could gain a lot from supporting citations from a
  database. (Actually, this is one of the main points where LaTeX (and
  LyX) are still far superior to common office software.)

* I agree that a backwards compatible, clean implementation that fits
  well in the existing syntax, should be found.

 
> An alternative could be to implement a new directive for citations,
> something like this::
> 
>     .. citation:: Goodger2006
>        :substitute: (Goodger 2006)
> 
>        This is the citation text.  The ":substitute:" option above
>        supplies the display citation label.  Directive options allow
>        for more flexible constructs than are otherwise possible, at
>        the expense of some verbosity.

This looks nice to me.

> But the biggest objection I have with the proposed mechanism
> (regardless of the syntax) is that there would be no explicit
> indication of the substitution *at the substitution site*.


On 12.07.06, David Goodger wrote:
> [Stuart Robinson]
> > Perhaps I have misunderstood something, but isn't the "unsurprising
> > goal" already violated by 'substition text' directives?
> > 
> > http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#substitution-definitions
> 
> No, because there's an explicit indication of the substitution:
> 
>     A substitution will happen |here|.
> 
> The substitution reference syntax is a clear indication that something's up.
> But:
> 
>     One [citation]_ and [another]_.
> 
> Which citation will be substituted?  Neither?  Both?
> There's no way to tell.

Citations will always be substituted.

(Sometimes the label and the substitution might conincide). 

This enables different common citation styles with a consistent syntax.
(e.g. in my publications I almost entirely need the sorted numbered
style:

.. citation:: Goodger2006
   :substitute: [1]

   ``On citations in reStructured text``, email correspondence at
   doc...@li..., June 2006
   
.. citation:: Isaac2006
   :substitute: [2]

   ``A proposal for citations in reStructured text``, email
   correspondence at doc...@li..., June 2006
   
However, during the editing of the text I would like to keep the
name-author labels so a new citation will not change all following
labels in the text.
   
Günter