Re: [Docutils-develop] Figure references

On Thu, Oct 10, 2002, Richard Jones wrote:
> 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 :)

+1

reST should be easy to read for people only minimally familiar with it.
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

Project Vote Smart: http://www.vote-smart.org/