Reading through 24.5 on the turtle module, I have a number of comments
aimed at improvements. Some are straightforward fixes which any doc
maintainer could enter. Others are questions about meaning that I
presume the current maintainer, gregor lingl may have to answer. But he
is not an option of the Assigned To: pulldown list. These are introduced
by '??'. Quotes are from 3.1.1 docs.

24.5.1. Introduction

"version of python installed with Tk support.": cap 'python' to 'Python'

'which draws on “the” Screen - instance': delete '-'

"To use multiple turtles an a screen ": an > on

"24.5.2. Overview over available Turtle and Screen methods":

'over' > 'of'

24.5.3.1. Turtle motion

?? distance units? pixel or world, depending on mode?
presume yes, but should say something here.

24.5.3.6. Using events

"turtle.onclick(fun, btn=1, add=None) 

It seems that 'add=False' would be same as 'add=None' and more
consistent with below.

"add – True or False – if True, a new binding will be added, otherwise
it will replace a former binding "

?? I do not understand what this means. Normal Python binding
(assignment) adds a new binding, replacing an old one if there was one.
How is turtle different? (And why should it be?)

"turtle.onrelease(fun, btn=1, add=None) "
"turtle.onrelease(fun, btn=1, add=None) "
 same pair of comments

24.5.3.8. Excursus about the use of compound shapes

'excursus' is so obscure that I have never seen/heard it before and had
to look it up to verify that it was an English word. The definitions I
found do not quite fit the usage. 'Compound shapes' is quite sufficient
for the section title. 

If change the title, there is also the reference to this section in
24.5.5. The public classes of the module turtle to be changed.


24.5.4. Methods of TurtleScreen/Screen and corresponding functions
"Most of the examples in this section refer to a TurtleScreen instance
called screen."

However, 
24.5.4.1. Window control
turtle.bgcolor(*args) "

and so on throughout the section.
??  I presume that should be 
"screen.bgcolor(*args)" and so on throughout the section.

.clear(), .reset()
"Note This TurtleScreen method is available as a global function only
under the name clearscreen. The global function clear is another one
derived from the Turtle method clear."

?? I presume 'another' means 'a different', but then I do not understand
the difference.

"turtle.delay(delay=None) 
Parameter: delay – positive integer 

Set or return the drawing delay in milliseconds. (This is approximately
the time interval between two consecutive canvas updates.) The longer
the drawing delay, the slower the animation."

?? Unclear how this interacts with turtle.speed

"turtle.tracer(n=None, delay=None) 
Parameters: n – nonnegative integer 
delay – nonnegative integer 

Turn turtle animation on/off and set delay for update drawings. If n is
given, only each n-th regular screen update is really performed. (Can be
used to accelerate the drawing of complex graphics.) Second argument
sets delay value (see delay())."

?? does .tracer() (no args) turn animation off?

"Remark: in order to be able to register key-events, TurtleScreen must
have the focus. (See method listen().
>>> def f():
...     fd(50)
...     lt(60)
...
>>> screen.onkey(f, "Up")
>>> screen.listen()"

From the Remark, I expected the two calls to be in the opposite order.
Ditto for .onkeypress()

24.5.4.4. Input methods

"turtle.numinput(title, prompt, default=None, minval=None, maxval=None) 
Parameters: title – string 
prompt – string 
default – number (optional) 
prompt – number (optional) 
prompt – number (optional) "

Last two param names are 'minval' and 'maxval', not 'prompt'.

24.5.4.5. Settings and special methods

?? .mode: 'world' like standard or logo w/r/t angles?

"24.5.4.6. Methods specific to Screen, not inherited from TurtleScreen
turtle.exitonclick() 
Bind bye() method to mouse clicks on the Screen."

"If the value “using_IDLE” in the configuration dictionary is False
(default value), also enter mainloop. Remark: If IDLE with the -n switch
(no subprocess) is used, this value should be set to True in turtle.cfg.
In this case IDLE’s own mainloop is active also for the client script."

From Windows shortcut, I cannot tell how IDLE is started, but seems to
work. Anything need to be said re IDLE/turtle on windows?

My guess is that IDLE is running normally (without -n), so that there is
a subprocess, so that 'using_IDLE' is False even though I am using it,
just not in the same process.  Correct?

24.5.8. Changes since Python 2.6

Sections about 2.x changes should not be in 3.x docs.

Thanks, Terry, for reading the docs that thoroughly.
Alas, for the next week I'm too busy (with preparing "Python für Kids"
for press) to work through this long list. 
Since it doesn't seem to be *very* urgent, I'll defer that work until
Oct. 12th or so. Then I'll be glad to discuss each and every point of
your list (some of them are known to me already) and I'm sure that the
necessary fixes and amendments can be done quickly then.
Best regards,
Gregor

