Merge alpha100 branch back to main trunk
diff --git a/Doc/ref/ref5.tex b/Doc/ref/ref5.tex
index 55f523f..3e60931 100644
--- a/Doc/ref/ref5.tex
+++ b/Doc/ref/ref5.tex
@@ -12,14 +12,14 @@
parentheses. The only places where expressions are used in the syntax
instead of conditions is in expression statements and on the
right-hand side of assignment statements; this catches some nasty bugs
-like accidentally writing \verb\x == 1\ instead of \verb\x = 1\.
+like accidentally writing \verb@x == 1@ instead of \verb@x = 1@.
\indexii{assignment}{statement}
The comma plays several roles in Python's syntax. It is usually an
operator with a lower precedence than all others, but occasionally
serves other purposes as well; e.g. it separates function arguments,
is used in list and dictionary constructors, and has special semantics
-in \verb\print\ statements.
+in \verb@print@ statements.
\index{comma}
When (one alternative of) a syntax rule has the form
@@ -28,8 +28,8 @@
name: othername
\end{verbatim}
-and no semantics are given, the semantics of this form of \verb\name\
-are the same as for \verb\othername\.
+and no semantics are given, the semantics of this form of \verb@name@
+are the same as for \verb@othername@.
\index{syntax}
\section{Arithmetic conversions}
@@ -38,7 +38,7 @@
When a description of an arithmetic operator below uses the phrase
``the numeric arguments are converted to a common type'',
this both means that if either argument is not a number, a
-\verb\TypeError\ exception is raised, and that otherwise
+\verb@TypeError@ exception is raised, and that otherwise
the following conversions are applied:
\exindex{TypeError}
\indexii{floating point}{number}
@@ -71,11 +71,13 @@
\index{identifier}
An identifier occurring as an atom is a reference to a local, global
-or built-in name binding. If a name can be assigned to anywhere in a
-code block, and is not mentioned in a \verb\global\ statement in that
-code block, it refers to a local name throughout that code block.
-Otherwise, it refers to a global name if one exists, else to a
-built-in name.
+or built-in name binding. If a name is assigned to anywhere in a code
+block (even in unreachable code), and is not mentioned in a
+\verb@global@ statement in that code block, then it refers to a local
+name throughout that code block. When it is not assigned to anywhere
+in the block, or when it is assigned to but also explicitly listed in
+a \verb@global@ statement, it refers to a global name if one exists,
+else to a built-in name (and this binding may dynamically change).
\indexii{name}{binding}
\index{code block}
\stindex{global}
@@ -84,7 +86,7 @@
When the name is bound to an object, evaluation of the atom yields
that object. When a name is not bound, an attempt to evaluate it
-raises a \verb\NameError\ exception.
+raises a \verb@NameError@ exception.
\exindex{NameError}
\subsection{Literals}
@@ -197,10 +199,10 @@
converts the resulting object into a string according to rules
specific to its type.
-If the object is a string, a number, \verb\None\, or a tuple, list or
+If the object is a string, a number, \verb@None@, or a tuple, list or
dictionary containing only objects whose type is one of these, the
resulting string is a valid Python expression which can be passed to
-the built-in function \verb\eval()\ to yield an expression with the
+the built-in function \verb@eval()@ to yield an expression with the
same value (or an approximation, if floating point numbers are
involved).
@@ -234,7 +236,7 @@
The primary must evaluate to an object of a type that supports
attribute references, e.g. a module or a list. This object is then
asked to produce the attribute whose name is the identifier. If this
-attribute is not available, the exception \verb\AttributeError\ is
+attribute is not available, the exception \verb@AttributeError@ is
raised. Otherwise, the type and value of the object produced is
determined by the object. Multiple evaluations of the same attribute
reference may yield different objects.
@@ -266,7 +268,7 @@
If it is a sequence, the condition must evaluate to a plain integer.
If this value is negative, the length of the sequence is added to it
-(so that, e.g. \verb\x[-1]\ selects the last item of \verb\x\.)
+(so that, e.g. \verb@x[-1]@ selects the last item of \verb@x@.)
The resulting value must be a nonnegative integer smaller than the
number of items in the sequence, and the subscription selects the item
whose index is that value (counting from zero).
@@ -318,7 +320,7 @@
class, the argument list must be empty; otherwise, the arguments are
evaluated.
-A call always returns some value, possibly \verb\None\, unless it
+A call always returns some value, possibly \verb@None@, unless it
raises an exception. How this value is computed depends on the type
of the callable object. If it is:
@@ -328,7 +330,7 @@
executed, passing it the argument list. The first thing the code
block will do is bind the formal parameters to the arguments; this is
described in section \ref{function}. When the code block executes a
-\verb\return\ statement, this specifies the return value of the
+\verb@return@ statement, this specifies the return value of the
function call.
\indexii{function}{call}
\indexiii{user-defined}{function}{call}
@@ -371,22 +373,22 @@
u_expr: primary | "-" u_expr | "+" u_expr | "~" u_expr
\end{verbatim}
-The unary \verb\"-"\ (minus) operator yields the negation of its
+The unary \verb@"-"@ (minus) operator yields the negation of its
numeric argument.
\index{negation}
\index{minus}
-The unary \verb\"+"\ (plus) operator yields its numeric argument
+The unary \verb@"+"@ (plus) operator yields its numeric argument
unchanged.
\index{plus}
-The unary \verb\"~"\ (invert) operator yields the bit-wise inversion
+The unary \verb@"~"@ (invert) operator yields the bit-wise inversion
of its plain or long integer argument. The bit-wise inversion of
-\verb\x\ is defined as \verb\-(x+1)\.
+\verb@x@ is defined as \verb@-(x+1)@.
\index{inversion}
In all three cases, if the argument does not have the proper type,
-a \verb\TypeError\ exception is raised.
+a \verb@TypeError@ exception is raised.
\exindex{TypeError}
\section{Binary arithmetic operations}
@@ -404,7 +406,7 @@
a_expr: m_expr | aexpr "+" m_expr | aexpr "-" m_expr
\end{verbatim}
-The \verb\"*"\ (multiplication) operator yields the product of its
+The \verb@"*"@ (multiplication) operator yields the product of its
arguments. The arguments must either both be numbers, or one argument
must be a plain integer and the other must be a sequence. In the
former case, the numbers are converted to a common type and then
@@ -412,40 +414,40 @@
performed; a negative repetition factor yields an empty sequence.
\index{multiplication}
-The \verb\"/"\ (division) operator yields the quotient of its
+The \verb@"/"@ (division) operator yields the quotient of its
arguments. The numeric arguments are first converted to a common
type. Plain or long integer division yields an integer of the same
type; the result is that of mathematical division with the `floor'
function applied to the result. Division by zero raises the
-\verb\ZeroDivisionError\ exception.
+\verb@ZeroDivisionError@ exception.
\exindex{ZeroDivisionError}
\index{division}
-The \verb\"%"\ (modulo) operator yields the remainder from the
+The \verb@"%"@ (modulo) operator yields the remainder from the
division of the first argument by the second. The numeric arguments
are first converted to a common type. A zero right argument raises
-the \verb\ZeroDivisionError\ exception. The arguments may be floating
-point numbers, e.g. \verb\3.14 % 0.7\ equals \verb\0.34\. The modulo
+the \verb@ZeroDivisionError@ exception. The arguments may be floating
+point numbers, e.g. \verb@3.14 % 0.7@ equals \verb@0.34@. The modulo
operator always yields a result with the same sign as its second
operand (or zero); the absolute value of the result is strictly
smaller than the second operand.
\index{modulo}
The integer division and modulo operators are connected by the
-following identity: \verb\x == (x/y)*y + (x%y)\. Integer division and
-modulo are also connected with the built-in function \verb\divmod()\:
-\verb\divmod(x, y) == (x/y, x%y)\. These identities don't hold for
+following identity: \verb@x == (x/y)*y + (x%y)@. Integer division and
+modulo are also connected with the built-in function \verb@divmod()@:
+\verb@divmod(x, y) == (x/y, x%y)@. These identities don't hold for
floating point numbers; there a similar identity holds where
-\verb\x/y\ is replaced by \verb\floor(x/y)\).
+\verb@x/y@ is replaced by \verb@floor(x/y)@).
-The \verb\"+"\ (addition) operator yields the sum of its arguments.
+The \verb@"+"@ (addition) operator yields the sum of its arguments.
The arguments must either both be numbers, or both sequences of the
same type. In the former case, the numbers are converted to a common
type and then added together. In the latter case, the sequences are
concatenated.
\index{addition}
-The \verb\"-"\ (subtraction) operator yields the difference of its
+The \verb@"-"@ (subtraction) operator yields the difference of its
arguments. The numeric arguments are first converted to a common
type.
\index{subtraction}
@@ -470,7 +472,7 @@
integers there is no overflow check so this drops bits and flip the
sign if the result is not less than $2^{31}$ in absolute value.
-Negative shift counts raise a \verb\ValueError\ exception.
+Negative shift counts raise a \verb@ValueError@ exception.
\exindex{ValueError}
\section{Binary bit-wise operations}
@@ -484,18 +486,18 @@
or_expr: xor_expr | or_expr "|" xor_expr
\end{verbatim}
-The \verb\"&"\ operator yields the bitwise AND of its arguments, which
+The \verb@"&"@ operator yields the bitwise AND of its arguments, which
must be plain or long integers. The arguments are converted to a
common type.
\indexii{bit-wise}{and}
-The \verb\"^"\ operator yields the bitwise XOR (exclusive OR) of its
+The \verb@"^"@ operator yields the bitwise XOR (exclusive OR) of its
arguments, which must be plain or long integers. The arguments are
converted to a common type.
\indexii{bit-wise}{xor}
\indexii{exclusive}{or}
-The \verb\"|"\ operator yields the bitwise (inclusive) OR of its
+The \verb@"|"@ operator yields the bitwise (inclusive) OR of its
arguments, which must be plain or long integers. The arguments are
converted to a common type.
\indexii{bit-wise}{or}
@@ -507,7 +509,7 @@
Contrary to C, all comparison operations in Python have the same
priority, which is lower than that of any arithmetic, shifting or
bitwise operation. Also contrary to C, expressions like
-\verb\a < b < c\ have the interpretation that is conventional in
+\verb@a < b < c@ have the interpretation that is conventional in
mathematics:
\index{C}
@@ -519,23 +521,23 @@
Comparisons yield integer values: 1 for true, 0 for false.
Comparisons can be chained arbitrarily, e.g. $x < y <= z$ is
-equivalent to $x < y$ \verb\and\ $y <= z$, except that $y$ is
+equivalent to $x < y$ \verb@and@ $y <= z$, except that $y$ is
evaluated only once (but in both cases $z$ is not evaluated at all
when $x < y$ is found to be false).
\indexii{chaining}{comparisons}
\catcode`\_=8
Formally, $e_0 op_1 e_1 op_2 e_2 ...e_{n-1} op_n e_n$ is equivalent to
-$e_0 op_1 e_1$ \verb\and\ $e_1 op_2 e_2$ \verb\and\ ... \verb\and\
+$e_0 op_1 e_1$ \verb@and@ $e_1 op_2 e_2$ \verb@and@ ... \verb@and@
$e_{n-1} op_n e_n$, except that each expression is evaluated at most once.
Note that $e_0 op_1 e_1 op_2 e_2$ does not imply any kind of comparison
between $e_0$ and $e_2$, e.g. $x < y > z$ is perfectly legal.
\catcode`\_=12
-The forms \verb\<>\ and \verb\!=\ are equivalent; for consistency with
-C, \verb\!=\ is preferred; where \verb\!=\ is mentioned below
-\verb\<>\ is also implied.
+The forms \verb@<>@ and \verb@!=@ are equivalent; for consistency with
+C, \verb@!=@ is preferred; where \verb@!=@ is mentioned below
+\verb@<>@ is also implied.
The operators {\tt "<", ">", "==", ">=", "<="}, and {\tt "!="} compare
the values of two objects. The objects needn't have the same type.
@@ -544,8 +546,8 @@
ordered consistently but arbitrarily.
(This unusual definition of comparison is done to simplify the
-definition of operations like sorting and the \verb\in\ and \verb\not
-in\ operators.)
+definition of operations like sorting and the \verb@in@ and
+\verb@not in@ operators.)
Comparison of objects of the same type depends on the type:
@@ -556,7 +558,7 @@
\item
Strings are compared lexicographically using the numeric equivalents
-(the result of the built-in function \verb\ord\) of their characters.
+(the result of the built-in function \verb@ord@) of their characters.
\item
Tuples and lists are compared lexicographically using comparison of
@@ -579,11 +581,11 @@
\end{itemize}
-The operators \verb\in\ and \verb\not in\ test for sequence
-membership: if $y$ is a sequence, $x ~\verb\in\~ y$ is true if and
+The operators \verb@in@ and \verb@not in@ test for sequence
+membership: if $y$ is a sequence, $x ~\verb@in@~ y$ is true if and
only if there exists an index $i$ such that $x = y[i]$.
-$x ~\verb\not in\~ y$ yields the inverse truth value. The exception
-\verb\TypeError\ is raised when $y$ is not a sequence, or when $y$ is
+$x ~\verb@not in@~ y$ yields the inverse truth value. The exception
+\verb@TypeError@ is raised when $y$ is not a sequence, or when $y$ is
a string and $x$ is not a string of length one.%
\footnote{The latter restriction is sometimes a nuisance.}
\opindex{in}
@@ -591,9 +593,9 @@
\indexii{membership}{test}
\obindex{sequence}
-The operators \verb\is\ and \verb\is not\ test for object identity:
-$x ~\verb\is\~ y$ is true if and only if $x$ and $y$ are the same
-object. $x ~\verb\is not\~ y$ yields the inverse truth value.
+The operators \verb@is@ and \verb@is not@ test for object identity:
+$x ~\verb@is@~ y$ is true if and only if $x$ and $y$ are the same
+object. $x ~\verb@is not@~ y$ yields the inverse truth value.
\opindex{is}
\opindex{is not}
\indexii{identity}{test}
@@ -613,38 +615,39 @@
In the context of Boolean operations, and also when conditions are
used by control flow statements, the following values are interpreted
-as false: \verb\None\, numeric zero of all types, empty sequences
+as false: \verb@None@, numeric zero of all types, empty sequences
(strings, tuples and lists), and empty mappings (dictionaries). All
other values are interpreted as true.
-The operator \verb\not\ yields 1 if its argument is false, 0 otherwise.
+The operator \verb@not@ yields 1 if its argument is false, 0 otherwise.
\opindex{not}
-The condition $x ~\verb\and\~ y$ first evaluates $x$; if $x$ is false,
+The condition $x ~\verb@and@~ y$ first evaluates $x$; if $x$ is false,
its value is returned; otherwise, $y$ is evaluated and the resulting
value is returned.
\opindex{and}
-The condition $x ~\verb\or\~ y$ first evaluates $x$; if $x$ is true,
+The condition $x ~\verb@or@~ y$ first evaluates $x$; if $x$ is true,
its value is returned; otherwise, $y$ is evaluated and the resulting
value is returned.
\opindex{or}
-(Note that \verb\and\ and \verb\or\ do not restrict the value and type
+(Note that \verb@and@ and \verb@or@ do not restrict the value and type
they return to 0 and 1, but rather return the last evaluated argument.
-This is sometimes useful, e.g. if \verb\s\ is a string that should be
+This is sometimes useful, e.g. if \verb@s@ is a string that should be
replaced by a default value if it is empty, the expression
-\verb\s or 'foo'\ yields the desired value. Because \verb\not\ has to
+\verb@s or 'foo'@ yields the desired value. Because \verb@not@ has to
invent a value anyway, it does not bother to return a value of the
-same type as its argument, so e.g. \verb\not 'foo'\ yields \verb\0\,
-not \verb\''\.)
+same type as its argument, so e.g. \verb@not 'foo'@ yields \verb@0@,
+not \verb@''@.)
Lambda forms (lambda expressions) have the same syntactic position as
conditions. They are a shorthand to create anonymous functions; the
-expression \verb\lambda\ {\em arguments}\verb\:\ {\em condition}
+expression {\em {\tt lambda} arguments{\tt :} condition}
yields a function object that behaves virtually identical to one
-defined with \verb\def\ {\em name}\verb\(\{\em arguments}\verb\) :
-return\ {\em condition}. See section \ref{function} for the syntax of
+defined with
+{\em {\tt def} name {\tt (}arguments{\tt ): return} condition}.
+See section \ref{function} for the syntax of
parameter lists. Note that functions created with lambda forms cannot
contain statements.
\label{lambda}
@@ -686,4 +689,4 @@
\indexii{trailing}{comma}
(To create an empty tuple, use an empty pair of parentheses:
-\verb\()\.)
+\verb@()@.)