Preliminary documentation for turtle module (Tk), by Moshe Zadka.

Fixed up a few TeXisms and markup nits, but otherwise unchanged.
Somewhat raw.

1 files changed, 160 insertions, 0 deletions

diff --git a/Doc/lib/libturtle.tex b/Doc/lib/libturtle.tex
new file mode 100644
index 0000000..641b40d
--- /dev/null
+++ b/Doc/lib/libturtle.tex
@@ -0,0 +1,160 @@
+\section{\module{turtle} ---
+         Turtle graphics for Tk}
+
+\declaremodule{standard}{turtle}
+   \platform{Tk}
+\moduleauthor{Guido van Rossum}{guido@python.org}
+\modulesynopsis{An environment for turtle graphics.}
+
+\sectionauthor{Moshe Zadka}{mzadka@geocities.com}
+
+
+The \module{turtle} module provides turtle graphics primitives, in both an
+object-oriented and procedure-oriented ways. Because it uses \module{Tkinter}
+for the underlying graphics, it needs a version of python installed with
+Tk support.
+
+The procedural interface uses a pen and a canvas which are automagically
+created when any of the functions are called.
+
+The \module{turtle} module defines the following functions:
+
+\begin{funcdesc}{degrees}{}
+Set angle measurement units to degrees.
+\end{funcdesc}
+
+\begin{funcdesc}{radians}{}
+Set angle measurement units to radians.
+\end{funcdesc}
+
+\begin{funcdesc}{reset}{}
+Clear the screen, re-center the pen, and set variables to the default
+values.
+\end{funcdesc}
+
+\begin{funcdesc}{clear}{}
+Clear the screen.
+\end{funcdesc}
+
+\begin{funcdesc}{tracer}{flag}
+Set tracing on/off (according to whether flag is true or not). Tracing
+means line are drawn more slowly, with an animation of an arrow along the 
+line.
+\end{funcdesc}
+
+\begin{funcdesc}{forward}{distance}
+Go forward \var{distance} steps.
+\end{funcdesc}
+
+\begin{funcdesc}{backward}{distance}
+Go backward \var{distance} steps.
+\end{funcdesc}
+
+\begin{funcdesc}{left}{angle}
+Turn left \var{angle} units. Units are by default degrees, but can be
+set via the \function{degrees()} and \function{radians()} functions.
+\end{funcdesc}
+
+\begin{funcdesc}{right}{angle}
+Turn right \var{angle} units. Units are by default degrees, but can be
+set via the \function{degrees()} and \function{radians()} functions.
+\end{funcdesc}
+
+\begin{funcdesc}{up}{}
+Move the pen up --- stop drawing.
+\end{funcdesc}
+
+\begin{funcdesc}{down}{}
+Move the pen up --- draw when moving.
+\end{funcdesc}
+
+\begin{funcdesc}{width}{width}
+Set the line width to \var{width}.
+\end{funcdesc}
+
+\begin{funcdesc}{color}{s}
+Set the color by giving a Tk color string.
+\end{funcdesc}
+
+\begin{funcdesc}{color}{(r, g, b)}
+Set the color by giving a RGB tuple, each between 0 and 1.
+\end{funcdesc}
+
+\begin{funcdesc}{color}{r, g, b}
+Set the color by giving the RGB components, each between 0 and 1.
+\end{funcdesc}
+
+\begin{funcdesc}{write}{text\optional{, move}}
+Write \var{text} at the current pen position. If \var{move} is true,
+the pen is moved to the bottom-right corner of the text. By default,
+\var{move} is false.
+\end{funcdesc}
+
+\begin{funcdesc}{fill}{flag}
+The complete specifications are rather complex, but the recommended 
+usage is: call \code{fill(1)} before drawing a path you want to fill,
+and call \code{fill(0)} when you finish to draw the path.
+\end{funcdesc}
+
+\begin{funcdesc}{circle}{radius\optional{, extent}}
+Draw a circle with radius \var{radius} whose center-point is where the 
+pen would be if a \code{forward(\var{radius})} were
+called. \var{extent} determines which part of a circle is drawn: if
+not given it defaults to a full circle.
+
+If \var{extent} is not a full circle, one endpoint of the arc is the
+current pen position. The arc is drawn in a counter clockwise
+direction if \var{radius} is positive, otherwise in a clockwise
+direction.
+\end{funcdesc}
+
+\begin{funcdesc}{goto}{x, y}
+Go to co-ordinates (\var{x}, \var{y}).
+\end{funcdesc}
+
+\begin{funcdesc}{goto}{(x, y)}
+Go to co-ordinates (\var{x}, \var{y}) (specified as a tuple instead of 
+individually).
+\end{funcdesc}
+
+This module also does a documented \code{from math import *}, so see
+the documentation for the \refmodule{math} module for additional
+constants and functions useful for turtle graphics.
+% XXX Should we mention this? If so, a \seealso is also in place...
+
+\begin{funcdesc}{demo}{}
+Exercise the module a bit.
+\end{funcdesc}
+
+\begin{excdesc}{Error}
+Exception raised on any error caught by this module.
+\end{excdesc}
+
+For examples, see the code of the \function{demo()} function.
+
+This module defines the following classes:
+
+\begin{classdesc}{Pen}{}
+Define a pen. All above functions can be called as a methods on the given
+pen. The constructor automatically creates a canvas do be drawn on.
+\end{classdesc}
+
+\begin{classdesc}{RawPen}{canvas}
+Define a pen which draws on a canvas \var{canvas}. This is useful if 
+you want to use the module to create graphics in a ``real'' program.
+\end{classdesc}
+
+\subsection{Pen and RawPen Objects \label{pen-rawpen-objects}}
+
+\class{Pen} and \class{RawPen} objects have all the global functions
+described above, except for \function{demo()} as methods, which
+manipulate the given pen.
+
+The only method which is more powerful as a method is
+\function{degrees()}.
+
+\begin{methoddesc}{degrees}{\optional{fullcircle}}
+\var{fullcircle} is by default 360. This can cause the pen to have any
+angular units whatever: give \var{fullcircle} 2*$\pi$ for radians, or
+400 for gradians.
+\end{methoddesc}