Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdeedu@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 822 insertions, 0 deletions

diff --git a/doc/kturtle/programming-reference.docbook b/doc/kturtle/programming-reference.docbook
new file mode 100644
index 00000000..12cd86db
--- /dev/null
+++ b/doc/kturtle/programming-reference.docbook
@@ -0,0 +1,822 @@
+<!--Dear translator: please NEVER translate the id or anything inside the tags as they are needed in english by the application
+     Thanks a lot in advance.-->
+<chapter id="reference">
+<title>&kturtle;'s &logo; Programming Reference</title>
+<para>This is the reference for the &kturtle;'s &logo;. In this chapter we first briefly touch all the <link linkend="different-instructions">different instruction types</link>. Then the <link linkend="commands">commands</link> are explained one by one. Then <link linkend="containers">containers</link>, <link linkend="math">math</link>, <link linkend="questions">questions</link> and <link linkend="controlling-execution">execution controllers</link> are explained. At last you are shown how to create you own commands with <link linkend="learn">learn</link>.</para>
+
+<sect1 id="different-instructions">
+<title>Different Instruction Types</title>
+<para>As in any language, LOGO has different types of words and symbols. Here the differences between the types are briefly explained.</para>
+
+<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>
+</para>
+<para>For a detailed overview of all commands that &kturtle; supports go <link linkend="commands">here</link>.</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>.
+</para>
+<para>Numbers can be used in <link linkend="math">mathematical calculations</link> and <link linkend="questions">questions</link>. They can also be put in <link linkend="containers">containers</link>.</para>
+<para>Numbers are <glossterm>highlighted</glossterm> with blue in the <link linkend="the-code-editor">code editor</link>.</para>
+</sect2>
+
+<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="containers">containers</link>. Yet they cannot be used in <link linkend="math">mathematical calculations</link> and <link linkend="questions">questions</link>.</para>
+<para>Strings are <glossterm>highlighted</glossterm> with dark red in the <link linkend="the-code-editor">code editor</link>.</para>
+</sect2>
+
+
+<sect2 id="name">
+<title>Names</title>
+<para>When using the &logo; programming language you create new things. If you write a program you will often need <link linkend="containers">containers</link> and in some cases you need <link linkend="learn">learn</link> to create new commands. When making a <link linkend="containers">container</link> or a new command with <link linkend="learn">learn</link> you will have to specify a name.</para>
+<para>You can choose any name, as long as it does not already have a meaning. For instance you cannot name a container <link linkend="forward">forward</link>, since that name is already used for a command, and thus has a meaning.
+<screen>
+# here forward is used as a container, but it already has a meaning
+# so this will produce an error:
+forward = 20
+
+# this works:
+forward 20
+</screen>
+Names can contain only letters, numbers and underscores (_). Yet they have to start with a letter. 
+</para>
+<para>
+Please read the documentation on <link linkend="containers">containers</link> and the <link linkend="learn">learn</link> command for a better explanation and more examples.
+</para>
+</sect2>
+
+<sect2 id="assignment">
+<title>Assignments</title>
+<para>Assignment are done with the <userinput>=</userinput> symbol. In programming languages it is better to read the single <userinput>=</userinput> not as 'equals' but as 'becomes'. The word 'equals' is more appropriate for the <userinput>==</userinput> which is a <link linkend="questions">question</link>.</para>
+<para>Assignments are generally use for two reasons, (1) to add content <link linkend="containers">containers</link>, and (2) to modify the content of a container. For example:
+<screen>
+x = 10
+# the container x now contains the number 10
+W = "My age is: "
+# the container W now contains the string "My age is: "
+# this prints the content of the containers 'W' and 'x' on the canvas
+print W + x
+</screen>
+</para>
+<para>For more examples see the section that explains <link linkend="containers">containers</link>.</para>
+</sect2>
+
+<sect2 id="math-symbols">
+<title>Math Symbols</title>
+<para>&kturtle; supports all basic math symbols: add (<userinput>+</userinput>), substract (<userinput>-</userinput>), multiply (<userinput>*</userinput>), divide (<userinput>/</userinput>) and the brackets <userinput>(</userinput> and <userinput>)</userinput>.</para>
+<para>For a complete explanation and more examples see the <link linkend="math">math</link> section.</para>
+</sect2>
+
+<sect2 id="question">
+<title>Questions</title>
+<para>We can ask simple questions on which the answer will be 'true' or 'false'.</para>
+<para>Using questions is extensively explained in the <link linkend="questions">questions</link> section.</para>
+</sect2>
+
+<sect2 id="questions-glue">
+<title>Question Glue-Words</title>
+<para>Questions can be glued together with so called 'question glue'. The glue words are <userinput>and</userinput>, <userinput>or</userinput>, and a special glue-word: <userinput>not</userinput>.</para>
+<para>Using question-glue is explained in the <link linkend="question-glue">Question Glue</link> section.</para>
+</sect2>
+
+
+<sect2 id="comment">
+<title>Comments</title>
+<para>Comments are lines that start with a <userinput>#</userinput>. For example:
+<screen>
+# this is a comment!
+print "this is not a comment"
+# the previous line is not a comment, but the next line is:
+# print "this is not a comment"
+</screen>
+We can add comments to the code for ourselves or for someone else to read. Comments are used for: (1) adding a small description to the program, (2) explaining how a piece of code works if it is a bit cryptic, and (3) to 'comment-out' lines of code that should be (temporarily) ignored (see the last line of the example).</para>
+<para>Commented lines are <glossterm>highlighted</glossterm> with dark yellow in the <link linkend="the-code-editor">code editor</link>.</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 commands that can be used in &kturtle;. Please note that all build in commands we discuss here are <glossterm>highlighted</glossterm> with dark green in the <link linkend="the-code-editor">code editor</link>, this can help you to distinguish them.</para>
+
+<sect2 id="moving-the-turtle">
+<title>Moving the turtle</title>
+<para>There are several commands to move the turtle over the screen.</para>
+  
+<sect3 id="forward">
+  <title>forward (fw)</title>
+  <variablelist>
+    <varlistentry> 
+      <term>forward</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>
+</sect3>
+<sect3 id="backward">
+  <title>backward (bw)</title>
+  <variablelist>
+    <varlistentry>  
+      <term>backward</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>
+</sect3>
+<sect3 id="turnleft">
+  <title>turnleft (tl)</title>
+  <variablelist>
+    <varlistentry> 
+      <term>turnleft</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>
+</sect3>
+<sect3 id="turnright">
+  <title>turnright (tr)</title>
+  <variablelist>
+    <varlistentry> 
+      <term>turnright</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>
+</sect3>
+<sect3 id="direction">
+  <title>direction (dir)</title>
+  <variablelist>
+    <varlistentry> 
+      <term>direction</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>
+</sect3>
+<sect3 id="center">
+  <title>center</title>
+  <variablelist>
+    <varlistentry> 
+      <term>center</term>
+      <listitem><para><screen>center</screen>
+      <userinput>center</userinput> moves the turtle to the center on the canvas.</para></listitem>
+    </varlistentry>
+  </variablelist>
+</sect3>
+<sect3 id="go">
+  <title>go</title>
+  <variablelist>
+    <varlistentry> 
+      <term>go</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> form the top of the canvas. Note that using the <userinput>go</userinput> command the turtle will not draw a line.</para></listitem>
+    </varlistentry>
+  </variablelist>
+</sect3>
+<sect3 id="gox">
+  <title>gox</title>
+  <variablelist>
+    <varlistentry> 
+      <term>gox</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.</para></listitem>
+    </varlistentry>
+  </variablelist>
+</sect3>
+<sect3 id="goy">
+  <title>goy</title>
+  <variablelist>
+    <varlistentry> 
+      <term>goy</term>
+      <listitem><para><screen>goy Y</screen>
+      <userinput>gox</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.</para></listitem>
+    </varlistentry>
+  </variablelist>
+</sect3>
+</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>
+<sect3 id="penup">
+  <title>penup (pu)</title>
+  <variablelist>
+    <varlistentry> 
+      <term>penup</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>
+</sect3>
+<sect3 id="pendown">
+  <title>pendown (pd)</title>
+  <variablelist>
+    <varlistentry> 
+      <term>pendown</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>
+</sect3>
+<sect3 id="setpenwidth">
+  <title>penwidth (pw)</title>
+  <variablelist>
+    <varlistentry> 
+      <term>penwidth</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>
+</sect3>
+<sect3 id="setfgcolor">
+  <title>pencolor (pc)</title>
+  <variablelist>
+    <varlistentry> 
+      <term>pencolor</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>
+</sect3>
+</sect2>
+
+<sect2 id="canvas">
+<title>Commands to control the canvas</title>
+<para>There are several commands to control the canvas.</para>
+<sect3 id="resizecanvas">
+  <title>canvassize (cs)</title>
+  <variablelist>
+    <varlistentry>
+      <term>canvassize</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>
+</sect3>
+<sect3 id="setbgcolor">
+  <title>canvascolor (cc)</title>
+  <variablelist>
+    <varlistentry> 
+      <term>canvascolor</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>
+</sect3>
+<sect3 id="wrapon">
+  <title>wrapon</title>
+  <variablelist>
+    <varlistentry> 
+      <term>wrapon</term>
+      <listitem><para><screen>wrapon</screen>
+      With the <userinput>wrapon</userinput> command you can set <glossterm linkend="wrapping">wrapping</glossterm> <quote>on</quote> for the canvas. Please see the glossary if you want to know what <glossterm linkend="wrapping">wrapping</glossterm> is.</para></listitem>
+    </varlistentry>
+  </variablelist>
+</sect3>
+<sect3 id="wrapoff">
+  <title>wrapoff</title>
+  <variablelist>
+    <varlistentry> 
+      <term>wrapoff</term>
+      <listitem><para><screen>wrapoff</screen>
+      With the <userinput>wrapoff</userinput> command you can set <glossterm linkend="wrapping">wrapping</glossterm> <quote>off</quote> for the canvas: this means the turtle can move off the canvas and can get <quote>lost</quote>. Please see the glossary if you want to know what <glossterm linkend="wrapping">wrapping</glossterm> is.</para></listitem>
+    </varlistentry>
+  </variablelist>
+</sect3>
+</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>
+<sect3 id="clear">
+  <title>clear (cr)</title>
+  <variablelist>
+    <varlistentry> 
+      <term>clear</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. <userinput>clear</userinput> can be abbreviated to <userinput>cr</userinput>.</para></listitem>
+    </varlistentry>
+  </variablelist>
+</sect3>
+<sect3 id="reset">
+  <title>reset</title>
+  <variablelist>
+    <varlistentry> 
+      <term>reset</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, and the turtle draws a black line on the canvas.</para></listitem>
+    </varlistentry>
+  </variablelist>
+</sect3>
+</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>
+<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>
+<sect3 id="spriteshow">
+  <title>show</title>
+  <variablelist>
+    <varlistentry> 
+      <term>show (ss)</term>
+      <listitem><para><screen>show</screen>
+      <userinput>show</userinput> makes the turtle visible again after it has been hidden. <userinput>show</userinput> can be abbreviated to <userinput>ss</userinput>.</para></listitem>
+    </varlistentry>
+  </variablelist>
+</sect3>
+<sect3 id="spritehide">
+  <title>hide (sh)</title>
+  <variablelist>
+    <varlistentry> 
+      <term>hide</term>
+      <listitem><para><screen>hide</screen>
+      <userinput>hide</userinput> hides the turtle. This can be used if the turtle does not fit in your drawing. <userinput>hide</userinput> can be abbreviated to <userinput>sh</userinput>.</para></listitem>
+    </varlistentry>
+  </variablelist>
+</sect3>
+</sect2>
+
+<sect2 id="writing">
+<title>Can the turtles write?</title>
+<para>The answer is: <quote>yes</quote>. The turtle can write: it writes just about everything you command it to.</para>
+<sect3 id="print">
+  <title>print</title>
+  <variablelist>
+    <varlistentry> 
+      <term>print</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>
+</sect3>
+<sect3 id="fontsize">
+  <title>fontsize</title>
+  <variablelist>
+    <varlistentry> 
+      <term>fontsize</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>
+</sect3>
+</sect2>
+
+<sect2 id="random">
+<title>A command that rolls dice for you</title>
+<para>There is one command that rolls dice for you, it is called <userinput>random</userinput>, and it is very useful for some unexpected results.</para>
+  <variablelist>
+    <varlistentry> 
+      <term>random</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 then 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>
+</sect2>
+
+<sect2 id="dialogs">
+<title>Input and feedback though 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>inputwindow</userinput></para>
+<sect3 id="message">
+  <title>message</title>
+  <variablelist>
+    <varlistentry> 
+      <term>message</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>
+year = 2003
+author = "Cies"
+print author + " started the KTurtle project in " + year + " and still enjoys working on it!"
+</screen>
+      </para></listitem>
+    </varlistentry>
+  </variablelist>
+</sect3>
+<sect3 id="inputwindow">
+  <title>inputwindow</title>
+  <variablelist>
+    <varlistentry> 
+      <term>inputwindow</term>
+      <listitem><para><screen>inputwindow X</screen>
+      <userinput>inputwindow</userinput> takes a <link linkend="string">string</link> as input. It shows a pop-up dialog containing the text from the string, just like the <link linkend="message">message</link>. But in addition to it also puts an input field on the dialog. Through this input filed the user can enter a <link linkend="number">number</link> or a <link linkend="string">string</link> which can be stored in a <link linkend="containers">container</link>. For example
+<screen>
+in = inputwindow "What is you age?"
+out = 2003 - in
+print "In 2003 you where " + out + " years old at some point."
+</screen>
+      When a user cancels the input dialog, or does not enter anything at all the <link linkend="containers">container</link> is emptied.</para></listitem>
+    </varlistentry>
+  </variablelist>
+</sect3>
+</sect2>
+
+</sect1>
+
+
+
+<sect1 id="containers">
+<title>Containers</title>
+<para>Containers are letters or words that can be used by the programmer to store a number or a text. Containers that contain a number are called <link linkend="variables">variables</link>, containers that can contain text are called <link linkend="string">string</link>.</para>
+
+<para>Containers that are not used contain nothing. An example:
+<screen>
+print N
+</screen>
+This will print nothing. If we try to do <link linkend="math">math</link> with empty containers we will get errors.
+</para>
+
+<sect2 id="variables">
+<title>Variables: number containers</title>
+<para>Let us start with an example:
+<screen>
+x = 3
+print x
+</screen>
+In the first line the letter <userinput>x</userinput> made into a variable (number container). As you see the value of the variable <userinput>x</userinput> is set to 3. On the second line the value is printed.</para>
+<para> Note that if we wanted to print an <quote>x</quote> that we should have written
+<screen>
+print "x"
+</screen>
+</para>
+<para>That was easy, now a bit harder example:
+<screen>
+A = 2004
+B = 25
+C = A + B
+
+# the next command prints "2029"
+print C
+backward 30
+# the next command prints "2004 plus 25"
+print A + " plus " + B
+backward 30
+# the next command prints "1979"
+print A - B
+</screen>
+In the first two lines the variables <userinput>A</userinput> and <userinput>B</userinput> are set to 2004 and 25. On the third line the variable <userinput>C</userinput> is set to <userinput>A + B</userinput>, which is 2029. The rest of the example consists of 3 <userinput>print</userinput> commands with <userinput>backward 30</userinput> in between. The <userinput>backward 30</userinput> is there to make sure every output is on a new line. In this example you also see that variables can be used in <link linkend="math">mathematical calculations</link>.</para>
+</sect2>
+
+<sect2 id="strings">
+<title>Containers that contain text (strings)</title>
+<para>In programming code the regular text is usually started and ended with quotes. As we have already seen:
+<screen>
+print "Hello programmer!"
+</screen>
+The regular is delimited with quotes. These pieces of regular text we call <link linkend="strings">strings</link>.</para>
+<para>Strings can also be stored in <link linkend="containers">containers</link> just like <link linkend="number">numbers</link>
+Strings are a lot like variables. The biggest difference is that they contain text in stead of numbers. For this reason strings cannot be used in <link linkend="math">mathematical calculations</link> and <link linkend="questions">questions</link>. An example of the use of strings:
+<screen>
+x = "Hello "
+name = inputwindow "Please enter your name..."
+print x + name + ", how are you?"
+</screen>
+On the first line the string <userinput>x</userinput> is set to <quote>Hello </quote>. On the second line the string <userinput>name</userinput> is set to the output of the <userinput>inputwindow</userinput> command. On the third line the program prints a composition of three strings on the canvas.</para>
+<para>This program ask you to enter your name. When you, for instance, enter the name <quote>Paul</quote>, the program prints <quote>Hello Paul, how are you?</quote>. Please note that the plus (+) is the only math symbol that you can use with strings.</para>
+</sect2>
+</sect1>
+
+<sect1 id="math">
+<title>Can the Turtle do math?</title>
+<para>Yes, &kturtle; will do your math. You can add (+), substract (-), multiply (*), and divide (/). Here is an example in which we use all of them:
+<screen>
+a = 20 - 5
+b = 15 * 2
+c = 30 / 30
+d = 1 + 1
+print "a: "+a+", b: "+b+", c: "+c+", d: "+d 
+</screen>
+Do you know what value a, b, c and d have? Please note the use of the <link linkend="assignment">assignment</link> symbol <userinput>=</userinput>.</para>
+<para>If you just want a simple calculation to be done you can do something like this:
+<screen>
+print 2004-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).</para>
+</sect1>
+
+<sect1 id="questions">
+<title>Asking questions, getting answers...</title>
+<para><link linkend="if"><userinput>if</userinput></link> and <link linkend="while"><userinput>while</userinput></link> are <link linkend="controlling-execution">execution controllers</link> that we will discuss in the next section. In this section we use the <link linkend="if"><userinput>if</userinput></link> command to explain questions.</para>
+<sect2 id="q">
+<title>Questions</title>
+<para>A simple example of a question:
+<screen>
+x = 6
+if x &gt; 5 [
+  print "hello"
+]
+</screen>
+
+In this example the question is the <userinput>x &gt; 5</userinput> part. If the answer to this question is 'true' the code between the brackets will be executed. Questions are an important part of programming and often used together with <link linkend="controlling-execution">execution controllers</link>, like <link linkend="if"><userinput>if</userinput></link>. All numbers and <link linkend="variables">variables</link> (number containers) can be compared to each other with questions.</para>
+<para>
+Here are all possible questions:
+<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-equal</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>
+</para>
+<para>Questions are <glossterm>highlighted</glossterm> with light blue in the <link linkend="the-code-editor">code editor</link>.</para> 
+</sect2>
+
+<sect2 id="question-glue">
+<title>Question Glue</title>
+<para>
+Question glue-words enable us to glue questions into one big question.
+<screen>
+a = 1
+b = 5
+if (a &lt; 5) and (b == 5) [
+  print "hello"
+]
+</screen>
+In this example the glue-word <userinput>and</userinput> is used to glue 2 questions (<userinput>a &lt; 5</userinput>, <userinput>b == 5</userinput>) together. If one side of the <userinput>and</userinput> would answer <quote>false</quote> the whole question would answer <quote>false</quote>, because with the glue-word <userinput>and</userinput> both sides need to be <quote>true</quote> in order to answer <quote>true</quote>. Please do not forget to use the brackets around the questions!</para>
+
+<para>
+Here is a schematic overview; a more detailed explanation follows below:
+<table>
+<title>Question glue-words</title>
+<tgroup cols="2">
+<tbody>
+<row>
+<entry><userinput>and</userinput></entry>
+<entry>Both sides need to be 'true' in order to answer 'true'</entry>
+</row>
+<row>
+<entry><userinput>or</userinput></entry>
+<entry>If one of the sides is 'true' the answer is 'true'</entry>
+</row>
+<row>
+<entry><userinput>not</userinput></entry>
+<entry>Special case: only works on one question! Changes 'true' into 'false' and 'false' into 'true'.</entry>
+</row>
+</tbody>
+</tgroup>
+</table>
+</para>
+<para>Question glue-words are <glossterm>highlighted</glossterm> with purple in the <link linkend="the-code-editor">code editor</link>.</para>
+
+<sect3 id="and">
+<title>and</title>
+<para>When two questions are glued together with <userinput>and</userinput>, both sides of the <userinput>and</userinput> have to be 'true' in order to result in 'true'. An example:
+<screen>
+a = 1
+b = 5
+if ((a &lt; 10) and (b == 5)) and (a &lt; b) [
+  print "hello"
+]
+</screen>
+In this example you see a glued question glued onto an other question.</para>
+</sect3>
+
+<sect3 id="or">
+<title>or</title>
+<para>If one of the two questions that are glued together with <userinput>or</userinput> is 'true' the result will be 'true'. An example:
+<screen>
+a = 1
+b = 5
+if ((a &lt; 10) or (b == 10)) or (a == 0) [
+  print "hello"
+]
+</screen>
+In this example you see a glued question glued onto an other question.</para>
+</sect3>
+
+<sect3 id="not">
+<title>not</title>
+<para><userinput>not</userinput> is a special question glue-word because it only works for one question at the time. <userinput>not</userinput> changes 'true' into 'false' and 'false' into 'true'. An example:
+<screen>
+a = 1
+b = 5
+if not ((a &lt; 10) and (b == 5)) [
+  print "hello"
+]
+else
+[
+  print "not hello ;-)"
+]
+</screen>
+In this example the glued question is 'true' yet the <userinput>not</userinput> changes it to 'false'. So in the end <userinput>"not hello ;-)"</userinput> is printed on the <link linkend="the-canvas">canvas</link>.</para>
+</sect3>
+
+</sect2>
+
+</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 square brackets are mostly used together with execution controllers and they are <glossterm>highlighted</glossterm> with light green.</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</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 "if"</title>
+  <variablelist>
+    <varlistentry>
+      <term>if</term>
+      <listitem><para><screen>if <link linkend="questions">question</link> [ ... ]</screen>
+      The code that is placed between the brackets will only be executed <userinput>if</userinput> the answer to the <link linkend="questions">question</link> is <quote>true</quote>. Please read for more information on <link linkend="questions">questions</link> in the <link linkend="questions">question section</link>.
+      <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 the <link linkend="questions">question</link> <userinput>x &gt; 5</userinput> is asked. Since the answer to this question is <quote>true</quote> the execution controller <userinput>if</userinput> will allow the code between the brackets to be executed</para></listitem>
+    </varlistentry>
+  </variablelist>
+</sect2>
+
+<sect2 id="while">
+<title>The "while" loop</title>
+  <variablelist>
+    <varlistentry>
+      <term>while</term>
+      <listitem><para><screen>while <link linkend="questions">question</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 answer to the <link linkend="questions">question</link> is <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 the <link linkend="questions">question</link> <userinput>x &lt; 5</userinput> is asked. 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 answer to the <link linkend="questions">question</link> is <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="else">
+<title>If not, in other words: "else"</title>
+  <variablelist>
+    <varlistentry>
+      <term>else</term>
+      <listitem><para><screen>if question [ ... ] 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 answer to the <link linkend="questions">question</link> that is asked is <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="questions">question</link> asks if <userinput>x</userinput> is greater than 5. Since <userinput>x</userinput> is set to 4 on the first line the answer to the question is <quote>false</quote>. This means the code between the brackets after <userinput>else</userinput> gets executed.</para></listitem>
+    </varlistentry>
+  </variablelist>
+</sect2>
+
+<sect2 id="for">
+<title>The "for" loop, a counting loop</title>
+  <variablelist>
+    <varlistentry>
+      <term>for</term>
+      <listitem><para><screen>for <userinput>start point</userinput> to <userinput>end point</userinput> [ ... ]</screen>
+      The <userinput>for</userinput> loop is a <quote>counting loop</quote>, &ie; it keeps count for you.
+      <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></listitem>
+    </varlistentry>
+  </variablelist>
+</sect2>
+
+</sect1>
+
+
+<sect1 id="learn">
+<title>Create your own commands with <quote>learn</quote></title>
+<para><userinput>learn</userinput> is a very special command, because it is used to create your own commands. The command 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>, a number, 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 30,30 
+circle 20
+
+go 40,40 
+circle 50  
+</screen>
+</para>
+<para>In the next example, a command with a return value is created.
+<screen>
+reset
+
+learn multiplyBySelf n [
+  r = n * 1
+  r = n * n
+  return r
+]
+i = inputwindow "Please enter a number and press OK"
+print i + " multiplied by itself is: " + multiplyBySelf i
+</screen>
+In this example a new command called <userinput>multiplyBySelf</userinput> is created. The input of this command is multiplied by itself and then returned, using the <anchor id="return" /><userinput>return</userinput> command. The <userinput>return</userinput> command is the way to output a value from a function you have created.
+</para>
+</sect1>
+
+</chapter>