Re: [Docutils-develop] Figure references

On Thu, 10 Oct 2002 2:25 pm, Aahz wrote:
> David wrote:
> > I've thought some more about this (full details soon to appear in the
> > spec/notes.txt file), and I think the best way to name an object is the
> > way we've always named targets::
> >
> >         .. _figure name:
> >
> >         .. figure:: image.png
> >
> > This applies equally well to tables.
>
> It's not clear to me how these two directives interact.

The ".. _figure name:" creates a target, placing a target called "figure name" 
in the document just before the ".. figure::" directive. Not entirely clear, 
no, and I'd actually prefer the

.. figure:: image.png
   :name: figure name

which looks a lot clearer (in terms of keeping related information together) 
to me as a document author. I've always seen the ".. _figure name:" target 
generation syntax as a last-resort fallback, as it's almost always jarring to 
see in the source text. But that could just be me :)


    Richard