[Python-Dev] The docs, reloaded

[Talin]

Greg Ewing wrote:
> Talin wrote:
>> As in the above example, the use of backticks can be signal to the 
>> document processor that the enclosed text should be examined for 
>> identifiers and other Python syntax.
> 
> Does this mean it's time for "pyST" -- Python-structured
> text?-)

I wasn't going to say it :)

Now, at the risk of going even further out of the mainstream (actually, 
there's no risk, it's a dead certainty), if I had been clever enough to 
think that I could write a LaTeX translator, I probably would have made 
my target language Docbook or some other flavor of XML.

Now, you might argue that XML is more cumbersome and harder to author 
than reST, and that is certainly a valid argument. On the other hand, 
there are a couple of interesting advantages to using XML:

1) You get an instant WYSIWYG preview capability by publishing a 
standard CSS stylesheet along with the docs. Anyone would be able to see 
what the output would look like merely by viewing it in a browser. While 
there would be some document transformations which would be not be 
previewable in CSS (such as breaking the document up into hyperlinked 
chapters), you would at least be able to see enough to be able to do a 
decent job of editing the text without having to install any special 
tools. And some of those more difficult transformations would be doable 
with a suitable XSTL stylesheet, which can be directly executed in most 
browsers. (As an example, I once wrote an XSLT stylesheet that converted 
OpenDocument XML into the equivalent HTML - this was part of my Firefox 
ODFReader plugin [http://www.alcoholicsunanimous.com/odfreader/], that 
allowed ODF documents to be directly viewed in the browser without 
having to launch an external helper application.)

2) There are a few WYSIWYG XML editors out there, which allow you to 
edit the styled text directly in an editor (although I don't know of any 
open source ones.)

3) The document processing tool could be very minimal, mostly assembled 
out of standard modules for processing XML.

4) XML has a well-specified method of escaping into other (XML-based) 
languages, which is XML namespaces. So for those who want equations in 
their docs, they could simply insert a block of MathML inside their 
Docbook XML. Similarly, illustrations could be embedded using bitmap 
images or SVG as appropriate.

5) Having XML-based docs would make it easy to write other kinds of 
processors that operate on the docs in different ways, such as building 
a keyword index or doing various kinds of analysis.

Now, this suggestion of using XML isn't really a serious one. But I 
think that the various advantages that I have listed ought to be 
considered when thinking about how the tool chain for python 
documentations should operate.

I think that there is a big advantage to making the document processing 
tools simple and hosted entirely in Python. People who contribute to the 
docs are likely to know quite a bit about Python, but it is far from 
certain what else they might know. And tools written in Python are 
automatically able to run in diverse environments, which may not be the 
case for tools written in other languages. This means that tools that 
are in Python are more likely to be used, and further, they are more 
likely to be improved or specialized to the task by those who use them.

In terms of authoring, the convenience of the markup language is only 
one factor; A bigger factor I think is having a short feedback cycle 
between edit and test, where 'test' means seeing what your written text 
would look like in the finished product. The quicker you can make that 
feedback loop, the more likely people will be to work on the docs.

-- Talin