[Doc-SIG] Python docs in reST
Felix.Wiemann at gmx.net
Thu May 26 00:14:41 CEST 2005
Ian Bicking wrote:
> Felix Wiemann wrote:
>> [Big document from many input files:] you'd need to parse all input
>> files (without resolving references etc.) and store the results
>> (namely Docutils node trees) in XML files.
> Hey, now we're getting back to exactly what I suggested! ;) Really, XML
> or rendered HTML, it's not a huge difference.
Oh, it is. :-)
Given a proper serialization algorithm, you could cleanly deserialize an
XML file into the original node tree, which is not possible with HTML.
> So, back to that expedient solution I talked about before, you can
> fairly easily get docutils to not try to resolve any links at all,
> outputing some marker that indicates this.
> [...] Then later you look for <a refname="XXX">...</a>, where refname
> contains the simplified link name (e.g., `This Link`_ becomes <a
> refname="this-link">This Link</a> in the HTML). There's a chance this
> will break with indirect links [...] But I'm sure that's resolvable.
I fear you'd end up re-implementing Docutils' reference-resolving
system. I had to work with it once before, and trust me, it's quite a
I wouldn't say a hack which does what you described would be a bad thing
For private mail please ensure that the header contains 'Felix Wiemann'.
More information about the Doc-SIG