[OpenSPARC-T2-DV] / tools / src / nas,5.n2.os.2 / lib / python / html / python / doc / latex-syntax.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="latex-structure.html" />
<link rel="prev" href="latex-primer.html" />
<link rel="parent" href="latex-primer.html" />
<link rel="next" href="latex-structure.html" />
<meta name='aesop' content='information' />
<title>4.1 Syntax </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="4 LaTeX Primer"
  href="latex-primer.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="4 LaTeX Primer"
  href="latex-primer.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="4.2 Hierarchical Structure"
  href="latex-structure.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="latex-primer.html">4 LaTeX Primer</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="latex-primer.html">4 LaTeX Primer</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="latex-structure.html">4.2 Hierarchical Structure</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H2><A NAME="SECTION000510000000000000000"></A><A NAME="latex-syntax"></A>
<BR>
4.1 Syntax 
</H2>

<P>
There are some things that an author of Python documentation needs
    to know about <span class="LaTeX">LaTeX</span> syntax.

<P>
A <i class="dfn">comment</i> is started by the ``percent'' character
    ("<tt class="character">%</tt>") and continues through the end of the line and all
    leading whitespace on the following line.  This is a little
    different from any programming language I know of, so an example
    is in order:

<P>
<div class="verbatim"><pre>
This is text.% comment
    This is more text.  % another comment
Still more text.
</pre></div>

<P>
The first non-comment character following the first comment is the
    letter "<tt class="character">T</tt>" on the second line; the leading whitespace on
    that line is consumed as part of the first comment.  This means
    that there is no space between the first and second sentences, so
    the period and letter "<tt class="character">T</tt>" will be directly adjacent in
    the typeset document.

<P>
Note also that though the first non-comment character after the
    second comment is the letter "<tt class="character">S</tt>", there is whitespace
    preceding the comment, so the two sentences are separated as
    expected.

<P>
A <i class="dfn">group</i> is an enclosure for a collection of text and
    commands which encloses the formatting context and constrains the
    scope of any changes to that context made by commands within the
    group.  Groups can be nested hierarchically.  The formatting
    context includes the font and the definition of additional macros
    (or overrides of macros defined in outer groups).  Syntactically,
    groups are enclosed in braces:

<P>
<div class="verbatim"><pre>
{text in a group}
</pre></div>

<P>
An alternate syntax for a group using brackets, <code>[...]</code>, is
    used by macros and environment constructors which take optional
    parameters; brackets do not normally hold syntactic significance.
    A degenerate group, containing only one atomic bit of content,
    does not need to have an explicit group, unless it is required to
    avoid ambiguity.  Since Python tends toward the explicit, groups
    are also made explicit in the documentation markup.

<P>
Groups are used only sparingly in the Python documentation, except
    for their use in marking parameters to macros and environments.

<P>
A <i class="dfn">macro</i> is usually a simple construct which is identified by
    name and can take some number of parameters.  In normal <span class="LaTeX">LaTeX</span>
    usage, one of these can be optional.  The markup is introduced
    using the backslash character ("<tt class="character">&#92;</tt>"), and the name is
    given by alphabetic characters (no digits, hyphens, or
    underscores).  Required parameters should be marked as a group,
    and optional parameters should be marked using the alternate
    syntax for a group.

<P>
For example, a macro which takes a single parameter
    would appear like this:

<P>
<div class="verbatim"><pre>
\name{parameter}
</pre></div>

<P>
A macro which takes an optional parameter would be typed like this
    when the optional parameter is given:

<P>
<div class="verbatim"><pre>
\name[optional]
</pre></div>

<P>
If both optional and required parameters are to be required, it
    looks like this:

<P>
<div class="verbatim"><pre>
\name[optional]{required}
</pre></div>

<P>
A macro name may be followed by a space or newline; a space
    between the macro name and any parameters will be consumed, but
    this usage is not practiced in the Python documentation.  Such a
    space is still consumed if there are no parameters to the macro,
    in which case inserting an empty group (<code>{}</code>) or explicit
    word space ("<tt class="samp">&#92; </tt>") immediately after the macro name helps to
    avoid running the expansion of the macro into the following text.
    Macros which take no parameters but which should not be followed
    by a word space do not need special treatment if the following
    character in the document source if not a name character (such as
    punctuation).

<P>
Each line of this example shows an appropriate way to write text
    which includes a macro which takes no parameters:

<P>
<div class="verbatim"><pre>
This \UNIX{} is followed by a space.
This \UNIX\ is also followed by a space.
\UNIX, followed by a comma, needs no additional markup.
</pre></div>

