********************************************************************** * * * Help for program turtle. * * * * * * * ********************************************************************** The Project Menu ---------------- Screen Mode ----------- Choose "Interlaced" for an interlaced screen, "Non-interlaced" for an ordinary hi-res screen. Current screen contents will be lost. Change Colours -------------- Choosing this item causes the appearance of a requester. Click on the colour you want to change and move the sliders to alter the red, green, and blue components of the colour. Click on "OK" to commit the changes, "Canc" to cancel them. Run Params ---------- Causes appearance of a requester which allows the run parameters to be changed. The parameters are: Foreground Pen : The pen colour drawings will take place in. Background Pen : The colour that "Clear Screen" will clear the screen to. X Position, Y Position : The current position; the screen is taken to be 640 x 512, whatever the screen mode, so the aspect ratio is 1:1 and the same drawing instructions will work for interlaced mode and non-interlaced mode. The top-left of the screen is 0,0, the bottom-right is 640,512. Heading : Direction in which the turtle is facing. Zero is upwards, 90 is to the right. Angle : The angle through which the turtle will turn when it turns left or right ('-' or '+'). Level : Number of expansions which will be applied to the initial run string. Line Length : Distance the turtle will move forward for each 'F' instruction. Some of these terms are more fully explained further on in this file, or in the tutorial. Algorithm --------- There is a choice of three different algorithms to do the string expansions: String ------ "String" fully expands the string at each level. It therefore has to allocate a lump of memory for each expansion, copy across the new string, and free the old memory. It performs all the expansions before it does any drawing. Recursive --------- This one works from the left of the string, expanding individual characters as far as they need to go, and drawing whenever a character needs no expansion or has been expanded to the bottom level. It is a recursive algorithm, so has a large number of nested subroutine calls; these use a lot of program stack, so the program may run out of stack space where there are a large number of expansions. Stack ----- A 'flat' version of the recursive algorithm: it uses its own stack instead of nesting subroutine calls, and so uses less stack space and is not dependent on program stack size. All three algoritms produce the same output. Their different approaches can be seen in turtle_algs.c in the source directory. Clear Screen ------------ Clears the screen to the background colour (see Run Params above). Help ---- You must know how to use this one. Quit ---- Exit the program. Files Menu ---------- Save Pic -------- Save the current picture as an IFF file. Edit File --------- Produces a file requester. Insert the name of the file you want to edit. The program should then invoke the editor which has its name in edit.bat. When you exit the editor, you will be returned to turtle. Run File -------- Produces a file requester. Insert the name of the file you want to run and press . Turtle will process the file and (hopefully) produce a drawing. If there are any errors in the file, a window will appear with the errors highlighted. The format of the run file is cunningly hidden under the heading 'Format of the Run File'. Rerun ----- The same as 'Run File' except that the selection doesn't produce a requester but uses the file name last entered using the 'Edit File' or 'Run File' menu options. --------------------------------------- How the Program Works --------------------- Turtle uses a run file to produce its drawings. The file is invoked using 'Run File' or 'Rerun' from the 'Files' menu. The run file is a text file, and can be edited using a text editor. Format of the Run File ---------------------- The run file contains three types of statement: Comments -------- The line starts with a '-'. The rest of the line is treated as a comment. Commands -------- Each command starts with a '#'. The commands are: #setpen(N) : Set Foreground pen colour to N. #cls(N) : Clear screen to colour N. #move(X,Y) : Move the turtle to screen position (X,Y). #set_heading(N): Set turtle heading to N. #set_angle(N) : Set the angle through which the turtle turns when it turns left or right ('-' or '+'). #set_level : set number of expansions which will be applied to the initial run string. #set_length(N) : set distance the turtle will move forward for each 'F' instruction. #text(STRING) : Output STRING (must be enclosed in double quotes) at current position. #run(STRING) : Start drawing, using STRING as the initial string. The string is not enclosed in quotes. Productions ----------- These are of the form: A=STRING where A is an alphabetic character. The production means that if we have a string, STR, which we are expanding, and STR includes the character 'A' in it, then all instances of 'A' are replaced with STRING. For example, given the production: B=AFFBA and the string which we are expanding: BFFXYBFF the outcome of the expansion is: AFFBAFFXYAFFBAFF ----- ----- String Expansion ---------------- Thus the program takes an initial string (given in the #run statement), a set of productions, and a level (set in the #set_level statement or by the Run Params menu item), and applies the productions to the initial string, level times, giving a final string which will go into the drawing process (actually for two of the algorithms, the expansion and drawing is interleaved, but the principles are the same). The Drawing Process ------------------- The input to the drawing process is the final string. Only certain characters in it are taken notice of; the rest are ignored. The characters of relevance are: 'F' : Move forward by length, drawing a line. 'f' : Move forward without drawing. '-' : Turn left. '+' : Turn right. '[' : Push turtle status (position and heading). ']' : Pop turtle status. Further explanations of how all this works can be found by choosing 'Files/Run' from the menus and entering 'tutorial'.