This file documents version 2.9 of logo.el.

Logo.el is written for GNU Emacs 20.5 or newer, running under X11.
You will (of-course) need Berkeley Logo (*v5.1* or newer) installed on
your system.

It is *not* designed to be used with Xemacs, Gnu Emacs compiled
without X support or Gnu Emacs started with -nw option. The last two
will partly work, but I did not test it that way.


============
INSTALLATION
============

Installing the Berkeley Logo package installs Logo-mode also.  See the
README file in the main ucblogo directory.

EACH USER who wants to use Logo-mode must run the shell command

	install-logo-mode

------------------------------------------------

Description of options for fine-tuning:

Set this to change the size of the frame (window) for
Logo-inferior-process buffer. If these forms are not present, the size
is set to 80x24. (This will work properly only with ucblogo 5.1 or
newer.)

(setq logo-term-columns nn)
(setq logo-term-rows mm)

Where nn and mm is whatever makes you happy.


By default logo-mode will indent continued lines in logo (edit) buffer
when RET-urn key is pressed. To insert a newline without indenting use
LFD (C-j) key. To reverse this behavior (reverse should probably be
considered "normal" behavior), add this form.

(setq logo-standard-indent t)


By default logo-mode starts with syntax highlighting enabled. If you
do not want it, set this:

(setq logo-syntax-highlight nil)

If you feel that the default syntax highlighting is slowing your system
too much, set this:

(setq logo-lazy-lock-mode t)


By default logo-mode starts with novice command management enabled. If
you don't want it set this:

(setq logo-novice-management nil)


By default logo-mode will start Logo process in setcursor mode. To
change this permanently set:

(setq logo-setcursor-start nil)


Default text input mode in setcursor mode is set to overwrite. To
change this permanently set:

(setq logo-setcursor-overwrite nil)


By default, the old text, after recalling the previous input in
setcursor mode will be cleared to the end of the line. If that gets in
your way, set this:

(setq logo-setcursor-spaces-old n)

where n is from 0 to any number. However, spaces are never pushed beyond
end of the line. 


By default two spaces are pushed ahead of end of the new input in
setcursor mode. If that gets in your way, set this:

(setq logo-setcursor-spaces-new n)

where n is from 0 to any number. However, spaces are never pushed beyond
end of the line.


If emacs lags behind during indenting Logo procedures, or simply when
hitting return key (you must be working on a *very* slow system to
notice this last one), add this form.

(setq logo-unbalanced-distance 4096)

On a very slow machine go down to 2048. By default, this is set to
8192, but it is doubtful that you will ever write a single implicitly
continued logo line that will be 8K long.


If you have installed ucblogo info files translated into another language,
then set this:

(setq logo-info-file-trans "/your-info-path/file-name.info")

However, for this to work - somebody has to write translation first. To the
best of my knowledge only Croatian translation exists. Therefore by default
this is set to "/usr/local/info/ucbl-hr.info" . If you change this to another
language you must also update the `Help' menu entry by setting this:

(setq logo-info-trans "(De)")

This "(De)" would be in case your translation is German, but you can use 
longer words as well. By default this is set to "(Hr)". 
If you don't care for this at all, set

(setq logo-info-trans nil)

With this set menu entry for translated manual will disappear.


By default emacs enables changes to Logo language through
Logo>>Language, and Logo>>Compiler menus. This has to do with .loops
initialization file. If you do not want to use this facility, set
this:

(setq logo-load-language nil)


Logo mode automatically sets the depth of setcursor input history menu
to safe value for the display resolution it is running on. (20 entries
for 640x480, 25 for 800x600 ...) To change this set following:

(setq logo-dynamic-menu-depth n) 

where n is any number (up to ... 48). However note that if you use
larger number, (depending on your display resolution, and emacs font
size) you may not be able to see nor use all menu entries.


If you don't want me messing with your default emacs colors, then
set this line:

(setq dont-mess-with-logo-colors t)


If you don't want parens matching on cursor movement, then set this line:

(setq logo-flash-on-movement nil)


If you want to change the delay after matching parentheses on cursor
movement, set this to any number of seconds you wish:

(setq logo-matching-delay-time seconds)

Default delay is set to 2 seconds, but even a very long delay -- say,
5 seconds would be OK, as you don't have to wait for it to
complete. Delay will be reset if you move the cursor again.

By default logo-mode starts with automatic expansion of common Logo
abbreviations enabled, If you do not want this, set:
(setq logo-expand-common-abbrevs nil)

For those that are translating Logo primitive names into another
language, (I know that the translation into French is underway), add
this form to enable the expansion of new primitives:

(define-abbrev-table 'logo-mode-abbrev-table 
      '(("op" "output")
	("pr" "print")
	...
	...))

of course, using your new names instead of those used here. 
 
4.  	There are several other options settable in .emacs file, but they
deal mostly with problem corrections. If I have done my work properly,
and if you have installed ucblogo (release 5.1 or newer) as instructed
in ucblogo README file, they will not be necessary.  Read logo.el file
(first five pages) for the description of other options. (For instance
if Emacs can't find Logo help files, debug menu doesn't work etc. ...)



========================================
USING BERKELEY LOGO WITH EMACS LOGO MODE
========================================

To start logo mode, open one Logo source file in emacs. As far as
emacs is concerned Logo source file is the file that ends with .lg ,
.lgo , or a file that has this `;;; -*- logo -*-' on a first line.