> It seems that 'add=False' would be same as 'add=None' and more
> consistent with below.

The add argument is passed unchanged to canvas' bind method which is documented as taking either '' or '+' string:

http://docs.python.org/library/tkinter.html?highlight=canvas#bindings-and-events

I think anything that can be used in boolean context can be used there.  None and '' are equivalent to False and '+' is equivalent to True.  I agree that True/False are better options and suggest to change tkinter doc accordingly.

As far as changing the default value from None to False, if this is done in doc, the same should be done in the code.  I am -0 on that.

Committed some of the simpler fixes in r85732.


> ?? Unclear how [delay()] interacts with turtle.speed

Unclear indeed.  See issue 3062.

From your commit:
-Excursus about the use of compound shapes
+Compound shapes
 -----------------------------------------

Having more hyphens than title characters is not an error for reST, but it’s not done in the rest of the document.  I suggest “fixing” that when you do further changes in the file (it’s not worth a commit in itself).  Cheers!

On Thu, Oct 21, 2010 at 2:03 PM, Éric Araujo <report@bugs.python.org> wrote:
..
> Having more hyphens than title characters is not an error for reST, but it’s not done in the rest of the document.
>  I suggest “fixing” that when you do further changes in the file (it’s not worth a commit in itself).  Cheers!

There are other ReST imperfections in turtle doc.  For example,
:class: tag is often missing on class names. (Search for "Turtle" with
capital 'T'.)   The hyphen fix, however seems easier to commit than to
remember.   I'll do it now.

On Thu, Oct 21, 2010 at 2:12 PM, Alexander Belopolsky
<belopolsky@users.sourceforge.net> wrote:
> The hyphen fix, however seems easier to commit than to
> remember.   I'll do it now.
>

Committed in r85778.

I also wonder if the title should be changed from "Turtle graphics for Tk" to simply "Turtle graphics".  As explained in issue3884, msg73465 turtle's use of Tk is an implementation detail and the title may be confusing to the target audience.  Presumably turtle module is targeted towards young and novice users who don't know and don need to know about Tk.

+1.

BTW, aren’t the fixes relevant for 2.7 too?

On Thu, Oct 21, 2010 at 3:00 PM, Éric Araujo <report@bugs.python.org> wrote:
..
> +1. [remove reference to Tk from title]
>
If we do that, I think we should move turtle documentation out of the
"Graphical User Interfaces with Tk" chapter.  It would be more
appropriate to place it under "Program Frameworks".

> BTW, aren’t the fixes relevant for 2.7 too?
>

They probably are, but for a purely educational module such as turtle,
I don't see much value in improving it in 2.x releases.

Agreed that Program Frameworks is the most adequate section.

For the backport, I don’t see that turtle should have different rules than other modules, but I’m not firmly attached to this, so do as you wish.

Attached patch, issue7061.diff, drops "for Tk" from turtle module title and move its doc section under frameworks.  I also fixed a couple of markup issues that affected TOC rendering.

Looks good.  Remember to adjust the number of signs making the reST title markup.

Nice that you’re fixing the ToC; I noticed a handful of issues some days ago and thought about making a patch in a week or two.  I’d open another report for them and backport the fixes to 2.7 too.

LGTM, if you verified that the label "debugger" is not in use at the moment.

On Tue, Oct 26, 2010 at 3:32 PM, Georg Brandl <report@bugs.python.org> wrote:
..
> LGTM, if you verified that the label "debugger" is not in use at the moment.

Good point.  I naively hoped that Sphinx would warn me about a
reference to an undefined label.  Grep found a reference in sys.rst.
I will replace that with a :mod:`pdb` reference which seems to be a
better fit.

Committed in revision 85853.

Terry, please chime in if I missed anything that you would consider part of this issue.  Note that the speed vs. delay may not be just a doc issue.  I opened issue 10170 for that.

