Initial revision

3 files changed, 923 insertions, 0 deletions

diff --git a/Doc/ref/ref6.tex b/Doc/ref/ref6.tex
new file mode 100644
index 0000000..cb257a3
--- /dev/null
+++ b/Doc/ref/ref6.tex
@@ -0,0 +1,468 @@
+\chapter{Simple statements}
+\indexii{simple}{statement}
+
+Simple statements are comprised within a single logical line.
+Several simple statements may occur on a single line separated
+by semicolons.  The syntax for simple statements is:
+
+\begin{verbatim}
+simple_stmt:    expression_stmt
+              | assignment_stmt
+              | pass_stmt
+              | del_stmt
+              | print_stmt
+              | return_stmt
+              | raise_stmt
+              | break_stmt
+              | continue_stmt
+              | import_stmt
+              | global_stmt
+\end{verbatim}
+
+\section{Expression statements}
+\indexii{expression}{statement}
+
+Expression statements are used (mostly interactively) to compute and
+write a value, or (usually) to call a procedure (a function that
+returns no meaningful result; in Python, procedures return the value
+\verb\None\):
+
+\begin{verbatim}
+expression_stmt: expression_list
+\end{verbatim}
+
+An expression statement evaluates the expression list (which may be a
+single expression).  If the value is not \verb\None\, it is converted
+to a string using the rules for string conversions (expressions in
+reverse quotes), and the resulting string is written to standard
+output (see section \ref{print}) on a line by itself.
+\indexii{expression}{list}
+\ttindex{None}
+\indexii{string}{conversion}
+\index{output}
+\indexii{standard}{output}
+\indexii{writing}{values}
+
+(The exception for \verb\None\ is made so that procedure calls, which
+are syntactically equivalent to expressions, do not cause any output.
+A tuple with only \verb\None\ items is written normally.)
+\indexii{procedure}{call}
+
+\section{Assignment statements}
+\indexii{assignment}{statement}
+
+Assignment statements are used to (re)bind names to values and to
+modify attributes or items of mutable objects:
+\indexii{binding}{name}
+\indexii{rebinding}{name}
+\obindex{mutable}
+\indexii{attribute}{assignment}
+
+\begin{verbatim}
+assignment_stmt: (target_list "=")+ expression_list
+target_list:     target ("," target)* [","]
+target:          identifier | "(" target_list ")" | "[" target_list "]"
+               | attributeref | subscription | slicing
+\end{verbatim}
+
+(See section \ref{primaries} for the syntax definitions for the last
+three symbols.)
+
+An assignment statement evaluates the expression list (remember that
+this can be a single expression or a comma-separated list, the latter
+yielding a tuple) and assigns the single resulting object to each of
+the target lists, from left to right.
+\indexii{expression}{list}
+
+Assignment is defined recursively depending on the form of the target
+(list).  When a target is part of a mutable object (an attribute
+reference, subscription or slicing), the mutable object must
+ultimately perform the assignment and decide about its validity, and
+may raise an exception if the assignment is unacceptable.  The rules
+observed by various types and the exceptions raised are given with the
+definition of the object types (see section \ref{types}).
+\index{target}
+\indexii{target}{list}
+
+Assignment of an object to a target list is recursively defined as
+follows.
+\indexiii{target}{list}{assignment}
+
+\begin{itemize}
+\item
+If the target list is a single target: the object is assigned to that
+target.
+
+\item
+If the target list is a comma-separated list of targets: the object
+must be a tuple with the same number of items as the list contains
+targets, and the items are assigned, from left to right, to the
+corresponding targets.
+
+\end{itemize}
+
+Assignment of an object to a single target is recursively defined as
+follows.
+
+\begin{itemize} % nested
+
+\item
+If the target is an identifier (name):
+
+\begin{itemize}
+
+\item
+If the name does not occur in a \verb\global\ statement in the current
+code block: the name is bound to the object in the current local name
+space.
+\stindex{global}
+
+\item
+Otherwise: the name is bound to the object in the current global name
+space.
+
+\end{itemize} % nested
+
+The name is rebound if it was already bound.
+
+\item
+If the target is a target list enclosed in parentheses: the object is
+assigned to that target list as described above.
+
+\item
+If the target is a target list enclosed in square brackets: the object
+must be a list with the same number of items as the target list
+contains targets, and its items are assigned, from left to right, to
+the corresponding targets.
+
+\item
+If the target is an attribute reference: The primary expression in the
+reference is evaluated.  It should yield an object with assignable
+attributes; if this is not the case, \verb\TypeError\ is raised.  That
+object is then asked to assign the assigned object to the given
+attribute; if it cannot perform the assignment, it raises an exception
+(usually but not necessarily \verb\AttributeError\).
+\indexii{attribute}{assignment}
+
+\item
+If the target is a subscription: The primary expression in the
+reference is evaluated.  It should yield either a mutable sequence
+(list) object or a mapping (dictionary) object.  Next, the subscript
+expression is evaluated.
+\indexii{subscription}{assignment}
+\obindex{mutable}
+
+If the primary is a mutable sequence object (a list), the subscript
+must yield a plain integer.  If it is negative, the sequence's length
+is added to it.  The resulting value must be a nonnegative integer
+less than the sequence's length, and the sequence is asked to assign
+the assigned object to its item with that index.  If the index is out
+of range, \verb\IndexError\ is raised (assignment to a subscripted
+sequence cannot add new items to a list).
+\obindex{sequence}
+\obindex{list}
+
+If the primary is a mapping (dictionary) object, the subscript must
+have a type compatible with the mapping's key type, and the mapping is
+then asked to to create a key/datum pair which maps the subscript to
+the assigned object.  This can either replace an existing key/value
+pair with the same key value, or insert a new key/value pair (if no
+key with the same value existed).
+\obindex{mapping}
+\obindex{dictionary}
+
+\item
+If the target is a slicing: The primary expression in the reference is
+evaluated.  It should yield a mutable sequence (list) object.  The
+assigned object should be a sequence object of the same type.  Next,
+the lower and upper bound expressions are evaluated, insofar they are
+present; defaults are zero and the sequence's length.  The bounds
+should evaluate to (small) integers.  If either bound is negative, the
+sequence's length is added to it.  The resulting bounds are clipped to
+lie between zero and the sequence's length, inclusive.  Finally, the
+sequence object is asked to replace the items indicated by the slice
+with the items of the assigned sequence.  This may change the
+sequence's length, if it allows it.
+\indexii{slicing}{assignment}
+
+\end{itemize}
+	
+(In the original implementation, the syntax for targets is taken
+to be the same as for expressions, and invalid syntax is rejected
+during the code generation phase, causing less detailed error
+messages.)
+
+\section{The {\tt pass} statement}
+\stindex{pass}
+
+\begin{verbatim}
+pass_stmt:      "pass"
+\end{verbatim}
+
+\verb\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:
+\indexii{null}{operation}
+
+\begin{verbatim}
+def f(arg): pass    # a function that does nothing (yet)
+
+class C: pass       # an class with no methods (yet)
+\end{verbatim}
+
+\section{The {\tt del} statement}
+\stindex{del}
+
+\begin{verbatim}
+del_stmt:       "del" target_list
+\end{verbatim}
+
+Deletion is recursively defined very similar to the way assignment is
+defined. Rather that spelling it out in full details, here are some
+hints.
+\indexii{deletion}{target}
+\indexiii{deletion}{target}{list}
+
+Deletion of a target list recursively deletes each target, from left
+to right.
+
+Deletion of a name removes the binding of that name (which must exist)
+from the local or global name space, depending on whether the name
+occurs in a \verb\global\ statement in the same code block.
+\stindex{global}
+\indexii{unbinding}{name}
+
+Deletion of attribute references, subscriptions and slicings
+is passed to the primary object involved; deletion of a slicing
+is in general equivalent to assignment of an empty slice of the
+right type (but even this is determined by the sliced object).
+\indexii{attribute}{deletion}
+
+\section{The {\tt print} statement} \label{print}
+\stindex{print}
+
+\begin{verbatim}
+print_stmt:     "print" [ condition ("," condition)* [","] ]
+\end{verbatim}
+
+\verb\print\ evaluates each condition in turn and writes the resulting
+object to standard output (see below).  If an object is not a string,
+it is first converted to a string using the rules for string
+conversions.  The (resulting or original) string is then written.  A
+space is written before each object is (converted and) written, unless
+the output system believes it is positioned at the beginning of a
+line.  This is the case: (1) when no characters have yet been written
+to standard output; or (2) when the last character written to standard
+output is \verb/\n/; or (3) when the last write operation on standard
+output was not a \verb\print\ statement.  (In some cases it may be
+functional to write an empty string to standard output for this
+reason.)
+\index{output}
+\indexii{writing}{values}
+
+A \verb/"\n"/ character is written at the end, unless the \verb\print\
+statement ends with a comma.  This is the only action if the statement
+contains just the keyword \verb\print\.
+\indexii{trailing}{comma}
+\indexii{newline}{suppression}
+
+Standard output is defined as the file object named \verb\stdout\
+in the built-in module \verb\sys\.  If no such object exists,
+or if it is not a writable file, a \verb\RuntimeError\ exception is raised.
+(The original implementation attempts to write to the system's original
+standard output instead, but this is not safe, and should be fixed.)
+\indexii{standard}{output}
+\bimodindex{sys}
+\ttindex{stdout}
+\exindex{RuntimeError}
+
+\section{The {\tt return} statement}
+\stindex{return}
+
+\begin{verbatim}
+return_stmt:    "return" [condition_list]
+\end{verbatim}
+
+\verb\return\ may only occur syntactically nested in a function
+definition, not within a nested class definition.
+\indexii{function}{definition}
+\indexii{class}{definition}
+
+If a condition list is present, it is evaluated, else \verb\None\
+is substituted.
+
+\verb\return\ leaves the current function call with the condition
+list (or \verb\None\) as return value.
+
+When \verb\return\ passes control out of a \verb\try\ statement
+with a \verb\finally\ clause, that finally clause is executed
+before really leaving the function.
+\kwindex{finally}
+
+\section{The {\tt raise} statement}
+\stindex{raise}
+
+\begin{verbatim}
+raise_stmt:     "raise" condition ["," condition]
+\end{verbatim}
+
+\verb\raise\ evaluates its first condition, which must yield
+a string object.  If there is a second condition, this is evaluated,
+else \verb\None\ is substituted.
+\index{exception}
+\indexii{raising}{exception}
+
+It then raises the exception identified by the first object,
+with the second one (or \verb\None\) as its parameter.
+
+\section{The {\tt break} statement}
+\stindex{break}
+
+\begin{verbatim}
+break_stmt:     "break"
+\end{verbatim}
+
+\verb\break\ may only occur syntactically nested in a \verb\for\
+or \verb\while\ loop, not nested in a function or class definition.
+\stindex{for}
+\stindex{while}
+\indexii{loop}{statement}
+
+It terminates the neares enclosing loop, skipping the optional
+\verb\else\ clause if the loop has one.
+\kwindex{else}
+
+If a \verb\for\ loop is terminated by \verb\break\, the loop control
+target keeps its current value.
+\indexii{loop control}{target}
+
+When \verb\break\ passes control out of a \verb\try\ statement
+with a \verb\finally\ clause, that finally clause is executed
+before really leaving the loop.
+\kwindex{finally}
+
+\section{The {\tt continue} statement}
+\stindex{continue}
+
+\begin{verbatim}
+continue_stmt:  "continue"
+\end{verbatim}
+
+\verb\continue\ may only occur syntactically nested in a \verb\for\ or
+\verb\while\ loop, not nested in a function or class definition, and
+not nested in the \verb\try\ clause of a \verb\try\ statement with a
+\verb\finally\ clause (it may occur nested in a \verb\except\ or
+\verb\finally\ clause of a \verb\try\ statement though).
+\stindex{for}
+\stindex{while}
+\indexii{loop}{statement}
+\kwindex{finally}
+
+It continues with the next cycle of the nearest enclosing loop.
+
+\section{The {\tt import} statement} \label{import}
+\stindex{import}
+
+\begin{verbatim}
+import_stmt:    "import" identifier ("," identifier)*
+              | "from" identifier "import" identifier ("," identifier)*
+              | "from" identifier "import" "*"
+\end{verbatim}
+
+Import statements are executed in two steps: (1) find a module, and
+initialize it if necessary; (2) define a name or names in the local
+name space (of the scope where the \verb\import\ statement occurs).
+The first form (without \verb\from\) repeats these steps for each
+identifier in the list, the \verb\from\ form performs them once, with
+the first identifier specifying the module name.
+\indexii{importing}{module}
+\indexii{name}{binding}
+\kwindex{from}
+
+The system maintains a table of modules that have been initialized,
+indexed by module name.  (The current implementation makes this table
+accessible as \verb\sys.modules\.)  When a module name is found in
+this table, step (1) is finished.  If not, a search for a module
+definition is started.  This first looks for a built-in module
+definition, and if no built-in module if the given name is found, it
+searches a user-specified list of directories for a file whose name is
+the module name with extension \verb\".py"\.  (The current
+implementation uses the list of strings \verb\sys.path\ as the search
+path; it is initialized from the shell environment variable
+\verb\$PYTHONPATH\, with an installation-dependent default.)
+\ttindex{modules}
+\ttindex{sys.modules}
+\indexii{module}{name}
+\indexii{built-in}{module}
+\indexii{user-defined}{module}
+\bimodindex{sys}
+\ttindex{path}
+\ttindex{sys.path}
+\indexii{filename}{extension}
+
+If a built-in module is found, its built-in initialization code is
+executed and step (1) is finished.  If no matching file is found,
+\verb\ImportError\ is raised.  If a file is found, it is parsed,
+yielding an executable code block.  If a syntax error occurs,
+\verb\SyntaxError\ is raised.  Otherwise, an empty module of the given
+name is created and inserted in the module table, and then the code
+block is executed in the context of this module.  Exceptions during
+this execution terminate step (1).
+\indexii{module}{initialization}
+\exindex{SyntaxError}
+\exindex{ImportError}
+\index{code block}
+
+When step (1) finishes without raising an exception, step (2) can
+begin.
+
+The first form of \verb\import\ statement binds the module name in the
+local name space to the module object, and then goes on to import the
+next identifier, if any.  The \verb\from\ from does not bind the
+module name: it goes through the list of identifiers, looks each one
+of them up in the module found in step (1), and binds the name in the
+local name space to the object thus found.  If a name is not found,
+\verb\ImportError\ is raised.  If the list of identifiers is replaced
+by a star (\verb\*\), all names defined in the module are bound,
+except those beginning with an underscore(\verb\_\).
+\indexii{name}{binding}
+\exindex{ImportError}
+
+Names bound by import statements may not occur in \verb\global\
+statements in the same scope.
+\stindex{global}
+
+The \verb\from\ form with \verb\*\ may only occur in a module scope.
+\kwindex{from}
+\ttindex{from ... import *}
+
+(The current implementation does not enforce the latter two
+restrictions, but programs should not abuse this freedom, as future
+implementations may enforce them or silently change the meaning of the
+program.)
+
+\section{The {\tt global} statement} \label{global}
+\stindex{global}
+
+\begin{verbatim}
+global_stmt:    "global" identifier ("," identifier)*
+\end{verbatim}
+
+The \verb\global\ statement is a declaration which holds for the
+entire current scope.  It means that the listed identifiers are to be
+interpreted as globals.  While {\em using} global names is automatic
+if they are not defined in the local scope, {\em assigning} to global
+names would be impossible without \verb\global\.
+\indexiii{global}{name}{binding}
+
+Names listed in a \verb\global\ statement must not be used in the same
+scope before that \verb\global\ statement is executed.
+
+Names listed in a \verb\global\ statement must not be defined as formal
+parameters or in a \verb\for\ loop control target, \verb\class\
+definition, function definition, or \verb\import\ statement.
+
+(The current implementation does not enforce the latter two
+restrictions, but programs should not abuse this freedom, as future
+implementations may enforce them or silently change the meaning of the
+program.)
diff --git a/Doc/ref/ref7.tex b/Doc/ref/ref7.tex
new file mode 100644
index 0000000..357bd5f
--- /dev/null
+++ b/Doc/ref/ref7.tex
@@ -0,0 +1,347 @@
+\chapter{Compound statements}
+\indexii{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 \verb\if\, \verb\while\ and \verb\for\ statements implement
+traditional control flow constructs.  \verb\try\ specifies exception
+handlers and/or cleanup code for a group of statements.  Function and
+class definitions are also syntactically compound statements.
+
+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 \verb\if\ clause a following \verb\else\ clause would
+belong:
+\index{clause}
+\index{suite}
+
+\begin{verbatim}
+if test1: if test2: print x
+\end{verbatim}
+
+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
+\verb\print\ statements are executed:
+
+\begin{verbatim}
+if x < y < z: print x; print y; print z
+\end{verbatim}
+
+Summarizing:
+
+\begin{verbatim}
+compound_stmt:  if_stmt | while_stmt | for_stmt
+              | try_stmt | funcdef | classdef
+suite:          stmt_list NEWLINE | NEWLINE INDENT statement+ DEDENT
+statement:      stmt_list NEWLINE | compound_stmt
+stmt_list:      simple_stmt (";" simple_stmt)* [";"]
+\end{verbatim}
+
+Note that statements always end in a \verb\NEWLINE\ possibly followed
+by a \verb\DEDENT\.
+\index{NEWLINE token}
+\index{DEDENT token}
+
+Also note that optional continuation clauses always begin with a
+keyword that cannot start a statement, thus there are no ambiguities
+(the `dangling \verb\else\' problem is solved in Python by requiring
+nested \verb\if\ statements to be indented).
+\indexii{dangling}{else}
+
+The formatting of the grammar rules in the following sections places
+each clause on a separate line for clarity.
+
+\section{The {\tt if} statement}
+\stindex{if}
+
+The \verb\if\ statement is used for conditional execution:
+
+\begin{verbatim}
+if_stmt:        "if" condition ":" suite
+               ("elif" condition ":" suite)*
+               ["else" ":" suite]
+\end{verbatim}
+
+It selects exactly one of the suites by evaluating the conditions 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 \verb\if\ statement is executed or evaluated).  If
+all conditions are false, the suite of the \verb\else\ clause, if
+present, is executed.
+\kwindex{elif}
+\kwindex{else}
+
+\section{The {\tt while} statement}
+\stindex{while}
+\indexii{loop}{statement}
+
+The \verb\while\ statement is used for repeated execution as long as a
+condition is true:
+
+\begin{verbatim}
+while_stmt:     "while" condition ":" suite
+               ["else" ":" suite]
+\end{verbatim}
+
+This repeatedly tests the condition and, if it is true, executes the
+first suite; if the condition is false (which may be the first time it
+is tested) the suite of the \verb\else\ clause, if present, is
+executed and the loop terminates.
+\kwindex{else}
+
+A \verb\break\ statement executed in the first suite terminates the
+loop without executing the \verb\else\ clause's suite.  A
+\verb\continue\ statement executed in the first suite skips the rest
+of the suite and goes back to testing the condition.
+\stindex{break}
+\stindex{continue}
+
+\section{The {\tt for} statement}
+\stindex{for}
+\indexii{loop}{statement}
+
+The \verb\for\ statement is used to iterate over the elements of a
+sequence (string, tuple or list):
+\obindex{sequence}
+
+\begin{verbatim}
+for_stmt:       "for" target_list "in" condition_list ":" suite
+               ["else" ":" suite]
+\end{verbatim}
+
+The condition list is evaluated once; it should yield a sequence.  The
+suite is then executed once for each item in the sequence, 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 \verb\else\ clause, if
+present, is executed, and the loop terminates.
+\kwindex{in}
+\kwindex{else}
+\indexii{target}{list}
+
+A \verb\break\ statement executed in the first suite terminates the
+loop without executing the \verb\else\ clause's suite.  A
+\verb\continue\ statement executed in the first suite skips the rest
+of the suite and continues with the next item, or with the \verb\else\
+clause if there was no next item.
+\stindex{break}
+\stindex{continue}
+
+The suite may assign to the variable(s) in the target list; this does
+not affect the next item assigned to it.
+
+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 \verb\range()\ returns a sequence of
+integers suitable to emulate the effect of Pascal's \verb\for i := a
+to b do\; e.g. \verb\range(3)\ returns the list \verb\[0, 1, 2]\.
+\bifuncindex{range}
+\index{Pascal}
+
+{\bf Warning:} 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.
+\index{loop!over mutable sequence}
+\index{mutable sequence!loop over}
+
+\begin{verbatim}
+for x in a[:]:
+    if x < 0: a.remove(x)
+\end{verbatim}
+
+\section{The {\tt try} statement}
+\stindex{try}
+
+The \verb\try\ statement specifies exception handlers and/or cleanup
+code for a group of statements:
+
+\begin{verbatim}
+try_stmt:       try_exc_stmt | try_fin_stmt
+try_exc_stmt:   "try" ":" suite
+               ("except" [condition ["," target]] ":" suite)+
+try_fin_stmt:   "try" ":" suite
+               "finally" ":" suite
+\end{verbatim}
+
+There are two forms of \verb\try\ statement: \verb\try...except\ and
+\verb\try...finally\.  These forms cannot be mixed.
+
+The \verb\try...except\ form specifies one or more exception handlers
+(the \verb\except\ clauses).  When no exception occurs in the
+\verb\try\ clause, no exception handler is executed.  When an
+exception occurs in the \verb\try\ suite, a search for an exception
+handler is started.  This inspects the except clauses in turn until
+one is found that matches the exception.  A condition-less except
+clause, if present, must be last; it matches any exception.  For an
+except clause with a condition, that condition 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 either the object that identifies the exception or it is a tuple
+containing an item that is compatible with the exception.  Note that
+the object identities must match, i.e. it must be the same object, not
+just an object with the same value.
+\kwindex{except}
+
+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 a condition in the header of an except clause
+raises an exception, the original search for a handler is cancelled
+and a search starts for the new exception in the surrounding code and
+on the call stack (it is treated as if the entire \verb\try\ statement
+raised the exception).
+
+When a matching except clause is found, the exception's parameter is
+assigned to the target specified in that except clause, if present,
+and the except clause's suite is executed.  When the end of this suite
+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.)
+
+The \verb\try...finally\ form specifies a `cleanup' handler.  The
+\verb\try\ clause is executed.  When no exception occurs, the
+\verb\finally\ clause is executed.  When an exception occurs in the
+\verb\try\ clause, the exception is temporarily saved, the
+\verb\finally\ clause is executed, and then the saved exception is
+re-raised.  If the \verb\finally\ clause raises another exception or
+executes a \verb\return\, \verb\break\ or \verb\continue\ statement,
+the saved exception is lost.
+\kwindex{finally}
+
+When a \verb\return\ or \verb\break\ statement is executed in the
+\verb\try\ suite of a \verb\try...finally\ statement, the
+\verb\finally\ clause is also executed `on the way out'.  A
+\verb\continue\ statement is illegal in the \verb\try\ clause.  (The
+reason is a problem with the current implementation --- this
+restriction may be lifted in the future).
+\stindex{return}
+\stindex{break}
+\stindex{continue}
+
+\section{Function definitions} \label{function}
+\indexii{function}{definition}
+
+A function definition defines a user-defined function object (see
+section \ref{types}):
+\obindex{user-defined function}
+\obindex{function}
+
+\begin{verbatim}
+funcdef:        "def" funcname "(" [parameter_list] ")" ":" suite
+parameter_list: (parameter ",")* ("*" identifier | parameter [","])
+sublist:        parameter ("," parameter)* [","]
+parameter:      identifier | "(" sublist ")"
+funcname:       identifier
+\end{verbatim}
+
+A function definition is an executable statement.  Its execution binds
+the function name in the current local name space to a function object
+(a wrapper around the executable code for the function).  This
+function object contains a reference to the current global name space
+as the global name space to be used when the function is called.
+\indexii{function}{name}
+\indexii{name}{binding}
+
+The function definition does not execute the function body; this gets
+executed only when the function is called.
+
+Function call semantics are described in section \ref{calls}.  When a
+user-defined function is called, the arguments (a.k.a. actual
+parameters) are bound to the (formal) parameters, as follows:
+\indexii{function}{call}
+\indexiii{user-defined}{function}{call}
+\index{parameter}
+\index{argument}
+\indexii{parameter}{formal}
+\indexii{parameter}{actual}
+
+\begin{itemize}
+
+\item
+If there are no formal parameters, there must be no arguments.
+
+\item
+If the formal parameter list does not end in a star followed by an
+identifier, there must be exactly as many arguments as there are
+parameters in the formal parameter list (at the top level); the
+arguments are assigned to the formal parameters one by one.  Note that
+the presence or absence of a trailing comma at the top level in either
+the formal or the actual parameter list makes no difference.  The
+assignment to a formal parameter is performed as if the parameter
+occurs on the left hand side of an assignment statement whose right
+hand side's value is that of the argument.
+
+\item
+If the formal parameter list ends in a star followed by an identifier,
+preceded by zero or more comma-followed parameters, there must be at
+least as many arguments as there are parameters preceding the star.
+Call this number {\em N}.  The first {\em N} arguments are assigned to
+the corresponding formal parameters in the way descibed above.  A
+tuple containing the remaining arguments, if any, is then assigned to
+the identifier following the star.  This variable will always be a
+tuple: if there are no extra arguments, its value is \verb\()\, if
+there is just one extra argument, it is a singleton tuple.
+\indexii{variable length}{parameter list}
+
+\end{itemize}
+
+Note that the `variable length parameter list' feature only works at
+the top level of the parameter list; individual parameters use a model
+corresponding more closely to that of ordinary assignment.  While the
+latter model is generally preferable, because of the greater type
+safety it offers (wrong-sized tuples aren't silently mistreated),
+variable length parameter lists are a sufficiently accepted practice
+in most programming languages that a compromise has been worked out.
+(And anyway, assignment has no equivalent for empty argument lists.)
+
+\section{Class definitions} \label{class}
+\indexii{class}{definition}
+
+A class definition defines a class object (see section \ref{types}):
+\obindex{class}
+
+\begin{verbatim}
+classdef:       "class" classname [inheritance] ":" suite
+inheritance:    "(" [condition_list] ")"
+classname:      identifier
+\end{verbatim}
+
+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.  The class's suite is then executed
+in a new execution frame (see section \ref{execframes}), using a newly
+created local name space and the original global name space.
+(Usually, the suite contains only function definitions.)  When the
+class's suite finishes execution, its execution frame is discarded but
+its local name space is saved.  A class object is then created using
+the inheritance list for the base classes and the saved local name
+space for the attribute dictionary.  The class name is bound to this
+class object in the original local name space.
+\index{inheritance}
+\indexii{class}{name}
+\indexii{name}{binding}
+\indexii{execution}{frame}
diff --git a/Doc/ref/ref8.tex b/Doc/ref/ref8.tex
new file mode 100644
index 0000000..59ef58c
--- /dev/null
+++ b/Doc/ref/ref8.tex
@@ -0,0 +1,108 @@
+\chapter{Top-level components}
+
+The Python interpreter can get its input from a number of sources:
+from a script passed to it as standard input or as program argument,
+typed in interactively, from a module source file, etc.  This chapter
+gives the syntax used in these cases.
+\index{interpreter}
+
+\section{Complete Python programs}
+\index{program}
+
+While a language specification need not prescribe how the language
+interpreter is invoked, it is useful to have a notion of a complete
+Python program.  A complete Python program is executed in a minimally
+initialized environment: all built-in and standard modules are
+available, but none have been initialized, except for \verb\sys\
+(various system services), \verb\builtin\ (built-in functions,
+exceptions and \verb\None\) and \verb\__main__\.  The latter is used
+to provide the local and global name space for execution of the
+complete program.
+\bimodindex{sys}
+\bimodindex{__main__}
+\bimodindex{builtin}
+
+The syntax for a complete Python program is that for file input,
+described in the next section.
+
+The interpreter may also be invoked in interactive mode; in this case,
+it does not read and execute a complete program but reads and executes
+one statement (possibly compound) at a time.  The initial environment
+is identical to that of a complete program; each statement is executed
+in the name space of \verb\__main__\.
+\index{interactive mode}
+
+Under {\UNIX}, a complete program can be passed to the interpreter in
+three forms: with the {\bf -c} {\it string} command line option, as a
+file passed as the first command line argument, or as standard input.
+If the file or standard input is a tty device, the interpreter enters
+interactive mode; otherwise, it executes the file as a complete
+program.
+\index{UNIX}
+\index{command line}
+\index{standard input}
+
+\section{File input}
+
+All input read from non-interactive files has the same form:
+
+\begin{verbatim}
+file_input:     (NEWLINE | statement)*
+\end{verbatim}
+
+This syntax is used in the following situations:
+
+\begin{itemize}
+
+\item when parsing a complete Python program (from a file or from a string);
+
+\item when parsing a module;
+
+\item when parsing a string passed to \verb\exec()\;
+\bifuncindex{exec}
+
+\item when parsing a file passed to \verb\execfile()\;
+\bifuncindex{execfile}
+
+\end{itemize}
+
+\section{Interactive input}
+
+Input in interactive mode is parsed using the following grammar:
+
+\begin{verbatim}
+interactive_input: [stmt_list] NEWLINE | compound_stmt NEWLINE
+\end{verbatim}
+
+Note that a (top-level) compound statement must be followed by a blank
+line in interactive mode; this is needed to help the parser detect the
+end of the input.
+
+\section{Expression input}
+\index{input}
+
+There are two forms of expression input.  Both ignore leading
+whitespace.
+ 
+The string argument to \verb\eval()\ must have the following form:
+\bifuncindex{eval}
+
+\begin{verbatim}
+eval_input:     condition_list NEWLINE*
+\end{verbatim}
+
+The input line read by \verb\input()\ must have the following form:
+\bifuncindex{input}
+
+\begin{verbatim}
+input_input:    condition_list NEWLINE
+\end{verbatim}
+
+Note: to read `raw' input line without interpretation, you can use the
+built-in function \verb\raw_input()\  or the \verb\readline()\ method
+of file objects.
+\obindex{file}
+\index{input!raw}
+\index{raw input}
+\bifuncindex{raw_index}
+\ttindex{readline}