[Twisted-Python] Structural issues in Lore XHTML documents
I've been looking over the xhtml documents used to generate the twisted documentation, and I've noticed a number of issues: - some docs do not have a DOCTYPE declaration, I think they should all have one - of those documents that do have DOCTYPEs, some are using xhmtl-strict, and some are using xhtml-transitional, which is preferred? I think they should all use the same one - some of the docs are lacking an xml namespace attribute in their root <html> element...I think they should either all have one, or none of them should - according to: http://twistedmatrix.com/projects/lore/documentation/howto/lore.html all of the docs should have the same text in both their <title> element and their <h1> element...this is not the case I'm planning to correct some of these issues, but I wanted to get others' opinions on exactly how to go about it. For example, what DOCTYPE to use, XMLNS to use, etc. Thoughts? Suggestions? I've opened a ticket (#4050) at http://twistedmatrix.com/trac/ticket/4050 Please comment. Thanks, Kevin Horn
On Mon, Oct 5, 2009 at 12:22 PM, Kevin Horn
I've been looking over the xhtml documents used to generate the twisted documentation, and I've noticed a number of issues:
Are these issues really affecting you in some way?
I'm planning to correct some of these issues, but I wanted to get others' opinions on exactly how to go about it. For example, what DOCTYPE to use, XMLNS to use, etc.
They are supposed to be XHTML, so they should be annotated as appropriate for that format. Lore doesn't define its own attributes, on purpose: it uses existing XHTML facilities like "class" to encode its metadata.
Thoughts? Suggestions?
I'm sure we'd be happy to accept some patches to clean these documents up, especially if it's bothering you, but it seems pretty low-priority to me :).
On Mon, Oct 5, 2009 at 1:25 PM, Glyph Lefkowitz
On Mon, Oct 5, 2009 at 12:22 PM, Kevin Horn
wrote: I've been looking over the xhtml documents used to generate the twisted documentation, and I've noticed a number of issues:
Are these issues really affecting you in some way?
Yes and no. I'm playing around with some automated processing of these documents (mostly as an exercise to learn lxml), and I'm having to work around some of these things. And since I was thinking about it anyway, I thought I'd take the opportunity to fix up some "broken windows".
I'm planning to correct some of these issues, but I wanted to get others' opinions on exactly how to go about it. For example, what DOCTYPE to use, XMLNS to use, etc.
They are supposed to be XHTML, so they should be annotated as appropriate for that format. Lore doesn't define its own attributes, on purpose: it uses existing XHTML facilities like "class" to encode its metadata.
The main thing I was worried about was whether they were supposed ot be xhtml-strict or xhtml-transitional.
Thoughts? Suggestions?
I'm sure we'd be happy to accept some patches to clean these documents up, especially if it's bothering you, but it seems pretty low-priority to me :).
It's not "bothering" me per se, and we're agreed that it's not any kind of priority, just thought I might as well try and fix it up while I was looking at it. FYI: I've hacked together a simple "lorelint" script to automatically check for these type of issues. Happy to share if anyone thinks it might be useful for future release mgmt automation or whatever. Kevin Horn
On Mon, Oct 5, 2009 at 1:44 PM, Kevin Horn
FYI: I've hacked together a simple "lorelint" script to automatically check for these type of issues. Happy to share if anyone thinks it might be useful for future release mgmt automation or whatever.
For benefit of future readers...Lore already does something like this. Try: lore -olint mydocument.xhtml Thanks to exarkun for pointing this out. Kevin Horn
participants (2)
-
Glyph Lefkowitz
-
Kevin Horn