Start ucblogo from a `Logo-start' menu. You can start Logo in `Other
Frame',or `Same Window'. The *BEST* way is `Other Frame', and I
definitely suggest using it. (The `Same Window' is given for archaic
reasons only.) Due to availability of setcursor mode I insist on a
minimum window (frame) size when Logo starts -- 81x26 (that is if the
usable size is left at 80x24). Do not change frame size of Inferior
Logo buffer (by dragging corners with the mouse), or Logo output will
be garbled. On the other hand - stretching the height of Logo edit
frame is perfectly OK.

Editing and sending Logo source code:
=====================================
You write Logo code in Logo edit buffer. All standard emacs editing
features are supported here. The notable difference from standard
behavior is automatic indenting bound to RET (enter) key.  You can
check special Logo editing features by pulling down `Logo-edit'
menu. All functions that are bound to a key sequence will show that
sequence as well. To see commands for sending source code (or parts of
it) to Logo, pull down `Logo-send' menu.  Choices that are shaded (in
all of these menus) denote that this option is presently not
available. For instance if `Send Region' is shaded it simply means
that no region has been selected.

You can have several source files opened, but only one Logo process
buffer. That is the reason for all three choices on `Logo-start' menu
being shaded after you have started Logo.

Syntax highlighting is turned on by default (unless you have disabled
it in .emacs file). However you can always turn it off/on with `Toggle
Syntax Highlighting' choice in `Logo-edit' pull-down menu.

Following syntax classes are highlighted:
Comments - (red) text.
Strings - (brown) text.
Start and end of Logo procedure definition (TO .MACRO DEFINE .DEFMACRO
END) - (blue) text.
Variables (actually :var.name) - (light blue) text.

Highlighting of beginning and end of Logo definitions is not so
dependable as functions that mark procedure boundaries (used for code
indenting and sending). TO, .MACRO, and END will not be highlighted if
they are indented.

