Move the 2.6 reST doc tree in place.
diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst
new file mode 100644
index 0000000..87d9d68
--- /dev/null
+++ b/Doc/reference/compound_stmts.rst
@@ -0,0 +1,548 @@
+
+.. _compound:
+
+*******************
+Compound statements
+*******************
+
+.. index:: pair: compound; statement
+
+Compound statements contain (groups of) other statements; they affect or control
+the execution of those other statements in some way. In general, compound
+statements span multiple lines, although in simple incarnations a whole compound
+statement may be contained in one line.
+
+The :keyword:`if`, :keyword:`while` and :keyword:`for` statements implement
+traditional control flow constructs. :keyword:`try` specifies exception
+handlers and/or cleanup code for a group of statements. Function and class
+definitions are also syntactically compound statements.
+
+.. index::
+ single: clause
+ single: suite
+
+Compound statements consist of one or more 'clauses.' A clause consists of a
+header and a 'suite.' The clause headers of a particular compound statement are
+all at the same indentation level. Each clause header begins with a uniquely
+identifying keyword and ends with a colon. A suite is a group of statements
+controlled by a clause. A suite can be one or more semicolon-separated simple
+statements on the same line as the header, following the header's colon, or it
+can be one or more indented statements on subsequent lines. Only the latter
+form of suite can contain nested compound statements; the following is illegal,
+mostly because it wouldn't be clear to which :keyword:`if` clause a following
+:keyword:`else` clause would belong: ::
+
+ 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`)* [";"]
+
+.. 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:
+
+The :keyword:`if` statement
+===========================
+
+.. index:: statement: if
+
+The :keyword:`if` statement is used for conditional execution:
+
+.. productionlist::
+ if_stmt: "if" `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
+
+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
+
+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
+
+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 continues
+with the next item, or with the :keyword:`else` clause if there was no next
+item.
+
+The suite may assign to the variable(s) in the target list; this does not affect
+the next item assigned to it.
+
+.. index::
+ builtin: range
+ pair: Pascal; language
+
+The target list is not deleted when the loop is finished, but if the sequence is
+empty, it will not have been assigned to at all by the loop. Hint: the built-in
+function :func:`range` returns a sequence of integers suitable to emulate the
+effect of Pascal's ``for i := a to b do``; e.g., ``range(3)`` returns the list
+``[0, 1, 2]``.
+
+.. warning::
+
+ .. index::
+ single: loop; over mutable sequence
+ single: mutable sequence; loop over
+
+ There is a subtlety when the sequence is being modified by the loop (this can
+ only occur for mutable sequences, i.e. lists). An internal counter is used to
+ keep track of which item is used next, and this is incremented on each
+ iteration. When this counter has reached the length of the sequence the loop
+ terminates. This means that if the suite deletes the current (or a previous)
+ item from the sequence, the next item will be skipped (since it gets the index
+ of the current item which has already been treated). Likewise, if the suite
+ 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:
+
+The :keyword:`try` statement
+============================
+
+.. index:: statement: try
+
+The :keyword:`try` statement specifies exception handlers and/or cleanup code
+for a group of statements:
+
+.. productionlist::
+ try_stmt: try1_stmt | try2_stmt
+ try1_stmt: "try" ":" `suite`
+ : ("except" [`expression` ["," `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
+just a string with the same value).
+
+If no except clause matches the exception, the search for an exception handler
+continues in the surrounding code and on the invocation stack. [#]_
+
+If the evaluation of an expression in the header of an except clause raises an
+exception, the original search for a handler is canceled and a search starts for
+the new exception in the surrounding code and on the call stack (it is treated
+as if the entire :keyword:`try` statement raised the exception).
+
+When a matching except clause is found, the exception is assigned to the target
+specified in that except clause, if present, and the except clause's suite is
+executed. All except clauses must have an executable block. When the end of
+this block is reached, execution continues normally after the entire try
+statement. (This means that if two nested handlers exist for the same
+exception, and the exception occurs in the try clause of the inner handler, the
+outer handler will not handle the exception.)
+
+.. 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:`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
+
+The optional :keyword:`else` clause is executed if and when control flows off
+the end of the :keyword:`try` clause. [#]_ Exceptions in the :keyword:`else`
+clause are not handled by the preceding :keyword:`except` clauses.
+
+.. index:: keyword: finally
+
+If :keyword:`finally` is present, it specifies a 'cleanup' handler. The
+:keyword:`try` clause is executed, including any :keyword:`except` and
+:keyword:`else` clauses. If an exception occurs in any of the clauses and is
+not handled, the exception is temporarily saved. The :keyword:`finally` clause
+is executed. If there is a saved exception, it is re-raised at the end of the
+:keyword:`finally` clause. If the :keyword:`finally` clause raises another
+exception or executes a :keyword:`return` or :keyword:`break` statement, the
+saved exception is lost. The exception information is not available to the
+program during execution of the :keyword:`finally` clause.
+
+.. index::
+ statement: return
+ statement: break
+ statement: continue
+
+When a :keyword:`return`, :keyword:`break` or :keyword:`continue` statement is
+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:
+
+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`
+
+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::
+
+ The :keyword:`with` statement guarantees that if the :meth:`__enter__` method
+ returns without an error, then :meth:`__exit__` will always be called. Thus, if
+ an error occurs during the assignment to the target list, it will be treated the
+ same as an error occurring within the suite would be. See step 5 below.
+
+#. The suite is executed.
+
+#. The context manager's :meth:`__exit__` method is invoked. If an exception
+ caused the suite to be exited, its type, value, and traceback are passed as
+ arguments to :meth:`__exit__`. Otherwise, three :const:`None` arguments are
+ supplied.
+
+ 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
+
+
+.. seealso::
+
+ :pep:`0343` - The "with" statement
+ The specification, background, and examples for the Python :keyword:`with`
+ statement.
+
+
+.. _function:
+
+Function definitions
+====================
+
+.. index::
+ pair: function; definition
+ statement: def
+
+.. index::
+ 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`+
+ decorator: "@" `dotted_name` ["(" [`argument_list` [","]] ")"] NEWLINE
+ dotted_name: `identifier` ("." `identifier`)*
+ parameter_list: (`defparameter` ",")*
+ : ( "*" `identifier` [, "**" `identifier`]
+ : | "**" `identifier`
+ : | `defparameter` [","] )
+ defparameter: `parameter` ["=" `expression`]
+ 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.
+
+A function definition may be wrapped by one or more 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::
+
+ def func(): pass
+ func = f1(arg)(f2(func))
+
+.. index:: triple: default; parameter; value
+
+When one or more top-level parameters have the form *parameter* ``=``
+*expression*, the function is said to have "default parameter values." For a
+parameter with a default value, the corresponding argument may be omitted from a
+call, in which case the parameter's default value is substituted. If a
+parameter has a default value, all following parameters must also have a default
+value --- this is a syntactic restriction that is not expressed by the grammar.
+
+**Default parameter values are evaluated when the function definition is
+executed.** This means that the expression is evaluated once, when the function
+is defined, and that that same "pre-computed" value is used for each call. This
+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
+
+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
+section :ref:`lambda`. Note that the lambda form is merely a shorthand for a
+simplified function definition; a function defined in a ":keyword:`def`"
+statement can be passed around or assigned to another name just like a function
+defined by a lambda form. The ":keyword:`def`" form is actually more powerful
+since it allows the execution of multiple statements.
+
+**Programmer's note:** Functions are first-class objects. A "``def``" form
+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
+ statement: class
+
+.. index:: object: class
+
+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.
+
+**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.
+
+.. rubric:: Footnotes
+
+.. [#] The exception is propogated 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.
+