[OpenSPARC-T2-DV] / tools / src / nas,5.n2.os.2 / lib / python / html / python / doc / showing-examples.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="inline-markup.html" />
<link rel="prev" href="info-units.html" />
<link rel="parent" href="special-constructs.html" />
<link rel="next" href="inline-markup.html" />
<meta name='aesop' content='information' />
<title>6.4 Showing Code Examples </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.3 Information Units"
  href="info-units.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.5 Inline Markup"
  href="inline-markup.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="info-units.html">6.3 Information Units</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="inline-markup.html">6.5 Inline Markup</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H2><A NAME="SECTION000740000000000000000"></A><A NAME="showing-examples"></A>
<BR>
6.4 Showing Code Examples 
</H2>

<P>
Examples of Python source code or interactive sessions are
    represented as <tt class='environment'>&#92;verbatim</tt> environments.  This environment
    is a standard part of <span class="LaTeX">LaTeX</span>.  It is important to only use
    spaces for indentation in code examples since <span class="TeX">TeX</span> drops tabs
    instead of converting them to spaces.

<P>
Representing an interactive session requires including the prompts
    and output along with the Python code.  No special markup is
    required for interactive sessions.  After the last line of input
    or output presented, there should not be an ``unused'' primary
    prompt; this is an example of what <em>not</em> to do:

<P>
<div class="verbatim"><pre>
&gt;&gt;&gt; 1 + 1
2
&gt;&gt;&gt;
</pre></div>

<P>
Within the <tt class='environment'>&#92;verbatim</tt> environment, characters special to
    <span class="LaTeX">LaTeX</span> do not need to be specially marked in any way.  The entire
    example will be presented in a monospaced font; no attempt at
    ``pretty-printing'' is made, as the environment must work for
    non-Python code and non-code displays.  There should be no blank
    lines at the top or bottom of any <tt class='environment'>&#92;verbatim</tt> display.

<P>
Longer displays of verbatim text may be included by storing the
    example text in an external file containing only plain text.  The
    file may be included using the standard <tt class='macro'>&#92;verbatiminput</tt>
    macro; this macro takes a single argument naming the file
    containing the text.  For example, to include the Python source
    file <span class="file">example.py</span>, use:

<P>
<div class="verbatim"><pre>
\verbatiminput{example.py}
</pre></div>

<P>
Use of <tt class='macro'>&#92;verbatiminput</tt> allows easier use of special editing
    modes for the included file.  The file should be placed in the
    same directory as the <span class="LaTeX">LaTeX</span> files for the document.

<P>
The Python Documentation Special Interest Group has discussed a
    number of approaches to creating pretty-printed code displays and
    interactive sessions; see the Doc-SIG area on the Python Web site
    for more information on this topic.

<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.3 Information Units"
  href="info-units.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.5 Inline Markup"
  href="inline-markup.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="info-units.html">6.3 Information Units</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="inline-markup.html">6.5 Inline 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
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="inline-markup.html" />
	12	<link rel="prev" href="info-units.html" />
	13	<link rel="parent" href="special-constructs.html" />
	14	<link rel="next" href="inline-markup.html" />
	15	<meta name='aesop' content='information' />
	16	<title>6.4 Showing Code Examples </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.3 Information Units"
	24	href="info-units.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.5 Inline Markup"
	30	href="inline-markup.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="info-units.html">6.3 Information Units</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="inline-markup.html">6.5 Inline Markup</A>
	48	</div>
	49	<hr /></div>
	50	</DIV>
	51	<!--End of Navigation Panel-->
	52
	53	<H2><A NAME="SECTION000740000000000000000"></A><A NAME="showing-examples"></A>
	54	<BR>
	55	6.4 Showing Code Examples
	56	</H2>
	57
	58	<P>
	59	Examples of Python source code or interactive sessions are
	60	represented as <tt class='environment'>\verbatim</tt> environments. This environment
	61	is a standard part of <span class="LaTeX">LaTeX</span>. It is important to only use
	62	spaces for indentation in code examples since <span class="TeX">TeX</span> drops tabs
	63	instead of converting them to spaces.
	64
