[OpenSPARC-T2-SAM] / sam-t2 / devtools / v9 / html / python / doc / structured.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<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>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<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>
</tr></table>
<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>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H2><A NAME="SECTION0001010000000000000000"></A><A NAME="structured"></A>
<BR>
9.1 Structured Documentation 
</H2>

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

<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="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.

<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 are 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, and the portability issues of those which are, are not
    expected to be significant.

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

<P>
XXX Eventual migration to XML.

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

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

<P>

<DIV CLASS="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<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>
</tr></table>
<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>
</div>
</div>
<hr />
<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
</DIV>
<!--End of Navigation Panel-->
<ADDRESS>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</ADDRESS>
</BODY>
</HTML>
Commit	Line	Data
920dae64 AT	1	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	2	<html>
	3	<head>
	4	<link rel="STYLESHEET" href="doc.css" type='text/css' />
	5	<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
	6	<link rel='start' href='../index.html' title='Python Documentation Index' />
	7	<link rel="first" href="doc.html" title='Documenting Python' />
	8	<link rel='contents' href='contents.html' title="Contents" />
	9	<link rel='last' href='about.html' title='About this document...' />
	10	<link rel='help' href='about.html' title='About this document...' />
	11	<link rel="next" href="discussion.html" />
	12	<link rel="prev" href="futures.html" />
	13	<link rel="parent" href="futures.html" />
	14	<link rel="next" href="discussion.html" />
	15	<meta name='aesop' content='information' />
	16	<title>9.1 Structured Documentation </title>
	17	</head>
	18	<body>
	19	<DIV CLASS="navigation">
	20	<div id='top-navigation-panel' xml:id='top-navigation-panel'>
	21	<table align="center" width="100%" cellpadding="0" cellspacing="2">
	22	<tr>
	23	<td class='online-navigation'><a rel="prev" title="9 Future Directions"
	24	href="futures.html"><img src='../icons/previous.png'
	25	border='0' height='32' alt='Previous Page' width='32' /></A></td>
	26	<td class='online-navigation'><a rel="parent" title="9 Future Directions"
	27	href="futures.html"><img src='../icons/up.png'
	28	border='0' height='32' alt='Up One Level' width='32' /></A></td>
	29	<td class='online-navigation'><a rel="next" title="9.2 Discussion Forums"
	30	href="discussion.html"><img src='../icons/next.png'
	31	border='0' height='32' alt='Next Page' width='32' /></A></td>
	32	<td align="center" width="100%">Documenting Python</td>
	33	<td class='online-navigation'><a rel="contents" title="Table of Contents"
	34	href="contents.html"><img src='../icons/contents.png'
	35	border='0' height='32' alt='Contents' width='32' /></A></td>
	36	<td class='online-navigation'><img src='../icons/blank.png'
	37	border='0' height='32' alt='' width='32' /></td>
	38	<td class='online-navigation'><img src='../icons/blank.png'
	39	border='0' height='32' alt='' width='32' /></td>
	40	</tr></table>
	41	<div class='online-navigation'>
	42	<b class="navlabel">Previous:</b>
	43	<a class="sectref" rel="prev" href="futures.html">9 Future Directions</A>
	44	<b class="navlabel">Up:</b>
	45	<a class="sectref" rel="parent" href="futures.html">9 Future Directions</A>
	46	<b class="navlabel">Next:</b>
	47	<a class="sectref" rel="next" href="discussion.html">9.2 Discussion Forums</A>
	48	</div>
	49	<hr /></div>
	50	</DIV>
	51	<!--End of Navigation Panel-->
	52
	53	<H2><A NAME="SECTION0001010000000000000000"></A><A NAME="structured"></A>
	54	<BR>
	55	9.1 Structured Documentation
	56	</H2>
	57
	58	<P>
	59	Most of the small changes to the <span class="LaTeX">LaTeX</span> markup have been made
	60	with an eye to divorcing the markup from the presentation, making
	61	both a bit more maintainable. Over the course of 1998, a large
	62	number of changes were made with exactly this in mind; previously,
	63	changes had been made but in a less systematic manner and with
	64	more concern for not needing to update the existing content. The
