Great job on new docs; small error report included

classic Classic list List threaded Threaded
2 messages Options
Reply | Threaded
Open this post in threaded view
|

Great job on new docs; small error report included

André Roberge
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.

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.


=======
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('[hidden email]', '[hidden email]',
"""To: [hidden email]
From: [hidden email]

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)
=================
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.

Hope it helps,

André (Roberge)
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: Great job on new docs; small error report included

Georg Brandl-2
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('[hidden email]', '[hidden email]',
> """To: [hidden email]
> From: [hidden email]
>
> 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.

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig