--- rest25/reference/compound_stmts.rst	2008-12-19 16:58:05.000000000 +0900
+++ rest262/reference/compound_stmts.rst	2009-04-05 05:01:44.000000000 +0900
@@ -35,130 +35,128 @@
    if test1: if test2: print x
 
 Also note that the semicolon binds tighter than the colon in this context, so
 that in the following example, either all or none of the :keyword:`print`
 statements are executed::
 
    if x < y < z: print x; print y; print z
 
 Summarizing:
 
 .. productionlist::
    compound_stmt: `if_stmt`
-                : \| `while_stmt`
-                : \| `for_stmt`
-                : \| `try_stmt`
-                : \| `with_stmt`
-                : \| `funcdef`
-                : \| `classdef`
-   suite: `stmt_list` NEWLINE \| NEWLINE INDENT `statement`\ + DEDENT
-   statement: `stmt_list` NEWLINE \| `compound_stmt`
-   stmt_list: `simple_stmt` (";" `simple_stmt`)\* [";"]
+                : | `while_stmt`
+                : | `for_stmt`
+                : | `try_stmt`
+                : | `with_stmt`
+                : | `funcdef`
+                : | `classdef`
+                : | `decorated`
+   suite: `stmt_list` NEWLINE | NEWLINE INDENT `statement`+ DEDENT
+   statement: `stmt_list` NEWLINE | `compound_stmt`
+   stmt_list: `simple_stmt` (";" `simple_stmt`)* [";"]
 
 .. index::
    single: NEWLINE token
    single: DEDENT token
    pair: dangling; else
 
 Note that statements always end in a ``NEWLINE`` possibly followed by a
 ``DEDENT``. Also note that optional continuation clauses always begin with a
 keyword that cannot start a statement, thus there are no ambiguities (the
 'dangling :keyword:`else`' problem is solved in Python by requiring nested
 :keyword:`if` statements to be indented).
 
 The formatting of the grammar rules in the following sections places each clause
 on a separate line for clarity.
 
 
 .. _if:
+.. _elif:
+.. _else:
 
 The :keyword:`if` statement
 ===========================
 
-.. index:: statement: if
+.. index::
+   statement: if
+   keyword: elif
+   keyword: else
 
 The :keyword:`if` statement is used for conditional execution:
 
 .. productionlist::
    if_stmt: "if" `expression` ":" `suite`
-          : ( "elif" `expression` ":" `suite` )\*
+          : ( "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
 :keyword:`if` statement is executed or evaluated).  If all expressions are
 false, the suite of the :keyword:`else` clause, if present, is executed.
 
 
 .. _while:
 
 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:
 
 .. productionlist::
    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
 terminates.
 
 .. index::
    statement: break
    statement: continue
 
 A :keyword:`break` statement executed in the first suite terminates the loop
 without executing the :keyword:`else` clause's suite.  A :keyword:`continue`
 statement executed in the first suite skips the rest of the suite and goes back
 to testing the expression.
 
 
 .. _for:
 
 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:
 
 .. productionlist::
    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
 ascending indices.  Each item in turn is assigned to the target list using the
 standard rules for assignments, and then the suite is executed.  When the items
 are exhausted (which is immediately when the sequence is empty), the suite in
 the :keyword:`else` clause, if present, is executed, and the loop terminates.
 
 .. index::
    statement: break
    statement: continue
 
@@ -197,49 +195,52 @@
    inserts an item in the sequence before the current item, the current item will
    be treated again the next time through the loop. This can lead to nasty bugs
    that can be avoided by making a temporary copy using a slice of the whole
    sequence, e.g.,
 
 ::
 
    for x in a[:]:
        if x < 0: a.remove(x)
 
 
 .. _try:
+.. _except:
+.. _finally:
 
 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:
 
 .. productionlist::
-   try_stmt: try1_stmt \| try2_stmt
+   try_stmt: try1_stmt | try2_stmt
    try1_stmt: "try" ":" `suite`
