A couple of grammatical nits.

Re-sequenced the function descriptions so that the formatting is described
before the assumption is made that the reader has a clue about the formatting.

Moved examples to be closer to the functions being demonstrated.

Added example of saferepr() result.

2 files changed, 164 insertions, 130 deletions

diff --git a/Doc/lib/libpprint.tex b/Doc/lib/libpprint.tex
index a602482..aabc8c7 100644
--- a/Doc/lib/libpprint.tex
+++ b/Doc/lib/libpprint.tex
@@ -12,46 +12,15 @@ classes, or instances are included, as well as many other builtin
 objects which are not representable as Python constants.
 
 The formatted representation keeps objects on a single line if it can,
-and breaks them out onto multiple lines if they won't fit within the
-width allowed width.  Construct PrettyPrinter objects explicitly if
-you need to adjust the width constraint.
+and breaks them onto multiple lines if they don't fit within the
+allowed width.  Construct PrettyPrinter objects explicitly if you need
+to adjust the width constraint.
 
-The \code{pprint} module defines the following functions:
+The \code{pprint} module defines one class:
 
 \renewcommand{\indexsubitem}{(in module pprint)}
 
-\begin{funcdesc}{pformat}{object}
-Return the formatted representation of \var{object} as a string.  The
-default parameters for formatting are used.
-\end{funcdesc}
-
-\begin{funcdesc}{pprint}{object\optional{, stream}}
-Prints the formatted representation of \var{object} on \var{stream},
-followed by a newline.  If \var{stream} is omitted, \code{sys.stdout}
-is used.  This may be used in the interactive interpreter instead of a
-\code{print} command for inspecting values.  The default parameters
-for formatting are used.
-\end{funcdesc}
-
-\begin{funcdesc}{isreadable}{object}
-Determine if the formatted representation of \var{object} is
-``readable,'' or can be used to reconstruct the value using
-\code{eval()}.  Note that this returns false for recursive objects.
-\end{funcdesc}
-
-\begin{funcdesc}{isrecursive}{object}
-Determine if \var{object} requires a recursive representation.
-\end{funcdesc}
-
-\begin{funcdesc}{saferepr}{object}
-Return a string representation of \var{object}, protected against
-recursive data structures.  If the representation of \var{object}
-exposes a recursive entry, the recursive reference will be represented
-as \samp{$<$Recursion on \var{typename} with id=\var{number}$>$}.
-\end{funcdesc}
-
-
-% Now for the implementation class:
+% First the implementation class:
 
 \begin{funcdesc}{PrettyPrinter}{...}
 Construct a PrettyPrinter instance.  This constructor understands
@@ -71,42 +40,25 @@ objects being formatted.  The desired output width is constrained
 using the \var{width} parameter; the default is eighty characters.  If
 a structure cannot be formatted within the constrained width, a best
 effort will be made.
-\end{funcdesc}
-
-
-% Guido marked this as a good spot for an example in the template,
-% but I think this needs a better location in this module.  Not sure where.
-
-Example:
 
 \begin{verbatim}
->>> import pprint
+>>> import pprint, sys
 >>> stuff = sys.path[:]
->>> stuff.insert(0, stuff)
->>> pprint.pprint(stuff)
-[<Recursion on list with id=869440>,
- '',
- '/usr/local/lib/python1.4',
- '/usr/local/lib/python1.4/test',
- '/usr/local/lib/python1.4/sunos5',
- '/usr/local/lib/python1.4/sharedmodules',
- '/usr/local/lib/python1.4/tkinter']
->>> 
->>> stuff[0] = stuff[1:]
+>>> stuff.insert(0, stuff[:])
 >>> pp = pprint.PrettyPrinter(indent=4)
 >>> pp.pprint(stuff)
 [   [   '',
-        '/usr/local/lib/python1.4',
-        '/usr/local/lib/python1.4/test',
-        '/usr/local/lib/python1.4/sunos5',
-        '/usr/local/lib/python1.4/sharedmodules',
-        '/usr/local/lib/python1.4/tkinter'],
+        '/usr/local/lib/python1.5',
+        '/usr/local/lib/python1.5/test',
+        '/usr/local/lib/python1.5/sunos5',
+        '/usr/local/lib/python1.5/sharedmodules',
+        '/usr/local/lib/python1.5/tkinter'],
     '',
