Improve turtle module documentation

[terryjreedy]

BPO	7061
Nosy	@akuchling, @birkenfeld, @rhettinger, @terryjreedy, @abalkin, @merwok, @bitdancer
Files	issue7061.diff issue7061a.diff issue7061b.diff issue7061-docstrings-r27.diff turtle-star-sidebar.diff: Use this patch together with turtle-star.png turtle-star.png: This file goes to Doc/library turtle-sidebar-screenshot.png: Rendered "Turtle graphics" page

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2014-10-10.01:38:23.128>
created_at = <Date 2009-10-05.04:34:31.142>
labels = ['docs']
title = 'Improve turtle module documentation'
updated_at = <Date 2014-10-10.01:38:23.126>
user = 'https://github.com/terryjreedy'

bugs.python.org fields:

activity = <Date 2014-10-10.01:38:23.126>
actor = 'r.david.murray'
assignee = 'docs@python'
closed = True
closed_date = <Date 2014-10-10.01:38:23.128>
closer = 'r.david.murray'
components = ['Documentation']
creation = <Date 2009-10-05.04:34:31.142>
creator = 'terry.reedy'
dependencies = []
files = ['19373', '19404', '19418', '19500', '19557', '19558', '19559']
hgrepos = []
issue_num = 7061
keywords = ['patch']
message_count = 41.0
messages = ['93574', '93575', '119154', '119166', '119324', '119326', '119327', '119329', '119330', '119336', '119337', '119629', '119632', '119642', '119672', '119673', '119675', '119814', '119921', '119922', '119923', '119926', '120025', '120028', '120029', '120099', '120454', '120470', '120501', '120508', '120837', '120868', '120869', '120872', '120880', '120882', '120885', '120888', '120926', '202289', '228940']
nosy_count = 9.0
nosy_names = ['akuchling', 'georg.brandl', 'rhettinger', 'terry.reedy', 'belopolsky', 'gregorlingl', 'eric.araujo', 'r.david.murray', 'docs@python']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue7061'
versions = ['Python 3.1', 'Python 3.2']

[terryjreedy]

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.

[gregorlingl]

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

[abalkin]

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.

[abalkin]

Committed some of the simpler fixes in r85732.

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

Unclear indeed. See bpo-3062.

[merwok]

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!

[abalkin]

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.

[abalkin]

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.

[abalkin]

I also wonder if the title should be changed from "Turtle graphics for Tk" to simply "Turtle graphics". As explained in bpo-3884, 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.

[merwok]

+1.

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

[abalkin]

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.

[merwok]

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.