If you do a full build, you'll get a warning; however, currently documents that reference a label will not be recognized as out of date when that label changes or is removed.

Attaching another small doc improvement: "gon" is better know as "grad" and even under that name requires an explanation. See issue7061a.diff

Committed issue7061a.diff r85930.  This is probably a backport candidate.

While working on issue 10225, I have found several mistakes in turtle.rst examples.  It probably makes sense to review these separately and commit as part of this issue rather than bunching with the other issue 10225 changes.

There are still two remaining failures that I attribute to sphinx bugs.  One is due to an already reported ellipsis bug, and the other is a rather strange failure in the shapetransform example.

Georg, can you take a look?

File "library/turtle.rst", line 1272, in default
Failed example:
    turtle.shapetransform()
Expected:
    (4.0, -1.0, -0.0, 2.0)
Got:
    (2.82842712474619, -2.121320343559643, 2.8284271247461907, 0.7071067811865472)


Note that this test succeeds when it is the only test in a file.

Gregor,

I suspect that there are doctest mistakes in the turtle.py docstrings, but I cannot figure out how to run it through doctest.  Can you help?

As I suspected, the turtle.shapetransform() stems from sphinx' failure to reinitialize the turtle variable as testsetup dictates.  I can work around this by adding 

      >>> turtle = Turtle()

above

      >>> turtle.shape("square")
      >>> turtle.shapesize(4,2)
      >>> turtle.shearfactor(-0.5)
      >>> turtle.shapetransform()
      (4.0, -1.0, -0.0, 2.0)

but I don't think it is a good idea to pollute the documentation this way.

On initialization: the json doc has 6 examples. Each starts with 'import json' so each is independent. However, I agree that doing the same for turtle examples would be a bit much. On the other hand, I think
24.5.3. *Methods of RawTurtle/Turtle and corresponding functions*
should explicitly give the needed code. So I would change "Most of the examples in this section refer to a Turtle instance called turtle." to

"The examples below that refer to a Turtle instance called turtle require something like the following to be run first:

>>> from turtle import turtle; turtle = Turtle()
"

The three examples above turtle.shapetransform start with
>>> turtle.reset()
I presume they need that to run reliably. If it is also needed for the shapetransform example to run correctly, then I would just added it there too.

I will post more after I compare my original post to your revision.

GREGOR, I think we need your help to answer a few of these.

Subissues from my opening post not resolved in rev85732
--------------------

"version of python installed with Tk support.": cap 'python' to 'Python'

Is there any standard on capitalizing 'Python'?
-----------

24.5.3.1. Turtle motion

?? distance units? pixel or world, depending on mode?
presume yes, but should say something here.
--------------

I said
'''
"turtle.onclick(fun, btn=1, add=None) 
It seems that 'add=False' would be same as 'add=None' and more
consistent with below.
"add – True or False – if True, a new binding will be added, otherwise
it will replace a former binding "
'''

In declining to make a change, you said
"
The add argument is passed unchanged to canvas' bind method which is documented as taking either '' or '+' string:"

However, naive users are not supposed to know that, which is why you moved turtle doc out of tk chapter. Anyway, one has to know or guess to look for the doc on the generic widget bind method.

There still remains a discrepancy between signature and following doc. If you do not want to change the signature, change the doc. Anyway, the sentence needs to be expanded so it makes sense without reading the generic tkinter bind doc. 

""add – True, False, or None - if True, add the new binding to any that already exist, otherwise replace all former bindings with the new one."

Same change is needed for onrelease and ondrag
----------------------

You changed the title "Excursus about the use of compound shapes" to "Compound shapes" but did not, as far as I can see, make the same change in the reference in *24.5.5. The public classes of the module turtle* after
"addcomponent(poly, fill, outline=None)"

Also, the above should actually be
"class turtle.addcomponent(poly, fill, outline=None)"
to be consistent with the other entries
----------------------------
'''
24.5.4. Methods of TurtleScreen/Screen and corresponding functions
"Most of the examples in this section refer to a TurtleScreen instance
called screen."

However, 
24.5.4.1. Window control
turtle.bgcolor(*args) "

and so on throughout the section.
??  I presume that should be 
"screen.bgcolor(*args)" and so on throughout the section.
'''
Not addressed as far as I can see.
------------------------

