From: David G. <go...@us...> - 2002-10-09 02:20:47
|
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). 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. > (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. > 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"?) (To-Do list is here: http://docutils.sf.net/spec/notes.html) > So whatever syntax you give me ought to allow me to say > <chapter name>:<figure name> and have it get processed properly. I believe this is a larger issue, applicable to all kinds of references. It should be kept separate from figure references. There's already an entry in the To-Do list, which requires more thought: * Support generic hyperlink references to targets in other documents? Not in an HTML-centric way, though (it's trivial to say ``http://www.example.com/doc#name``, and useless in non-HTML contexts). XLink/XPointer? ``.. baseref::``? See Doc-SIG 2001-08-10. > 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. -- David Goodger <go...@us...> Open-source projects: - Python Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) - The Go Tools Project: http://gotools.sourceforge.net/ |