[Python-Dev] The docs, reloaded
talin at acm.org
Thu May 24 08:20:47 CEST 2007
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
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.
More information about the Python-Dev