For `adventurous' novices (meaning mostly Emacs novices) I have
included novice command management feature. This simply tags
potentially dangerous commands, and they are not executed
immediately. Instead, emacs will pop a window with warning, and basic
instructions what to do next. You can still execute the command if you
decide so. If you find this disturbing (I do) then turn it off with
Logo-edit>>Preferences>>Toggle Novice Management choice from menu-bar,
or set it permanently in .emacs file.

Interacting with Logo:
======================
To run and test your procedures switch to Inferior Logo buffer. If you
have started Logo in `Same Window', to switch -- you have to use
`C-c l'. Otherwise simply move the mouse pointer to Logo buffer.

The usual goodies from Scheme (or Lisp modes) are present in Logo mode
as well. You can step with `M-p' / `M-n' (C-up / C-down, should also
work, if not trapped by your Window Manager) through the previous
inputs to Logo in all modes, and edit these inputs as you wish. When
finished with editing (input) simply hit Return key wherever you are
in the input line. Emacs will correctly grab the whole input and send
it to Logo. You can use S-down-mouse-2 (shift and press mouse-2)
anywhere on the Inferior Logo window to pop-up the `List Input
History' menu. Release mouse on any of the entries, and that input
will be inserted on command line.

Several standard editing keys work "slightly" different in Inferior
Logo mode. Delete and Backspace keys work only within current command
(input) line. Kill and yank (paste) commands work only on input line,
by killing or yanking the whole input. Do not bother aiming with the
mouse accurately. No matter where you are in Inferior Logo buffer,
mouse-2 will paste new input line, overwriting the old line. The old
input is cleared, so don't try pasting two inputs hoping they will
concatenate.  You can not tell emacs where is the end of input line,
by positioning the point there. That is chosen
automatically. (Actually this is not entirely true -- if emacs ever
gets hopelessly confused about the position of logo-input-marker, you
can set it manually with `C-@'.)  The whole purpose for this yanking
(pasting) business is to transfer input lines from other applications
running on your X display, therefore X-selection always takes
precedence over emacs kill-ring. (To retrieve previous inputs from
your current Logo/logo-mode session use `M-p' instead.)

Probably the *most useful* key to remember in Inferior Logo mode is
`C-l'. This is not bound to `recenter' as in the rest of logo-mode
buffers, but to `logo-find-input-end' which takes you back to the end
of Logo command line (in case you had wondered off).

To stop a "runaway" Logo hit `C-c C-c' in Inferior Logo buffer. If this
doesn't work use one of the choices from from `Signals' pull-down menu
in Inferior buffer. 
`BREAK' (`C-c C-c') to which Logo should respond with "Stopping..."
`QUIT' to which Logo should respond with "Pausing..."
`KILL' to which emacs responds with "Process logo killed"
Signals menu is not part of logo.el, so there are no Logo specific
choices there - it is built into comint mode.

You do not have to worry (as you should if using Logo without
logo-mode) about saving your source files before you test any of
them. Even if Logo crashes in Inferior Logo buffer (with a message
like ... segmentation fault ...), your sources are still intact in
Logo edit buffer. Simply restart Logo with `Logo-start' menu, and
re-send your procedures to it with any of the choices on `Logo-send'
pull-down menu.

Workspace Management:
=====================
To choose procedures for tracing or stepping, use `Logo-debug'
sub-menu under `Logo' pull-down menu in Inferior Logo buffer.  Debug
buffer lists all names currently defined, and lets you select
procedures (variables or properties) for tracing or stepping. Mouse
bindings are as in XFM. Mouse-1 selects only the pointed name
(de-selects everything else), mouse-2 toggles the selection for the
name, mouse-3 selects pointed name, quits debug-buffer and sends all
selected names to Logo. `q' key also quits debug-buffer and sends all
selected names to Logo.  When you open `Trace...' or `Step...' menus,
the names that were traced or stepped before will be highlighted (and
placed in parentheses).

The last entry under `Logo>>Logo-debug' menu is `Erase'. You can mark
(with the same mechanism as for tracing); procedures, variables or
plists for erasing. After `q' key is pressed, marked names will be
erased from Logo workspace, and GC will run automatically. To check
which is the buffer you're actually working with (trace, step or
erase), as all three look alike -- read the buffer mode line. For
erase buffer it will state: `(Fundamental Logo-ERASE View)' etc.

Help system:
============
Logo-mode has a very simple help system.

Help works in source buffers. Press mouse-3 on any valid Logo name,
and the help file (for that procedure) will open. To exit hit `q'. If
the help for the procedure doesn't exist, HELPCONTENTS file will be
opened. There you can choose as many help files as you want (with
mouse-3). Hit `q' in HELPCONTENTS to return to the source file. If you
want to check HELPCONTENTS, either click mouse-3 on a word which is not
defined in Logo, or use `Logo-help' sub-menu on emacs `Help' pull-down
menu. This option is available only on Logo edit frame menu bar.

To get better organized and more comprehensive help, browse through
Logo User Manual by pulling down the `Help' menu and choosing from
`Logo-help' sub-menu, `User Manual'. That will work if you have
installed ucblogo.info files (normally installed automatically). To
exit from Logo User Manual buffer hit `q'.

To get help for logo-mode itself hit `C-h m' in any of emacs logo mode
buffers.

Although completion facilities are not part of the help system, you
can regard them as such. Two types of completion are available in logo
edit buffers. Completion for Logo keywords (actually standardly
defined names of Logo primitive and library procedures) and completion
for words that were already used in any of opened logo edit buffers.

To perform completion for Logo keywords write a few starting letters
and hit ESC TAB. This will open a window with a list of all possible
Logo keyword completions. Click mouse-2 on the one you want, and your
keyword will be completed in edit buffer.

To perform completion on a word that is not standardly defined Logo
name (this works both in edit and Logo process buffers), write a few
letters, and hit M-/ (Alt-/). If possible, emacs will complete the
word with the word you have used before in this, or any other Logo
buffer currently opened. If there are more possible completions,
cycle through them by repeatedly pressing M-/, until you find the one
you want. The other way to accomplish the same result is to hit C-M-/
(Ctrl-Alt-/) and emacs will open a window with all available
completions listed. Click mouse-2 on the one you want.

Logo common abbreviations are expanded when one of these characters
is entered after the word that constitutes abbreviation: space,
newline, ], }, and ). To disable this in the current session click on
Logo-Edit>>Preferences>>Toggle Abbreviation Expansion. You can
reactivate expansion using the same menu. Current state of
abbreviation expansion is visible on the mode line; if it reads
(Logo), expansion is disabled, if it reads (Logo Abbrev) it is
enabled. If you want to disable the expansion only on the current
word, escape the character that triggers the expansion. E.g.: if you
do not want to expand OP to OUTPUT after hitting space key, press
escape key, and then the space key. The expansion will not occur this
time, but next time you hit space after the abbreviation, the
expansion will be carried out.

