<div class="gmail_quote">On Tue, Nov 17, 2009 at 2:13 AM, Glyph Lefkowitz <span dir="ltr"><<a href="mailto:glyph@twistedmatrix.com">glyph@twistedmatrix.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
<div style="word-wrap: break-word;"><br><div><div class="im"><div>On Nov 16, 2009, at 5:37 PM, Kevin Horn wrote:</div><br><blockquote type="cite">On Mon, Nov 16, 2009 at 3:11 PM, <span dir="ltr"><<a href="mailto:exarkun@twistedmatrix.com" target="_blank">exarkun@twistedmatrix.com</a>></span> wrote:<br>
<div class="gmail_quote"><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
<div>On 06:09 pm, <a href="mailto:kevin.horn@gmail.com" target="_blank">kevin.horn@gmail.com</a> wrote:<br>
>><br>
>er, sorry, forgot to post the link...<br>
><br>
>here it is:<br>
><a href="http://twistedsphinx.funsize.net/" target="_blank">http://twistedsphinx.funsize.net/</a><br>
<br>
</div>Thanks. It's good to be able to see (at least an early draft of) what<br>
the outcome of this proposal will be.<br>
<br>
I'm glad the reactions have been good so far, but I want to be a wet<br>
blanket for a moment and suggest that we try to avoid being influenced<br>
excessively by the "new look" effect. </blockquote><div><br>Wet blanket away! Every project needs a good "devil's advocate".</div></div></blockquote><div><br></div></div><div>Well! If it's time for criticism I've got some ;-).</div>
<div><br></div><div>I'd really like to see the stylesheets on this site adjusted to look as much as possible like the current Twisted style. Use the verbatim stylesheets from <a href="http://twistedmatrix.com" target="_blank">twistedmatrix.com</a> as much as possible. I realize you'll have to have some custom elements, but it should be possible to at least avoid creating any new images and to stitch together the existing styles rather than make new ones wholesale.</div>
<div><br></div><div>If we ever have the resources to do a site redesign again (and I hope we do, it would be nice to get a fresh look every few years) I want to be able to re-style the _entire_ site.</div><div><br></div><div>
We could do this with the Lore documentation too, but if we're going to make the investment I'd rather it be on something easier to maintain, as your conversion project promises to be. I also suspect that it would be a lot easier to style the output from sphinx, as it is explicitly designed to be themable, and has actually been modified to have multiple, radically different stylesheets already. Actually integrating this with the L&F of the rest of the Twisted site would go a long way towards demonstrating Sphinx's superiority in this area :).</div>
</div></div></blockquote><div><br>The current look is the "sphinxdoc" theme, that comes with Sphinx. My intention is to create a new one for the Twisted docs that will be very similar to the Twisted site. I haven't really even started on this yet, though.<br>
</div><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;"><div style="word-wrap: break-word;"><div><div>On the "things to do" side, while the mere presence of this page is itself unintentionally hilarious - <<a href="http://twistedsphinx.funsize.net/projects/lore/howto/lore.html" target="_blank">http://twistedsphinx.funsize.net/projects/lore/howto/lore.html</a>> - and it will likely be removed from the final output, it does contain a good enumeration of all the things that need to be converted in one place. I suspect that if you made all those UNHANDLED_TAG output warts go away, we'd be most of the way towards converting all of the documentation.</div>
</div></div></blockquote><div><br>Heh, that is pretty funny. If you'll notice though, almost all the UNHANDLED_TAG stuff (on that page anyway) is related to the table on that page. I haven't even touched tables yet. I don't think they'll be too difficult, as long as there aren't any nested tables (there aren't in the Twisted docs...I haven't looked at the Divmod stuff yet). Since I think there's only 2 tables in the Twisted docs, there kind of low on the priority list.<br>
<br>FYI, those UNHANDLED_TAG messages are intentionally ugly, to make it easier to find things that haven't been handled yet.<br><br>As far as what still needs to be done on conversion, this falls into a couple of main areas:<br>
<br>- handling unhandled tags<br>- fixing some whitespace handling issues (notice that nested lists are totally borked at the moment)<br>- going back through the "Using Lore" document, making sure all the various tags are being handled correctly, and fixing any problems<br>
- building a "twisteddocs" theme<br><br>After this stuff is done, then the real grunt-work begins...fixing the bits manually that can't be easily converted. So far, I think this only really involves 3 pages of Lore XHTML, but I'm sure I'll find other problems. :)<br>
</div><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;"><div style="word-wrap: break-word;"><div><div class="im"><blockquote type="cite"><div class="gmail_quote">
<div>The next "tier" of advantages (again IMO) also have nothing to do with the output, those advantages being:<br>
<br>- a more approachable document format (in the sense that I think there are probably more people familiar with the Sphinx dialect of RestructuredText than are familiar with Lore's subset of XHTML...and the number of Sphinx users is growing)<br>
</div></div></blockquote><div><br></div></div><div>Actually, I think that this particular often-touted advantage is a wash. The "approachableness" of ReST is questionable, especially once you get into the weird corner cases where the syntax just completely falls apart and turns into an incomprehensible line-noise jumble. I mean, the syntax for tables reads like a joke about how trying to make the plain-text input look like the output is a bad idea: <<a href="http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#tables" target="_blank">http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#tables</a>>. Consider trying to re-flow the contents of a table cell after adding text to it, for example. Plus, a _lot_ of people know HTML -- still many more than know ReST, I would argue -- and lore adds relatively little to HTML.</div>
</div></div></blockquote><div><br>I'm not sure I agree here. While it's true that lots of people know HTML, I'm not sure that that helps more than it hurts. First of all, XHTML is subtly different from HTML, but more importantly, everyone who "knows" HTML doesn't know it to the same level, and has different opinions about what different elements should be used for. The "Using Lore" page spells things out pretty clearly, but even some of those clear rules aren't followed very well in the actual Twisted docs. I think because people "know" HTML, they just use what they know instead of paying close attention to the actual Lore rules. (going way out on the opinion limb here, though)<br>
<br>I guess my point is that I think it takes about the same amount of effort to really learn the Lore subset of XHTML as it does to learn Sphinx's dialect of RestructuredText. And more people know Sphinx-RestructuredText to the level practically usable for documentation (from using it on other projects). There's arguments either way I guess. <br>
<br>On a personal level, having written docs in other XML/XHTML dialects and in Sphinx/ReST, I know I can write them way faster and with much less thought to format in ReST. And, IMO, those corner cases are very much in the corner. They don't come up very often, at least for me.<br>
<br>There's no defending ReST tables though. You're totally right there. Yuck.<br> </div><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
<div style="word-wrap: break-word;"><div><div></div><div>However, the motivation for choosing HTML was that "any day now" there would be a good, commonly used, GUI editor for HTML documents and we could easily annotate the output of one of those with the extra metadata that lore wanted. That hasn't happened. What *has* happened is that despite the difficulty involved in parsing and emitting ReST as compared to something fairly regular like HTML or XML, tools like these have been emerging:</div>
<div><br></div><div> <a href="http://kib2.free.fr/reSTinPeace/" target="_blank">http://kib2.free.fr/reSTinPeace/</a></div><div> <a href="http://blog.enthought.com/?p=127" target="_blank">http://blog.enthought.com/?p=127</a></div>
<div><br></div><div>which let users edit ReST documents in a sort-of-wsyiwyg way, so you get immediate feedback when you put a "|" or a "`" in some obscure spot that makes your entire document disappear, rather than trying to hunt it down after an hour of writing. Plus, docutils provides a document model for ReST so you can transform it programmatically and ignore its syntactic peculiarities.</div>
</div></div></blockquote><div><br>I think the underlying reason this has happened is that ReST is less flexible than HTML, and therefore less ambiguous. I couldn't tell you why I think that, though. Just a feeling.<br>
</div><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;"><div style="word-wrap: break-word;"><div><div></div><div>Which all comes down to the fact that I'm mainly just restating this point as the primary advantage:</div>
<div class="im"><br><blockquote type="cite"><div class="gmail_quote"><div>
- a much larger user base, and clear extension API, which allows us to take advantage of existing extensions, etc.<font color="#000000"><font color="#144fae"><br></font></font></div></div></blockquote><div><br></div></div>
The active user community means that not only is somebody else mantaining the basics, lots of other people are working on *tools* that we can use for more intense usage. I am personally looking forward to using some of those GUI tools for actually editing the documentation; it's a much more streamlined workflow than running the 'lore' commandline and reloading in a browser.</div>
</div></blockquote><div><br>Kevin Horn <br></div></div><br>