<P>
An <i class="dfn">environment</i> is a larger construct than a macro, and can
    be used for things with more content than would conveniently fit
    in a macro parameter.  They are primarily used when formatting
    parameters need to be changed before and after a large chunk of
    content, but the content itself needs to be highly flexible.  Code
    samples are presented using an environment, and descriptions of
    functions, methods, and classes are also marked using environments.

<P>
Since the content of an environment is free-form and can consist
    of several paragraphs, they are actually marked using a pair of
    macros: <tt class='macro'>&#92;begin</tt> and <tt class='macro'>&#92;end</tt>.  These macros both take the
    name of the environment as a parameter.  An example is the
    environment used to mark the abstract of a document:

<P>
<div class="verbatim"><pre>
\begin{abstract}
  This is the text of the abstract.  It concisely explains what
  information is found in the document.

  It can consist of multiple paragraphs.
\end{abstract}
</pre></div>

<P>
An environment can also have required and optional parameters of
    its own.  These follow the parameter of the <tt class='macro'>&#92;begin</tt> macro.
    This example shows an environment which takes a single required
    parameter:

<P>
<div class="verbatim"><pre>
\begin{datadesc}{controlnames}
  A 33-element string array that contains the \ASCII{} mnemonics for
  the thirty-two \ASCII{} control characters from 0 (NUL) to 0x1f
  (US), in order, plus the mnemonic \samp{SP} for the space character.
\end{datadesc}
</pre></div>

<P>
There are a number of less-used marks in <span class="LaTeX">LaTeX</span> which are used
    to enter characters which are not found in ASCII or which a
    considered special, or <em>active</em> in <span class="TeX">TeX</span> or <span class="LaTeX">LaTeX</span>.  Given
    that these are often used adjacent to other characters, the markup
    required to produce the proper character may need to be followed
    by a space or an empty group, or the markup can be enclosed in a
    group.  Some which are found in Python documentation are:

<P>
<div class="center"><table class="realtable">
  <thead>
    <tr>
      <th class="center">Character</th>
      <th class="left"  >Markup</th>
      </tr>
    </thead>
  <tbody>
    <tr><td class="center" valign="baseline">^</td>
        <td class="left"  ><code>&#92;textasciicircum</code></td></tr>
    <tr><td class="center" valign="baseline">~</td>
        <td class="left"  ><code>&#92;textasciitilde</code></td></tr>
    <tr><td class="center" valign="baseline">&gt;</td>
        <td class="left"  ><code>&#92;textgreater</code></td></tr>
    <tr><td class="center" valign="baseline">&lt;</td>
        <td class="left"  ><code>&#92;textless</code></td></tr>
    <tr><td class="center" valign="baseline">&#231;</td>
        <td class="left"  ><code>&#92;c c</code></td></tr>
    <tr><td class="center" valign="baseline">&#246;</td>
        <td class="left"  ><code>&#92;"o</code></td></tr>
    <tr><td class="center" valign="baseline">&#248;</td>
        <td class="left"  ><code>&#92;o</code></td></tr></tbody>
</table></div>

<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="4 LaTeX Primer"
  href="latex-primer.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="4 LaTeX Primer"
  href="latex-primer.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="4.2 Hierarchical Structure"
  href="latex-structure.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="latex-primer.html">4 LaTeX Primer</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="latex-primer.html">4 LaTeX Primer</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="latex-structure.html">4.2 Hierarchical Structure</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
86530b38 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="latex-structure.html" />
	12	<link rel="prev" href="latex-primer.html" />
	13	<link rel="parent" href="latex-primer.html" />
	14	<link rel="next" href="latex-structure.html" />
	15	<meta name='aesop' content='information' />
	16	<title>4.1 Syntax </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="4 LaTeX Primer"
	24	href="latex-primer.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="4 LaTeX Primer"
	27	href="latex-primer.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="4.2 Hierarchical Structure"
	30	href="latex-structure.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="latex-primer.html">4 LaTeX Primer</A>
	44	<b class="navlabel">Up:</b>
	45	<a class="sectref" rel="parent" href="latex-primer.html">4 LaTeX Primer</A>
	46	<b class="navlabel">Next:</b>
	47	<a class="sectref" rel="next" href="latex-structure.html">4.2 Hierarchical Structure</A>
	48	</div>
	49	<hr /></div>
	50	</DIV>
	51	<!--End of Navigation Panel-->
	52
	53	<H2><A NAME="SECTION000510000000000000000"></A><A NAME="latex-syntax"></A>
	54	<BR>
	55	4.1 Syntax
	56	</H2>
	57
	58	<P>
	59	There are some things that an author of Python documentation needs
	60	to know about <span class="LaTeX">LaTeX</span> syntax.
	61
	62	<P>
	63	A <i class="dfn">comment</i> is started by the ``percent'' character
	64	("<tt class="character">%</tt>") and continues through the end of the line and all
