1
;; tutorial.lg -- TUTORIAL for logo-mode
3
;; YOU SHOULD READ THE TEXT AND CARRY OUT THE ACTIONS INDICATED HEREIN
4
;; ===================================================================
6
;; First I'll assume that you have a 3 button mouse, and will call the
7
;; buttons; mouse-1, mouse-2, and mouse-3 -- starting from left.
9
;; Now click mouse-1 on the `Logo-start' menu (menu-bar top right),
10
;; and choose `Run Logo Other Frame'. (If you have already started and
11
;; tested ucblogo/logo-mode installation, then skip to TUTORIAL.)
13
;; This should pop-up a new emacs frame with title *logo*, and Logo
14
;; should greet you in it with:
16
;; Welcome to Berkeley Logo version 5.1
19
;; If you can see this, then both Logo and emacs logo-mode, are probably
20
;; properly installed. Let's test one more thing. Position the cursor on
21
;; the line of Logo code (below) that starts with `ct repeat 120 [...'
22
;; and hit C-x C-e (Control-x Control-e).
24
ct repeat 120 [setcursor list random 75 random 23 type standout cursor]
26
;; You should see 120 pairs of highlighted numbers appear scattered in
27
;; *logo* frame. If there were no beeps and error messages, you have a
28
;; working version of logo-mode.
33
;; You write logo programs in this window (frame), which I will refer to
34
;; as edit buffer, to distinguish it from the other window which I will
37
;; Let's clean the logo buffer (from scattered numbers) first. Move the
38
;; focus to logo buffer (make it active), write ct (Logo command
39
;; CLEARTEXT), and press Enter. Depending on the focus policy of your
40
;; Window Manager (basically, there are two -- click-to-focus and
41
;; focus-follows-pointer) you may have heard a beep when you wrote the
42
;; first letter (c). Not to worry, this was just emacs telling you that
43
;; you started writing out of Logo command line. The reason is that you
44
;; had to click the window to give it focus, which also shifted the
45
;; cursor away from Logo command line. (That's why I prefer focus follows
46
;; pointer policy -- no clicking is necessary.) You can also return to
47
;; Logo command line by pressing C-l (Control-l).
49
;; Now we can start with one graphical example:
50
;; Actually, you should be writing this, but I'll do it -- for now.
52
to spiro :side :angle :step :limit
53
if :side > :limit [stop]
56
spiro sum :side :step :angle :step :limit
59
;; Position the cursor (cursor is not the I beam showing current mouse
60
;; position) somewhere on the definition of procedure spiro (above). It
61
;; doesn't really matter where, as long as it is between the `t' (of
62
;; `to') and the first empty line below 'end'. Now press C-M-x (left
63
;; Control-Alt-x or Control-Meta-x). This will send the definition of
64
;; procedure spiro to Logo, and Logo will acknowledge that by writing
65
;; new prompt (? ) on a new line.
68
;;; The key-chord C-M-x (Ctrl-Alt-x) will not always work, and as it is
69
;;; the most frequently used keyboard shortcut (much faster than using
70
;;; Send Definition from Logo-send menu), additional instructions are in
71
;;; order. Some window managers (KDE 2.1 for instance) use this same
72
;;; combination for their own purposes, and will therefore intercept this
73
;;; key-chord. You can still use Esc C-x combination (Esc always works in
74
;;; the place of Meta or Alt key), but this is much slower that C-M-x. The
75
;;; only way to restore the functionality of C-M-x in logo mode is to
76
;;; disable this key combination in the KDE Control Center.
78
;; Then shift the focus to logo buffer and write (in logo buffer) this
81
spiro 1 121 2 160 ;(and press Enter -- I will not repeat this again)
83
;; Logo popped up a new window (black) where the turtle did it's thing.
85
;; Then continue in logo buffer:
87
;; setpc 4 (sets the pen color to red)
90
;; And now one important instruction -- say you would like to run spiro
91
;; again, but with changed inputs:
93
;; press (still in logo buffer) M-p (left Alt-p), and the last command
94
;; you entered will appear (in this case `spiro 1 91 2 160'). (If you get
95
;; an error message instead, then you are not on the command line -- just
96
;; hit C-l and repeat M-p.) Then press again M-p (`setpc 4' will appear), and
97
;; again. Now we have the command line we want (spiro 1 121 2 160). Place
98
;; the cursor on `0' of `160' and change the command line into
101
;; You can hit Enter anywhere on the command line (in this case if you
102
;; edited the line backwards, you would end with cursor on `2'), and Logo
103
;; will respond by drawing a new pattern in graphics window.
105
;; Try to retrieve the `setpc 4' command by pressing M-p repeatedly. If you
106
;; overshoot, you can also move back in command-line history with M-n
107
;; (Alt-n). When you have found it, change the 4 to 7 and hit Enter on it to
108
;; change the pen color back to white.
111
;; Now, you should be ready to work on your own:
112
;; Try to write a procedure `triangle' (that draws a triangle) in the
113
;; space below. (I have started it.)
119
;; When you have completed it, send it to Logo (C-M-x), and run it
120
;; (from logo buffer) with -- say `triangle 120' .
122
;; So far I have mostly explained how to send a procedure definition from
123
;; edit buffer to Logo. Now we are going to look at some other
126
;; You can send from edit buffer command lines as well. Take a look at
127
;; those instruction lines below.
131
repeat 4 [fd 100 rt 90]
133
;; Place the cursor, and press C-x C-e on each one. Every time, when you
134
;; sent the line, Logo responded with showing another prompt in logo
135
;; buffer (? ), but also carrying out the instruction in graphics window.
136
;; Therefore instead of a triangle (from the previous example) we see a
139
;; This is rather slow, so there is a faster way as well. We can send a
140
;; whole region to Logo. First change slightly the repeat command. Change
141
;; 100 into 50. Then place the cursor on the blank line above `cs' and
142
;; drag mouse-1 to below `repeat 4 [fd 50 rt 90]'. This will highlight
143
;; the region. Now press C-c r (or C-c C-r) and emacs will send the
144
;; marked region to Logo. Logo will react by drawing a smaller square.
145
;; However, note that sending commands are designed primarily to send
146
;; procedure definitions to Logo. Giving Logo direct instructions is
147
;; easier from logo buffer.
149
;; There are several other commands for sending (communication with
150
;; Logo). One of more important is `C-c b' or `C-c C-b', which sends the
151
;; whole buffer. This is the command you would normally use when you open
152
;; a new source file, and want to send the contents to Logo. To check
153
;; all communication commands click on the `Logo-send' menu on the menu
154
;; bar of edit buffer. You will notice there several send commands that end
155
;; with `... & Go'. These are here for archaic reasons only, and will work
156
;; only if you started Logo with `Run Logo Other Window' or `Run Logo Same
157
;; window'. If you followed the instructions to start Logo in `Other Frame'
158
;; (which is the most convenient and safe way) than you still have to shift
159
;; the focus manually (with the mouse).
161
;; Writing Logo source code in edit buffer is relatively comfortable,
162
;; because logo-mode recognizes Logo syntax and will automatically mark
163
;; (flash) delimiters `({[', and will not get confused by a single ". It
164
;; also knows about Logo syntax for strings `||', so delimiters inside ||
165
;; will not be marked. It will also automatically indent Logo code
166
;; (according to the indenting style set forth by Brian's CSLS books).
168
;; This indenting business can cause some confusion at first as Enter and
169
;; Tab keys may seem to be malfunctioning. Enter (Return) is bound to
170
;; newline-and-indent command, so it will insert newline (which everybody
171
;; expects) but will also indent the new line if the surrounding code
172
;; warrants that. To understand this, place the cursor at the end of the
173
;; line (below), after `... I hope]]' but before `)' and press Enter.
175
(if "false [print [This will not be printed -- I hope]] )
177
;; The cursor and `)' will drop one line down, but not flush
178
;; left. Instead cursor will be under `"' in `"false'. That is because
179
;; this line is now implicitly continued (all delimiters are not closed
180
;; as we just dropped down the closing `)' ).
181
;; Now (still at the same position) write this:
182
;; [print [This will be printed]]
183
;; The closing `)' should remain to the right of last `]]'.
185
;; This looks like two lines now, but to Logo it is only one. To check
186
;; this -- with the cursor on any of these "two physical" lines press C-x
187
;; C-e. Logo will respond by printing (in logo buffer)
189
;; This will be printed
192
;; If you press Tab on any of these two physical lines, nothing will
193
;; happen. Lines are properly indented, and there is nothing for Tab to
194
;; do. To show you that Tab does work, take a look at the same two lines
197
(if "false [print [This will not be printed -- I hope]]
198
[print [This will be printed]])
200
;; Now press Tab on both of them (first on the top line). They will
203
;; There are several other options available for editing. To see them,
204
;; click on the `Logo-edit' menu. The last three (accessed through
205
;; Preferences submenu), actually, have nothing to do with editing --
206
;; but I had to stick them somewhere :-). `Toggle Syntax
207
;; Highlighting' should be self explanatory. Click on it, and this
208
;; text will revert to default text face -- no coloring. As syntax
209
;; highlighting is actually useful when working through this tutorial
210
;; (makes it easier to see what is tutorial text, and what is Logo
211
;; code), click again on `Toggle Syntax Highlighting' to restore it.
213
;; `Toggle Novice Management' menu option takes a bit more explaining.
214
;; I have disabled several standard emacs commands, that I feel could cause
215
;; either the loss of source code, confusion, or simply frustration of
216
;; a novice user. Emacs has an overwhelming number of commands (heck,
217
;; I probably know less than 1/10), and some are freely available
218
;; on the menu-bar. Let's try one disabled command. Click on Files menu,
219
;; and choose `Kill Current Buffer' option. This window will split in two,
220
;; with information about invoked command showing in lower part. Read what
221
;; it says, and then press N . That would always be the safest course of
222
;; action, unless you are absolutely sure of what you're doing. If you
223
;; really want to execute the command press Space. And, of-course, if
224
;; you are not a novice emacs user, and all this annoys you -- click on
225
;; `Toggle Novice Management' to get rid of it.
227
;;`Toggle Abbreviation Expansion' menu disables or enables the Logo
228
;; common abbreviation expansion. Current state of abbreviation
229
;; expansion is visible on the mode line; if it reads (Logo), expansion
230
;; is disabled, if it reads (Logo Abbrev) it is enabled. To see how
231
;; expansion works, place the cursor directly after the FD on the next
232
;; line of Logo code.
236
;; Then press space, and fd will expand to forward (with the space
237
;; added after it. To disable expansion (just once), restore the line,
238
;; place the cursor after FD again, hit escape, and then space. Space
239
;; will be added, but no expansion will have happened. Expansion works
240
;; when any of the following characters is entered after the word that
241
;; constitutes one of Logo abbreviations: space, newline, ], ), and
242
;; }. If you do not want the current abbreviation expanded, all of the
243
;; trigger characters can be escaped (just like space).
245
;; One of the nice features of logo-mode is that it allows
246
;; simultaneous editing of two or more source files. To test this
247
;; click on `Files' menu on the menu-bar of edit buffer, and choose
248
;; `Logo-mode Files>>Open Logo File...'. Emacs will pop a new frame
249
;; and drop it in dired (directory) mode. There you can either choose
250
;; an existing source file (by clicking mouse-2 on it) or use
251
;; `Files>>Open File...' menu to create a new source file. If you
252
;; create new file, do not forget to name it `some-name.lg'. Without
253
;; `.lg' extension, new file will not be opened in logo-mode.
254
;; However if you forgot (.lg extension), or you opened Logo source
255
;; file that neither has the extension, nor Logo mode-line as the
256
;; first line, use `Files>>Logo-mode Files>>Convert to Logo-mode'
257
;; choice from the pull-down menu. (Only files opened in fundamental
258
;; mode can be converted.)
260
;; Do this now. (Click on `Files>>Logo-mode Files>>Open Logo File...'
261
;; and open tutor1.lg file.)
263
;; Now (with focus on tutor1.lg buffer) send the whole buffer to Logo with
264
;; C-c C-b . Logo will respond with new (? ) prompt.
266
;; Before we try to run queens or insert.sort procedures, take a close
267
;; look at this code. If you were going to say that it doesn't really
268
;; look like standard Logo, you would be right. To execute this, we
269
;; must load .loops extensions. Click on `LOOPS' pull-down menu in
270
;; *logo* buffer and choose `Language>>Ucblogo + LOOPS'. Logo will
273
;; ? ALLOWGETSET and UNBURYONEDIT disabled
274
;; loading LOOPS ... Lisp layer OK ... OOP layer OK
277
;; Just a brief explanation of what happened with this `loading LOOPS
278
;; ...'. We have loaded .loops initialization file which -- technically
279
;; speaking is not part of standard Berkeley Logo, and most users will
280
;; not need, nor appreciate the changes introduced with it. I insist
281
;; on loading it now, as it is needed to work through this part of
282
;; tutorial. When you start Logo next time, you do not have to load
283
;; it, and if you want to get rid of it completely, uncomment one line
284
;; in your .emacs file. (To understand fully what LOOPS does, check
285
;; the `LOOPS User Manual' in `Help>>Logo-Help' menu. BTW -- it stands
286
;; for Logo Object Oriented Programming System.)
288
;; You can test the insert-sort program now by sending the following
289
;; line (below) to Logo with C-x C-e .
291
show insert.sort [5 4 3 111 22]
293
;; This was running very slowly. To improve the performance, you have
294
;; to compile both insert.sort, and queens procedures. To do that,
295
;; click on `Logo' menu in logo buffer and choose
296
;; `Compiler>>Compile Workspace'. Logo will respond with:
298
;; compiling insert.sort ... OK
299
;; compiling queens ... OK
300
;; compiling spiro ... nothing to do for spiro
301
;; compiling triangle ... nothing to do for triangle
302
;; compilation completed
305
;; Try insert-sort again. Mark the line `show insert.sort [...'
306
;; (above) by dragging mouse-1 over it and then yank it back (paste
307
;; it) by pressing mouse-2 in logo buffer (press Enter after
308
;; that). Of-course -- you would normally use this way (pasting) to
309
;; copy from other applications running on your X display. This time,
310
;; sort was running much faster.
312
;; Try running `queens' program. Enter `(queens 6 "false)' in logo
313
;; buffer. Logo will respond with:
315
;; position 1 [2 4 6 1 3 5]
316
;; position 2 [3 6 2 5 1 4]
317
;; position 3 [4 1 5 2 6 3]
318
;; position 4 [5 3 1 6 4 2]
321
;; If you want to run insert.sort program on a changed input list, (instead
322
;; of using M-p repeatedly) you can press and hold shift key, and press
323
;; mouse-2 button (anywhere in logo buffer). This will pop `Setcursor Menu'.
324
;; Drag the pointer to `List Input History' and release it on
325
;; `show insert.sort [5 4 3 111 22]' entry. This will copy that input
326
;; line to logo buffer.
328
;; If you want to save compiled versions of insert.sort and queens,
329
;; click on `Logo' menu in logo buffer and choose `Compiler>>Save
330
;; compiled procedures ...'. Logo will ask -- `Enter file name to
331
;; save to: '. Input any name you wish (but end it with .lgo) and hit
332
;; enter. (You do not have to quote the name, but it doesn't hurt if
333
;; you do.) To inspect the compiled code, you can open just saved file
334
;; using the same procedure as before: Click on `Files>>Logo-mode
335
;; Files>>Open Logo File...'
337
;; To avoid possible misunderstandings about compiling Logo code, you
338
;; should realize two facts: One -- you can compile only procedures
339
;; that use LOOPS extensions (LETREC, COND, and CASE), and two --
340
;; compiled code is just a standard Logo source code, that runs at the
341
;; same speed as if it were hand written in standard Logo.
343
;; If you don't need LOOPS extensions any more, you can restore
344
;; standard ucblogo by clicking on `LOOPS' menu and choosing
345
;; `Language>>Standard Ucblogo'. Logo will respond with:
347
;; ? Standard Berkeley Logo restored.
350
;; With standard language restored, you can't run insert.sort any
351
;; more. If you try, Logo will respond with an error message. If by
352
;; any chance you want to work with LOOPS extensions most of the time,
353
;; you can change the language again to `ucblogo + LOOPS' and click
354
;; on `LOOPS>>Language>>Set Startup Default' menu. This will force emacs
355
;; to load LOOPS extensions every time you start Logo. Of-course you
356
;; can `Set Startup Default' to Standard Ucblogo the same way.
361
;; With focus in the second edit buffer (tutor1.lg), click with
362
;; mouse-3 on the Logo command `foreach' (second line in the procedure
363
;; `queens'). The tutor1.lg buffer will disappear and help file for
364
;; `foreach' will show instead. To return to tutor1.lg buffer press
365
;; `q' in help buffer. If you want to see all procedures that ucblogo
366
;; has help for, click on `Help' menu in edit buffer, and choose
367
;; Logo-help>>Help Contents. This buffer will disappear and
368
;; HELPCONTENTS file will open. There, you can click on any name to
369
;; show help for that procedure. To return here press `q' in
370
;; HELPCONTENTS buffer.
372
;; If you want to read ucblogo user manual (in TeX-info format), click on
373
;; `Help' menu and choose Logo-help>>User Manual. You move through
374
;; user-manual by clicking mouse-2 on links (words that change color when
375
;; mouse pointer is over them). To exit user-manual, press `q'.
377
;; Another form of help are completion facilities. Focus tutor1.lg
378
;; buffer, move to the end of the file and write letters `ins' . Then
379
;; (with the cursor just after s) hit M-/ (Alt-/ or ESC /). Letters
380
;; `ins' will expand to insert. Hit M-/ again, and completion will
381
;; change to insert.sort, hit again ... Emacs will find all possible
382
;; completions for word `ins' that exist in tutor1.lg and tutorial.lg
383
;; buffers. If there are many completions, a faster way of choosing is
384
;; by hitting C-M-/ (Ctrl-Alt-/ or ESC Ctrl-/) after the word
385
;; `ins'. Emacs will open a window with all completions listed. Click
386
;; mouse-2, on the one you want, and letters `ins' will expand to the
387
;; chosen word. In our current situation (with tutorial.lg buffer
388
;; present) emacs will find a lot of useless completion words like
389
;; installation, insist, but that is only because tutorial.lg buffer
390
;; consists mostly of English text, and not of Logo code. In a real
391
;; logo source buffer, you will mostly get previously defined names of
392
;; procedures and variables, which is what you probably want.
394
;; The second form of completion facilities is completion for Logo
395
;; defined keywords (names of primitive and library procedures). Again
396
;; in tutor1.lg buffer, clear any previous completions of `ins' , and
397
;; write letters `set' (with the cursor just after t) hit ESC TAB . Emacs
398
;; will open a window with the listing of all possible keyword
399
;; completions. Click with mouse-2 on the one you want, and `set' will
400
;; expand to that keyword.
402
;; Interactive TRACE STEP and ERASE (choosing)
403
;; In logo buffer click on `Logo' menu and choose Logo-debug>>Trace...
404
;; You will get a buffer with three regions:
408
;; insert.sort queens spiro triangle
416
;; Here we have four defined procedures (insert.sort ... spiro
417
;; triangle). If we click on any one of them, we will mark that
418
;; procedure for tracing. Mouse-1 chooses the pointed procedure,
419
;; deselects everything else. Mouse-2 toggles selection for pointed
420
;; procedure. Mouse-3 chooses the pointed procedure, sends all
421
;; selected procedures to Logo, and exits debug buffer. To quit debug
422
;; mode, you can also press `q'. This also sends selected procedures
423
;; to Logo. All mouse actions are confirmed by highlighting relevant
424
;; procedure names. If you open debug buffer again, all procedures
425
;; that were selected (for tracing or stepping) before, will be
426
;; highlighted (and placed in parentheses).
428
;; Try this now. Click on `Logo>>Logo-debug>>Erase...' menu. Read the
429
;; mode-line of this buffer. It should say: (Fundamental Logo-ERASE
430
;; View). This is just to make sure that you don't choose procedures
431
;; for tracing or stepping, while you're actually erasing them. Click
432
;; mouse-1 on the word `triangle'. Triangle should now be
433
;; highlighted. (Don't drag the mouse while clicking!) Press `q' and
434
;; you're back in logo buffer. Now try to run triangle; press shift
435
;; mouse-2 (to invoke `List Input History' menu), choose `triangle
436
;; 120', and hit Enter. Logo should respond with:
438
;; I don't know how to triangle
441
;; ===========================================
443
;; For detailed instructions on how to use logo-mode, read the README
444
;; file in /usr/local/lib/logo/emacs/ directory.
446
;; To end this tutorial (or any future logo-mode sessions) click on
447
;; `Files' menu and choose `Exit Emacs' option. Emacs will ask if you
448
;; want to save file (meaning the source file you were working on --
449
;; right now, this file) to which you normally answer `Yes'. Then it will
450
;; ask; `Active processes exist; kill them and exit anyway?', to which
451
;; you click on `Yes'. (This is actually asking if you want to kill
454
;; DO NOT - EVER - try to kill Logo by clicking on X in the top right
455
;; corner of logo buffer window (if your window manager has that X). This
456
;; will kill logo frame, but *not* Logo itself, and you will loose
457
;; the communication channel with it. You will not be able to use
458
;; `Logo-start' menu on edit buffer, because as far as logo-mode is
459
;; concerned Logo is still running, and two Logo processes are not
460
;; allowed. You can, however, type `bye' on the Logo command line to kill
461
;; it. In that case you can also restart it from `Logo-start' menu.
463
;; If you started this tutorial from a "real" Logo source file, and
464
;; you want to return to that file and continue working on it -- then
465
;; instead of `Exit Emacs', use `Files>>Kill Current Buffer'
466
;; option. Tutorial buffer will disappear, and the file you have been
467
;; working on before will show again.