#22613: remaining corrections in extending/reference docs (thanks Jacques Ducasse)

8 files changed, 44 insertions, 54 deletions

diff --git a/Doc/c-api/arg.rst b/Doc/c-api/arg.rst
index 2f02241..5d069b6 100644
--- a/Doc/c-api/arg.rst
+++ b/Doc/c-api/arg.rst
@@ -429,10 +429,11 @@ API Functions
 
    Function used to deconstruct the argument lists of "old-style" functions ---
    these are functions which use the :const:`METH_OLDARGS` parameter parsing
-   method.  This is not recommended for use in parameter parsing in new code, and
-   most code in the standard interpreter has been modified to no longer use this
-   for that purpose.  It does remain a convenient way to decompose other tuples,
-   however, and may continue to be used for that purpose.
+   method, which has been removed in Python 3.  This is not recommended for use
+   in parameter parsing in new code, and most code in the standard interpreter
+   has been modified to no longer use this for that purpose.  It does remain a
+   convenient way to decompose other tuples, however, and may continue to be
+   used for that purpose.
 
 
 .. c:function:: int PyArg_UnpackTuple(PyObject *args, const char *name, Py_ssize_t min, Py_ssize_t max, ...)
diff --git a/Doc/extending/extending.rst b/Doc/extending/extending.rst
index a3bf265..e78fe0c 100644
--- a/Doc/extending/extending.rst
+++ b/Doc/extending/extending.rst
@@ -857,11 +857,8 @@ reclaim the memory belonging to any objects in a reference cycle, or referenced
 from the objects in the cycle, even though there are no further references to
 the cycle itself.
 
