Re: [Docutils-develop] Figure references

[Aahz <aa...@py...>]

>>>> Let's suppose I've got a figure, and I want to refer to it (e.g. "See
>>>> figure 3.11"), how do I do that?
>>> 
>>> I don't know.  Currently, figures don't have any attribute which can be
>>> referenced.  Perhaps a "name" option on figures?  For example::
>>> 
>>>     .. figure:: image.png
>>>        :name: image's name
> 
> 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.

> Too complicated.  The original interpreted text approach is better::
> 
>     See :figure:`figure name` on :page:`figure name`.
> 
> The "figure" and "page" roles could generate some boilerplate text.
> The position of the role (prefix or suffix) could also be utilized.

That works for me.

>>>> I'm probably going to create some kind of ToC directive that goes
>>>> in an include file so I can create cross-chapter references
>>>> easily.
>>> 
>>> I don't follow.
>>
>> What I'm thinking more of (at least for starters) is an
>> extremely simple list of references to reST documents.
> 
> Can you elaborate with details of the file's contents, and ideas of
> how it would work?  I'd like to understand what you're proposing (and
> I don't have a clue now).

First the ToC::

    .. ToC-list::
        Introduction.txt
        Objects.txt
        Data.txt
        Control.txt

Then a sample use::

    .. include:: ToC.txt

    As I said earlier in chapter :chapter:`Objects.txt`, the reference
    count gets increased every time a binding is made.

Which produces::

    As I said earlier in chapter 2, the reference count gets increased
    every time a binding is made.

The ToC in this form doesn't even need to be references to actual reST
documents; I'm simply doing it that way for a minimum of future-proofing,
in case I do want to add the ability to pick up references within
external chapters.
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

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