Wording and markup changes.

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
+in cross-platform applications (such code can be found in ``Lib/shutil.py``).
-is raised for similar errors as OSError is raised for on other systems.
+Second, it inherits from OSError and is raised for similar errors as OSError
-Third, the user wanting access to low-level exception specifics has to
+is raised for on other systems. Third, the user wanting access to low-level
-examine the ``errno`` or ``winerror`` attribute anyway.
+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
+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.
+between the calls to ``os.path.exists`` and ``os.remove``, it won't be
-This can produce bugs in the application, or even security issues.
+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
+cryptic mnemonics from the ``errno`` module.  It imposes an additional
-burden and gets tiresome rather quickly.  Consequently, many programmers
+cognitive burden and gets tiresome rather quickly.  Consequently, many
-will instead write the following code, which silences exceptions too
+programmers will instead write the following code, which silences exceptions
-broadly::
+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
+* select() and poll objects raise select.error, which doesn't inherit from
-anything (but poll.modify() which raises IOError).
+  anything (but poll.modify() raises IOError);
-epoll objects raise IOError.
+* epoll objects raise IOError;
-kqueue objects raise both OSError and IOError.
+* kqueue objects raise both OSError and IOError.
 
 signal
 ''''''