Incorporate some suggestions by Tait Stevens.
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 @@
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 @@
... 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 @@
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 @@
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 @@
>>> 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 @@
* 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 @@
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 @@
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 @@
* 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.