[docs] Bug in Python Tutorial

[Jeff Mullen]

Gentlemen:

I am trying to get a Sikuli script going (Sikuli is an extension of 
Python) and have come to your documentation to learn how to affect 
statement grouping in Python. Unfortunately, your documentation is quite 
obscure on this point. Relevant parts of the documentation that I could 
find were as follows:

3.2 First Steps Toward Programming

...

The body of the loop is indented: indentation is Python’s way of 
grouping statements. Python does not (yet!) provide an intelligent input 
line editing facility, so you have to type a tab or space(s) for each 
indented line. In practice you will prepare more complicated input for 
Python with a text editor; most text editors have an auto-indent 
facility. When a compound statement is entered interactively, it must be 
followed by a blank line to indicate completion (since the parser cannot 
guess when you have typed the last line). Note that each line within a 
basic block must be indented by the same amount.

-----------------

and

-----------------

4.4. break and continue Statements, and else Clauses on Loops

The break statement, like in C, breaks out of the smallest enclosing for 
or while loop.

The continue statement, also borrowed from C, continues with the next 
iteration of the loop.

Loop statements may have an else clause; it is executed when the loop 
terminates through exhaustion of the list (with for) or when the 
condition becomes false (with while), but not when the loop is 
terminated by a break statement. This is exemplified by the following 
loop, which searches for prime numbers:
 >>>

 >>> for n in range(2, 10):
... for x in range(2, n):
... if n % x == 0:
... print n, 'equals', x, '*', n/x
... break
... else:
... # loop fell through without finding a factor
... print n, 'is a prime number'
...
2 is a prime number
3 is a prime number
4 equals 2 * 2
5 is a prime number
6 equals 2 * 3
7 is a prime number
8 equals 2 * 4
9 equals 3 * 3

(Yes, this is the correct code. Look closely: the else clause belongs to 
the for loop, not the if statement.)

------------------------

This is not sufficient to show me how to code in Python. Note in the 
last sentence, it says that the else clause groups with the for 
statement, not the if statement. It does not, however, explain why. Nor 
does the document anywhere explain how statements are grouped in Python. 
The best I can come up with is that the compiler itself uses the 
indentation level to make this determination--which strikes me as rather 
kludgy, as indentation level is something that different people often 
have different interpretations of.

I would offer more specific wording for your documentation (I've had a 
couple of short stories published, so I can assure you that my writing 
skills are adequate), but I'm not sure how the thing works.

Can you clear up my confusion?

Thanks in advance.

Sincerely,

Jeff Mullen
Computer Programmer
Published Author