Obvious *NOT To DOs* when running Logo in Logo mode:
====================================================
Entering `edit "whatever' in Inferior Logo buffer defeats the purpose
of using Logo mode. Whatever you edit this way will be lost (unless you
save it manually). You will not be able to use logo-mode editing
features this way, even if your EDITOR environment variable is set to
emacs. This will also block Logo -- no interaction from other
logo-mode buffers will be possible.

Entering `load "whatever' in Inferior Logo buffer is not the right way
to do it. Use `Open Logo File...' choice from `Files>>Logo-mode Files'
pull-down menu in Logo edit buffer. Emacs will pop-up a new frame
(that is, if you started Logo with `Run Logo Other Frame') and drop it
in a `Dired' mode, with default directory (the directory where the
first source file resides) displayed. Then choose (mouse-2) the
desired file. This way you can see both source files at the same
time. To send this file to Logo, simply hit `C-c b'.  If you opened
Logo source file that neither has the `.lg' extension, nor Logo
mode-line as the first line, use `Files>>Logo-mode Files>>Convert to
Logo-mode' choice from the pull-down menu. (Only files opened in
fundamental mode can be converted.)

If you started Logo with `Run Logo Same Window' choice, you can still
have several source files opened. Switch between them with `C-c l' key
using prefix. (If you have three files opened `C-u 1 C-c l' switches
from Inferior Logo buffer to the newest source buffer, and `C-u 3 C-c
l' switches to the oldest buffer -- or just use emacs `Buffers' menu
to switch.)

There is no need to use help, trace or step Logo commands
manually. They can't hurt, but logo-mode provides interactive, mouse
driven interface, which is easier to use.

Do not define Logo procedures by typing them directly to Logo in
Inferior Logo buffer. This will work OK, but you will not be able to
change them later on. `M-p' will retrieve them line by line, and not
as a whole definition. Instead, simply enter definitions in Logo edit
buffer and send them over with `C-M-x'. The key-chord C-M-x
(Ctrl-Alt-x) will not always work, and as it is the most frequently
used keyboard shortcut (much faster than using Send Definition from
Logo-send menu), additional instructions are in order. Some window
managers (KDE 2.1 for instance) use this same combination for their
own purposes, and will therefore intercept this key-chord. You can
still use Esc C-x combination (Esc always works in the place of Meta
or Alt key), but this is much slower that C-M-x. The only way to
restore the functionality of C-M-x in logo mode is to disable this key
combination in the KDE Control Center.

