[issue7061] Improve 24.5. turtle doc
Terry J. Reedy <tjreedy@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@bugs.python.org> <http://bugs.python.org/issue7061> _______________________________________
Alexander Belopolsky <belopolsky@users.sourceforge.net> added the comment: 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 tracker <report@bugs.python.org> <http://bugs.python.org/issue7061> _______________________________________
participants (2)
-
Alexander Belopolsky
-
Terry J. Reedy