Incorporate some suggestions by Tait Stevens.

4 files changed, 42 insertions, 27 deletions

diff --git a/Doc/tutorial/classes.rst b/Doc/tutorial/classes.rst
index bca9108..43f2c6d 100644
--- a/Doc/tutorial/classes.rst
+++ b/Doc/tutorial/classes.rst
@@ -208,7 +208,7 @@ the class's namespace when the class object was created.  So, if the class
 definition looked like this::
 
    class MyClass:
-       "A simple example class"
+       """A simple example class"""
        i = 12345
        def f(self):
            return 'hello world'
diff --git a/Doc/tutorial/controlflow.rst b/Doc/tutorial/controlflow.rst
index 4fa9858..a77618f 100644
--- a/Doc/tutorial/controlflow.rst
+++ b/Doc/tutorial/controlflow.rst
@@ -17,6 +17,7 @@ Perhaps the most well-known statement type is the :keyword:`if` statement.  For
 example::
 
    >>> x = int(raw_input("Please enter an integer: "))
+   Please enter an integer: 42
    >>> if x < 0:
    ...      x = 0
    ...      print 'Negative changed to zero'
@@ -26,7 +27,8 @@ example::
    ...      print 'Single'
    ... else:
    ...      print 'More'
-   ... 
+   ...
+   More
 
 There can be zero or more :keyword:`elif` parts, and the :keyword:`else` part is
 optional.  The keyword ':keyword:`elif`' is short for 'else if', and is useful
@@ -161,7 +163,7 @@ The :keyword:`pass` statement does nothing. It can be used when a statement is
 required syntactically but the program requires no action. For example::
 
    >>> while True:
-   ...       pass # Busy-wait for keyboard interrupt
+   ...     pass  # Busy-wait for keyboard interrupt (Ctrl+C)
    ... 
 
 
@@ -192,14 +194,14 @@ boundary::
 The keyword :keyword:`def` introduces a function *definition*.  It must be
 followed by the function name and the parenthesized list of formal parameters.
 The statements that form the body of the function start at the next line, and
-must be indented.  The first statement of the function body can optionally be a
-string literal; this string literal is the function's documentation string, or
-:dfn:`docstring`.
+must be indented.
 
+The first statement of the function body can optionally be a string literal;
+this string literal is the function's documentation string, or :dfn:`docstring`.
+(More about docstrings can be found in the section :ref:`tut-docstrings`.)
 There are tools which use docstrings to automatically produce online or printed
 documentation, or to let the user interactively browse through code; it's good
-practice to include docstrings in code that you write, so try to make a habit of
-it.
+practice to include docstrings in code that you write, so make a habit of it.
 
 The *execution* of a function introduces a new symbol table used for the local
 variables of the function.  More precisely, all variable assignments in a
@@ -228,12 +230,12 @@ mechanism::
    >>> f(100)
    1 1 2 3 5 8 13 21 34 55 89
 
