[OpenSPARC-T2-SAM] / sam-t2 / devtools / v8plus / html / python / 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'>&#92;seealso</tt> or <tt class='environment'>&#92;seealso*</tt> environments.  These environments
    define some additional macros to support creating reference
    entries in a reasonable manner.

<P>
The <tt class='environment'>&#92;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'>&#92;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>&#92;begin{<b class='environment'>seealso</b>}</tt>
    
<br /><tt>&#92;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>&#92;begin{<b class='environment'>seealso*</b>}</tt>
    
<br /><tt>&#92;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'>&#92;seealso</tt> and <tt class='environment'>&#92;seealso*</tt> environments.

<P>

<dl class='macrodesc'>
<dt><b><tt class='macro'>&#92;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'>&#92;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'>&#92;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'>&#92;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'>&#92;declaremodule</tt> is required).</span>
    </dd></dl>

<P>

<dl class='macrodesc'>
<dt><b><tt class='macro'>&#92;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'>&#92;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'>&#92;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'>&#92;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'>&#92;url</tt> macro.  This should consist of one or more
      complete sentences.
    </dd></dl>

<P>

<dl class='macrodesc'>
<dt><b><tt class='macro'>&#92;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'>&#92;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'>&#92;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'>&#92;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.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="indexing.html" />
	12	<link rel="prev" href="table-markup.html" />
	13	<link rel="parent" href="special-constructs.html" />
	14	<link rel="next" href="indexing.html" />
	15	<meta name='aesop' content='information' />
	16	<title>6.10 Reference List Markup </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="6.9 Table Markup"
	24	href="table-markup.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="6 Special Markup Constructs"
	27	href="special-constructs.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="6.11 Index-generating Markup"
	30	href="indexing.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="table-markup.html">6.9 Table Markup</A>
	44	<b class="navlabel">Up:</b>
	45	<a class="sectref" rel="parent" href="special-constructs.html">6 Special Markup Constructs</A>
	46	<b class="navlabel">Next:</b>
	47	<a class="sectref" rel="next" href="indexing.html">6.11 Index-generating Markup</A>
	48	</div>
	49	<hr /></div>
	50	</DIV>
	51	<!--End of Navigation Panel-->
	52
	53	<H2><A NAME="SECTION0007100000000000000000"></A><A NAME="references"></A>
	54	<BR>
	55	6.10 Reference List Markup
	56	</H2>
	57
	58	<P>
	59	Many sections include a list of references to module documentation
	60	or external documents. These lists are created using the
	61	<tt class='environment'>\seealso</tt> or <tt class='environment'>\seealso*</tt> environments. These environments
	62	define some additional macros to support creating reference
	63	entries in a reasonable manner.
	64
