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 _______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com