docutils-develop

[Docutils-develop] reST chapter references

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

Dethe wants the opposite of what I want: I'm building a book out of
multiple chapters, each chapter in a subdirectory.  While the output of
each chapter should stay in its own subdirectory, I'll want to make
cross-chapter references.  How should I do that?
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

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

Re: [Docutils-develop] reST chapter references

[David G. <go...@us...>]

Aahz wrote:
> Dethe wants the opposite of what I want: I'm building a book out of
> multiple chapters, each chapter in a subdirectory.  While the output
> of each chapter should stay in its own subdirectory, I'll want to
> make cross-chapter references.  How should I do that?

Good question.  No concrete answers yet, but the idea has been examined
a bit.  More thinking to date:

From the to-do list (http://docutils.sf.net/spec/notes.html#general):

    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"?)

http://docutils.sf.net/spec/notes.html#restructuredtext-parser:

    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.

Or perhaps URLs are general enough for our purposes?

Also see http://docutils.sf.net/spec/notes.html#reference-merging
(transform idea).

-- 
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/