65	leading whitespace on the following line. This is a little
66	different from any programming language I know of, so an example
67	is in order:
68
69	<P>
70	<div class="verbatim"><pre>
71	This is text.% comment
72	This is more text. % another comment
73	Still more text.
74	</pre></div>
75
76	<P>
77	The first non-comment character following the first comment is the
78	letter "<tt class="character">T</tt>" on the second line; the leading whitespace on
79	that line is consumed as part of the first comment. This means
80	that there is no space between the first and second sentences, so
81	the period and letter "<tt class="character">T</tt>" will be directly adjacent in
82	the typeset document.
83
84	<P>
85	Note also that though the first non-comment character after the
86	second comment is the letter "<tt class="character">S</tt>", there is whitespace
87	preceding the comment, so the two sentences are separated as
88	expected.
89
90	<P>
91	A <i class="dfn">group</i> is an enclosure for a collection of text and
92	commands which encloses the formatting context and constrains the
93	scope of any changes to that context made by commands within the
94	group. Groups can be nested hierarchically. The formatting
95	context includes the font and the definition of additional macros
96	(or overrides of macros defined in outer groups). Syntactically,
97	groups are enclosed in braces:
98
99	<P>
100	<div class="verbatim"><pre>
101	{text in a group}
102	</pre></div>
103
104	<P>
105	An alternate syntax for a group using brackets, <code>[...]</code>, is
106	used by macros and environment constructors which take optional
107	parameters; brackets do not normally hold syntactic significance.
108	A degenerate group, containing only one atomic bit of content,
109	does not need to have an explicit group, unless it is required to
110	avoid ambiguity. Since Python tends toward the explicit, groups
111	are also made explicit in the documentation markup.
112
113	<P>
114	Groups are used only sparingly in the Python documentation, except
115	for their use in marking parameters to macros and environments.
116
117	<P>
118	A <i class="dfn">macro</i> is usually a simple construct which is identified by
119	name and can take some number of parameters. In normal <span class="LaTeX">LaTeX</span>
120	usage, one of these can be optional. The markup is introduced
121	using the backslash character ("<tt class="character">\</tt>"), and the name is
122	given by alphabetic characters (no digits, hyphens, or
123	underscores). Required parameters should be marked as a group,
124	and optional parameters should be marked using the alternate
125	syntax for a group.
126
127	<P>
128	For example, a macro which takes a single parameter
129	would appear like this:
130
131	<P>
132	<div class="verbatim"><pre>
133	\name{parameter}
134	</pre></div>
135
136	<P>
137	A macro which takes an optional parameter would be typed like this
138	when the optional parameter is given:
139
140	<P>
141	<div class="verbatim"><pre>
142	\name[optional]
143	</pre></div>
144
145	<P>
146	If both optional and required parameters are to be required, it
147	looks like this:
148
149	<P>
150	<div class="verbatim"><pre>
151	\name[optional]{required}
152	</pre></div>
153
154	<P>
155	A macro name may be followed by a space or newline; a space
156	between the macro name and any parameters will be consumed, but
157	this usage is not practiced in the Python documentation. Such a
158	space is still consumed if there are no parameters to the macro,
159	in which case inserting an empty group (<code>{}</code>) or explicit
160	word space ("<tt class="samp">\ </tt>") immediately after the macro name helps to
161	avoid running the expansion of the macro into the following text.
162	Macros which take no parameters but which should not be followed
163	by a word space do not need special treatment if the following
164	character in the document source if not a name character (such as
165	punctuation).
166
167	<P>
168	Each line of this example shows an appropriate way to write text
169	which includes a macro which takes no parameters:
170
171	<P>
172	<div class="verbatim"><pre>
173	This \UNIX{} is followed by a space.
174	This \UNIX\ is also followed by a space.
175	\UNIX, followed by a comma, needs no additional markup.
176	</pre></div>
177
178	<P>
179	An <i class="dfn">environment</i> is a larger construct than a macro, and can
180	be used for things with more content than would conveniently fit
181	in a macro parameter. They are primarily used when formatting
182	parameters need to be changed before and after a large chunk of
183	content, but the content itself needs to be highly flexible. Code
184	samples are presented using an environment, and descriptions of
185	functions, methods, and classes are also marked using environments.
186
187	<P>
188	Since the content of an environment is free-form and can consist
189	of several paragraphs, they are actually marked using a pair of
190	macros: <tt class='macro'>\begin</tt> and <tt class='macro'>\end</tt>. These macros both take the
191	name of the environment as a parameter. An example is the
192	environment used to mark the abstract of a document:
193
194	<P>
195	<div class="verbatim"><pre>
196	\begin{abstract}
197	This is the text of the abstract. It concisely explains what
198	information is found in the document.
199
200	It can consist of multiple paragraphs.
201	\end{abstract}
202	</pre></div>
203
204	<P>
205	An environment can also have required and optional parameters of
206	its own. These follow the parameter of the <tt class='macro'>\begin</tt> macro.
207	This example shows an environment which takes a single required
208	parameter:
209
210	<P>
211	<div class="verbatim"><pre>
212	\begin{datadesc}{controlnames}
213	A 33-element string array that contains the \ASCII{} mnemonics for
214	the thirty-two \ASCII{} control characters from 0 (NUL) to 0x1f
215	(US), in order, plus the mnemonic \samp{SP} for the space character.
216	\end{datadesc}
217	</pre></div>
218
219	<P>
220	There are a number of less-used marks in <span class="LaTeX">LaTeX</span> which are used
221	to enter characters which are not found in ASCII or which a
222	considered special, or <em>active</em> in <span class="TeX">TeX</span> or <span class="LaTeX">LaTeX</span>. Given
223	that these are often used adjacent to other characters, the markup
224	required to produce the proper character may need to be followed
225	by a space or an empty group, or the markup can be enclosed in a
226	group. Some which are found in Python documentation are:
227
228	<P>
229	<div class="center"><table class="realtable">
230	<thead>
231	<tr>
232	<th class="center">Character</th>
233	<th class="left" >Markup</th>
234	</tr>
235	</thead>
236	<tbody>
237	<tr><td class="center" valign="baseline">^</td>
238	<td class="left" ><code>\textasciicircum</code></td></tr>
239	<tr><td class="center" valign="baseline">~</td>
240	<td class="left" ><code>\textasciitilde</code></td></tr>
241	<tr><td class="center" valign="baseline">></td>
242	<td class="left" ><code>\textgreater</code></td></tr>
243	<tr><td class="center" valign="baseline"><</td>
244	<td class="left" ><code>\textless</code></td></tr>
245	<tr><td class="center" valign="baseline">ç</td>
246	<td class="left" ><code>\c c</code></td></tr>
247	<tr><td class="center" valign="baseline">ö</td>
248	<td class="left" ><code>\"o</code></td></tr>
249	<tr><td class="center" valign="baseline">ø</td>
250	<td class="left" ><code>\o</code></td></tr></tbody>
251	</table></div>
252
253	<P>
254
255	<DIV CLASS="navigation">
256	<div class='online-navigation'>
257	<p></p><hr />
258	<table align="center" width="100%" cellpadding="0" cellspacing="2">
259	<tr>
260	<td class='online-navigation'><a rel="prev" title="4 LaTeX Primer"
261	href="latex-primer.html"><img src='../icons/previous.png'
262	border='0' height='32' alt='Previous Page' width='32' /></A></td>
263	<td class='online-navigation'><a rel="parent" title="4 LaTeX Primer"
264	href="latex-primer.html"><img src='../icons/up.png'
265	border='0' height='32' alt='Up One Level' width='32' /></A></td>
266	<td class='online-navigation'><a rel="next" title="4.2 Hierarchical Structure"
267	href="latex-structure.html"><img src='../icons/next.png'
268	border='0' height='32' alt='Next Page' width='32' /></A></td>
269	<td align="center" width="100%">Documenting Python</td>
270	<td class='online-navigation'><a rel="contents" title="Table of Contents"
271	href="contents.html"><img src='../icons/contents.png'
272	border='0' height='32' alt='Contents' width='32' /></A></td>
273	<td class='online-navigation'><img src='../icons/blank.png'
274	border='0' height='32' alt='' width='32' /></td>
275	<td class='online-navigation'><img src='../icons/blank.png'
276	border='0' height='32' alt='' width='32' /></td>
277	</tr></table>
278	<div class='online-navigation'>
279	<b class="navlabel">Previous:</b>
280	<a class="sectref" rel="prev" href="latex-primer.html">4 LaTeX Primer</A>
281	<b class="navlabel">Up:</b>
282	<a class="sectref" rel="parent" href="latex-primer.html">4 LaTeX Primer</A>
283	<b class="navlabel">Next:</b>
284	<a class="sectref" rel="next" href="latex-structure.html">4.2 Hierarchical Structure</A>
285	</div>
286	</div>
287	<hr />
288	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
289	</DIV>
290	<!--End of Navigation Panel-->
291	<ADDRESS>
292	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
293	</ADDRESS>
294	</BODY>
295	</HTML>