-The cycle detector is able to detect garbage cycles and can reclaim them so long
-as there are no finalizers implemented in Python (:meth:`__del__` methods).
-When there are such finalizers, the detector exposes the cycles through the
-:mod:`gc` module (specifically, the :attr:`~gc.garbage` variable in that module).
-The :mod:`gc` module also exposes a way to run the detector (the
+The cycle detector is able to detect garbage cycles and can reclaim them.
+The :mod:`gc` module exposes a way to run the detector (the
 :func:`~gc.collect` function), as well as configuration
 interfaces and the ability to disable the detector at runtime.  The cycle
 detector is considered an optional component; though it is included by default,
diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index 6089de7..cbccb1e 100644
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -1133,8 +1133,10 @@ Basic customization
       reference to the object on the stack frame that raised an unhandled
       exception in interactive mode (the traceback stored in
       ``sys.last_traceback`` keeps the stack frame alive).  The first situation
-      can only be remedied by explicitly breaking the cycles; the latter two
-      situations can be resolved by storing ``None`` in ``sys.last_traceback``.
+      can only be remedied by explicitly breaking the cycles; the second can be
+      resolved by freeing the reference to the traceback object when it is no
+      longer useful, and the third can be resolved by storing ``None`` in
+      ``sys.last_traceback``.
       Circular references which are garbage are detected and cleaned up when
       the cyclic garbage collector is enabled (it's on by default). Refer to the
       documentation for the :mod:`gc` module for more information about this
@@ -1556,9 +1558,9 @@ saved because *__dict__* is not created for each instance.
 .. data:: object.__slots__
 
    This class variable can be assigned a string, iterable, or sequence of
-   strings with variable names used by instances.  If defined in a
-   class, *__slots__* reserves space for the declared variables and prevents the
-   automatic creation of *__dict__* and *__weakref__* for each instance.
+   strings with variable names used by instances.  *__slots__* reserves space
+   for the declared variables and prevents the automatic creation of *__dict__*
+   and *__weakref__* for each instance.
 
 
 Notes on using *__slots__*
diff --git a/Doc/reference/executionmodel.rst b/Doc/reference/executionmodel.rst
index 664d736..a3948e3 100644
--- a/Doc/reference/executionmodel.rst
+++ b/Doc/reference/executionmodel.rst
@@ -111,8 +111,9 @@ specified in the statement refer to the binding of that name in the top-level
 namespace.  Names are resolved in the top-level namespace by searching the
 global namespace, i.e. the namespace of the module containing the code block,
 and the builtins namespace, the namespace of the module :mod:`builtins`.  The
-global namespace is searched first.  If the name is not found there, the builtins
-namespace is searched.  The global statement must precede all uses of the name.
+global namespace is searched first.  If the name is not found there, the
+builtins namespace is searched.  The :keyword:`global` statement must precede
+all uses of the name.
 
 .. XXX document "nonlocal" semantics here
 
diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst
index 2b81522..9fc5f4d 100644
--- a/Doc/reference/expressions.rst
+++ b/Doc/reference/expressions.rst
@@ -619,8 +619,8 @@ slice list contains no proper slice).
    single: stop (slice object attribute)
    single: step (slice object attribute)
 
-The semantics for a slicing are as follows.  The primary must evaluate to a
-mapping object, and it is indexed (using the same :meth:`__getitem__` method as
+The semantics for a slicing are as follows.  The primary is indexed (using the
+same :meth:`__getitem__` method as
 normal subscription) with a key that is constructed from the slice list, as
 follows.  If the slice list contains at least one comma, the key is a tuple
 containing the conversion of the slice items; otherwise, the conversion of the
diff --git a/Doc/reference/lexical_analysis.rst b/Doc/reference/lexical_analysis.rst
index 454d98e..2bf66b1 100644
--- a/Doc/reference/lexical_analysis.rst
+++ b/Doc/reference/lexical_analysis.rst
@@ -443,7 +443,7 @@ instance of the :class:`bytes` type instead of the :class:`str` type.  They
 may only contain ASCII characters; bytes with a numeric value of 128 or greater
 must be expressed with escapes.
 
-As of Python 3.3 it is possible again to prefix unicode strings with a
+As of Python 3.3 it is possible again to prefix string literals with a
 ``u`` prefix to simplify maintenance of dual 2.x and 3.x codebases.
 
 Both string and bytes literals may optionally be prefixed with a letter ``'r'``
@@ -453,24 +453,24 @@ escapes in raw strings are not treated specially. Given that Python 2.x's raw
 unicode literals behave differently than Python 3.x's the ``'ur'`` syntax
 is not supported.
 
-   .. versionadded:: 3.3
-      The ``'rb'`` prefix of raw bytes literals has been added as a synonym
-      of ``'br'``.
+.. versionadded:: 3.3
+   The ``'rb'`` prefix of raw bytes literals has been added as a synonym
+   of ``'br'``.
 
-   .. versionadded:: 3.3
-      Support for the unicode legacy literal (``u'value'``) was reintroduced
-      to simplify the maintenance of dual Python 2.x and 3.x codebases.
-      See :pep:`414` for more information.
+.. versionadded:: 3.3
+   Support for the unicode legacy literal (``u'value'``) was reintroduced
+   to simplify the maintenance of dual Python 2.x and 3.x codebases.
+   See :pep:`414` for more information.
 
-In triple-quoted strings, unescaped newlines and quotes are allowed (and are
-retained), except that three unescaped quotes in a row terminate the string.  (A
-"quote" is the character used to open the string, i.e. either ``'`` or ``"``.)
+In triple-quoted literals, unescaped newlines and quotes are allowed (and are
+retained), except that three unescaped quotes in a row terminate the literal.  (A
+"quote" is the character used to open the literal, i.e. either ``'`` or ``"``.)
 
 .. index:: physical line, escape sequence, Standard C, C
 
-Unless an ``'r'`` or ``'R'`` prefix is present, escape sequences in strings are
-interpreted according to rules similar to those used by Standard C.  The
-recognized escape sequences are:
+Unless an ``'r'`` or ``'R'`` prefix is present, escape sequences in string and
+bytes literals are interpreted according to rules similar to those used by
+Standard C.  The recognized escape sequences are:
 
 +-----------------+---------------------------------+-------+
 | Escape Sequence | Meaning                         | Notes |
@@ -547,20 +547,20 @@ Notes:
 .. index:: unrecognized escape sequence
 
 Unlike Standard C, all unrecognized escape sequences are left in the string
-unchanged, i.e., *the backslash is left in the string*.  (This behavior is
+unchanged, i.e., *the backslash is left in the result*.  (This behavior is
 useful when debugging: if an escape sequence is mistyped, the resulting output
 is more easily recognized as broken.)  It is also important to note that the
 escape sequences only recognized in string literals fall into the category of
 unrecognized escapes for bytes literals.
 
-Even in a raw string, string quotes can be escaped with a backslash, but the
-backslash remains in the string; for example, ``r"\""`` is a valid string
+Even in a raw literal, quotes can be escaped with a backslash, but the
+backslash remains in the result; for example, ``r"\""`` is a valid string
 literal consisting of two characters: a backslash and a double quote; ``r"\"``
 is not a valid string literal (even a raw string cannot end in an odd number of
-backslashes).  Specifically, *a raw string cannot end in a single backslash*
+backslashes).  Specifically, *a raw literal cannot end in a single backslash*
 (since the backslash would escape the following quote character).  Note also
 that a single backslash followed by a newline is interpreted as those two
-characters as part of the string, *not* as a line continuation.
+characters as part of the literal, *not* as a line continuation.
 
 
 .. _string-catenation:
diff --git a/Doc/reference/simple_stmts.rst b/Doc/reference/simple_stmts.rst
index 1748d5a..8946b4f 100644
--- a/Doc/reference/simple_stmts.rst
+++ b/Doc/reference/simple_stmts.rst
@@ -548,8 +548,8 @@ printed::
    RuntimeError: Something bad happened
 
 A similar mechanism works implicitly if an exception is raised inside an
-exception handler: the previous exception is then attached as the new
-exception's :attr:`__context__` attribute::
+exception handler or a :keyword:`finally` clause: the previous exception is then
+attached as the new exception's :attr:`__context__` attribute::
 
    >>> try:
    ...     print(1 / 0)
@@ -731,10 +731,9 @@ in the module's namespace which do not begin with an underscore character
 to avoid accidentally exporting items that are not part of the API (such as
 library modules which were imported and used within the module).
 
-The :keyword:`from` form with ``*`` may only occur in a module scope.  The wild
-card form of import --- ``from module import *`` --- is only allowed at the
-module level.  Attempting to use it in class or function definitions will raise
-a :exc:`SyntaxError`.
+The wild card form of import --- ``from module import *`` --- is only allowed at
+the module level.  Attempting to use it in class or function definitions will
+raise a :exc:`SyntaxError`.
 
 .. index::
     single: relative; import
diff --git a/Doc/reference/toplevel_components.rst b/Doc/reference/toplevel_components.rst
index f4bc71f..e1687ff 100644
--- a/Doc/reference/toplevel_components.rst
+++ b/Doc/reference/toplevel_components.rst
@@ -97,20 +97,10 @@ Expression input
 ================
 
 .. index:: single: input
-
 .. index:: builtin: eval
 
-There are two forms of expression input.  Both ignore leading whitespace. The
+:func:`eval` is used for expression input.  It ignores leading whitespace. The
 string argument to :func:`eval` must have the following form:
 
 .. productionlist::
    eval_input: `expression_list` NEWLINE*
-
-.. index::
-   object: file
-   single: input; raw
-   single: readline() (file method)
-
-Note: to read 'raw' input line without interpretation, you can use the
-:meth:`readline` method of file objects, including ``sys.stdin``.
-