.delay vs. speed is #10170
------------
'''
"Remark: in order to be able to register key-events, TurtleScreen must
have the focus. (See method listen().
>>> def f():
...     fd(50)
...     lt(60)
...
>>> screen.onkey(f, "Up")
>>> screen.listen()"

From the Remark, I expected the two calls to be in the opposite order.
Ditto for .onkeypress()
'''
Since the .listen doc says "Set focus on TurtleScreen (in order to collect key-events). ", I strongly suspect that 'register' in the remark should be changed to 'collect', 'capture', or 'respond to' for both onkeypress and onkeyrelease. Then the example is correct.
---------------

The last 3 sub-issues are still open
'''
24.5.4.5. Settings and special methods

?? .mode: 'world' like standard or logo w/r/t angles?
'''
'''
"24.5.4.6. Methods specific to Screen, not inherited from TurtleScreen
turtle.exitonclick() 
Bind bye() method to mouse clicks on the Screen."

"If the value “using_IDLE” in the configuration dictionary is False
(default value), also enter mainloop. Remark: If IDLE with the -n switch
(no subprocess) is used, this value should be set to True in turtle.cfg.
In this case IDLE’s own mainloop is active also for the client script."

From Windows shortcut, I cannot tell how IDLE is started, but seems to
work. Anything need to be said re IDLE/turtle on windows?

My guess is that IDLE is running normally (without -n), so that there is
a subprocess, so that 'using_IDLE' is False even though I am using it,
just not in the same process.  Correct?
'''
'''
24.5.8. Changes since Python 2.6

Sections about 2.x changes should not be in 3.x docs.
'''
-----------------------
Thanks for the other half that are fixed!

On Sat, Oct 30, 2010 at 8:27 PM, Terry J. Reedy <report@bugs.python.org> wrote:
..
> "version of python installed with Tk support.": cap 'python' to 'Python'
>
> Is there any standard on capitalizing 'Python'?

It looks like it is consistently capitalized in the Python manual.

> -----------
>
> 24.5.3.1. Turtle motion
>
> ?? distance units? pixel or world, depending on mode?
> presume yes, but should say something here.
> --------------

I would just use "distance units" and "angle units" throughout the
documentation and explain somewhere how the settings determine the
units.

..
> There still remains a discrepancy between signature and following doc. If you do not want to change the signature, change the doc. Anyway, the sentence needs to be expanded so it makes sense without reading the generic tkinter bind doc.
>
> ""add – True, False, or None - if True, add the new binding to any that already exist, otherwise replace all former bindings with the new one."

I would rather change the default to False in both documentation and
the code, but let's hear from Gregor first.

>
> Same change is needed for onrelease and ondrag
> ----------------------
>
> You changed the title "Excursus about the use of compound shapes" to "Compound shapes" but did not, as far as I can see, make the same change in the reference in *24.5.5. The public classes of the module turtle* after
> "addcomponent(poly, fill, outline=None)"

I missed that.  I'll rename that section to "Public classes".

>
> Also, the above should actually be
> "class turtle.addcomponent(poly, fill, outline=None)"
> to be consistent with the other entries

I am not sure what you mean.  AFAICT, addcomponent is a method and
correctly marked as such.