-            : ("except" [`expression` ["," `target`]] ":" `suite`)+
+            : ("except" [`expression` [("as" | ",") `target`]] ":" `suite`)+
             : ["else" ":" `suite`]
             : ["finally" ":" `suite`]
    try2_stmt: "try" ":" `suite`
             : "finally" ":" `suite`
 
 .. versionchanged:: 2.5
    In previous versions of Python, :keyword:`try`...\ :keyword:`except`...\
    :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
 handler is started.  This search inspects the except clauses in turn until one
 is found that matches the exception.  An expression-less except clause, if
 present, must be last; it matches any exception.  For an except clause with an
 expression, that expression is evaluated, and the clause matches the exception
 if the resulting object is "compatible" with the exception.  An object is
 compatible with an exception if it is the class or a base class of the exception
 object, a tuple containing an item compatible with the exception, or, in the
 (deprecated) case of string exceptions, is the raised string itself (note that
 the object identities must match, i.e. it must be the same string object, not
@@ -263,25 +264,25 @@
 
 .. index::
    module: sys
    object: traceback
    single: exc_type (in module sys)
    single: exc_value (in module sys)
    single: exc_traceback (in module sys)
 
 Before an except clause's suite is executed, details about the exception are
 assigned to three variables in the :mod:`sys` module: ``sys.exc_type`` receives
 the object identifying the exception; ``sys.exc_value`` receives the exception's
 parameter; ``sys.exc_traceback`` receives a traceback object (see section
-:ref:`traceback`) identifying the point in the program where the exception
+:ref:`types`) identifying the point in the program where the exception
 occurred. These details are also available through the :func:`sys.exc_info`
 function, which returns a tuple ``(exc_type, exc_value, exc_traceback)``.  Use
 of the corresponding variables is deprecated in favor of this function, since
 their use is unsafe in a threaded program.  As of Python 1.5, the variables are
 restored to their previous values (before the call) when returning from a
 function that handled an exception.
 
 .. index::
    keyword: else
    statement: return
    statement: break
    statement: continue
@@ -311,39 +312,40 @@
 executed in the :keyword:`try` suite of a :keyword:`try`...\ :keyword:`finally`
 statement, the :keyword:`finally` clause is also executed 'on the way out.' A
 :keyword:`continue` statement is illegal in the :keyword:`finally` clause. (The
 reason is a problem with the current implementation --- this restriction may be
 lifted in the future).
 
 Additional information on exceptions can be found in section :ref:`exceptions`,
 and information on using the :keyword:`raise` statement to generate exceptions
 may be found in section :ref:`raise`.
 
 
 .. _with:
+.. _as:
 
 The :keyword:`with` statement
 =============================
 
 .. index:: statement: with
 
 .. versionadded:: 2.5
 
 The :keyword:`with` statement is used to wrap the execution of a block with
 methods defined by a context manager (see section :ref:`context-managers`). This
 allows common :keyword:`try`...\ :keyword:`except`...\ :keyword:`finally` usage
 patterns to be encapsulated for convenient reuse.
 
 .. productionlist::
-   with_stmt: "with" `expression` ["as" target] ":" `suite`
+   with_stmt: "with" `expression` ["as" `target`] ":" `suite`
 
 The execution of the :keyword:`with` statement proceeds as follows:
 
 #. The context expression is evaluated to obtain a context manager.
 
 #. The context manager's :meth:`__enter__` method is invoked.
 
 #. If a target was included in the :keyword:`with` statement, the return value
    from :meth:`__enter__` is assigned to it.
 
    .. note::
 
@@ -362,82 +364,79 @@
    If the suite was exited due to an exception, and the return value from the
    :meth:`__exit__` method was false, the exception is reraised. If the return
    value was true, the exception is suppressed, and execution continues with the
    statement following the :keyword:`with` statement.
 
    If the suite was exited for any reason other than an exception, the return value
    from :meth:`__exit__` is ignored, and execution proceeds at the normal location
    for the kind of exit that was taken.
 
 .. 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::
 
    :pep:`0343` - The "with" statement
       The specification, background, and examples for the Python :keyword:`with`
       statement.
 
 
 .. _function:
+.. _def:
 
 Function definitions
 ====================
 
 .. index::
-   pair: function; definition
    statement: def
-
-.. index::
+   pair: function; definition
+   pair: function; name
+   pair: name; binding
    object: user-defined function
    object: function
 
 A function definition defines a user-defined function object (see section
 :ref:`types`):
 
 .. productionlist::
-   funcdef: [`decorators`] "def" `funcname` "(" [`parameter_list`] ")" ":" `suite`
-   decorators: `decorator`\ +
+   decorated: decorators (classdef | funcdef)
+   decorators: `decorator`+
    decorator: "@" `dotted_name` ["(" [`argument_list` [","]] ")"] NEWLINE
-   dotted_name: `identifier` ("." `identifier`)\*
-   parameter_list: (`defparameter` ",")\*
-                 : (  "\*" `identifier` [, "\*\*" `identifier`]
-                 : \| "\*\*" `identifier`
-                 : \| `defparameter` [","] )
+   funcdef: "def" `funcname` "(" [`parameter_list`] ")" ":" `suite`
+   dotted_name: `identifier` ("." `identifier`)*
+   parameter_list: (`defparameter` ",")*
+                 : (  "*" `identifier` [, "**" `identifier`]
+                 : | "**" `identifier`
+                 : | `defparameter` [","] )
    defparameter: `parameter` ["=" `expression`]
-   sublist: `parameter` ("," `parameter`)\* [","]
-   parameter: `identifier` \| "(" `sublist` ")"
+   sublist: `parameter` ("," `parameter`)* [","]
+   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
 reference to the current global namespace as the global namespace to be used
 when the function is called.
 
 The function definition does not execute the function body; this gets executed
-only when the function is called.
+only when the function is called. [#]_
+
+.. index::
+  statement: @
 
-A function definition may be wrapped by one or more decorator expressions.
+A function definition may be wrapped by one or more :term:`decorator` expressions.
 Decorator expressions are evaluated when the function is defined, in the scope
 that contains the function definition.  The result must be a callable, which is
 invoked with the function object as the only argument. The returned value is
 bound to the function name instead of the function object.  Multiple decorators
 are applied in nested fashion. For example, the following code::
 
    @f1(arg)
    @f2
    def func(): pass
 
 is equivalent to::
 
@@ -459,24 +458,28 @@
 is especially important to understand when a default parameter is a mutable
 object, such as a list or a dictionary: if the function modifies the object
 (e.g. by appending an item to a list), the default value is in effect modified.
 This is generally not what was intended.  A way around this  is to use ``None``
 as the default, and explicitly test for it in the body of the function, e.g.::
 
    def whats_on_the_telly(penguin=None):
        if penguin is None:
            penguin = []
        penguin.append("property of the zoo")
        return penguin
 
+.. index::
+  statement: *
+  statement: **
+
 Function call semantics are described in more detail in section :ref:`calls`. A
 function call always assigns values to all parameters mentioned in the parameter
 list, either from position arguments, from keyword arguments, or from default
 values.  If the form "``*identifier``" is present, it is initialized to a tuple
 receiving any excess positional parameters, defaulting to the empty tuple.  If
 the form "``**identifier``" is present, it is initialized to a new dictionary
 receiving any excess keyword arguments, defaulting to a new empty dictionary.
 
 .. index:: pair: lambda; form
 
 It is also possible to create anonymous functions (functions not bound to a
 name), for immediate use in expressions.  This uses lambda forms, described in
@@ -490,59 +493,70 @@
 executed inside a function definition defines a local function that can be
 returned or passed around.  Free variables used in the nested function can
 access the local variables of the function containing the def.  See section
 :ref:`naming` for details.
 
 
 .. _class:
 
 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
+   single: docstring
 
 A class definition defines a class object (see section :ref:`types`):
 
 .. productionlist::
    classdef: "class" `classname` [`inheritance`] ":" `suite`
    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
 then executed in a new execution frame (see section :ref:`naming`), using a
 newly created local namespace and the original global namespace. (Usually, the
 suite contains only function definitions.)  When the class's suite finishes
-execution, its execution frame is discarded but its local namespace is saved.  A
-class object is then created using the inheritance list for the base classes and
-the saved local namespace for the attribute dictionary.  The class name is bound
-to this class object in the original local namespace.
+execution, its execution frame is discarded but its local namespace is
+saved. [#]_ A class object is then created using the inheritance list for the
+base classes and 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 new-style classes, descriptors can
-be used to create instance variables with different implementation details.
+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.
+
+Class definitions, like function definitions, may be wrapped by one or more
+:term:`decorator` expressions.  The evaluation rules for the decorator
+expressions are the same as for functions.  The result must be a class object,
+which is then bound to the class name.
 
 .. rubric:: Footnotes
 
-.. [#] The exception is propogated to the invocation stack only if there is no
+.. [#] The exception is propagated to the invocation stack only if there is no
    :keyword:`finally` clause that negates the exception.
 
 .. [#] 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.
 
+.. [#] A string literal appearing as the first statement in the function body is
+   transformed into the function's ``__doc__`` attribute and therefore the
+   function's :term:`docstring`.
+
+.. [#] A string literal appearing as the first statement in the class body is
+   transformed into the namespace's ``__doc__`` item and therefore the class's
+   :term:`docstring`.
