SF bug #1168135: Python 2.5a0 Tutorial errors and observations

(Contributed by Michael R Bax.)

Doc/tut/tut.tex

@@ -100,7 +100,7 @@ types Python is applicable to a much larger problem domain than
 \emph{Awk} or even \emph{Perl}, yet many things are at least as easy
 in Python as in those languages.
 
-Python allows you to split up your program in modules that can be
+Python allows you to split your program in modules that can be
 reused in other Python programs.  It comes with a large collection of
 standard modules that you can use as the basis of your programs --- or
 as examples to start learning to program in Python.  Some of these
@@ -114,7 +114,7 @@ easy to experiment with features of the language, to write throw-away
 programs, or to test functions during bottom-up program development.
 It is also a handy desk calculator.
 
-Python allows writing very compact and readable programs.  Programs
+Python enables programs to written compactly and readably.  Programs
 written in Python are typically much shorter than equivalent C or
 \Cpp{} programs, for several reasons:
 \begin{itemize}
@@ -145,7 +145,7 @@ it is encouraged!
 
 Now that you are all excited about Python, you'll want to examine it
 in some more detail.  Since the best way to learn a language is
-using it, you are invited to do so with this tutorial.
+to use it, you are invited to do so with this tutorial.
 
 In the next chapter, the mechanics of using the interpreter are
 explained.  This is rather mundane information, but essential for
