[New-bugs-announce] [issue7061] Improve 24.5. turtle doc

[Terry J. Reedy]

New submission from Terry J. Reedy <tjreedy at 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 <report at bugs.python.org>
<http://bugs.python.org/issue7061>
_______________________________________