If you have been using SETCURSOR command in Inferior Logo mode, and
Inferior Logo buffer is cluttered with old text, do *not* try to clear
the buffer using emacs. Instead, use Logo to do the job -- enter `ct'
(CLEARTEXT) command on Logo input line.

Not so obvious *NOT To DOs*:
============================
Do not leave blank lines (spaces only) inside Logo string
constants. Indenting and procedure sending functions in logo-mode depend
on this. If you really need a blank line in Logo string, you can use this: 

make "foo "|abc
||
def|

instead of this:

make "foo "|abc

def|

As far as Logo is concerned, result is the same. Logo-mode, however will
malfunction on the second.

Although you can leave blank lines and comment lines (comments only)
inside procedure definitions in Logo edit buffer, their use is
restricted to areas between lines that are not continued, or are
implicitly continued (Lisp style). Do not use blank lines between
explicitly continued Logo lines (lines that end with `~'). Neither
Logo, nor logo-mode function properly in these circumstances. You can
use comment only lines between two explicitly continued Logo lines, but
you must end them with `~'. However, you are on your own here -- in
some cases Logo will reject those.

This is what I was talking about:

to worldtree

;; comment
make "world ~
     tree "world ~
     (list
          
          ;; comment
          (tree "France leaves [Paris Dijon Avignon])
          
          ;; comment
          (tree "China leaves [Beijing Shanghai Guangzhou Suzhou])
          ...

This works OK. However if you try to insert a comment line between

make "world ~ 
     tree "world ~

lines, Logo will print error message when worldtree is run.


Do not use names like `x\;y' `x\(y' `x| |y' `x|;|y' `x\\y' or some
such for your procedures and variables. Although Logo will accept
this, you will not be able to mark these names in Workspace Management
(Debug) buffer. I have allowed some rather weird characters to
accommodate Brian's MATCH program, but that's as far as I'll go.


Do not use yank (paste) facility to paste procedure definitions
directly to Inferior Logo buffer -- this will not work. Yank can be
used only to paste the command line (input) directly to Logo. This
probably sounds ambiguous, therefore one small example:

Let's say that you have in another editor window (it can be another
copy of emacs, or whatever) this procedure:

to remove1 :e :l
op filter [[x] [op or not equalp :e :x memberp :x ?rest]] :l
end

and you want to test it in current Logo/logo-mode session. If you yank
it directly to Inferior Logo buffer, it will arrive as one line
(setcursor mode), and Logo will not accept this as a procedure
definition. Instead, yank it to Logo edit buffer, and use `C-M-x'
to send it to Logo.

On the other hand (once Logo has received the procedure definition),
you can use yank to paste from other editor test inputs to procedure
remove1. For instance, you can yank:
`show remove1 2 [1 2 3 1 2 3 1 2 3]'
directly to Inferior Logo buffer and hit return. Logo should respond
by printing following:

? show remove1 2 [1 2 3 1 2 3 1 2 3]            
[1 2 3 1 2 3 1 3]
?                                                                        

This is an oversimplified example, but, there will be times (when
testing tree recursive procedures -- for instance) where the test input
will be several lines long elaborately constructed tree list...


Do *not* try to close Logo by clicking on X in the upper right corner
of *logo* frame (or by using close option on the upper left corner of
the *logo* frame). This will close that frame, and make Logo
unaccessible to you, but it will *not* kill Logo. If you want to kill
Logo, type `bye' in *logo* buffer.


Not so obvious *To DOs*:
========================
One of the facilities built into logo-mode is automatic loading of
.loops initialization file from your home directory - if it exists. The
idea here is not so much to write additions to Logo library (although
it can be used for that as well), but to alter the standard behavior
of Logo interpreter. The last version (v.0.9) adds LOOPS, a rudimentary
Logo Object Oriented Programming System (just an experiment).

As an example of what can be done with initialization file, copy the
included .loops (dot.loops) file to your home directory, and start
Logo. Click on `LOOPS>>Language>>Ucblogo + LOOPS' menu, and emacs will
load .loops extensions into Logo.

The Compiler sub-menu on Logo pull-down menu in Inferior Logo buffer
is LOOPS specific. To understand what it does, and -- indeed, how to
use LOOPS extensions click on `Help>>Logo-help>>LOOPS User Manual'. 
*(Part of the LOOPS User Manual needs updating.)*


===============================
COMMENTS BUG REPORTS AND To-DOs
===============================

Logo-mode is tested only on Intel machines running Linux and
FreeBSD. I have no access to anything else. The original work started
on emacs 19.34.1(b), but that version is no longer supported.
Logo-mode v2.9 will work only with emacs 20.5 and newer. Your safest
bet is to upgrade to the latest version.

Right now I have a lot "To-DO", but am willing to listen to
"reasonable" suggestions.


For more information, comments, or bug reports, send e-mail to
<hblazevi@ri.tel.hr>

 