65	<P>
66	The <tt class='environment'>\seealso</tt> environment is typically placed in a section
67	just before any sub-sections. This is done to ensure that
68	reference links related to the section are not hidden in a
69	subsection in the hypertext renditions of the documentation. For
70	the HTML output, it is shown as a ``side bar,'' boxed off from the
71	main flow of the text. The <tt class='environment'>\seealso*</tt> environment is
72	different in that it should be used when a list of references is
73	being presented as part of the primary content; it is not
74	specially set off from the text.
75
76	<P>
77
78	<dl class='envdesc'>
79	<dt><tt>\begin{<b class='environment'>seealso</b>}</tt>
80
81	<br /><tt>\end{<b class='environment'>seealso</b>}</tt></dt>
82	<dd>
83	This environment creates a ``See also:'' heading and defines the
84	markup used to describe individual references.
85	</dd></dl>
86
87	<P>
88
89	<dl class='envdesc'>
90	<dt><tt>\begin{<b class='environment'>seealso*</b>}</tt>
91
92	<br /><tt>\end{<b class='environment'>seealso*</b>}</tt></dt>
93	<dd>
94	This environment is used to create a list of references which
95	form part of the main content. It is not given a special
96	header and is not set off from the main flow of the text. It
97	provides the same additional markup used to describe individual
98	references.
99	</dd></dl>
100
101	<P>
102	For each of the following macros, <var>why</var> should be one or more
103	complete sentences, starting with a capital letter (unless it
104	starts with an identifier, which should not be modified), and
105	ending with the appropriate punctuation.
106
107	<P>
108	These macros are only defined within the content of the
109	<tt class='environment'>\seealso</tt> and <tt class='environment'>\seealso*</tt> environments.
110
111	<P>
112
113	<dl class='macrodesc'>
114	<dt><b><tt class='macro'>\seelink</tt></b>
115	<tt>{</tt><var>url</var><tt>}</tt><tt>{</tt><var>linktext</var><tt>}</tt><tt>{</tt><var>why</var><tt>}</tt></dt>
116	<dd>
117	References to specific on-line resources should be given using
118	the <tt class='macro'>\seelink</tt> macro if they don't have a meaningful title
119	but there is some short description of what's at the end of the
120	link. Online documents which have identifiable titles should be
121	referenced using the <tt class='macro'>\seetitle</tt> macro, using the optional
122	parameter to that macro to provide the URL.
123	</dd></dl>
124
125	<P>
126
127	<dl class='macrodesc'>
128	<dt><b><tt class='macro'>\seemodule</tt></b>
129	<tt>[</tt><var>key</var><tt>]</tt><tt>{</tt><var>name</var><tt>}</tt><tt>{</tt><var>why</var><tt>}</tt></dt>
130	<dd>
131	Refer to another module. <var>why</var> should be a brief
132	explanation of why the reference may be interesting. The module
133	name is given in <var>name</var>, with the link key given in
134	<var>key</var> if necessary. In the HTML and PDF conversions, the
135	module name will be a hyperlink to the referred-to module.
136	<span class="note"><b class="label">Note:</b>
137	The module must be documented in the same
138	document (the corresponding <tt class='macro'>\declaremodule</tt> is required).</span>
139	</dd></dl>
140
141	<P>
142
143	<dl class='macrodesc'>
144	<dt><b><tt class='macro'>\seepep</tt></b>
145	<tt>{</tt><var>number</var><tt>}</tt><tt>{</tt><var>title</var><tt>}</tt><tt>{</tt><var>why</var><tt>}</tt></dt>
146	<dd>
147	Refer to an Python Enhancement Proposal (PEP). <var>number</var>
148	should be the official number assigned by the PEP Editor,
149	<var>title</var> should be the human-readable title of the PEP as
150	found in the official copy of the document, and <var>why</var> should
151	explain what's interesting about the PEP. This should be used
152	to refer the reader to PEPs which specify interfaces or language
153	features relevant to the material in the annotated section of the
154	documentation.
155	</dd></dl>
156
157	<P>
158
159	<dl class='macrodesc'>
160	<dt><b><tt class='macro'>\seerfc</tt></b>
161	<tt>{</tt><var>number</var><tt>}</tt><tt>{</tt><var>title</var><tt>}</tt><tt>{</tt><var>why</var><tt>}</tt></dt>
162	<dd>
163	Refer to an IETF Request for Comments (RFC). Otherwise very
164	similar to <tt class='macro'>\seepep</tt>. This should be used
165	to refer the reader to PEPs which specify protocols or data
166	formats relevant to the material in the annotated section of the
167	documentation.
168	</dd></dl>
169
170	<P>
171
172	<dl class='macrodesc'>
173	<dt><b><tt class='macro'>\seetext</tt></b>
174	<tt>{</tt><var>text</var><tt>}</tt></dt>
175	<dd>
176	Add arbitrary text <var>text</var> to the ``See also:'' list. This
177	can be used to refer to off-line materials or on-line materials
178	using the <tt class='macro'>\url</tt> macro. This should consist of one or more
179	complete sentences.
180	</dd></dl>
181
182	<P>
183
184	<dl class='macrodesc'>
185	<dt><b><tt class='macro'>\seetitle</tt></b>
186	<tt>[</tt><var>url</var><tt>]</tt><tt>{</tt><var>title</var><tt>}</tt><tt>{</tt><var>why</var><tt>}</tt></dt>
187	<dd>
188	Add a reference to an external document named <var>title</var>. If
189	<var>url</var> is given, the title is made a hyperlink in the HTML
190	version of the documentation, and displayed below the title in
191	the typeset versions of the documentation.
192	</dd></dl>
193
194	<P>
195
196	<dl class='macrodesc'>
197	<dt><b><tt class='macro'>\seeurl</tt></b>
198	<tt>{</tt><var>url</var><tt>}</tt><tt>{</tt><var>why</var><tt>}</tt></dt>
199	<dd>
200	References to specific on-line resources should be given using
201	the <tt class='macro'>\seeurl</tt> macro if they don't have a meaningful title.
202	Online documents which have identifiable titles should be
203	referenced using the <tt class='macro'>\seetitle</tt> macro, using the optional
204	parameter to that macro to provide the URL.
205	</dd></dl>
206
207	<P>
208
209	<DIV CLASS="navigation">
210	<div class='online-navigation'>
211	<p></p><hr />
212	<table align="center" width="100%" cellpadding="0" cellspacing="2">
213	<tr>
214	<td class='online-navigation'><a rel="prev" title="6.9 Table Markup"
215	href="table-markup.html"><img src='../icons/previous.png'
216	border='0' height='32' alt='Previous Page' width='32' /></A></td>
217	<td class='online-navigation'><a rel="parent" title="6 Special Markup Constructs"
218	href="special-constructs.html"><img src='../icons/up.png'
219	border='0' height='32' alt='Up One Level' width='32' /></A></td>
220	<td class='online-navigation'><a rel="next" title="6.11 Index-generating Markup"
221	href="indexing.html"><img src='../icons/next.png'
222	border='0' height='32' alt='Next Page' width='32' /></A></td>
223	<td align="center" width="100%">Documenting Python</td>
224	<td class='online-navigation'><a rel="contents" title="Table of Contents"
225	href="contents.html"><img src='../icons/contents.png'
226	border='0' height='32' alt='Contents' width='32' /></A></td>
227	<td class='online-navigation'><img src='../icons/blank.png'
228	border='0' height='32' alt='' width='32' /></td>
229	<td class='online-navigation'><img src='../icons/blank.png'
230	border='0' height='32' alt='' width='32' /></td>
231	</tr></table>
232	<div class='online-navigation'>
233	<b class="navlabel">Previous:</b>
234	<a class="sectref" rel="prev" href="table-markup.html">6.9 Table Markup</A>
235	<b class="navlabel">Up:</b>
236	<a class="sectref" rel="parent" href="special-constructs.html">6 Special Markup Constructs</A>
237	<b class="navlabel">Next:</b>
238	<a class="sectref" rel="next" href="indexing.html">6.11 Index-generating Markup</A>
239	</div>
240	</div>
241	<hr />
242	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
243	</DIV>
244	<!--End of Navigation Panel-->
245	<ADDRESS>
246	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
247	</ADDRESS>
248	</BODY>
249	</HTML>