On Tue, Oct 08, 2002, David Goodger wrote:
> Aahz wrote:
>> 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
> DocBook and others do this kind of reference (all references, actually)
> using IDs. reStructuredText uses reference names, not IDs, and the names
> are converted to IDs internally. Perhaps Docutils needs an explicit ID
> mechanism, something like::
> .. figure:: image.png
> :id: image-id
> How to refer to a figure though? Perhaps something like this::
> See :figure:`image's name`.
> This could produce "See figure 1.", assuming that figures grow a numbering
> mechanism as well (they don't have one yet).
That's roughly what I was thinking of. There will need to be a generic
naming and numbering mechanism, because other kinds of document elements
(e.g. tables) will want references and numbering.
> In order to get "figure 3.11"-style references, we'd need sequences,
> such as chapter numbers, that are persistent across multi-file
> processing runs. This is getting complicated.
That's one way of doing it, but see below.
>> (I've now read much of reStructuredText.txt, so I've got a better grasp
>> of what's available (i.e. knowing about "::"), but I'm still having some
>> trouble knowing which constructs are best for specific purposes.)
> Such as? Have you looked at http://docutils.sf.net/docs/rst/quickref.html?
> (OT: It would be nice if this file were converted to "self-hosted"
> reStructuredText. It's the only hand-coded HTML in the project.) The
> tools/test.txt file (http://docutils.sf.net/tools/test.html) may also
> provide clues.
Well, such as this figure referencing problem. ;-) Don't worry, I'll
mention others as I come across them.
>> 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. Examples? Perhaps this To-Do entry is relevant:
> * Perhaps store a name-to-id mapping file? This could be stored
> permanently, read by subsequent processing runs, and updated
> with new entries. ("Persistent ID mapping"?)
Not quite. What I'm thinking more of (at least for starters) is an
extremely simple list of references to reST documents. Initially, it'd
just be for the purpose of auto-numbering references to those documents
(i.e. chapter references); later on, it could evolve into a true
multi-file system for garnering internal references. But because I'm
focused on book writing at this point, hyperlinks are *not* what I'm
So for now I'm likely to hard-code the actual figure numbers (but not
the chapter numbers) for cross-chapter references.
>> I'm thinking that interpreted text is likely the way to go, but David
>> has previously expressed some distaste for interpreted text that gets
>> completely removed.
> I wouldn't worry about that. If interpreted text ends up being the way to
> go, then so be it (interpreted text isn't actually implemented yet; it
> awaits real world use cases). More importantly, we need to work out the
> mechanism before we can say what syntax applies.
To repeat what I've said above differently, one concern I've had in
reading through the reST docs is the extent to which references,
particularly external references, are often equated with hyperlinks.
That's simply not particularly applicable to my domain.
Aahz (aahz@...) <*> http://www.pythoncraft.com/
Project Vote Smart: http://www.vote-smart.org/