Warning, /education/kturtle/doc/programming-reference.docbook is written in an unsupported language. File is not indexed.

 <chapter id="reference">
 <title>&turtlescript; Programming Reference</title>
 <para>This is the reference for &kturtle;'s &turtlescript;. In the first section of this chapter have a look at some aspects of the <link linkend="grammar">grammar</link> of &turtlescript; programs. The second section deals exclusively with <link linkend="mathematical-operators">mathematical operators</link>, <link linkend="boolean-operators">boolean (true/false) operators</link> and <link linkend="comparing-operators">comparison operators</link>. The third section is basically a giant list of all <link linkend="commands">commands</link> explaining them one-by-one. Section four explains how to <link linkend="assignment-of-variables">assign</link> values to <link linkend="assignment-of-variables">variables</link>. Finally we explain how to arrange the execution of commands with <link linkend="controlling-execution">execution controlling statements</link> in section five and how to create you own commands with <link linkend="learn"><userinput>learn</userinput></link> in section six.</para>
 
 <sect1 id="grammar">
 <title>The Grammar of &turtlescript;</title>
 <para>As in any language, &turtlescript; has different types of words and symbols. In English we distinguish verbs (like 'to walk' or 'to sing') and nouns (like 'sister' or 'house'), they are used for different purposes. &turtlescript; is a programming language, it is used to instruct &kturtle; what to do.</para>
 <para>In this section some of &turtlescript;'s different types of words and symbols are briefly explained. We explain <link linkend="comment">comments</link>, <link linkend="command">commands</link> and the three different kinds of literals: <link linkend="number">numbers</link>, <link linkend="string">strings</link> and <link linkend="boolean-value">boolean (true/false) values</link>.</para>
 
 
 <sect2 id="comment">
 <title>Comments</title>
 <para>A program consists instructions that are executed when the program is run and so called comments. Comments are not executed, &kturtle; simply ignores them when executing your program. Comment are there for other programmers to make them understand your program better. Everything that follows on a <userinput>#</userinput> symbol is considered a comment in &turtlescript;. For example this little program that does nothing:
 <screen>
 # this little program does nothing, it is only a comment!
 </screen>
 It is a bit useless but it explain the matter well.</para>
 <para>Comments get very useful when the program gets a little bit more complex. It can help to give some advice to other programmers. In the following program you see comments being used together with the <link linkend="print">print</link> command.
 <screen>
 # this program has been made by Cies Breijs.
 print "this text will get printed on the canvas"
 # the previous line is not a comment, but the next line is:
 # print "this text will not get printed!"
 </screen>
 The first line describes the program. The second line is executed by &kturtle; and prints <userinput>this text will get printed on the canvas</userinput> on the canvas. The third line is a comment. And the forth line is a comment that contains a piece of &turtlescript;, if the <userinput>#</userinput> symbol would be removed on the fourth line the print statement will we executed by &kturtle;. Programmers say: the print statement on the fourth line is 'commented out'.</para>
 <para>Commented lines are <glossterm>highlighted</glossterm> with light gray in the <link linkend="the-editor">code editor</link>.</para>
 </sect2>
 
 <sect2 id="command">
 <title>Commands</title>
 <para>Using commands you tell the turtle or &kturtle; to do something. Some commands need input, some give output.
 <screen>
 # forward is a command that needs input, in this case the number 100:
 forward 100
 </screen>
 The first line is a <link linkend="comment">comment</link>. The second line contains the <userinput>forward</userinput> command and the <link linkend="number">number</link> <userinput>100</userinput>. The number is not part of command, it is considered 'input' for the command.</para>
 <para>Some commands like &eg; <userinput>go</userinput> need more than one input value. Multiple values have to be separated using the <userinput>,</userinput> character (comma).</para>
 <para> For a detailed overview of all commands that &kturtle; supports go <link linkend="commands">here</link>. Built-in commands are <glossterm>highlighted</glossterm> in dark blue.</para>
 </sect2>
 
 <sect2 id="number">
 <title>Numbers</title>
 <para>Most likely you already know quite a bit about numbers. The way numbers are used in &kturtle; is not much different from spoken language, or math.</para>
 <para>We have the so called natural numbers: <userinput>0</userinput>, <userinput>1</userinput>, <userinput>2</userinput>, <userinput>3</userinput>, <userinput>4</userinput>, <userinput>5</userinput>, &etc; The negative numbers: <userinput>-1</userinput>, <userinput>-2</userinput>, <userinput>-3</userinput>, &etc; And the numbers with decimals, or dot-numbers, for example: <userinput>0.1</userinput>, <userinput>3.14</userinput>, <userinput>33.3333</userinput>, <userinput>-5.05</userinput>, <userinput>-1.0</userinput>.
 The <userinput>.</userinput> character (dot) is used as decimal separator.
 </para>
 <para>Numbers can be used in <link linkend="mathematical-operators">mathematical operators</link> and <link linkend="comparing-operators">comparison operators</link>. They can also be stored in <link linkend="assignment-of-variables">variables</link>. Numbers are <glossterm>highlighted</glossterm> in dark red.</para>
 </sect2>
 
 <!-- constants like pi? -->
 
 <sect2 id="string">
 <title>Strings</title>
 <para>First an example:
 <screen>
 print "Hello, I'm a string."
 </screen>
 In this example <userinput>print</userinput> is a command where <userinput>"Hello, I'm a string."</userinput> is a string. Strings start and end with the <userinput>"</userinput> mark, by these marks &kturtle; knows it is a string.</para>
 <para>Strings can be put in <link linkend="assignment-of-variables">variables</link>, just like <link linkend="number">numbers</link>. Yet, unlike numbers, strings cannot be used in <link linkend="mathematical-operators">mathematical operators</link> or <link linkend="comparing-operators">comparison operators</link>. Strings are <glossterm>highlighted</glossterm> with red.</para>
 </sect2>
 
 <sect2 id="boolean-value">
 <title>Boolean (true/false) values</title>
 <para>There are only two boolean values: <userinput>true</userinput><indexterm><primary>true</primary></indexterm> and <userinput>false</userinput><indexterm><primary>false</primary></indexterm>. Sometimes they are also called: <quote><userinput>on</userinput></quote> and <quote><userinput>off</userinput></quote>, <quote><userinput>yes</userinput></quote> and <quote><userinput>no</userinput></quote>, <quote><userinput>one</userinput></quote> and <quote><userinput>zero</userinput></quote>. But in &turtlescript; we call them, always, <userinput>true</userinput> and <userinput>false</userinput>. Have a look at this piece of &turtlescript;:
 <screen>
 $a = true
 </screen>
 If you look in the <link linkend="the-inspector">inspector</link> you can see that the <link linkend="assignment-of-variables">variable</link> <userinput>$a</userinput> is set to <userinput>true</userinput>, and has the boolean type.</para>
 <para>Often boolean values are the result of a <link linkend="comparing-operators">comparison operator</link>, like in the following piece of &turtlescript;:
 <screen>
 $answer = 10 &gt; 3
 </screen>
 The <link linkend="assignment-of-variables">variable</link> <userinput>$answer</userinput> is set to <userinput>true</userinput> because <userinput>10</userinput> is larger than <userinput>3</userinput>.</para>
 <para>Boolean values, <userinput>true</userinput> and <userinput>false</userinput>, are <glossterm>highlighted</glossterm> with dark red.</para>
 </sect2>
 
 </sect1>
 
 
 
 <sect1 id="operators">
 <title>Mathematical, boolean and comparing operators</title>
 <para>The title of this section might sound very difficult, yet it is not as difficult as it sound.</para>
 
 <sect2 id="mathematical-operators">
 <title>Mathematical operators</title>
 <para>These are the basic math symbols known as: add (<userinput>+</userinput>), subtract (<userinput>-</userinput>), multiply (<userinput>*</userinput>), divide (<userinput>/</userinput>) and power (<userinput>^</userinput>).</para>
 
 <para>Here a small example of the mathematical operators you can use in &turtlescript;:
 <screen>
 $add      = 1 + 1
 $subtract = 20 - 5
 $multiply = 15 * 2
 $divide   = 30 / 30
 $power    = 2 ^ 2
 </screen>
 The values resulting from the mathematical operations get <link linkend="assignment-of-variables">assigned</link> to various <link linkend="assignment-of-variables">variables</link>. Using the <link linkend="the-inspector">inspector</link> you can see the values.</para>
 <para>If you just want a simple calculation to be done you can do something like this:
 <screen>
 print 2010-12
 </screen></para>
 <para>Now an example with parentheses:
 <screen>
 print ( ( 20 - 5 ) * 2 / 30 ) + 1
 </screen>
 The expressions inside parentheses will be calculated first. In this example, 20-5 will be calculated, then multiplied by 2, divided by 30, and then 1 is added (giving 2). Parentheses can also be used in other cases.</para>
 <para>&kturtle; also has more advanced mathematical features in the form of commands. Have a look at the following commands but be aware that it concerns advanced operations: <link linkend="round">round</link>, <link linkend="random">random</link>, <link linkend="sqrt">sqrt</link>
 <!--, <link linkend="exp">exp</link> -->
 , <link linkend="pi">pi</link>, <link linkend="sin">sin</link>, <link linkend="cos">cos</link>, <link linkend="tan">tan</link>, <link linkend="arcsin">arcsin</link>, <link linkend="arccos">arccos</link>, <link linkend="arctan">arctan</link>.</para>
 </sect2>
 
 <sect2 id="boolean-operators">
 <title>Boolean (true/false) operators</title>
 <para>Where <link linkend="mathematical-operators">mathematical operators</link> are mainly for <link linkend="number">numbers</link>, boolean operators are for <link linkend="boolean-value">boolean values</link> (<userinput>true</userinput> and <userinput>false</userinput>). There are only three boolean operators, namely: <userinput>and</userinput><indexterm><primary>and</primary></indexterm>, <userinput>or</userinput><indexterm><primary>or</primary></indexterm>, and <userinput>not</userinput><indexterm><primary>not</primary></indexterm>. The following piece of &turtlescript; shows how to use them:
 <screen>
 $and_1_1 = true and true    # -> true
 $and_1_0 = true and false   # -> false
 $and_0_1 = false and true   # -> false
 $and_0_0 = false and false  # -> false
 
 $or_1_1 = true or true    # -> true
 $or_1_0 = true or false   # -> true
 $or_0_1 = false or true   # -> true
 $or_0_0 = false or false  # -> false
 
 $not_1 = not true   # -> false
 $not_0 = not false  # -> true
 </screen>
 Using the <link linkend="the-inspector">inspector</link> you can see the values, yet we also supply these results as little comments at the end of the lines. <userinput>and</userinput> evaluates <userinput>true</userinput> only if both sides are <userinput>true</userinput>. <userinput>or</userinput> evaluates <userinput>true</userinput> if either side is <userinput>true</userinput>. And <userinput>not</userinput> turns a <userinput>true</userinput> into <userinput>false</userinput> and a <userinput>false</userinput> into <userinput>true</userinput>.</para>
 <para>Boolean operators are <glossterm>highlighted</glossterm> with pink.</para>
 
 <sect3 id="boolean-operators-advanced-examples">
 <title>Some more advanced examples</title>
 <para>Consider the following example with <userinput>and</userinput>:
 <screen>
 $a = 1
 $b = 5
 if (($a &lt; 10) and ($b == 5)) and ($a &lt; $b) {
   print "hello"
 }
 </screen>
 In this piece of &turtlescript; the result of three <link linkend="comparing-operators">comparing operators</link> are merged using <userinput>and</userinput> operators. This means that all three have to evaluate <quote>true</quote> in order for the <quote>hello</quote> to be printed.</para>
 
 <para>An example with <userinput>or</userinput>:
 <screen>
 $n = 1
 if ($n &lt; 10) or ($n == 2) {
   print "hello"
 }
 </screen>
 In this piece of &turtlescript; the left side of the <userinput>or</userinput> is evaluating to <quote>true</quote>, the right side to <quote>false</quote>. Since one of the two sides of the <userinput>or</userinput> operator is <quote>true</quote>, the <userinput>or</userinput> operator evaluates <quote>true</quote>. That means <quote>hello</quote> gets printed.</para>
 
 <para>And finally an example with <userinput>not</userinput> which changes <quote>true</quote> into <quote>false</quote> and <quote>false</quote> into <quote>true</quote>. Have a look:
 <screen>
 $n = 1
 if not ($n == 3) {
   print "hello"
 } else {
   print "not hello ;-)"
 }
 </screen></para>
 </sect3>
 </sect2>
 
 <sect2 id="comparing-operators">
 <title>Comparing operators</title>
 <para>Consider this simple comparison:
 <screen>
 $answer = 10 &gt; 3
 </screen>
 Here <userinput>10</userinput> is compared to <userinput>3</userinput> with the <quote>greater than</quote> operator. The result of this comparison, the <link linkend="boolean-value">boolean value</link> <userinput>true</userinput> is stored in the <link linkend="assignment-of-variables">variable</link> <userinput>$answer</userinput>.</para>
 <para>All <link linkend="number">numbers</link> and <link linkend="assignment-of-variables">variables</link> (that contain numbers) can be compared to each other with comparing operators.</para>
 <para>
 Here are all possible comparing operators:
 <table>
 <title>Types of questions</title>
 <tgroup cols="3">
 <tbody>
 <row>
 <entry><userinput>$A == $B</userinput></entry>
 <entry>equals</entry>
 <entry>answer is <quote>true</quote> if <userinput>$A</userinput> equals <userinput>$B</userinput></entry>
 </row>
 <row>
 <entry><userinput>$A != $B</userinput></entry>
 <entry>not-equals</entry>
 <entry>answer is <quote>true</quote> if <userinput>$A</userinput> does not equal <userinput>$B</userinput></entry>
 </row>
 <row>
 <entry><userinput>$A &gt; $B</userinput></entry>
 <entry>greater than</entry>
 <entry>answer is <quote>true</quote> if <userinput>$A</userinput> is greater than <userinput>$B</userinput></entry>
 </row>
 <row>
 <entry><userinput>$A &lt; $B</userinput></entry>
 <entry>smaller than</entry>
 <entry>answer is <quote>true</quote> if <userinput>$A</userinput> is smaller than <userinput>$B</userinput></entry>
 </row>
 <row>
 <entry><userinput>$A &gt;= $B</userinput></entry>
 <entry>greater than or equals</entry>
 <entry>answer is <quote>true</quote> if <userinput>$A</userinput> is greater than or equals <userinput>$B</userinput></entry>
 </row>
 <row>
 <entry><userinput>$A &lt;= $B</userinput></entry>
 <entry>smaller than or equals</entry>
 <entry>answer is <quote>true</quote> if <userinput>$A</userinput> is smaller than or equals <userinput>$B</userinput></entry>
 </row>
 </tbody>
 </tgroup>
 </table>
 Please note that <userinput>$A</userinput> and <userinput>$B</userinput> have to be <link linkend="number">numbers</link> or <link linkend="assignment-of-variables">variables</link> that contain numbers.</para>
 </sect2>
 
 
 </sect1>
 
 
 
 <sect1 id="commands">
 <title>Commands</title>
 <para>Using commands you tell the turtle or &kturtle; to do something. Some commands need input, some give output. In this section we explain all the built-in commands of &kturtle;. Alternatively, using <link linkend="learn"><userinput>learn</userinput></link>, you can create your own commands. Built-in commands we discuss here are <glossterm>highlighted</glossterm> with dark blue.</para>
 
 <sect2 id="moving-the-turtle">
 <title>Moving the turtle</title>
 <para>There are several commands to move the turtle over the screen.</para>
 
   <variablelist>
     <anchor id="forward" />
     <varlistentry> 
       <term>forward (fw)<indexterm><primary>forward (fw)</primary></indexterm></term>
       <listitem><para><screen>forward X</screen>
       <userinput>forward</userinput> moves the turtle forward by the amount of X pixels. When the pen is down the turtle will leave a trail. <userinput>forward</userinput> can be abbreviated to <userinput>fw</userinput>.</para></listitem>
     </varlistentry>
   </variablelist>
   <variablelist>
     <anchor id="backward" />
     <varlistentry>  
       <term>backward (bw)<indexterm><primary>backward (bw)</primary></indexterm></term>
       <listitem><para><screen>backward X</screen>
       <userinput>backward</userinput> moves the turtle backward by the amount of X pixels. When the pen is down the turtle will leave a trail. <userinput>backward</userinput> can be abbreviated to <userinput>bw</userinput>.</para></listitem>
     </varlistentry>
   </variablelist>
   <variablelist>
     <anchor id="turnleft" />
     <varlistentry> 
       <term>turnleft (tl)<indexterm><primary>turnleft (tl)</primary></indexterm></term>
       <listitem><para><screen>turnleft X</screen>
       <userinput>turnleft</userinput> commands the turtle to turn an amount of X degrees to the left. <userinput>turnleft</userinput> can be abbreviated to <userinput>tl</userinput>.</para></listitem>
     </varlistentry>
   </variablelist>
   <variablelist>
     <anchor id="turnright" />
     <varlistentry> 
       <term>turnright (tr)<indexterm><primary>turnright (tr)</primary></indexterm></term>
       <listitem><para><screen>turnright X</screen>
       <userinput>turnright</userinput> the turtle to turn an amount of X degrees to the right. <userinput>turnright</userinput> can be abbreviated to <userinput>tr</userinput>.</para></listitem>
     </varlistentry>
   </variablelist>
   <variablelist>
     <anchor id="direction" />
     <varlistentry> 
       <term>direction (dir)<indexterm><primary>direction (dir)</primary></indexterm></term>
       <listitem><para><screen>direction X</screen>
       <userinput>direction</userinput> set the turtle's direction to an amount of X degrees counting from zero, and thus is not relative to the turtle's previous direction. <userinput>direction</userinput> can be abbreviated to <userinput>dir</userinput>.</para></listitem>
     </varlistentry>
   </variablelist>
   <variablelist>
     <anchor id="getdirection" />
     <varlistentry> 
       <term>getdirection<indexterm><primary>getdirection</primary></indexterm></term>
       <listitem><para><screen>getdirection</screen>
       <userinput>getdirection</userinput> returns the turtle's direction as an amount of degrees counting from zero, where zero is the direction when the turtle is pointing upwards.</para></listitem>
     </varlistentry>
   </variablelist>
   <variablelist>
     <anchor id="center" />
     <varlistentry> 
       <term>center<indexterm><primary>center</primary></indexterm></term>
       <listitem><para><screen>center</screen>
       <userinput>center</userinput> moves the turtle to the center on the canvas.</para></listitem>
     </varlistentry>
   </variablelist>
   <variablelist>
     <anchor id="go" />
     <varlistentry> 
       <term>go<indexterm><primary>go</primary></indexterm></term>
       <listitem><para><screen>go X,Y</screen>
       <userinput>go</userinput> commands the turtle to go to a certain place on the canvas. This place is X <glossterm linkend="pixels">pixels</glossterm> from the left of the canvas, and Y <glossterm linkend="pixels">pixels</glossterm> from the top of the canvas.</para></listitem>
     </varlistentry>
   </variablelist>
   <variablelist>
     <anchor id="gox" />
     <varlistentry> 
       <term>gox<indexterm><primary>gox (gx)</primary></indexterm></term>
       <listitem><para><screen>gox X</screen>
       <userinput>gox</userinput> using this command the turtle will move to X <glossterm linkend="pixels">pixels</glossterm> from the left of the canvas whilst staying at the same height. <userinput>gox</userinput> can be abbreviated to <userinput>gx</userinput>.</para></listitem>
     </varlistentry>
   </variablelist>
   <variablelist>
     <anchor id="goy" />
     <varlistentry> 
       <term>goy<indexterm><primary>goy (gy)</primary></indexterm></term>
       <listitem><para><screen>goy Y</screen>
       <userinput>goy</userinput> using this command the turtle will move to Y <glossterm linkend="pixels">pixels</glossterm> from the top of the canvas whilst staying at the same distance from the left border of the canvas. <userinput>goy</userinput> can be abbreviated to <userinput>gy</userinput>.</para></listitem>
     </varlistentry>
   </variablelist>
   <note><para>Using the commands <userinput>go</userinput>, <userinput>gox</userinput>, <userinput>goy</userinput> and <userinput>center</userinput> the turtle will not draw a line, no matter if the pen is up or down.</para>
   </note>
 </sect2>
 
 <sect2 id="locate-the-turtle">
 <title>Where is the turtle?</title>
 <para>There are two commands which return the position of the turtle on the screen.</para>
 
   <variablelist>
     <anchor id="getx" />
     <varlistentry> 
       <term>getx<indexterm><primary>getx</primary></indexterm></term>
       <listitem><para>
       <userinput>getx</userinput> returns the number of pixels from the left of the canvas to the current position of the turtle.</para></listitem>
     </varlistentry>
   </variablelist>
   <variablelist>
     <anchor id="gety" />
     <varlistentry> 
       <term>gety<indexterm><primary>gety</primary></indexterm></term>
       <listitem><para>
       <userinput>gety</userinput> returns the number of pixels from the top of the canvas to the current position of the turtle.</para></listitem>
     </varlistentry>
   </variablelist>
 </sect2>
 
 <sect2 id="pen">
 <title>The turtle has a pen</title>
 <para>The turtle has a pen that draws a line when the turtle moves. There are a few commands to control the pen. In this section we explain these commands.</para>
   <variablelist>
     <anchor id="penup" />
     <varlistentry> 
       <term>penup (pu)<indexterm><primary>penup (pu)</primary></indexterm></term>
       <listitem><para><screen>penup</screen>
       <userinput>penup</userinput> lifts the pen from the canvas. When the pen is <quote>up</quote> no line will be drawn when the turtle moves. See also <userinput>pendown</userinput>. <userinput>penup</userinput> can be abbreviated to <userinput>pu</userinput>.</para></listitem>
     </varlistentry>
   </variablelist>
   <variablelist>
     <anchor id="pendown" />
     <varlistentry> 
       <term>pendown (pd)<indexterm><primary>pendown (pd)</primary></indexterm></term>
       <listitem><para><screen>pendown</screen>
       <userinput>pendown</userinput> presses the pen down on the canvas. When the pen is press <quote>down</quote> on the canvas a line will be drawn when the turtle moves. See also <userinput>penup</userinput>. <userinput>pendown</userinput> can be abbreviated to <userinput>pd</userinput>.</para></listitem>
     </varlistentry>
   </variablelist>
   <variablelist>
     <anchor id="setpenwidth" />
     <varlistentry> 
       <term>penwidth (pw)<indexterm><primary>penwidth (pw)</primary></indexterm></term>
       <listitem><para><screen>penwidth X</screen>
       <userinput>penwidth</userinput> sets the width of the pen (the line width) to an amount of X <glossterm linkend="pixels">pixels</glossterm>. <userinput>penwidth</userinput> can be abbreviated to <userinput>pw</userinput>.</para></listitem>
     </varlistentry>
   </variablelist>
   <variablelist>
     <anchor id="setfgcolor" />
     <varlistentry> 
       <term>pencolor (pc)<indexterm><primary>pencolor (pc)</primary></indexterm></term>
       <listitem><para><screen>pencolor R,G,B</screen>
       <userinput>pencolor</userinput> sets the color of the pen. <userinput>pencolor</userinput> takes an <glossterm linkend="rgb">RGB combination</glossterm> as input. <userinput>pencolor</userinput> can be abbreviated to <userinput>pc</userinput>.</para></listitem>
     </varlistentry>
   </variablelist>
 </sect2>
 
 <sect2 id="canvas">
 <title>Commands to control the canvas</title>
 <para>There are several commands to control the canvas.</para>
   <variablelist>
     <anchor id="resizecanvas" />
     <varlistentry>
       <term>canvassize (cs)<indexterm><primary>canvassize (cs)</primary></indexterm></term>
       <listitem><para><screen>canvassize X,Y</screen>
       With the <userinput>canvassize</userinput> command you can set the size of the canvas. It takes X and Y as input, where X is the new canvas width in <glossterm linkend="pixels">pixels</glossterm>, and Y is the new height of the canvas in <glossterm linkend="pixels">pixels</glossterm>. <userinput>canvassize</userinput> can be abbreviated to <userinput>cs</userinput>.</para></listitem>
     </varlistentry>
   </variablelist>
   <variablelist>
     <anchor id="setbgcolor" />
     <varlistentry> 
       <term>canvascolor (cc)<indexterm><primary>canvascolor (cc)</primary></indexterm></term>
       <listitem><para><screen>canvascolor R,G,B</screen>
       <userinput>canvascolor</userinput> set the color of the canvas. <userinput>canvascolor</userinput> takes an <glossterm linkend="rgb">RGB combination</glossterm> as input. <userinput>canvascolor</userinput> can be abbreviated to <userinput>cc</userinput>.</para></listitem>
     </varlistentry>
   </variablelist>
 </sect2>
 
 <sect2 id="clean">
 <title>Commands to clean up</title>
 <para>There are two commands to clean up the canvas after you have made a mess.</para>
   <variablelist>
     <anchor id="clear" />
     <varlistentry> 
       <term>clear (ccl)<indexterm><primary>clear (ccl)</primary></indexterm></term>
       <listitem><para><screen>clear</screen>
       With <userinput>clear</userinput> you can clean all drawings from the canvas. All other things remain: the position and angle of the turtle, the canvascolor, the visibility of the turtle, and the canvas size.</para></listitem>
     </varlistentry>
   </variablelist>
   <variablelist>
     <anchor id="reset" />
     <varlistentry> 
       <term>reset<indexterm><primary>reset</primary></indexterm></term>
       <listitem><para><screen>reset</screen>
       <userinput>reset</userinput> cleans much more thoroughly than the <userinput>clear</userinput> command. After a <userinput>reset</userinput> command everything is like is was when you had just started &kturtle;. The turtle is positioned at the middle of the screen, the canvas color is white, the turtle draws a black line on the canvas and the canvassize is set to 400 x 400 pixels.</para></listitem>
     </varlistentry>
   </variablelist>
 </sect2>
 
 <sect2 id="sprites">
 <title>The turtle is a sprite</title>
 <para>First a brief explanation of what sprites are: sprites are small pictures that can be moved around the screen, like we often see in computer games. Our turtle is also a sprite. For more info see the glossary on <glossterm linkend="sprites">sprites</glossterm>.</para>
 <para>Next you will find a full overview on all commands to work with sprites.</para>
 <note><para>The current version of &kturtle; does not yet support the use of sprites other than the turtle. With future versions you will be able to change the turtle into something of your own design.</para></note>
   <variablelist>
     <anchor id="spriteshow" />
     <varlistentry> 
       <term>spriteshow (ss)<indexterm><primary>spriteshow (ss)</primary></indexterm></term>
       <listitem><para><screen>spriteshow</screen>
       <userinput>spriteshow</userinput> makes the turtle visible again after it has been hidden. <userinput>spriteshow</userinput> can be abbreviated to <userinput>ss</userinput>.</para></listitem>
     </varlistentry>
   </variablelist>
   <variablelist>
     <anchor id="spritehide" />
     <varlistentry> 
       <term>spritehide (sh)<indexterm><primary>spritehide (sh)</primary></indexterm></term>
       <listitem><para><screen>spritehide</screen>
       <userinput>spritehide</userinput> hides the turtle. This can be used if the turtle does not fit in your drawing. <userinput>spritehide</userinput> can be abbreviated to <userinput>sh</userinput>.</para></listitem>
     </varlistentry>
   </variablelist>
 </sect2>
 
 <sect2 id="writing">
 <title>Can the turtle write?</title>
 <para>The answer is: <quote>yes</quote>. The turtle can write: it writes just about everything you command it to.</para>
   <variablelist>
     <anchor id="print" />
     <varlistentry> 
       <term>print<indexterm><primary>print</primary></indexterm></term>
       <listitem><para><screen>print X</screen>
       The <userinput>print</userinput> command is used to command the turtle to write something on the canvas. <userinput>print</userinput> takes numbers and strings as input. You can <userinput>print</userinput> various numbers and strings using the <quote>+</quote> symbol. See here a small example:
 <screen>
 $year = 2003
 $author = "Cies"
 print $author + " started the KTurtle project in " + $year + " and still enjoys working on it!"
 </screen>
       </para></listitem>
     </varlistentry>
   </variablelist>
   <variablelist>
     <anchor id="fontsize" />
     <varlistentry> 
       <term>fontsize<indexterm><primary>fontsize</primary></indexterm></term>
       <listitem><para><screen>fontsize X</screen>
       <userinput>fontsize</userinput> sets the size of the font that is used by <userinput>print</userinput>. <userinput>fontsize</userinput> takes one input which should be a number. The size is set in <glossterm linkend="pixels">pixels</glossterm>.</para></listitem>
     </varlistentry>
   </variablelist>
 </sect2>
 
 <sect2 id="math-commands">
 <title>Mathematical commands</title>
 <para>The following commands are &kturtle;'s more advanced mathematical commands.</para>
   <variablelist>
     <anchor id="round" />
     <varlistentry>
       <term>round<indexterm><primary>round</primary></indexterm></term>
       <listitem><para><screen>round(x)</screen>
       <userinput>round</userinput> the given number to the nearest integer.
 <screen>
 print round(10.8)
 forward 20
 print round(10.3)
 </screen>
       With this code the turtle will print the numbers 11 and 10.</para></listitem>
     </varlistentry>
   </variablelist>
   <variablelist>
     <anchor id="random" />
     <varlistentry> 
       <term>random (rnd)<indexterm><primary>random (rnd)</primary></indexterm></term>
       <listitem><para><screen>random X,Y</screen>
       <userinput>random</userinput> is a command that takes input and gives output. As input are required two numbers, the first (X) sets the minimum output, the second (Y) sets the maximum. The output is a randomly chosen number that is equal or greater than the minimum and equal or smaller than the maximum. Here a small example:
       <screen>
 repeat 500 {
   $x = random 1,20
   forward $x
   turnleft 10 - $x
 }
 </screen>
       Using the <userinput>random</userinput> command you can add a bit of chaos to your program.</para></listitem>
     </varlistentry>
   </variablelist>
   <variablelist>
     <anchor id="mod" />
     <varlistentry> 
       <term>mod<indexterm><primary>mod</primary></indexterm></term>
       <listitem><para><screen>mod X,Y</screen>
       The <userinput>mod</userinput> returns remainder of the division of first number by the second number.</para></listitem>
     </varlistentry>
   </variablelist>
   <variablelist>
     <anchor id="sqrt" />
     <varlistentry> 
       <term>sqrt<indexterm><primary>sqrt</primary></indexterm></term>
       <listitem><para><screen>sqrt X</screen>
       The <userinput>sqrt</userinput> command is sued to find the square root of a number, X.</para></listitem>
     </varlistentry>
   </variablelist>
 <!--
   <variablelist>
     <anchor id="exp" />
     <varlistentry> 
       <term>exp<indexterm><primary>exp</primary></indexterm></term>
       <listitem><para><screen>sqrt X</screen>
       </para></listitem>
     </varlistentry>
   </variablelist>
 -->
   <variablelist>
     <anchor id="pi" />
     <varlistentry> 
       <term>pi<indexterm><primary>pi</primary></indexterm></term>
       <listitem><para><screen>pi</screen>
       This command returns the constant Pi, <userinput>3.14159</userinput>.</para></listitem>
     </varlistentry>
   </variablelist>
   <variablelist>
     <anchor id="sin" />
     <anchor id="cos" />
     <anchor id="tan" />
     <varlistentry>
       <term>sin<indexterm><primary>sin</primary></indexterm>, cos<indexterm><primary>cos</primary></indexterm>, tan<indexterm><primary>tan</primary></indexterm></term>
       <listitem><para>
 <screen>
 sin X
 cos X
 tan X
 </screen>
       These three commands represent the world famous trigoniometrical functions <userinput>sin</userinput>, <userinput>cos</userinput> and <userinput>tan</userinput>. The input argument of these commands, X, is a <link linkend="number">number</link>.</para></listitem>
     </varlistentry>
   </variablelist>
   <variablelist>
     <anchor id="arcsin" />
     <anchor id="arccos" />
     <anchor id="arctan" />
     <varlistentry>
       <term>arcsin<indexterm><primary>arcsin</primary></indexterm>, arccos<indexterm><primary>arccos</primary></indexterm>, arctan<indexterm><primary>arctan</primary></indexterm></term>
       <listitem><para>
 <screen>
 arcsin X
 arccos X
 arctan X
 </screen>
       These commands are the inverse functions of <link linkend="sin">sin</link>, <link linkend="cos">cos</link> and <link linkend="tan">tan</link>. The input argument of these commands, X, is a <link linkend="number">number</link>.</para></listitem>
     </varlistentry>
   </variablelist>
 </sect2>
 
 <sect2 id="dialogs">
 <title>Input and feedback through dialogs</title>
 <para>A dialog is a small pop-up window that provides some feedback or asks for some input. &kturtle; has two commands for dialogs, namely: <userinput>message</userinput> and <userinput>ask</userinput></para>
   <variablelist>
     <anchor id="message" />
     <varlistentry> 
       <term>message<indexterm><primary>message</primary></indexterm></term>
       <listitem><para><screen>message X</screen>
       The <userinput>message</userinput> command takes a <link linkend="string">string</link> as input. It shows a pop-up dialog containing the text from the <link linkend="string">string</link>.
 <screen>
 message "Cies started KTurtle in 2003 and still enjoys working on it!"
 </screen>
       </para></listitem>
     </varlistentry>
   </variablelist>
   <variablelist>
     <anchor id="ask" />
     <varlistentry> 
       <term>ask<indexterm><primary>ask</primary></indexterm></term>
       <listitem><para><screen>ask X</screen>
       <userinput>ask</userinput> takes a <link linkend="string">string</link> as input.  It shows this string in a pop-up dialog (similar to <link linkend="message">message</link>), along with an input field.  After the user has entered a <link linkend="number">number</link> or a <link linkend="string">string</link> into this, the result can be stored in a <link linkend="assignment-of-variables">variable</link> or passed as an argument to a <link linkend="commands">command</link>. For example:
 <screen>
 $in = ask "What is your year of birth?"
 $out = 2003 - $in
 print "In 2003 you were " + $out + " years old at some point."
 </screen>
       If the user cancels the input dialog, or does not enter anything at all, the <link linkend="assignment-of-variables">variable</link> is empty.</para></listitem>
     </varlistentry>
   </variablelist>
 </sect2>
 
 </sect1>
 
 
 
 <sect1 id="assignment-of-variables">
 <title>Assignment of variables</title>
 <para>First we have a look at variables, then we look at assigning values to those variables.
 <!-- The final part of this section considers <link linkend="scoping">scoping of variables</link>. -->
 </para>
 
 <para>Variables are words that start with a <quote>$</quote>, in the <link linkend="the-editor">editor</link> they are <glossterm>highlighted</glossterm> with purple.</para>
 
 <para>Variables can contain any <link linkend="number">number</link>, <link linkend="string">string</link> or <link linkend="boolean-value">boolean (true/false) value</link>. Using the assignment, <userinput>=</userinput>, a variable is given its content. It will keep that content until the program finishes executing or until the variable is reassigned to something else.</para>
 
 <para>You can use variables, once assigned, just as if they are their content. For instance in the following piece of &turtlescript;:
 <screen>
 $x = 10
 $x = $x / 3
 print $x
 </screen>
 First the variable <userinput>$x</userinput> is assigned to <userinput>10</userinput>. Then <userinput>$x</userinput> is reassigned to itself divided by <userinput>3</userinput> &mdash; this effectively means <userinput>$x</userinput> is reassigned to product of <userinput>10 / 3</userinput>. Finally <userinput>$x</userinput> is printed. In line two and three you see that <userinput>$x</userinput> is used as if it is its contents.</para>
 
 <para>Variables have to be assigned in order to be used. For example:
 <screen>
 print $n
 </screen>
 Will result in an error message.</para>
 
 <para>Please consider the following piece of &turtlescript;:
 <screen>
 $a = 2004
 $b = 25
 
 # the next command prints "2029"
 print $a + $b
 backward 30
 # the next command prints "2004 plus 25 equals 2029"
 print $a + " plus " + $b + " equals " + ($a + $b)
 </screen>
 In the first two lines the variables <userinput>$a</userinput> and <userinput>$b</userinput> are set to 2004 and 25. Then in two <userinput>print</userinput> commands with a <userinput>backward 30</userinput> in between are executed. The comments before the <userinput>print</userinput> commands explain what they are doing. The command <userinput>backward 30</userinput> is there to make 
 sure every output is on a new line.
 As you see variables can be used just as if their where what they contain, you can use them with any kind of <link linkend="operators">operators</link> or give them as input when invoking <link linkend="commands">commands</link>.</para>
 
 <para>One more example:
 <screen>
 $name = ask "What is your name?"
 print "Hi " + $name + "! Good luck while learning the art of programming..."
 </screen>
 Pretty straight forward. Again you can see that the variable <userinput>$name</userinput>, treated just like a string.</para>
 
 <para>When using variables the <link linkend="the-inspector">inspector</link> is very helpful. It shows you the contents of all variables that are currently in use.</para>
 </sect1>
 
 
 
 <sect1 id="controlling-execution">
 <title>Controlling execution</title>
 <para>The execution controllers enable you &mdash; as their name implies &mdash; to control execution.</para>
 <para>Execution controlling commands are <glossterm>highlighted</glossterm> with dark green in a bold font type. The brackets are mostly used together with execution controllers and they are <glossterm>highlighted</glossterm> with black.</para>
 
 <sect2 id="wait">
 <title>Have the turtle wait</title>
 <para>If you have done some programming in &kturtle; you have might noticed that the turtle can be very quick at drawing. This command makes the turtle wait for a given amount of time.</para>
   <variablelist>
     <varlistentry>
       <term>wait<indexterm><primary>wait</primary></indexterm></term>
       <listitem><para><screen>wait X</screen>
       <userinput>wait</userinput> makes the turtle wait for X seconds.
 <screen>
 repeat 36 {
   forward 5
   turnright 10
   wait 0.5
 }
 </screen>
       This code draws a circle, but the turtle will wait half a second
       after each step. This gives the impression of a slow-moving turtle.</para></listitem>
     </varlistentry>
   </variablelist>
 </sect2>
 
 <sect2 id="if">
 <title>Execute <quote>if</quote></title>
   <variablelist>
     <varlistentry>
       <term>if<indexterm><primary>if</primary></indexterm></term>
       <listitem><para><screen>if <link linkend="boolean-value">boolean</link> { ... }</screen>
       The code that is placed between the brackets will only be executed <userinput>if</userinput> the <link linkend="boolean-value">boolean value</link> evaluates <quote>true</quote>.
       <screen>
 $x = 6
 if $x &gt; 5 {
   print "$x is greater than five!"
 }
 </screen>
       On the first line <userinput>$x</userinput> is set to 6. On the second line a <link linkend="comparing-operators">comparing operator</link> is used to evaluate <userinput>$x &gt; 5</userinput>. Since this evaluates <quote>true</quote>, 6 is larger than 5, the execution controller <userinput>if</userinput> will allow the code between the brackets to be executed.</para></listitem>
     </varlistentry>
   </variablelist>
 </sect2>
 
 <sect2 id="else">
 <title>If not, in other words: <quote>else</quote></title>
   <variablelist>
     <varlistentry>
       <term>else<indexterm><primary>else</primary></indexterm></term>
       <listitem><para><screen>if <link linkend="boolean-value">boolean</link> { ... } else { ... }</screen>
       <userinput>else</userinput> can be used in addition to the execution controller <link linkend="if"><userinput>if</userinput></link>. The code between the brackets after <userinput>else</userinput> is only executed if the <link linkend="boolean-value">boolean</link> evaluates <quote>false</quote>.
       <screen>
 reset
 $x = 4
 if $x &gt; 5 {
   print "$x is greater than five!"
 } else {
   print "$x is smaller than six!"
 }
 </screen>
       The <link linkend="comparing-operators">comparing operator</link> evaluates the expression <userinput>$x &gt; 5</userinput>. Since 4 is not greater than 5 the expression evaluates <quote>false</quote>. This means the code between the brackets after <userinput>else</userinput> gets executed.</para></listitem>
     </varlistentry>
   </variablelist>
 </sect2>
 
 <sect2 id="while">
 <title>The <quote>while</quote> loop</title>
   <variablelist>
     <varlistentry>
       <term>while<indexterm><primary>while</primary></indexterm></term>
       <listitem><para><screen>while <link linkend="boolean-value">boolean</link> { ... }</screen>
       The execution controller <userinput>while</userinput> is a lot like <link linkend="if"><userinput>if</userinput></link>. The difference is that <userinput>while</userinput> keeps repeating (looping) the code between the brackets until the <link linkend="boolean-value">boolean</link> evaluates <quote>false</quote>.
       <screen>
 $x = 1
 while $x &lt; 5 {
   forward 10
   wait 1
   $x = $x + 1
 }
 </screen>
       On the first line <userinput>$x</userinput> is set to 1. On the second line <userinput>$x &lt; 5</userinput> is evaluated. Since the answer to this question is <quote>true</quote> the execution controller <userinput>while</userinput> starts executing the code between the brackets until the <userinput>$x &lt; 5</userinput> evaluates <quote>false</quote>. In this case the code between the brackets will be executed 4 times, because every time the fifth line is executed <userinput>$x</userinput> increases by 1.</para></listitem>
     </varlistentry>
   </variablelist>
 </sect2>
 
 <sect2 id="repeat">
 <title>The <quote>repeat</quote> loop</title>
   <variablelist>
     <varlistentry>
       <term>repeat<indexterm><primary>repeat</primary></indexterm></term>
       <listitem><para><screen>repeat <link linkend="number">number</link> { ... }</screen>
       The execution controller <userinput>repeat</userinput> is a lot like <link linkend="while"><userinput>while</userinput></link>. The difference is that <userinput>repeat</userinput> keeps repeating (looping) the code between the brackets for as many times as the given number.</para></listitem>
     </varlistentry>
   </variablelist>
 </sect2>
 
 <sect2 id="for">
 <title>The <quote>for</quote> loop, a counting loop</title>
   <variablelist>
     <varlistentry>
       <term>for<indexterm><primary>for</primary></indexterm><indexterm><primary>to</primary></indexterm><indexterm><primary>step</primary></indexterm></term>
       <listitem><para><screen>for <link linkend="assignment-of-variables">variable</link> = <link linkend="number">number</link> to <link linkend="number">number</link> { ... }</screen>
       The <userinput>for</userinput> loop is a <quote>counting loop</quote>, &ie; it keeps count for you. The first number sets the variable to the value in the first loop. Every loop the number is increased until the second number is reached.
       <screen>
 for $x = 1 to 10 {
   print $x * 7
   forward 15
 }
 </screen>
      Every time the code between the brackets is executed the <userinput>$x</userinput> is increased by 1, until <userinput>$x</userinput> reaches the value of 10. The code between the brackets prints the <userinput>$x</userinput> multiplied by 7. After this program finishes its execution you will see the times table of 7 on the canvas.
      </para>
      <para>
      The default step size of a loop is 1, you can use an other value with
      <screen>for <link linkend="assignment-of-variables">variable</link> = <link linkend="number">number</link> to <link linkend="number">number</link> step <link linkend="number">number</link> { ... }</screen></para></listitem>
     </varlistentry>
   </variablelist>
 </sect2>
 
 <sect2 id="break">
 <title>Leave a loop</title>
   <variablelist>
     <varlistentry>
       <term>break<indexterm><primary>break</primary></indexterm></term>
       <listitem><para><screen>break</screen>
       Terminates the current loop immediately and transfers control to the statement immediately following that loop.</para></listitem>
     </varlistentry>
   </variablelist>
 </sect2>
 
 <sect2 id="exit">
 <title>Stop executing your program</title>
   <variablelist>
     <varlistentry>
       <term>exit<indexterm><primary>exit</primary></indexterm></term>
       <listitem><para><screen>exit</screen>
       Finishes the execution of your program.</para></listitem>
     </varlistentry>
   </variablelist>
 </sect2>
 
 <sect2 id="assert">
 <title>Checking assertions at runtime</title>
   <variablelist>
     <varlistentry>
       <term>assert<indexterm><primary>assert</primary></indexterm></term>
       <listitem><para><screen>assert <link linkend="boolean-value">boolean</link></screen>
       Can be used to reason about program or input correctness.
       <screen>
 $in = ask "What is your year of birth?"
 # the year must be positive
 assert $in > 0
 </screen></para></listitem>
     </varlistentry>
   </variablelist>
 </sect2>
 </sect1>
 
 
 <sect1 id="learn">
 
 <title>Create your own commands with <quote>learn</quote></title>
 <para><userinput>learn</userinput><indexterm><primary>learn</primary></indexterm> is special as it is used to create your own commands. The commands you create can take <glossterm linkend="input-output">input</glossterm> and return <glossterm linkend="input-output">output</glossterm>. Let us take a look at how a new command is created:
 <screen>
 learn circle $x {
   repeat 36 {
     forward $x
     turnleft 10
   }
 }
 </screen>
 The new command is called <userinput>circle</userinput>. <userinput>circle</userinput> takes one <glossterm linkend="input-output">input</glossterm> argument, to set the size of the circle. <userinput>circle</userinput> returns no <glossterm linkend="input-output">output</glossterm>. The <userinput>circle</userinput> command can now be used like a normal command in the rest of the code. See this example:
 <screen>
 learn circle $X {
   repeat 36 {
     forward $X 
     turnleft 10 
   }
 }
 
 go 200,200 
 circle 20
 
 go 300,200 
 circle 40  
 </screen>
 </para>
 <para>In the next example, a command with a return<indexterm><primary>return</primary></indexterm> value is created.
 <screen>
 learn faculty $x {
   $r = 1
   for $i = 1 to $x {
     $r = $r * $i
   }
   return $r
 }
 
 print faculty 5
 </screen>
 In this example a new command called <userinput>faculty</userinput> is created. If the input of this command is <userinput>5</userinput> then the output is <userinput>5*4*3*2*1</userinput>. By using <userinput>return</userinput> the <glossterm linkend="input-output">output</glossterm> value is specified and the execution is returned.</para>
 <para>Commands can have more than one <glossterm linkend="input-output">input</glossterm>. In the next example, a command that draws a rectangle is created:
 <screen>
 learn box $x, $y {
   forward $y
   turnright 90
   forward $x
   turnright 90
   forward $y
   turnright 90
   forward $x
   turnright 90
 }
 </screen>
 Now you can run <userinput>box 50, 100</userinput> and the turtle will draw a rectangle on the canvas. 
 </para>
   
 </sect1>
 
 </chapter>