<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!--Converted with LaTeX2HTML 98.2 beta6 (August 14th, 1998)
original version by:  Nikos Drakos, CBLU, University of Leeds
* revised and updated by:  Marcus Hennecke, Ross Moore, Herb Swan
* with significant contributions from:
  Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
<HTML>
<HEAD>
<TITLE>8.1 Structured Documentation </TITLE>
<META NAME="description" CONTENT="8.1 Structured Documentation ">
<META NAME="keywords" CONTENT="doc">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<LINK REL="STYLESHEET" HREF="doc.css">
<LINK REL="next" HREF="discussion.html">
<LINK REL="previous" HREF="futures.html">
<LINK REL="up" HREF="futures.html">
<LINK REL="next" HREF="discussion.html">
</HEAD>
<BODY bgcolor="#ffffff">
<div class=navigation>
<table align=center width="100%" cellpadding=0 cellspacing=2>
<tr>
<td><A HREF="discussion.html"><img width=32 height=32 align=bottom border=0 alt="next"
 src="../icons/next.gif"></A></td>
<td><A HREF="futures.html"><img width=32 height=32 align=bottom border=0 alt="up"
 src="../icons/up.gif"></A></td>
<td><A HREF="futures.html"><img width=32 height=32 align=bottom border=0 alt="previous"
 src="../icons/previous.gif"></A></td>
<td align=center bgcolor="#99CCFF" width="100%">
 <b class=title>Documenting Python</b></td>
<td><A HREF="contents.html"><img width=32 height=32 align=bottom border=0 alt="contents"
 src="../icons/contents.gif"></A></td>
<td><img width=32 height=32 align=bottom border=0 alt=""
 src="../icons/blank.gif"></td>
<td><img width=32 height=32 align=bottom border=0 alt=""
 src="../icons/blank.gif"></td>
</tr></table><b class=navlabel>Next:</b> <span class=sectref><A HREF="discussion.html">8.2 Discussion Forums</A></span>
<b class=navlabel>Up:</b> <span class=sectref><A HREF="futures.html">8. Future Directions</A></span>
<b class=navlabel>Previous:</b> <span class=sectref><A HREF="futures.html">8. Future Directions</A></span>
<br><hr></div>
<!--End of Navigation Panel-->

<H2><A NAME="SECTION000910000000000000000"></A>
<BR>
8.1 Structured Documentation 
</H2>

<P>
Most of the small changes to the <SPAN CLASS="logo LaTeX">L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X</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="logo LaTeX">L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X</SPAN>.  With almost no basic <SPAN CLASS="logo TeX">T<SMALL>E</SMALL>X</SPAN> or
    <SPAN CLASS="logo LaTeX">L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X</SPAN> markup in use, however, the markup syntax is about the
    only evidence of <SPAN CLASS="logo LaTeX">L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X</SPAN> in the actual document sources.

<P>
One side effect of this is that while we've been able to use
    standard ``engines'' for manipulating the documents, such as
    <SPAN CLASS="logo LaTeX">L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X</SPAN> and <SPAN CLASS="logo LaTeX">L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X</SPAN>2HTML, most of the actual transformations have
    been created specifically for Python.  The <SPAN CLASS="logo LaTeX">L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X</SPAN> document
    classes and <SPAN CLASS="logo LaTeX">L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X</SPAN>2HTML support are both complete implementations
    of the specific markup designed for these documents.

<P>
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.

<P>
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.

<P>
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 is available, but
    most are not free; for those which are, portability issues remain
    a problem.

<P>
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.

<P>
XXX Eventual migration to SGML/XML.

<P>
<p>
<div class=navigation><hr><table align=center width="100%" cellpadding=0 cellspacing=2>
<tr>
<td><A HREF="discussion.html"><img width=32 height=32 align=bottom border=0 alt="next"
 src="../icons/next.gif"></A></td>
<td><A HREF="futures.html"><img width=32 height=32 align=bottom border=0 alt="up"
 src="../icons/up.gif"></A></td>
<td><A HREF="futures.html"><img width=32 height=32 align=bottom border=0 alt="previous"
 src="../icons/previous.gif"></A></td>
<td align=center bgcolor="#99CCFF" width="100%">
 <b class=title>Documenting Python</b></td>
<td><A HREF="contents.html"><img width=32 height=32 align=bottom border=0 alt="contents"
 src="../icons/contents.gif"></A></td>
<td><img width=32 height=32 align=bottom border=0 alt=""
 src="../icons/blank.gif"></td>
<td><img width=32 height=32 align=bottom border=0 alt=""
 src="../icons/blank.gif"></td>
</tr></table><b class=navlabel>Next:</b> <span class=sectref><A HREF="discussion.html">8.2 Discussion Forums</A></span>
<b class=navlabel>Up:</b> <span class=sectref><A HREF="futures.html">8. Future Directions</A></span>
<b class=navlabel>Previous:</b> <span class=sectref><A HREF="futures.html">8. Future Directions</A></span>
</div>
<!--End of Navigation Panel-->
<ADDRESS>
<hr>Send comments on this document to <a href="mailto:python-docs@python.org">python-docs@python.org</a>.
</ADDRESS>
</BODY>
</HTML>