-You might object that ``fib`` is not a function but a procedure.  In Python,
-like in C, procedures are just functions that don't return a value.  In fact,
-technically speaking, procedures do return a value, albeit a rather boring one.
-This value is called ``None`` (it's a built-in name).  Writing the value
-``None`` is normally suppressed by the interpreter if it would be the only value
-written.  You can see it if you really want to using :keyword:`print`::
+Coming from other languages, you might object that ``fib`` is not a function but
+a procedure since it doesn't return a value.  In fact, even functions without a
+:keyword:`return` statement do return a value, albeit a rather boring one.  This
+value is called ``None`` (it's a built-in name).  Writing the value ``None`` is
+normally suppressed by the interpreter if it would be the only value written.
+You can see it if you really want to using :keyword:`print`::
 
    >>> fib(0)
    >>> print fib(0)
@@ -259,7 +261,7 @@ This example, as usual, demonstrates some new Python features:
 
 * The :keyword:`return` statement returns with a value from a function.
   :keyword:`return` without an expression argument returns ``None``. Falling off
-  the end of a procedure also returns ``None``.
+  the end of a function also returns ``None``.
 
 * The statement ``result.append(b)`` calls a *method* of the list object
   ``result``.  A method is a function that 'belongs' to an object and is named
@@ -400,21 +402,21 @@ list.  (``*name`` must occur before ``**name``.) For example, if we define a
 function like this::
 
    def cheeseshop(kind, *arguments, **keywords):
-       print "-- Do you have any", kind, '?'
+       print "-- Do you have any", kind, "?"
        print "-- I'm sorry, we're all out of", kind
        for arg in arguments: print arg
-       print '-'*40
+       print "-" * 40
        keys = keywords.keys()
        keys.sort()
-       for kw in keys: print kw, ':', keywords[kw]
+       for kw in keys: print kw, ":", keywords[kw]
 
 It could be called like this::
 
-   cheeseshop('Limburger', "It's very runny, sir.",
+   cheeseshop("Limburger", "It's very runny, sir.",
               "It's really very, VERY runny, sir.",
-              client='John Cleese',
               shopkeeper='Michael Palin',
-              sketch='Cheese Shop Sketch')
+              client="John Cleese",
+              sketch="Cheese Shop Sketch")
 
 and of course it would print::
 
@@ -442,8 +444,8 @@ Arbitrary Argument Lists
 
 Finally, the least frequently used option is to specify that a function can be
 called with an arbitrary number of arguments.  These arguments will be wrapped
-up in a tuple.  Before the variable number of arguments, zero or more normal
-arguments may occur. ::
+up in a tuple (see :ref:`tut-tuples`).  Before the variable number of arguments,
+zero or more normal arguments may occur. ::
 
    def write_multiple_items(file, separator, *args):
        file.write(separator.join(args))
@@ -600,7 +602,8 @@ extracted for you:
 
 * Name your classes and functions consistently; the convention is to use
   ``CamelCase`` for classes and ``lower_case_with_underscores`` for functions
-  and methods.  Always use ``self`` as the name for the first method argument.
+  and methods.  Always use ``self`` as the name for the first method argument
+  (see :ref:`tut-firstclasses` for more on classes and methods).
 
 * Don't use fancy encodings if your code is meant to be used in international
   environments.  Plain ASCII works best in any case.
diff --git a/Doc/tutorial/datastructures.rst b/Doc/tutorial/datastructures.rst
index fa71870..931f506 100644
--- a/Doc/tutorial/datastructures.rst
+++ b/Doc/tutorial/datastructures.rst
@@ -345,6 +345,7 @@ of an empty list to the slice).  For example::
 Referencing the name ``a`` hereafter is an error (at least until another value
 is assigned to it).  We'll find other uses for :keyword:`del` later.
 
+.. _tut-tuples:
 
 .. _tut-tuples:
 
diff --git a/Doc/tutorial/introduction.rst b/Doc/tutorial/introduction.rst
index c138ce6..797e531 100644
--- a/Doc/tutorial/introduction.rst
+++ b/Doc/tutorial/introduction.rst
@@ -13,9 +13,11 @@ end a multi-line command.
 
 Many of the examples in this manual, even those entered at the interactive
 prompt, include comments.  Comments in Python start with the hash character,
-``#``, and extend to the end of the physical line.  A comment may appear at
-the start of a line or following whitespace or code, but not within a string
+``#``, and extend to the end of the physical line.  A comment may appear at the
+start of a line or following whitespace or code, but not within a string
 literal.  A hash character within a string literal is just a hash character.
+Since comments are to clarify code and are not interpreted by Python, they may
+be omitted when typing in examples.
 
 Some examples::
 
@@ -77,6 +79,15 @@ A value can be assigned to several variables simultaneously::
    >>> z
    0
 
+Variables must be "defined" (assigned a value) before they can be used, or an
+error will occur::
+
+   >>> # try to access an undefined variable
+   ... n
+   Traceback (most recent call last):   
+     File "<stdin>", line 1, in <module>
+   NameError: name 'n' is not defined
+
 There is full support for floating point; operators with mixed type operands
 convert the integer operand to floating point::
 
@@ -269,7 +280,7 @@ omitted second index defaults to the size of the string being sliced. ::
    >>> word[2:]    # Everything except the first two characters
    'lpA'
 
-Unlike a C string, Python strings cannot be changed.  Assigning to an  indexed
+Unlike a C string, Python strings cannot be changed.  Assigning to an indexed
 position in the string results in an error::
 
    >>> word[0] = 'x'