New submission from Terry J. Reedy <tjre...@udel.edu>: 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. ---------- assignee: georg.brandl components: Documentation messages: 93574 nosy: georg.brandl, gregorlingl, tjreedy severity: normal status: open title: Improve 24.5. turtle doc versions: Python 3.1, Python 3.2 _______________________________________ Python tracker <rep...@bugs.python.org> <http://bugs.python.org/issue7061> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
