[Doc-SIG] Great job on new docs; small error report included

[Georg Brandl]

Andre Roberge schrieb:
> Hi everyone,
> 
> First of all, congrats to Georg Brandl and whomever else helped him in
> getting the docs in the new format; it looks *much* better.

Thanks!

> In perusing the doc (using a development version of Crunchy) I found
> some small mistakes in the way that it was formatted.  I've included
> my notes in a rather cryptic fashion - if needed (and if I get the
> time), I could probably get a proper bug report but I'd rather not
> wait until then and risk forgetting about it.
> 
> ==========
> in both
> http://docs.python.org/dev/tutorial/controlflow.html
> and
> http://docs.python.org/dev/3.0/tutorial/controlflow.html
> 
> last code example
> -----begin code-----
>>>> def my_function():
> ...     """Do nothing, but document it.
> ...
> ...     No, really, it doesn't do anything....
>    """
> ...     pass
> ...
>>>> print my_function.__doc__
> Do nothing, but document it.
> 
>    No, really, it doesn't do anything.
> -----------end-------
> 
> Note how the continuation line "..." are misplaced after the word "anything".
> (The source file is ok - this is *much* easier to see on the page than
> in this email).  This seems to be a parsing bug in the tool used to
> create the html page.

Indeed, it's a bug in the console lexer of Pygments, should be fixed now
(and the docs will be correct next time a rebuild of that file triggers).

> =======
> http://docs.python.org/dev/tutorial/stdlib.html
> http://docs.python.org/dev/3.0/tutorial/stdlib.html
> 
> under Internet access
> -----
>>>> import urllib2
>>>> for line in urllib2.urlopen('http://tycho.usno.navy.mil/cgi-bin/timer.pl'):
> ...     if 'EST' in line or 'EDT' in line:  # look for Eastern Time
> ...         print line
> 
> <BR>Nov. 25, 09:43:32 PM EST
> 
>>>> import smtplib
>>>> server = smtplib.SMTP('localhost')
>>>> server.sendmail('soothsayer at example.org', 'jcaesar at example.org',
> """To: jcaesar at example.org
> From: soothsayer at example.org
> 
> Beware the Ides of March.
> """)
>>>> server.quit()
> ------------
> 
> The "..." are missing before each line of the triple quoted string.
> (The error is in the source file)
> 
> Aside: I could not get the second example to work on my Mac (it gave
> me a traceback when I tried to create a server)

The smtplib example requires a mailserver running on localhost. This is
not too common for desktop machines, so I added a note.

> =================
> Suggestion for changes:
> in http://docs.python.org/dev/3.0/tutorial/controlflow.html  (twice on
> that page)
> http://docs.python.org/dev/3.0/tutorial/errors.html  (once on that page)
> 
> There is no need to define raw_input(); simply use input(), which will
> effectively have the same role that raw_input() currently has.

Indeed.

> Hope it helps,

Always,
Georg

-- 
Thus spake the Lord: Thou shalt indent with four spaces. No more, no less.
Four shall be the number of spaces thou shalt indent, and the number of thy
indenting shall be four. Eight shalt thou not indent, nor either indent thou
two, excepting that thou then proceed to four. Tabs are right out.