<!DOCTYPE html PUBLIC
"-//W3C//DTD HTML 4.0 Transitional//EN">
<link rel=
"STYLESHEET" href=
"doc.css" type='text/css'
/>
<link rel=
"SHORTCUT ICON" href=
"../icons/pyfav.png" type=
"image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index'
/>
<link rel=
"first" href=
"doc.html" title='Documenting Python'
/>
<link rel='contents' href='contents.html'
title=
"Contents" />
<link rel='last' href='about.html' title='About this document...'
/>
<link rel='help' href='about.html' title='About this document...'
/>
<link rel=
"next" href=
"discussion.html" />
<link rel=
"prev" href=
"futures.html" />
<link rel=
"parent" href=
"futures.html" />
<link rel=
"next" href=
"discussion.html" />
<meta name='aesop' content='information'
/>
<title>9.1 Structured Documentation
</title>
<div id='top-navigation-panel' xml:id='top-navigation-panel'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"9 Future Directions"
href=
"futures.html"><img src='../icons/previous.png'
border='
0' height='
32' alt='Previous Page' width='
32'
/></A></td><td class='online-navigation'
><a rel=
"parent" title=
"9 Future Directions"
href=
"futures.html"><img src='../icons/up.png'
border='
0' height='
32' alt='Up One Level' width='
32'
/></A></td><td class='online-navigation'
><a rel=
"next" title=
"9.2 Discussion Forums"
href=
"discussion.html"><img src='../icons/next.png'
border='
0' height='
32' alt='Next Page' width='
32'
/></A></td><td align=
"center" width=
"100%">Documenting Python
</td>
<td class='online-navigation'
><a rel=
"contents" title=
"Table of Contents"
href=
"contents.html"><img src='../icons/contents.png'
border='
0' height='
32' alt='Contents' width='
32'
/></A></td><td class='online-navigation'
><img src='../icons/blank.png'
border='
0' height='
32' alt='' width='
32'
/></td><td class='online-navigation'
><img src='../icons/blank.png'
border='
0' height='
32' alt='' width='
32'
/></td><div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"futures.html">9 Future Directions
</A>
<b class=
"navlabel">Up:
</b>
<a class=
"sectref" rel=
"parent" href=
"futures.html">9 Future Directions
</A>
<b class=
"navlabel">Next:
</b>
<a class=
"sectref" rel=
"next" href=
"discussion.html">9.2 Discussion Forums
</A>
<!--End of Navigation Panel-->
<H2><A NAME=
"SECTION0001010000000000000000"></A><A NAME=
"structured"></A>
9.1 Structured Documentation
Most of the small changes to the
<span class=
"LaTeX">LaTeX
</span> 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
<span class=
"LaTeX">LaTeX
</span>. With almost no basic
<span class=
"TeX">TeX
</span> or
<span class=
"LaTeX">LaTeX
</span> markup in use, however, the markup syntax is about the
only evidence of
<span class=
"LaTeX">LaTeX
</span> 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
<span class=
"LaTeX">LaTeX
</span> and
<span class=
"LaTeX">LaTeX
</span>2HTML, most of the actual transformations have
been created specifically for Python. The
<span class=
"LaTeX">LaTeX
</span> document
classes and
<span class=
"LaTeX">LaTeX
</span>2HTML 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
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
The timeframe for the conversion is not clear since there doesn't
seem to be much time available to work on this, but the apparent
benefits are growing more substantial at a moderately rapid pace.
<div class='online-navigation'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"9 Future Directions"
href=
"futures.html"><img src='../icons/previous.png'
border='
0' height='
32' alt='Previous Page' width='
32'
/></A></td><td class='online-navigation'
><a rel=
"parent" title=
"9 Future Directions"
href=
"futures.html"><img src='../icons/up.png'
border='
0' height='
32' alt='Up One Level' width='
32'
/></A></td><td class='online-navigation'
><a rel=
"next" title=
"9.2 Discussion Forums"
href=
"discussion.html"><img src='../icons/next.png'
border='
0' height='
32' alt='Next Page' width='
32'
/></A></td><td align=
"center" width=
"100%">Documenting Python
</td>
<td class='online-navigation'
><a rel=
"contents" title=
"Table of Contents"
href=
"contents.html"><img src='../icons/contents.png'
border='
0' height='
32' alt='Contents' width='
32'
/></A></td><td class='online-navigation'
><img src='../icons/blank.png'
border='
0' height='
32' alt='' width='
32'
/></td><td class='online-navigation'
><img src='../icons/blank.png'
border='
0' height='
32' alt='' width='
32'
/></td><div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"futures.html">9 Future Directions
</A>
<b class=
"navlabel">Up:
</b>
<a class=
"sectref" rel=
"parent" href=
"futures.html">9 Future Directions
</A>
<b class=
"navlabel">Next:
</b>
<a class=
"sectref" rel=
"next" href=
"discussion.html">9.2 Discussion Forums
</A>
<span class=
"release-info">Release
2.4.2, documentation updated on
28 September
2005.
</span>
<!--End of Navigation Panel-->
See
<i><a href=
"about.html">About this document...
</a></i> for information on suggesting changes.
projects / OpenSPARC-T2-DV / blob