@@ -293,7 +293,7 @@ the stack trace.  (Exceptions handled by an \keyword{except} clause in a
 unconditionally fatal and cause an exit with a nonzero exit; this
 applies to internal inconsistencies and some cases of running out of
 memory.  All error messages are written to the standard error stream;
-normal output from the executed commands is written to standard
+normal output from executed commands is written to standard
 output.
 
 Typing the interrupt character (usually Control-C or DEL) to the
@@ -1227,7 +1227,7 @@ containing arithmetic progressions:
 \end{verbatim}
 
 The given end point is never part of the generated list;
-\code{range(10)} generates a list of 10 values, exactly the legal
+\code{range(10)} generates a list of 10 values, the legal
 indices for items of a sequence of length 10.  It is possible to let
 the range start at another number, or to specify a different increment
 (even negative; sometimes this is called the `step'):
@@ -1426,7 +1426,7 @@ define different methods.  Methods of different types may have the
 same name without causing ambiguity.  (It is possible to define your
 own object types and methods, using \emph{classes}, as discussed later
 in this tutorial.)
-The method \method{append()} shown in the example, is defined for
+The method \method{append()} shown in the example is defined for
 list objects; it adds a new element at the end of the list.  In this
 example it is equivalent to \samp{result = result + [b]}, but more
 efficient.
@@ -1521,7 +1521,7 @@ instance, the following function:
 \begin{verbatim}
 def parrot(voltage, state='a stiff', action='voom', type='Norwegian Blue'):
     print "-- This parrot wouldn't", action,
-    print "if you put", voltage, "Volts through it."
+    print "if you put", voltage, "volts through it."
     print "-- Lovely plumage, the", type
     print "-- It's", state, "!"
 \end{verbatim}
@@ -1646,7 +1646,7 @@ are not available separately, write the function call with the
 \subsection{Lambda Forms \label{lambda}}
 
 By popular demand, a few features commonly found in functional
-programming languages and Lisp have been added to Python.  With the
+programming languages like Lisp have been added to Python.  With the
 \keyword{lambda} keyword, small anonymous functions can be created.
 Here's a function that returns the sum of its two arguments:
 \samp{lambda a, b: a+b}.  Lambda forms can be used wherever function
@@ -1753,8 +1753,8 @@ It is an error if there is no such item.
 
 \begin{methoddesc}[list]{pop}{\optional{i}}
 Remove the item at the given position in the list, and return it.  If
-no index is specified, \code{a.pop()} returns the last item in the
-list.  The item is also removed from the list.  (The square brackets
+no index is specified, \code{a.pop()} removes and returns the last item
+in the list.  The item is also removed from the list.  (The square brackets
 around the \var{i} in the method signature denote that the parameter
 is optional, not that you should type square brackets at that
 position.  You will see this notation frequently in the
@@ -1857,10 +1857,12 @@ use \method{pop()} with \code{0} as the index.  For example:
 There are three built-in functions that are very useful when used with
 lists: \function{filter()}, \function{map()}, and \function{reduce()}.
 
-\samp{filter(\var{function}, \var{sequence})} returns a sequence (of
-the same type, if possible) consisting of those items from the
-sequence for which \code{\var{function}(\var{item})} is true.  For
-example, to compute some primes:
+\samp{filter(\var{function}, \var{sequence})} returns a sequence
+consisting of those items from the
+sequence for which \code{\var{function}(\var{item})} is true.
+If \var{sequence} is a \class{string} or \class{tuple}, the result will
+be of the same type; otherwise, it is always a \class{list}.
+For example, to compute some primes:
 
 \begin{verbatim}
 >>> def f(x): return x % 2 != 0 and x % 3 != 0
@@ -1974,7 +1976,7 @@ SyntaxError: invalid syntax
 \end{verbatim}
 
 List comprehensions are much more flexible than \function{map()} and can be
-applied to functions with more than one argument and to nested functions:
+applied to complex expressions and nested functions:
 
 \begin{verbatim}
 >>> [str(round(355/113.0, i)) for i in range(1,6)]
@@ -1985,7 +1987,9 @@ applied to functions with more than one argument and to nested functions:
 \section{The \keyword{del} statement \label{del}}
 
 There is a way to remove an item from a list given its index instead
-of its value: the \keyword{del} statement.  This can also be used to
+of its value: the \keyword{del} statement.  Unlike the \method{pop()})
+method which returns a value, the \keyword{del} keyword is a statement 
+and can also be used to
 remove slices from a list (which we did earlier by assignment of an
 empty list to the slice).  For example:
 
@@ -2074,7 +2078,7 @@ is also possible:
 \end{verbatim}
 
 This is called, appropriately enough, \emph{sequence unpacking}.
-Sequence unpacking requires that the list of variables on the left
+Sequence unpacking requires the list of variables on the left to
 have the same number of elements as the length of the sequence.  Note
 that multiple assignment is really just a combination of tuple packing
 and sequence unpacking!
@@ -2097,12 +2101,12 @@ Here is a brief demonstration:
 
 \begin{verbatim}
 >>> basket = ['apple', 'orange', 'apple', 'pear', 'orange', 'banana']
->>> fruits = set(basket)               # create a set without duplicates
->>> fruits
+>>> fruit = set(basket)               # create a set without duplicates
+>>> fruit
 set(['orange', 'pear', 'apple', 'banana'])
->>> 'orange' in fruits                 # fast membership testing
+>>> 'orange' in fruit                 # fast membership testing
 True
->>> 'crabgrass' in fruits
+>>> 'crabgrass' in fruit
 False
 
 >>> # Demonstrate set operations on unique letters from two words
@@ -2133,8 +2137,8 @@ which can be any immutable type; strings and numbers can always be
 keys.  Tuples can be used as keys if they contain only strings,
 numbers, or tuples; if a tuple contains any mutable object either
 directly or indirectly, it cannot be used as a key.  You can't use
-lists as keys, since lists can be modified in place using their
-\method{append()} and \method{extend()} methods, as well as slice and
+lists as keys, since lists can be modified in place using methods like
+\method{append()} and \method{extend()} or modified with slice and
 indexed assignments.
 
 It is best to think of a dictionary as an unordered set of
@@ -2291,7 +2295,7 @@ Comparisons can be chained.  For example, \code{a < b == c} tests
 whether \code{a} is less than \code{b} and moreover \code{b} equals
 \code{c}.
 
-Comparisons may be combined by the Boolean operators \code{and} and
+Comparisons may be combined using the Boolean operators \code{and} and
 \code{or}, and the outcome of a comparison (or of any other Boolean
 expression) may be negated with \code{not}.  These have lower
 priorities than comparison operators; between them, \code{not} has
@@ -2304,9 +2308,9 @@ The Boolean operators \code{and} and \code{or} are so-called
 left to right, and evaluation stops as soon as the outcome is
 determined.  For example, if \code{A} and \code{C} are true but
 \code{B} is false, \code{A and B and C} does not evaluate the
-expression \code{C}.  In general, the return value of a short-circuit
-operator, when used as a general value and not as a Boolean, is the
-last evaluated argument.
+expression \code{C}.  When used as a general value and not as a
+Boolean, the return value of a short-circuit operator is the last
+evaluated argument.
 
 It is possible to assign the result of a comparison or other Boolean
 expression to a variable.  For example,
@@ -2337,8 +2341,8 @@ items of two sequences compare equal, the sequences are considered
 equal.  If one sequence is an initial sub-sequence of the other, the
 shorter sequence is the smaller (lesser) one.  Lexicographical
 ordering for strings uses the \ASCII{} ordering for individual
-characters.  Some examples of comparisons between sequences with the
-same types:
+characters.  Some examples of comparisons between sequences of the
+same type:
 
 \begin{verbatim}
 (1, 2, 3)              < (1, 2, 4)
@@ -2619,7 +2623,7 @@ C>
 These two variables are only defined if the interpreter is in
 interactive mode.
 
-The variable \code{sys.path} is a list of strings that determine the
+The variable \code{sys.path} is a list of strings that determines the
 interpreter's search path for modules. It is initialized to a default
 path taken from the environment variable \envvar{PYTHONPATH}, or from
 a built-in default if \envvar{PYTHONPATH} is not set.  You can modify
@@ -2946,8 +2950,9 @@ resulting from this formatting operation.
 One question remains, of course: how do you convert values to strings?
 Luckily, Python has ways to convert any value to a string: pass it to
 the \function{repr()}  or \function{str()} functions.  Reverse quotes
-(\code{``}) are equivalent to \function{repr()}, but their use is
-discouraged.
+(\code{``}) are equivalent to \function{repr()}, but they are no
+longer used in modern Python code and will likely not be in future
+versions of the language.
 
 The \function{str()} function is meant to return representations of
 values which are fairly human-readable, while \function{repr()} is
@@ -3035,7 +3040,7 @@ the input string is too long, they don't truncate it, but return it
 unchanged; this will mess up your column lay-out but that's usually
 better than the alternative, which would be lying about a value.  (If
 you really want truncation you can always add a slice operation, as in
-\samp{x.ljust(~n)[:n]}.)
+\samp{x.ljust(n)[:n]}.)
 
 There is another method, \method{zfill()}, which pads a
 numeric string on the left with zeros.  It understands about plus and
@@ -3123,8 +3128,8 @@ mode opens the file in binary mode, so there are also modes like
 distinction between text and binary files; the end-of-line characters
 in text files are automatically altered slightly when data is read or
 written.  This behind-the-scenes modification to file data is fine for
-\ASCII{} text files, but it'll corrupt binary data like that in JPEGs or
-\file{.EXE} files.  Be very careful to use binary mode when reading and
+\ASCII{} text files, but it'll corrupt binary data like that in \file{JPEG} or
+\file{EXE} files.  Be very careful to use binary mode when reading and
 writing such files.
 
 \subsection{Methods of File Objects \label{fileMethods}}
@@ -3367,8 +3372,8 @@ The rest of the line provides detail based on the type of exception
 and what caused it.
 
 The preceding part of the error message shows the context where the
-exception happened, in the form of a stack backtrace.
-In general it contains a stack backtrace listing source lines; however,
+exception happened, in the form of a stack traceback.
+In general it contains a stack traceback listing source lines; however,
 it will not display lines read from standard input.
 
 The \citetitle[../lib/module-exceptions.html]{Python Library
@@ -3390,7 +3395,7 @@ raising the \exception{KeyboardInterrupt} exception.
 ...         x = int(raw_input("Please enter a number: "))
 ...         break
 ...     except ValueError:
-...         print "Oops! That was no valid number.  Try again..."
+...         print "Oops!  That was no valid number.  Try again..."
 ...     
 \end{verbatim}
 
@@ -3424,7 +3429,7 @@ specify handlers for different exceptions.  At most one handler will
 be executed.  Handlers only handle exceptions that occur in the
 corresponding try clause, not in other handlers of the same
 \keyword{try} statement.  An except clause may name multiple exceptions
-as a parenthesized list, for example:
+as a parenthesized tuple, for example:
 
 \begin{verbatim}
 ... except (RuntimeError, TypeError, NameError):
@@ -3479,7 +3484,7 @@ When an exception occurs, it may have an associated value, also known as
 the exception's \emph{argument}.
 The presence and type of the argument depend on the exception type.
 
-The except clause may specify a variable after the exception name (or list).
+The except clause may specify a variable after the exception name (or tuple).
 The variable is bound to an exception instance with the arguments stored
 in \code{instance.args}.  For convenience, the exception instance
 defines \method{__getitem__} and \method{__str__} so the arguments can
@@ -3667,11 +3672,11 @@ left via a \keyword{break} or \keyword{return} statement.
 
 The code in the finally clause is useful for releasing external
 resources (such as files or network connections), regardless of
-whether or not the use of the resource was successful.
+whether the use of the resource was successful.
 
 A \keyword{try} statement must either have one or more except clauses
 or one finally clause, but not both (because it would be unclear which
-clause should be executed).
+clause should be executed first).
 
 
 \chapter{Classes \label{classes}}
@@ -3684,7 +3689,7 @@ rely on the politeness of the user not to ``break into the
 definition.''  The most important features of classes are retained
 with full power, however: the class inheritance mechanism allows
 multiple base classes, a derived class can override any methods of its
-base class or classes, a method can call the method of a base class with the
+base class or classes, and a method can call the method of a base class with the
 same name.  Objects can contain an arbitrary amount of private data.
 
 In \Cpp{} terminology, all class members (including the data members) are
@@ -3806,10 +3811,13 @@ names.
 
 If a name is declared global, then all references and assignments go
 directly to the middle scope containing the module's global names.
-Otherwise, all variables found outside of the innermost scope are read-only.
+Otherwise, all variables found outside of the innermost scope are read-only
+(an attempt to write to such a variable will simply create a \emph{new}
+local variable in the innermost scope, leaving the identically named
+outer variable unchanged).
 
 Usually, the local scope references the local names of the (textually)
-current function.  Outside of functions, the local scope references
+current function.  Outside functions, the local scope references
 the same namespace as the global scope: the module's namespace.
 Class definitions place yet another namespace in the local scope.
 
@@ -3873,7 +3881,7 @@ When a class definition is left normally (via the end), a \emph{class
 object} is created.  This is basically a wrapper around the contents
 of the namespace created by the class definition; we'll learn more
 about class objects in the next section.  The original local scope
-(the one in effect just before the class definitions were entered) is
+(the one in effect just before the class definition was entered) is
 reinstated, and the class object is bound here to the class name given
 in the class definition header (\class{ClassName} in the example).
 
@@ -5309,7 +5317,7 @@ the Korn shell and the GNU Bash shell.  This is implemented using the
 editing.  This library has its own documentation which I won't
 duplicate here; however, the basics are easily explained.  The
 interactive editing and history described here are optionally
-available in the \UNIX{} and CygWin versions of the interpreter.
+available in the \UNIX{} and Cygwin versions of the interpreter.
 
 This chapter does \emph{not} document the editing facilities of Mark
 Hammond's PythonWin package or the Tk-based environment, IDLE,
@@ -5541,7 +5549,7 @@ the binary approximation stored for 0.1, it would have to display
 0.1000000000000000055511151231257827021181583404541015625
 \end{verbatim}
 
-instead!  The Python prompt (implicitly) uses the builtin
+instead!  The Python prompt uses the builtin
 \function{repr()} function to obtain a string version of everything it
 displays.  For floats, \code{repr(\var{float})} rounds the true
 decimal value to 17 significant digits, giving
@@ -5556,7 +5564,7 @@ turns out that's enough (on most machines) so that
 \var{x}, but rounding to 16 digits is not enough to make that true.
 
 Note that this is in the very nature of binary floating-point: this is
-not a bug in Python, it is not a bug in your code either.  You'll
+not a bug in Python, and it is not a bug in your code either.  You'll
 see the same kind of thing in all languages that support your
 hardware's floating-point arithmetic (although some languages may
 not \emph{display} the difference by default, or in all output modes).
@@ -5595,8 +5603,8 @@ was already the best possible binary approximation to 1/10, so trying
 to round it again can't make it better:  it was already as good as it
 gets.
 
-Another consequence is that since 0.1 is not exactly 1/10, adding 0.1
-to itself 10 times may not yield exactly 1.0, either:
+Another consequence is that since 0.1 is not exactly 1/10,
+summing ten values of 0.1 may not yield exactly 1.0, either:
 
 \begin{verbatim}
 >>> sum = 0.0
@@ -5637,7 +5645,7 @@ This section explains the ``0.1'' example in detail, and shows how
 you can perform an exact analysis of cases like this yourself.  Basic
 familiarity with binary floating-point representation is assumed.
 
-\dfn{Representation error} refers to that some (most, actually)
+\dfn{Representation error} refers to fact that some (most, actually)
 decimal fractions cannot be represented exactly as binary (base 2)
 fractions.  This is the chief reason why Python (or Perl, C, \Cpp,
 Java, Fortran, and many others) often won't display the exact decimal
@@ -5672,9 +5680,9 @@ and recalling that \var{J} has exactly 53 bits (is \code{>= 2**52} but
 \begin{verbatim}
 >>> 2**52
 4503599627370496L
->>> 2L**53
+>>> 2**53
 9007199254740992L
->>> 2L**56/10
+>>> 2**56/10
 7205759403792793L
 \end{verbatim}
 
@@ -5683,7 +5691,7 @@ exactly 53 bits.  The best possible value for \var{J} is then that
 quotient rounded:
 
 \begin{verbatim}
->>> q, r = divmod(2L**56, 10)
+>>> q, r = divmod(2**56, 10)
 >>> r
 6L
 \end{verbatim}
@@ -5711,7 +5719,7 @@ So the computer never ``sees'' 1/10:  what it sees is the exact
 fraction given above, the best 754 double approximation it can get:
 
 \begin{verbatim}
->>> .1 * 2L**56
+>>> .1 * 2**56
 7205759403792794.0
 \end{verbatim}
 
@@ -5719,7 +5727,7 @@ If we multiply that fraction by 10**30, we can see the (truncated)
 value of its 30 most significant decimal digits:
 
 \begin{verbatim}
->>> 7205759403792794L * 10L**30 / 2L**56
+>>> 7205759403792794 * 10**30 / 2**56
 100000000000000005551115123125L
 \end{verbatim}