..
> and so on throughout the section.
> ??  I presume that should be
> "screen.bgcolor(*args)" and so on throughout the section.
> '''
> Not addressed as far as I can see.

I cannot find "turtle.bgcolor".  Can you post a patch with what you
want to change?

[skipped issues for which I would appreciate Gregor's input]

> -----------------------
> Thanks for the other half that are fixed!

I thought I did better than that.

“Python” is lower-cased only when referring to the executable (as a file) itself.  When talking about the language, the implementation or the VM in an abstract way (not a file), It think it’s always “Python”.

I am attaching a patch that adds a hack that allows to run turtle doctests using turtle.run_doctests() function.  Running this function has revealed numerous mistakes in doctests that are corrected in the patch.

The patch is against release27 branch because there are even more problems in py3k.

I don't think run_doctests hack belongs to turtle module.  I think it would be more appropriate to place it in test.test_turtle.

I have also not been able to figure out how to make global functions' doctests runnable.  The current patch disables them by mangling the >>> prompts in docstrings.

Why shouldn't global function doctests be runnable?

On Fri, Nov 5, 2010 at 3:34 AM, Georg Brandl <report@bugs.python.org> wrote:
..
> Why shouldn't global function doctests be runnable?

They should - I just couldn't figure out a better hack that would work
for both mathods and functions.  Note that functions are
auto-generated in turtle from Screen and Turtle methods.  The doctests
are just method doctests with turtle. or screen. prefix dropped.  In
order to remove dependency between doctests, I create a new turtle for
each test and assign it to global "turtle" variable.  For some reason
similar approach did not work for functions.  I'll keep trying,
though.

On the other hand, since function doctests are auto-generated from
method doctests, there is little to be gained from running them
separately.

What do you mean with "similar approach"?

Keep in mind, that functions derived form turtle methods,
call methods for the class variable _pen of class Turtle.
A new Turtle-object is bound to _pen, if it is not already
present, whenever one of these functions is called, via _getpen()

So perhaps _getpen() can do for you what you need?

(A similar approach is used for screen-oriented functions with turtle._screen.)

I'm very sorry that, due to time restrictions, for the next two or three months I'm not able to participate in these discussions as intensely as I'd like to.

Best regards,
Gregor

From IRC (raymondh):

in the turtle docs, can you add a quick start guide (like we have in the unittest docs)
the turtle docs have grown into a small book and is intimidating to get started with.

As a follow-up to Raymond's suggestion, I am attaching a patch that will add a sidebar to the introduction section of the turtle documentation section.  While it is not common to include screenshots in python documentation, I think it is very appropriate for a visual module such as turtle.  I considered a "Basic example" subsection similar to that in unittest module documentation, but turtle introduction already has a basic example (forward(15); left(25) embedded in the prose, so I think a sidebar like this is more appropriate. 

Since svn does not include binary files in the patch, I will have to attach the embedded image separately.  I will also post a screenshot of the rendered HTML page.

I like it!

On Sat, Oct 30, 2010 at 8:27 PM, Terry J. Reedy <report@bugs.python.org> wrote:
..
> Sections about 2.x changes should not be in 3.x docs.

I agree.  Neither "Changes since Python 2.6" nor "Changes since Python 2.6" belong in this section.  The first belongs to "What's new in Python 2.7" and the second to "What's new in Python 3.1".  Do we edit these files retroactively?  I don't want to simply remove these sections.  Raymond, can you advise?

On a similar note, I don't think the introduction section should refer to "the old turtle module".

The mini change log is harmless.  I would leave it as is.

On Tue, Nov 9, 2010 at 11:45 AM, Raymond Hettinger
<report@bugs.python.org> wrote:
..
> Raymond Hettinger <rhettinger@users.sourceforge.net> added the comment:
>
> The mini change log is harmless.  I would leave it as is.

It is not entirely harmless.  First, it occupies valuable easy to
scroll to end-of-page real estate which is better used for the "Demo
scripts" section.  Second, "Changes since 3.0" in 3.2 documentation
without  "Changes since 3.1" give a feel of unmaintained module.
Third, "Changes since 3.0" refers to the Demo directory which no
longer exists and I don't want to add "Changes since 3.1" to fix that.
 However, I don't feel too strongly about removing them.  I would
leave this for the "What's new" editor to decide and if that's
Raymond, I guess the decision has been made.

To me, the mini change logs are both distracting noise and contrary to the general start-fresh policy for 3.x docs, stated somewhere by Georg B, which I really like.

Committed a slightly modified turtle-star-sidebar.diff in revision 86364.  Note that I've included both pdf and postscript files in case someone would want to run postscript through a better distiller than the OSX preview that I used.  The postscript was produced using postscript() method of the tkinter canvas and bbox was manually adjusted.

On Sun, Oct 31, 2010 at 8:00 PM, Éric Araujo <report@bugs.python.org> wrote:
..
> “Python” is lower-cased only when referring to the executable (as a 
> file) itself.  When talking about the language, the implementation or
> the VM in an abstract way (not a file), It think it’s always “Python”.

For the record, this is covered in the Python documentation style guide:

"""
Python

    The name of our favorite programming language is always capitalized.
"""

http://docs.python.org/dev/documenting/style.html

Is there anything left to do for this issue?

If there *is* anything left to do here, new issues should be opened.