Update based on @AA-Turner's feedback

Author: warsaw

peps/pep-0813.rst

@@ -1,6 +1,6 @@
 PEP: 813
 Title: The Pretty Print Protocol
-Author: Barry Warsaw <barry@python.org>
+Author: Barry Warsaw <barry@python.org>, Eric V. Smith <eric@trueblade.com>
 Discussions-To: Pending
 Status: Draft
 Type: Standards Track
@@ -21,8 +21,9 @@ Motivation
 
 "Pretty printing" is a feature which provides a capability to format object representations for better
 readability.  The core functionality is implemented by the standard library :mod:`pprint` module.  ``pprint``
-includes a class and APIs which users can invoke to format and print more readable representations of objects.
-Important use cases include pretty printing large dictionaries and other complicated objects.
+includes a class and APIs which users can invoke to format and print more readable representations of objects,
+versus the standard ``repr()`` built-in function.  Important use cases include pretty printing large
+dictionaries and other complicated objects for debugging purposes.
 
 The ``pprint`` module is great as far as it goes.  This PEP builds on the features of this module to provide
 more customization and convenience.
@@ -45,7 +46,7 @@ These two extensions work independently, but hand-in-hand can provide a powerful
 Specification
 =============
 
-There are two parts to this proposal.
+There are several parts to this proposal.
 
 
 ``__pprint__()`` methods
@@ -54,24 +55,28 @@ There are two parts to this proposal.
 Classes can implement a new dunder method, ``__pprint__()`` which if present, generates the pretty printed
 representation of their instances.  This augments ``__repr__()`` which, prior to this proposal, was the only
 method used to generate a pretty representation of the object.  Since object reprs provide functionality
-distinct from pretty printing, some classes may want more control over their pretty display.
+distinct from pretty printing, some classes may want more control over their pretty display.  The
+:py:class:`python:pprint.PrettyPrinter` class is modified to respect an object's ``__pprint__()`` method if
+present.
 
 ``__pprint__()`` is optional; if missing, the standard pretty printers fall back to ``__repr__()``
 for full backward compatibility (technically speaking, :py:func:`python:pprint.saferepr` is used).
 However, if defined on a class, ``__pprint__()`` has the same argument signature as
 :py:meth:`python:pprint.PrettyPrinter.format`, taking four arguments:
 
-* ``object`` - the object to print, which is effectively always ``self``
+* ``self`` - this object (described in ``PrettyPrinter.format()`` method as ``object``)
 * ``context`` - a dictionary mapping the ``id()`` of objects which are part of the current presentation
   context
 * ``maxlevels`` - the requested limit to recursion
 * ``levels`` - the current recursion level
 
-Similarly, ``__pprint__()`` returns three values, the string to be used as the pretty printed representation,
-a boolean indicating whether the returned value is "readable", and a boolean indicating whether recursion has
-been detected.  In this context, "readable" means the same as
-:py:meth:`python:pprint.PrettyPrinter.isreadable`, i.e. that the returned value can be used to reconstruct the
-original object using ``eval()``.
+Similarly, ``__pprint__()`` returns three values:
+
+* the string to be used as the pretty printed representation
+* a boolean indicating whether the returned value is "readable" (defined by
+  :py:meth:`python:pprint.PrettyPrinter.isreadable`, i.e. that the returned value can be used to reconstruct the
+  original object using ``eval()``).
+* boolean indicating whether recursion has been detected.
 
 See :py:meth:`python:pprint.PrettyPrinter.format` for details.