[Twisted-Python] Refactoring Documentation

[Kevin Horn]

On Thu, Jan 20, 2011 at 6:06 PM, <exarkun at twistedmatrix.com> wrote:

> On 20 Jan, 11:57 pm, screwtape at froup.com wrote:
> >On Thu, Jan 20, 2011 at 05:22:55PM -0600, Kevin Horn wrote:
> >>Hmmm...yes, I think it does.  It looks like the l2s_builder script is
> >>choking on fetching the DTD for some reason.  lore2sphinx itself is
> >>supposed
> >>to cache the DTD between runs, but I'm betting it doesn't work in the
> >>buildbot due to the (hopefully) clean environment it has every time it
> >>runs.
> >>
> >>I can change it to not care about that, but if I do, then it won't be
> >>able
> >>to resolve HTML entities (of which there are a few in the Lore
> >>sources,
> >>mostly em-dashes IIRC).
> >
> >You mean these DTDs?
> >
> >    twisted/lore/xhtml1-strict.dtd
> >    twisted/lore/xhtml1-transitional.dtd
> >
> >They reference the xhtml-*.ent entity definitions which are also in the
> >same directory. It would be neat if lore2sphinx could be taught to use
> >the DTDs packaged with lore instead of having to download them from the
> >Internet every time.
>
> It could even use Lore's parser, twisted.lore.tree.parseFileAndReport ;)
>
> Jean-Paul
>
>
Yes, but:

- The docs (well, docstrings) aren't very clear about exactly what that
does, or what quirks it might or might not have.
- Is the DOM document it returns a typical XHTML DOM document?  Is there
anything special/different about it since it's a Lore XHTML doc?
- Consider the number of tickets open involving Lore's parser (or at least
there were several when I started this whole business).
- The whole point of this project is to stop using (and by extension
supporting/maintaining) Lore, so it seems kind of backwards to me to depend
on it.
- I'd rather deal with an etree-a-like, than a straight DOM document
(admittedly, personal preference)
- I certainly don't want to rewrite everything at this point ;)

Kevin Horn
-------------- next part --------------
An HTML attachment was scrubbed...
URL: </pipermail/twisted-python/attachments/20110120/c4a64784/attachment.html>