65	<P>
66	Representing an interactive session requires including the prompts
67	and output along with the Python code. No special markup is
68	required for interactive sessions. After the last line of input
69	or output presented, there should not be an ``unused'' primary
70	prompt; this is an example of what <em>not</em> to do:
71
72	<P>
73	<div class="verbatim"><pre>
74	>>> 1 + 1
75	2
76	>>>
77	</pre></div>
78
79	<P>
80	Within the <tt class='environment'>\verbatim</tt> environment, characters special to
81	<span class="LaTeX">LaTeX</span> do not need to be specially marked in any way. The entire
82	example will be presented in a monospaced font; no attempt at
83	``pretty-printing'' is made, as the environment must work for
84	non-Python code and non-code displays. There should be no blank
85	lines at the top or bottom of any <tt class='environment'>\verbatim</tt> display.
86
87	<P>
88	Longer displays of verbatim text may be included by storing the
89	example text in an external file containing only plain text. The
90	file may be included using the standard <tt class='macro'>\verbatiminput</tt>
91	macro; this macro takes a single argument naming the file
92	containing the text. For example, to include the Python source
93	file <span class="file">example.py</span>, use:
94
95	<P>
96	<div class="verbatim"><pre>
97	\verbatiminput{example.py}
98	</pre></div>
99
100	<P>
101	Use of <tt class='macro'>\verbatiminput</tt> allows easier use of special editing
102	modes for the included file. The file should be placed in the
103	same directory as the <span class="LaTeX">LaTeX</span> files for the document.
104
105	<P>
106	The Python Documentation Special Interest Group has discussed a
107	number of approaches to creating pretty-printed code displays and
108	interactive sessions; see the Doc-SIG area on the Python Web site
109	for more information on this topic.
110
111	<P>
112
113	<DIV CLASS="navigation">
114	<div class='online-navigation'>
115	<p></p><hr />
116	<table align="center" width="100%" cellpadding="0" cellspacing="2">
117	<tr>
118	<td class='online-navigation'><a rel="prev" title="6.3 Information Units"
119	href="info-units.html"><img src='../icons/previous.png'
120	border='0' height='32' alt='Previous Page' width='32' /></A></td>
121	<td class='online-navigation'><a rel="parent" title="6 Special Markup Constructs"
122	href="special-constructs.html"><img src='../icons/up.png'
123	border='0' height='32' alt='Up One Level' width='32' /></A></td>
124	<td class='online-navigation'><a rel="next" title="6.5 Inline Markup"
125	href="inline-markup.html"><img src='../icons/next.png'
126	border='0' height='32' alt='Next Page' width='32' /></A></td>
127	<td align="center" width="100%">Documenting Python</td>
128	<td class='online-navigation'><a rel="contents" title="Table of Contents"
129	href="contents.html"><img src='../icons/contents.png'
130	border='0' height='32' alt='Contents' width='32' /></A></td>
131	<td class='online-navigation'><img src='../icons/blank.png'
132	border='0' height='32' alt='' width='32' /></td>
133	<td class='online-navigation'><img src='../icons/blank.png'
134	border='0' height='32' alt='' width='32' /></td>
135	</tr></table>
136	<div class='online-navigation'>
137	<b class="navlabel">Previous:</b>
138	<a class="sectref" rel="prev" href="info-units.html">6.3 Information Units</A>
139	<b class="navlabel">Up:</b>
140	<a class="sectref" rel="parent" href="special-constructs.html">6 Special Markup Constructs</A>
141	<b class="navlabel">Next:</b>
142	<a class="sectref" rel="next" href="inline-markup.html">6.5 Inline Markup</A>
143	</div>
144	</div>
145	<hr />
146	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
147	</DIV>
148	<!--End of Navigation Panel-->
149	<ADDRESS>
150	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
151	</ADDRESS>
152	</BODY>
153	</HTML>