9.1 Structured Documentation
Most of the small changes to the LaTeX markup have been made with an eye to divorcing the markup from the presentation, making both a bit more maintainable. Over the course of 1998, a large number of changes were made with exactly this in mind; previously, changes had been made but in a less systematic manner and with more concern for not needing to update the existing content. The result has been a highly structured and semantically loaded markup language implemented in LaTeX. With almost no basic TeX or LaTeX markup in use, however, the markup syntax is about the only evidence of LaTeX in the actual document sources.
One side effect of this is that while we've been able to use standard ``engines'' for manipulating the documents, such as LaTeX and LaTeX2HTML, most of the actual transformations have been created specifically for Python. The LaTeX document classes and LaTeX2HTML support are both complete implementations of the specific markup designed for these documents.
Combining highly customized markup with the somewhat esoteric systems used to process the documents leads us to ask some questions: Can we do this more easily? and, Can we do this better? After a great deal of discussion with the community, we have determined that actively pursuing modern structured documentation systems is worth some investment of time.
There appear to be two real contenders in this arena: the Standard General Markup Language (SGML), and the Extensible Markup Language (XML). Both of these standards have advantages and disadvantages, and many advantages are shared.
SGML offers advantages which may appeal most to authors, especially those using ordinary text editors. There are also additional abilities to define content models. A number of high-quality tools with demonstrated maturity are available, but most are not free; for those which are, portability issues remain a problem.
The advantages of XML include the availability of a large number of evolving tools. Unfortunately, many of the associated standards are still evolving, and the tools will have to follow along. This means that developing a robust tool set that uses more than the basic XML 1.0 recommendation is not possible in the short term. The promised availability of a wide variety of high-quality tools which support some of the most important related standards is not immediate. Many tools are likely to be free, and the portability issues of those which are, are not expected to be significant.
It turns out that converting to an XML or SGML system holds promise for translators as well; how much can be done to ease the burden on translators remains to be seen, and may have some impact on the schema and specific technologies used.
XXX Eventual migration to XML.
The documentation will be moved to XML in the future, and tools are being written which will convert the documentation from the current format to something close to a finished version, to the extent that the desired information is already present in the documentation. Some XSLT stylesheets have been started for presenting a preliminary XML version as HTML, but the results are fairly rough.
The timeframe for the conversion is not clear since there doesn't seem to be much time available to work on this, but the appearant benefits are growing more substantial at a moderately rapid pace.
 |
 |
 |
Documenting Python |  |
 |
|
Release 2.4b2, documentation updated on 13 November 2004.