65	result has been a highly structured and semantically loaded markup
66	language implemented in <span class="LaTeX">LaTeX</span>. With almost no basic <span class="TeX">TeX</span> or
67	<span class="LaTeX">LaTeX</span> markup in use, however, the markup syntax is about the
68	only evidence of <span class="LaTeX">LaTeX</span> in the actual document sources.
69
70	<P>
71	One side effect of this is that while we've been able to use
72	standard ``engines'' for manipulating the documents, such as
73	<span class="LaTeX">LaTeX</span> and <span class="LaTeX">LaTeX</span>2HTML, most of the actual transformations have
74	been created specifically for Python. The <span class="LaTeX">LaTeX</span> document
75	classes and <span class="LaTeX">LaTeX</span>2HTML support are both complete implementations
76	of the specific markup designed for these documents.
77
78	<P>
79	Combining highly customized markup with the somewhat esoteric
80	systems used to process the documents leads us to ask some
81	questions: Can we do this more easily? and, Can we do this
82	better? After a great deal of discussion with the community, we
83	have determined that actively pursuing modern structured
84	documentation systems is worth some investment of time.
85
86	<P>
87	There appear to be two real contenders in this arena: the Standard
88	General Markup Language (SGML), and the Extensible Markup Language
89	(XML). Both of these standards have advantages and disadvantages,
90	and many advantages are shared.
91
92	<P>
93	SGML offers advantages which may appeal most to authors,
94	especially those using ordinary text editors. There are also
95	additional abilities to define content models. A number of
96	high-quality tools with demonstrated maturity are available, but
97	most are not free; for those which are, portability issues remain
98	a problem.
99
100	<P>
101	The advantages of XML include the availability of a large number
102	of evolving tools. Unfortunately, many of the associated
103	standards are still evolving, and the tools will have to follow
104	along. This means that developing a robust tool set that uses
105	more than the basic XML 1.0 recommendation is not possible in the
106	short term. The promised availability of a wide variety of
107	high-quality tools which support some of the most important
108	related standards is not immediate. Many tools are likely to be
109	free, and the portability issues of those which are, are not
110	expected to be significant.
111
112	<P>
113	It turns out that converting to an XML or SGML system holds
114	promise for translators as well; how much can be done to ease the
115	burden on translators remains to be seen, and may have some impact
116	on the schema and specific technologies used.
117
118	<P>
119	XXX Eventual migration to XML.
120
121	<P>
122	The documentation will be moved to XML in the future, and tools
123	are being written which will convert the documentation from the
124	current format to something close to a finished version, to the
125	extent that the desired information is already present in the
126	documentation. Some XSLT stylesheets have been started for
127	presenting a preliminary XML version as HTML, but the results are
128	fairly rough.
129
130	<P>
131	The timeframe for the conversion is not clear since there doesn't
132	seem to be much time available to work on this, but the apparent
133	benefits are growing more substantial at a moderately rapid pace.
134
135	<P>
136
137	<DIV CLASS="navigation">
138	<div class='online-navigation'>
139	<p></p><hr />
140	<table align="center" width="100%" cellpadding="0" cellspacing="2">
141	<tr>
142	<td class='online-navigation'><a rel="prev" title="9 Future Directions"
143	href="futures.html"><img src='../icons/previous.png'
144	border='0' height='32' alt='Previous Page' width='32' /></A></td>
145	<td class='online-navigation'><a rel="parent" title="9 Future Directions"
146	href="futures.html"><img src='../icons/up.png'
147	border='0' height='32' alt='Up One Level' width='32' /></A></td>
148	<td class='online-navigation'><a rel="next" title="9.2 Discussion Forums"
149	href="discussion.html"><img src='../icons/next.png'
150	border='0' height='32' alt='Next Page' width='32' /></A></td>
151	<td align="center" width="100%">Documenting Python</td>
152	<td class='online-navigation'><a rel="contents" title="Table of Contents"
153	href="contents.html"><img src='../icons/contents.png'
154	border='0' height='32' alt='Contents' width='32' /></A></td>
155	<td class='online-navigation'><img src='../icons/blank.png'
156	border='0' height='32' alt='' width='32' /></td>
157	<td class='online-navigation'><img src='../icons/blank.png'
158	border='0' height='32' alt='' width='32' /></td>
159	</tr></table>
160	<div class='online-navigation'>
161	<b class="navlabel">Previous:</b>
162	<a class="sectref" rel="prev" href="futures.html">9 Future Directions</A>
163	<b class="navlabel">Up:</b>
164	<a class="sectref" rel="parent" href="futures.html">9 Future Directions</A>
165	<b class="navlabel">Next:</b>
166	<a class="sectref" rel="next" href="discussion.html">9.2 Discussion Forums</A>
167	</div>
168	</div>
169	<hr />
170	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
171	</DIV>
172	<!--End of Navigation Panel-->
173	<ADDRESS>
174	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
175	</ADDRESS>
176	</BODY>
177	</HTML>