Simplify index entries; fix #1712.

3 files changed, 70 insertions, 97 deletions

diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst
index e37618a..02ce783 100644
--- a/Doc/reference/compound_stmts.rst
+++ b/Doc/reference/compound_stmts.rst
@@ -76,7 +76,10 @@ on a separate line for clarity.
 The :keyword:`if` statement
 ===========================
 
-.. index:: statement: if
+.. index::
+   statement: if
+   keyword: elif
+   keyword: else
 
 The :keyword:`if` statement is used for conditional execution:
 
@@ -85,10 +88,6 @@ The :keyword:`if` statement is used for conditional execution:
           : ( "elif" `expression` ":" `suite` )*
           : ["else" ":" `suite`]
 
-.. index::
-   keyword: elif
-   keyword: else
-
 It selects exactly one of the suites by evaluating the expressions one by one
 until one is found to be true (see section :ref:`booleans` for the definition of
 true and false); then that suite is executed (and no other part of the
@@ -104,6 +103,7 @@ The :keyword:`while` statement
 .. index::
    statement: while
    pair: loop; statement
+   keyword: else
 
 The :keyword:`while` statement is used for repeated execution as long as an
 expression is true:
@@ -112,8 +112,6 @@ expression is true:
    while_stmt: "while" `expression` ":" `suite`
              : ["else" ":" `suite`]
 
-.. index:: keyword: else
-
 This repeatedly tests the expression and, if it is true, executes the first
 suite; if the expression is false (which may be the first time it is tested) the
 suite of the :keyword:`else` clause, if present, is executed and the loop
@@ -137,8 +135,10 @@ The :keyword:`for` statement
 .. index::
    statement: for
    pair: loop; statement
-
-.. index:: object: sequence
+   keyword: in
+   keyword: else
+   pair: target; list
+   object: sequence
 
 The :keyword:`for` statement is used to iterate over the elements of a sequence
 (such as a string, tuple or list) or other iterable object:
@@ -147,11 +147,6 @@ The :keyword:`for` statement is used to iterate over the elements of a sequence
    for_stmt: "for" `target_list` "in" `expression_list` ":" `suite`
            : ["else" ":" `suite`]
 
-.. index::
-   keyword: in
-   keyword: else
-   pair: target; list
-
 The expression list is evaluated once; it should yield an iterable object.  An
 iterator is created for the result of the ``expression_list``.  The suite is
 then executed once for each item provided by the iterator, in the order of
@@ -214,7 +209,10 @@ effect of Pascal's ``for i := a to b do``; e.g., ``range(3)`` returns the list
 The :keyword:`try` statement
 ============================
 
-.. index:: statement: try
+.. index::
+   statement: try
+   keyword: except
+   keyword: finally
 
 The :keyword:`try` statement specifies exception handlers and/or cleanup code
 for a group of statements:
@@ -233,8 +231,6 @@ for a group of statements:
    :keyword:`finally` did not work. :keyword:`try`...\ :keyword:`except` had to be
    nested in :keyword:`try`...\ :keyword:`finally`.
 
-.. index:: keyword: except
-
 The :keyword:`except` clause(s) specify one or more exception handlers. When no
 exception occurs in the :keyword:`try` clause, no exception handler is executed.
 When an exception occurs in the :keyword:`try` suite, a search for an exception
@@ -376,12 +372,8 @@ The execution of the :keyword:`with` statement proceeds as follows:
 .. note::
 
    In Python 2.5, the :keyword:`with` statement is only allowed when the
-   ``with_statement`` feature has been enabled.  It will always be enabled in
-   Python 2.6.  This ``__future__`` import statement can be used to enable the
-   feature::
-
-      from __future__ import with_statement
-
+   ``with_statement`` feature has been enabled.  It is always enabled in
+   Python 2.6.
 
 .. seealso::
 
@@ -397,10 +389,10 @@ Function definitions
 ====================
 
 .. index::
-   pair: function; definition
    statement: def
-
-.. index::
+   pair: function; definition
+   pair: function; name
+   pair: name; binding
    object: user-defined function
    object: function
 
@@ -421,10 +413,6 @@ A function definition defines a user-defined function object (see section
    parameter: `identifier` | "(" `sublist` ")"
    funcname: `identifier`
 
-.. index::
-   pair: function; name
-   pair: name; binding
-
 A function definition is an executable statement.  Its execution binds the
 function name in the current local namespace to a function object (a wrapper
 around the executable code for the function).  This function object contains a
@@ -505,10 +493,13 @@ Class definitions
 =================
 
 .. index::
-   pair: class; definition
+   object: class
    statement: class
-
-.. index:: object: class
+   pair: class; definition
+   pair: class; name
+   pair: name; binding
+   pair: execution; frame
+   single: inheritance
 
 A class definition defines a class object (see section :ref:`types`):
 
@@ -517,12 +508,6 @@ A class definition defines a class object (see section :ref:`types`):
    inheritance: "(" [`expression_list`] ")"
    classname: `identifier`
 
-.. index::
-   single: inheritance
-   pair: class; name
-   pair: name; binding
-   pair: execution; frame
-
 A class definition is an executable statement.  It first evaluates the
 inheritance list, if present.  Each item in the inheritance list should evaluate
 to a class object or class type which allows subclassing.  The class's suite is
@@ -535,13 +520,13 @@ the saved local namespace for the attribute dictionary.  The class name is bound
 to this class object in the original local namespace.
 
 **Programmer's note:** Variables defined in the class definition are class
-variables; they are shared by all instances.  To define instance variables, they
-must be given a value in the :meth:`__init__` method or in another method.  Both
-class and instance variables are accessible through the notation
-"``self.name``", and an instance variable hides a class variable with the same
-name when accessed in this way.  Class variables with immutable values can be
-used as defaults for instance variables. For :term:`new-style class`\es,
-descriptors can be used to create instance variables with different
+variables; they are shared by all instances.  To create instance variables, they
+can be set in a method with ``self.name = value``.  Both class and instance
+variables are accessible through the notation "``self.name``", and an instance
+variable hides a class variable with the same name when accessed in this way.
+Class variables can be used as defaults for instance variables, but using
+mutable values there can lead to unexpected results.  For :term:`new-style
+class`\es, descriptors can be used to create instance variables with different
 implementation details.
 
 .. rubric:: Footnotes
@@ -552,4 +537,3 @@ implementation details.
 .. [#] Currently, control "flows off the end" except in the case of an exception or the
    execution of a :keyword:`return`, :keyword:`continue`, or :keyword:`break`
    statement.
-
diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index 6fc1f8e..7ea6ca7 100644
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -1097,16 +1097,15 @@ implemented before for compatibility concerns, like the method resolution order
 in case of multiple inheritance.
 
 This manual is not up-to-date with respect to new-style classes.  For now,
-please see http://www.python.org/doc/newstyle.html for more information.
+please see http://www.python.org/doc/newstyle/ for more information.
 
 .. index::
-   single: class
-   single: class
-   single: class
+   single: class; new-style
+   single: class; classic
+   single: class; old-style
 
 The plan is to eventually drop old-style classes, leaving only the semantics of
 new-style classes.  This change will probably only be feasible in Python 3.0.
-new-style classic old-style
 
 
 .. _specialnames:
@@ -2242,7 +2241,7 @@ For more information on context managers, see :ref:`typecontextmanager`.
    extensive revision, it must now be taken as authoritative only regarding
    "classic classes", that are still the default, for compatibility purposes, in
    Python 2.2 and 2.3.  For more information, see
-   http://www.python.org/doc/newstyle.html.
+   http://www.python.org/doc/newstyle/.
 
 .. [#] This, and other statements, are only roughly true for instances of new-style
    classes.
diff --git a/Doc/reference/simple_stmts.rst b/Doc/reference/simple_stmts.rst
index 513543b..0767170 100644
--- a/Doc/reference/simple_stmts.rst
+++ b/Doc/reference/simple_stmts.rst
@@ -34,7 +34,9 @@ simple statements is:
 Expression statements
 =====================
 
-.. index:: pair: expression; statement
+.. index::
+   pair: expression; statement
+   pair: expression; list
 
 Expression statements are used (mostly interactively) to compute and write a
 value, or (usually) to call a procedure (a function that returns no meaningful
@@ -45,8 +47,6 @@ expression statement is:
 .. productionlist::
    expression_stmt: `expression_list`
 
-.. index:: pair: expression; list
-
 An expression statement evaluates the expression list (which may be a single
 expression).
 
@@ -311,13 +311,13 @@ is determined when the interpreter starts.
 The :keyword:`pass` statement
 =============================
 
-.. index:: statement: pass
+.. index::
+   statement: pass
+   pair: null; operation
 
 .. productionlist::
    pass_stmt: "pass"
 
-.. index:: pair: null; operation
-
 :keyword:`pass` is a null operation --- when it is executed, nothing happens.
 It is useful as a placeholder when a statement is required syntactically, but no
 code needs to be executed, for example::
@@ -332,15 +332,14 @@ code needs to be executed, for example::
 The :keyword:`del` statement
 ============================
 
-.. index:: statement: del
-
-.. productionlist::
-   del_stmt: "del" `target_list`
-
 .. index::
+   statement: del
    pair: deletion; target
    triple: deletion; target; list
 
+.. productionlist::
+   del_stmt: "del" `target_list`
+
 Deletion is recursively defined very similar to the way assignment is defined.
 Rather that spelling it out in full details, here are some hints.
 
@@ -399,8 +398,6 @@ functional to write an empty string to standard output for this reason.)
 .. index::
    single: output
    pair: writing; values
-
-.. index::
    pair: trailing; comma
    pair: newline; suppression
 
@@ -434,15 +431,14 @@ then ``sys.stdout`` is used as the file for output.
 The :keyword:`return` statement
 ===============================
 
-.. index:: statement: return
-
-.. productionlist::
-   return_stmt: "return" [`expression_list`]
-
 .. index::
+   statement: return
    pair: function; definition
    pair: class; definition
 
+.. productionlist::
+   return_stmt: "return" [`expression_list`]
+
 :keyword:`return` may only occur syntactically nested in a function definition,
 not within a nested class definition.
 
@@ -468,17 +464,16 @@ raised.
 The :keyword:`yield` statement
 ==============================
 
-.. index:: statement: yield
-
-.. productionlist::
-   yield_stmt: `yield_expression`
-
 .. index::
+   statement: yield
    single: generator; function
    single: generator; iterator
    single: function; generator
    exception: StopIteration
 
+.. productionlist::
+   yield_stmt: `yield_expression`
+
 The :keyword:`yield` statement is only used when defining a generator function,
 and is only used in the body of the generator function. Using a :keyword:`yield`
 statement in a function definition is sufficient to cause that definition to
@@ -528,15 +523,14 @@ clauses to execute.
 The :keyword:`raise` statement
 ==============================
 
-.. index:: statement: raise
-
-.. productionlist::
-   raise_stmt: "raise" [`expression` ["," `expression` ["," `expression`]]]
-
 .. index::
+   statement: raise
    single: exception
    pair: raising; exception
 
+.. productionlist::
+   raise_stmt: "raise" [`expression` ["," `expression` ["," `expression`]]]
+
 If no expressions are present, :keyword:`raise` re-raises the last exception
 that was active in the current scope.  If no exception is active in the current
 scope, a :exc:`TypeError` exception is raised indicating that this is an error
@@ -578,16 +572,15 @@ and information about handling exceptions is in section :ref:`try`.
 The :keyword:`break` statement
 ==============================
 
-.. index:: statement: break
-
-.. productionlist::
-   break_stmt: "break"
-
 .. index::
+   statement: break
    statement: for
    statement: while
    pair: loop; statement
 
+.. productionlist::
+   break_stmt: "break"
+
 :keyword:`break` may only occur syntactically nested in a :keyword:`for` or
 :keyword:`while` loop, but not nested in a function or class definition within
 that loop.
@@ -614,17 +607,16 @@ really leaving the loop.
 The :keyword:`continue` statement
 =================================
 
-.. index:: statement: continue
-
-.. productionlist::
-   continue_stmt: "continue"
-
 .. index::
+   statement: continue
    statement: for
    statement: while
    pair: loop; statement
    keyword: finally
 
+.. productionlist::
+   continue_stmt: "continue"
+
 :keyword:`continue` may only occur syntactically nested in a :keyword:`for` or
 :keyword:`while` loop, but not nested in a function or class definition or
 :keyword:`finally` statement within that loop. [#]_ It continues with the next
@@ -739,8 +731,6 @@ raise a :exc:`SyntaxError`.
 .. index::
    keyword: from
    statement: from
-
-.. index::
    triple: hierarchical; module; names
    single: packages
    single: __init__.py
@@ -840,13 +830,13 @@ after the script is executed.
 The :keyword:`global` statement
 ===============================
 
-.. index:: statement: global
+.. index::
+   statement: global
+   triple: global; name; binding
 
 .. productionlist::
    global_stmt: "global" `identifier` ("," `identifier`)*
 
-.. index:: triple: global; name; binding
-
 The :keyword:`global` statement is a declaration which holds for the entire
 current code block.  It means that the listed identifiers are to be interpreted
 as globals.  It would be impossible to assign to a global variable without
@@ -908,7 +898,7 @@ variables.  If two expressions are given, they are used for the global and local
 variables, respectively. If provided, *locals* can be any mapping object.
 
 .. versionchanged:: 2.4
-   formerly *locals* was required to be a dictionary.
+   Formerly, *locals* was required to be a dictionary.
 
 .. index::
    single: __builtins__