File: //usr/share/doc/python-docs-2.4.3/html/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'>\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>
>>> 1 + 1
2
>>>
</pre></div>
<P>
Within the <tt class='environment'>\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'>\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'>\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'>\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.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>