[docs] [issue7061] Improve 24.5. turtle doc

[Terry J. Reedy]

Terry J. Reedy <tjreedy at udel.edu> added the comment:

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!

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue7061>
_______________________________________