File: //usr/share/doc/python-docs-2.4.3/html/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">\</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">\ </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'>\begin</tt> and <tt class='macro'>\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'>\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>\textasciicircum</code></td></tr>
<tr><td class="center" valign="baseline">~</td>
<td class="left" ><code>\textasciitilde</code></td></tr>
<tr><td class="center" valign="baseline">></td>
<td class="left" ><code>\textgreater</code></td></tr>
<tr><td class="center" valign="baseline"><</td>
<td class="left" ><code>\textless</code></td></tr>
<tr><td class="center" valign="baseline">ç</td>
<td class="left" ><code>\c c</code></td></tr>
<tr><td class="center" valign="baseline">ö</td>
<td class="left" ><code>\"o</code></td></tr>
<tr><td class="center" valign="baseline">ø</td>
<td class="left" ><code>\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.3, documentation updated on 29 March 2006.</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>