sam-t2/devtools/amd64/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>