-    '/usr/local/lib/python1.4',
-    '/usr/local/lib/python1.4/test',
-    '/usr/local/lib/python1.4/sunos5',
-    '/usr/local/lib/python1.4/sharedmodules',
-    '/usr/local/lib/python1.4/tkinter']
+    '/usr/local/lib/python1.5',
+    '/usr/local/lib/python1.5/test',
+    '/usr/local/lib/python1.5/sunos5',
+    '/usr/local/lib/python1.5/sharedmodules',
+    '/usr/local/lib/python1.5/tkinter']
 >>>
 >>> import parser
 >>> tup = parser.ast2tuple(
@@ -115,6 +67,71 @@ Example:
 >>> pp.pprint(tup)
 (266, (267, (307, (287, (288, (...))))))
 \end{verbatim}
+\end{funcdesc}
+
+
+% Now the derivative functions:
+
+The PrettyPrinter class supports several derivative functions:
+
+\begin{funcdesc}{pformat}{object}
+Return the formatted representation of \var{object} as a string.  The
+default parameters for formatting are used.
+\end{funcdesc}
+
+\begin{funcdesc}{pprint}{object\optional{, stream}}
+Prints the formatted representation of \var{object} on \var{stream},
+followed by a newline.  If \var{stream} is omitted, \code{sys.stdout}
+is used.  This may be used in the interactive interpreter instead of a
+\code{print} command for inspecting values.  The default parameters
+for formatting are used.
+
+\begin{verbatim}
+>>> stuff = sys.path[:]
+>>> stuff.insert(0, stuff)
+>>> pprint.pprint(stuff)
+[<Recursion on list with id=869440>,
+ '',
+ '/usr/local/lib/python1.5',
+ '/usr/local/lib/python1.5/test',
+ '/usr/local/lib/python1.5/sunos5',
+ '/usr/local/lib/python1.5/sharedmodules',
+ '/usr/local/lib/python1.5/tkinter']
+\end{verbatim}
+\end{funcdesc}
+
+\begin{funcdesc}{isreadable}{object}
+Determine if the formatted representation of \var{object} is
+``readable,'' or can be used to reconstruct the value using
+\code{eval()}.  Note that this returns false for recursive objects.
+
+\begin{verbatim}
+>>> pprint.isreadable(stuff)
+0
+\end{verbatim}
+\end{funcdesc}
+
+\begin{funcdesc}{isrecursive}{object}
+Determine if \var{object} requires a recursive representation.
+\end{funcdesc}
+
+
+One more support function is also defined:
+
+\begin{funcdesc}{saferepr}{object}
+Return a string representation of \var{object}, protected against
+recursive data structures.  If the representation of \var{object}
+exposes a recursive entry, the recursive reference will be represented
+as \samp{$<$Recursion on \var{typename} with id=\var{number}$>$}.  The
+representation is not otherwise formatted.
+
+\begin{verbatim}
+>>> pprint.saferepr(stuff)
+"[<Recursion on list with id=682968>, '', '/usr/local/lib/python1.4', '/usr/loca
+l/lib/python1.4/test', '/usr/local/lib/python1.4/sunos5', '/usr/local/lib/python
+1.4/sharedmodules', '/usr/local/lib/python1.4/tkinter']"
+\end{verbatim}
+\end{funcdesc}
 
 
 \subsection{PrettyPrinter Objects}
diff --git a/Doc/libpprint.tex b/Doc/libpprint.tex
index a602482..aabc8c7 100644
--- a/Doc/libpprint.tex
+++ b/Doc/libpprint.tex
@@ -12,46 +12,15 @@ classes, or instances are included, as well as many other builtin
 objects which are not representable as Python constants.
 
 The formatted representation keeps objects on a single line if it can,
-and breaks them out onto multiple lines if they won't fit within the
-width allowed width.  Construct PrettyPrinter objects explicitly if
-you need to adjust the width constraint.
+and breaks them onto multiple lines if they don't fit within the
+allowed width.  Construct PrettyPrinter objects explicitly if you need
+to adjust the width constraint.
 
-The \code{pprint} module defines the following functions:
+The \code{pprint} module defines one class:
 
 \renewcommand{\indexsubitem}{(in module pprint)}
 
-\begin{funcdesc}{pformat}{object}
-Return the formatted representation of \var{object} as a string.  The
-default parameters for formatting are used.
-\end{funcdesc}
-
-\begin{funcdesc}{pprint}{object\optional{, stream}}
-Prints the formatted representation of \var{object} on \var{stream},
-followed by a newline.  If \var{stream} is omitted, \code{sys.stdout}
-is used.  This may be used in the interactive interpreter instead of a
-\code{print} command for inspecting values.  The default parameters
-for formatting are used.
-\end{funcdesc}
-
-\begin{funcdesc}{isreadable}{object}
-Determine if the formatted representation of \var{object} is
-``readable,'' or can be used to reconstruct the value using
-\code{eval()}.  Note that this returns false for recursive objects.
-\end{funcdesc}
-
-\begin{funcdesc}{isrecursive}{object}
-Determine if \var{object} requires a recursive representation.
-\end{funcdesc}
-
-\begin{funcdesc}{saferepr}{object}
-Return a string representation of \var{object}, protected against
-recursive data structures.  If the representation of \var{object}
-exposes a recursive entry, the recursive reference will be represented
-as \samp{$<$Recursion on \var{typename} with id=\var{number}$>$}.
-\end{funcdesc}
-
-
-% Now for the implementation class:
+% First the implementation class:
 
 \begin{funcdesc}{PrettyPrinter}{...}
 Construct a PrettyPrinter instance.  This constructor understands
@@ -71,42 +40,25 @@ objects being formatted.  The desired output width is constrained
 using the \var{width} parameter; the default is eighty characters.  If
 a structure cannot be formatted within the constrained width, a best
 effort will be made.
-\end{funcdesc}
-
-
-% Guido marked this as a good spot for an example in the template,
-% but I think this needs a better location in this module.  Not sure where.
-
-Example:
 
 \begin{verbatim}
->>> import pprint
+>>> import pprint, sys
 >>> stuff = sys.path[:]
->>> stuff.insert(0, stuff)
->>> pprint.pprint(stuff)
-[<Recursion on list with id=869440>,
- '',
- '/usr/local/lib/python1.4',
- '/usr/local/lib/python1.4/test',
- '/usr/local/lib/python1.4/sunos5',
- '/usr/local/lib/python1.4/sharedmodules',
- '/usr/local/lib/python1.4/tkinter']
->>> 
->>> stuff[0] = stuff[1:]
+>>> stuff.insert(0, stuff[:])
 >>> pp = pprint.PrettyPrinter(indent=4)
 >>> pp.pprint(stuff)
 [   [   '',
-        '/usr/local/lib/python1.4',
-        '/usr/local/lib/python1.4/test',
-        '/usr/local/lib/python1.4/sunos5',
-        '/usr/local/lib/python1.4/sharedmodules',
-        '/usr/local/lib/python1.4/tkinter'],
+        '/usr/local/lib/python1.5',
+        '/usr/local/lib/python1.5/test',
+        '/usr/local/lib/python1.5/sunos5',
+        '/usr/local/lib/python1.5/sharedmodules',
+        '/usr/local/lib/python1.5/tkinter'],
     '',
-    '/usr/local/lib/python1.4',
-    '/usr/local/lib/python1.4/test',
-    '/usr/local/lib/python1.4/sunos5',
-    '/usr/local/lib/python1.4/sharedmodules',
-    '/usr/local/lib/python1.4/tkinter']
+    '/usr/local/lib/python1.5',
+    '/usr/local/lib/python1.5/test',
+    '/usr/local/lib/python1.5/sunos5',
+    '/usr/local/lib/python1.5/sharedmodules',
+    '/usr/local/lib/python1.5/tkinter']
 >>>
 >>> import parser
 >>> tup = parser.ast2tuple(
@@ -115,6 +67,71 @@ Example:
 >>> pp.pprint(tup)
 (266, (267, (307, (287, (288, (...))))))
 \end{verbatim}
+\end{funcdesc}
+
+
+% Now the derivative functions:
+
+The PrettyPrinter class supports several derivative functions:
+
+\begin{funcdesc}{pformat}{object}
+Return the formatted representation of \var{object} as a string.  The
+default parameters for formatting are used.
+\end{funcdesc}
+
+\begin{funcdesc}{pprint}{object\optional{, stream}}
+Prints the formatted representation of \var{object} on \var{stream},
+followed by a newline.  If \var{stream} is omitted, \code{sys.stdout}
+is used.  This may be used in the interactive interpreter instead of a
+\code{print} command for inspecting values.  The default parameters
+for formatting are used.
+
+\begin{verbatim}
+>>> stuff = sys.path[:]
+>>> stuff.insert(0, stuff)
+>>> pprint.pprint(stuff)
+[<Recursion on list with id=869440>,
+ '',
+ '/usr/local/lib/python1.5',
+ '/usr/local/lib/python1.5/test',
+ '/usr/local/lib/python1.5/sunos5',
+ '/usr/local/lib/python1.5/sharedmodules',
+ '/usr/local/lib/python1.5/tkinter']
+\end{verbatim}
+\end{funcdesc}
+
+\begin{funcdesc}{isreadable}{object}
+Determine if the formatted representation of \var{object} is
+``readable,'' or can be used to reconstruct the value using
+\code{eval()}.  Note that this returns false for recursive objects.
+
+\begin{verbatim}
+>>> pprint.isreadable(stuff)
+0
+\end{verbatim}
+\end{funcdesc}
+
+\begin{funcdesc}{isrecursive}{object}
+Determine if \var{object} requires a recursive representation.
+\end{funcdesc}
+
+
+One more support function is also defined:
+
+\begin{funcdesc}{saferepr}{object}
+Return a string representation of \var{object}, protected against
+recursive data structures.  If the representation of \var{object}
+exposes a recursive entry, the recursive reference will be represented
+as \samp{$<$Recursion on \var{typename} with id=\var{number}$>$}.  The
+representation is not otherwise formatted.
+
+\begin{verbatim}
+>>> pprint.saferepr(stuff)
+"[<Recursion on list with id=682968>, '', '/usr/local/lib/python1.4', '/usr/loca
+l/lib/python1.4/test', '/usr/local/lib/python1.4/sunos5', '/usr/local/lib/python
+1.4/sharedmodules', '/usr/local/lib/python1.4/tkinter']"
+\end{verbatim}
+\end{funcdesc}
 
 
 \subsection{PrettyPrinter Objects}