From e742aa991be05d55b25cea144f3f37e48956b175 Mon Sep 17 00:00:00 2001
From: Antoine Pitrou <solipsis@pitrou.net>
Date: Wed, 21 Jul 2010 17:44:30 +0000
Subject: [PATCH] Wording and markup changes.

---
 pep-3151.txt | 40 +++++++++++++++++++++-------------------
 1 file changed, 21 insertions(+), 19 deletions(-)

diff --git a/pep-3151.txt b/pep-3151.txt
index 9c20fe181..e397952c3 100644
--- a/pep-3151.txt
+++ b/pep-3151.txt
@@ -87,10 +87,11 @@ primitive it chooses to use at runtime.
 
 As for WindowsError, it seems to be a pointless distinction.  First, it
 only exists on Windows systems, which requires tedious compatibility code
-in cross-platform applications.  Second, it inherits from OSError and
-is raised for similar errors as OSError is raised for on other systems.
-Third, the user wanting access to low-level exception specifics has to
-examine the ``errno`` or ``winerror`` attribute anyway.
+in cross-platform applications (such code can be found in ``Lib/shutil.py``).
+Second, it inherits from OSError and is raised for similar errors as OSError
+is raised for on other systems. Third, the user wanting access to low-level
+exception specifics has to examine the ``errno`` or ``winerror`` attribute
+anyway.
 
 
 Lack of fine-grained exceptions
@@ -104,9 +105,9 @@ suffers from an obvious race condition::
     if os.path.exists(filename):
         os.remove(filename)
 
-If a file named as `filename` is created by another thread or process
-between the calls to `os.path.exists` and `os.remove`, it won't be deleted.
-This can produce bugs in the application, or even security issues.
+If a file named as ``filename`` is created by another thread or process
+between the calls to ``os.path.exists`` and ``os.remove``, it won't be
+deleted.  This can produce bugs in the application, or even security issues.
 
 Therefore, the solution is to try to remove the file, and ignore the error
 if the file doesn't exist (an idiom known as Easier to Ask Forgiveness
@@ -128,10 +129,10 @@ or even::
             raise
 
 This is a lot more to type, and also forces the user to remember the various
-cryptic mnemonics from the errno module.  It imposes an additional cognitive
-burden and gets tiresome rather quickly.  Consequently, many programmers
-will instead write the following code, which silences exceptions too
-broadly::
+cryptic mnemonics from the ``errno`` module.  It imposes an additional
+cognitive burden and gets tiresome rather quickly.  Consequently, many
+programmers will instead write the following code, which silences exceptions
+too broadly::
 
     try:
         os.remove(filename)
@@ -151,7 +152,7 @@ something such as::
         pass
 
 
-Compatibility concerns
+Compatibility strategy
 ======================
 
 Reworking the exception hierarchy will obviously change the exact semantics
@@ -213,6 +214,8 @@ Deprecation of names
 
 It is not yet decided whether the old names will be deprecated (then removed)
 or all alternative names will continue living in the root namespace.
+Deprecation of names from the root namespace presents some implementation
+challenges, especially where performance is important.
 
 
 Step 2: define additional subclasses
@@ -575,7 +578,8 @@ Raises IOError when trying to open a directory under Unix::
       File "<stdin>", line 1, in <module>
     IOError: [Errno 21] Is a directory: 'Python/'
 
-Raises IOError for unsupported operations::
+Raises IOError or io.UnsupportedOperation (which inherits from the former)
+for unsupported operations::
 
     >>> open("LICENSE").write("bar")
     Traceback (most recent call last):
@@ -590,8 +594,6 @@ Raises IOError for unsupported operations::
       File "<stdin>", line 1, in <module>
     IOError: can't do nonzero cur-relative seeks
 
-(io.UnsupportedOperation inherits from IOError)
-
 Raises either IOError or TypeError when the inferior I/O layer misbehaves
 (i.e. violates the API it is expected to implement).
 
@@ -653,10 +655,10 @@ Raises IOError in various file-handling functions::
 select
 ''''''
 
-select() and poll objects raise select.error, which doesn't inherit from
-anything (but poll.modify() which raises IOError).
-epoll objects raise IOError.
-kqueue objects raise both OSError and IOError.
+* select() and poll objects raise select.error, which doesn't inherit from
+  anything (but poll.modify() raises IOError);
+* epoll objects raise IOError;
+* kqueue objects raise both OSError and IOError.
 
 signal
 ''''''