File: //usr/share/doc/python-docs-2.4.3/html/doc/references.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="indexing.html" />
<link rel="prev" href="table-markup.html" />
<link rel="parent" href="special-constructs.html" />
<link rel="next" href="indexing.html" />
<meta name='aesop' content='information' />
<title>6.10 Reference List Markup </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="6.9 Table Markup"
href="table-markup.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="6 Special Markup Constructs"
href="special-constructs.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="6.11 Index-generating Markup"
href="indexing.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="table-markup.html">6.9 Table Markup</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="special-constructs.html">6 Special Markup Constructs</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="indexing.html">6.11 Index-generating Markup</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->
<H2><A NAME="SECTION0007100000000000000000"></A><A NAME="references"></A>
<BR>
6.10 Reference List Markup
</H2>
<P>
Many sections include a list of references to module documentation
or external documents. These lists are created using the
<tt class='environment'>\seealso</tt> or <tt class='environment'>\seealso*</tt> environments. These environments
define some additional macros to support creating reference
entries in a reasonable manner.
<P>
The <tt class='environment'>\seealso</tt> environment is typically placed in a section
just before any sub-sections. This is done to ensure that
reference links related to the section are not hidden in a
subsection in the hypertext renditions of the documentation. For
the HTML output, it is shown as a ``side bar,'' boxed off from the
main flow of the text. The <tt class='environment'>\seealso*</tt> environment is
different in that it should be used when a list of references is
being presented as part of the primary content; it is not
specially set off from the text.
<P>
<dl class='envdesc'>
<dt><tt>\begin{<b class='environment'>seealso</b>}</tt>
<br /><tt>\end{<b class='environment'>seealso</b>}</tt></dt>
<dd>
This environment creates a ``See also:'' heading and defines the
markup used to describe individual references.
</dd></dl>
<P>
<dl class='envdesc'>
<dt><tt>\begin{<b class='environment'>seealso*</b>}</tt>
<br /><tt>\end{<b class='environment'>seealso*</b>}</tt></dt>
<dd>
This environment is used to create a list of references which
form part of the main content. It is not given a special
header and is not set off from the main flow of the text. It
provides the same additional markup used to describe individual
references.
</dd></dl>
<P>
For each of the following macros, <var>why</var> should be one or more
complete sentences, starting with a capital letter (unless it
starts with an identifier, which should not be modified), and
ending with the appropriate punctuation.
<P>
These macros are only defined within the content of the
<tt class='environment'>\seealso</tt> and <tt class='environment'>\seealso*</tt> environments.
<P>
<dl class='macrodesc'>
<dt><b><tt class='macro'>\seelink</tt></b>
<tt>{</tt><var>url</var><tt>}</tt><tt>{</tt><var>linktext</var><tt>}</tt><tt>{</tt><var>why</var><tt>}</tt></dt>
<dd>
References to specific on-line resources should be given using
the <tt class='macro'>\seelink</tt> macro if they don't have a meaningful title
but there is some short description of what's at the end of the
link. Online documents which have identifiable titles should be
referenced using the <tt class='macro'>\seetitle</tt> macro, using the optional
parameter to that macro to provide the URL.
</dd></dl>
<P>
<dl class='macrodesc'>
<dt><b><tt class='macro'>\seemodule</tt></b>
<tt>[</tt><var>key</var><tt>]</tt><tt>{</tt><var>name</var><tt>}</tt><tt>{</tt><var>why</var><tt>}</tt></dt>
<dd>
Refer to another module. <var>why</var> should be a brief
explanation of why the reference may be interesting. The module
name is given in <var>name</var>, with the link key given in
<var>key</var> if necessary. In the HTML and PDF conversions, the
module name will be a hyperlink to the referred-to module.
<span class="note"><b class="label">Note:</b>
The module must be documented in the same
document (the corresponding <tt class='macro'>\declaremodule</tt> is required).</span>
</dd></dl>
<P>
<dl class='macrodesc'>
<dt><b><tt class='macro'>\seepep</tt></b>
<tt>{</tt><var>number</var><tt>}</tt><tt>{</tt><var>title</var><tt>}</tt><tt>{</tt><var>why</var><tt>}</tt></dt>
<dd>
Refer to an Python Enhancement Proposal (PEP). <var>number</var>
should be the official number assigned by the PEP Editor,
<var>title</var> should be the human-readable title of the PEP as
found in the official copy of the document, and <var>why</var> should
explain what's interesting about the PEP. This should be used
to refer the reader to PEPs which specify interfaces or language
features relevant to the material in the annotated section of the
documentation.
</dd></dl>
<P>
<dl class='macrodesc'>
<dt><b><tt class='macro'>\seerfc</tt></b>
<tt>{</tt><var>number</var><tt>}</tt><tt>{</tt><var>title</var><tt>}</tt><tt>{</tt><var>why</var><tt>}</tt></dt>
<dd>
Refer to an IETF Request for Comments (RFC). Otherwise very
similar to <tt class='macro'>\seepep</tt>. This should be used
to refer the reader to PEPs which specify protocols or data
formats relevant to the material in the annotated section of the
documentation.
</dd></dl>
<P>
<dl class='macrodesc'>
<dt><b><tt class='macro'>\seetext</tt></b>
<tt>{</tt><var>text</var><tt>}</tt></dt>
<dd>
Add arbitrary text <var>text</var> to the ``See also:'' list. This
can be used to refer to off-line materials or on-line materials
using the <tt class='macro'>\url</tt> macro. This should consist of one or more
complete sentences.
</dd></dl>
<P>
<dl class='macrodesc'>
<dt><b><tt class='macro'>\seetitle</tt></b>
<tt>[</tt><var>url</var><tt>]</tt><tt>{</tt><var>title</var><tt>}</tt><tt>{</tt><var>why</var><tt>}</tt></dt>
<dd>
Add a reference to an external document named <var>title</var>. If
<var>url</var> is given, the title is made a hyperlink in the HTML
version of the documentation, and displayed below the title in
the typeset versions of the documentation.
</dd></dl>
<P>
<dl class='macrodesc'>
<dt><b><tt class='macro'>\seeurl</tt></b>
<tt>{</tt><var>url</var><tt>}</tt><tt>{</tt><var>why</var><tt>}</tt></dt>
<dd>
References to specific on-line resources should be given using
the <tt class='macro'>\seeurl</tt> macro if they don't have a meaningful title.
Online documents which have identifiable titles should be
referenced using the <tt class='macro'>\seetitle</tt> macro, using the optional
parameter to that macro to provide the URL.
</dd></dl>
<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="6.9 Table Markup"
href="table-markup.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="6 Special Markup Constructs"
href="special-constructs.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="6.11 Index-generating Markup"
href="indexing.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="table-markup.html">6.9 Table Markup</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="special-constructs.html">6 Special Markup Constructs</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="indexing.html">6.11 Index-generating Markup</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>