@make(Report)
@device(x9700)

@pageheading(even, right "@c[Tutor System Manual]",
		   left "@c[@value(page)]")
@pageheading(odd, left "@c[@Title(Chapter)]",
		  right "@c[@value(page)]")

@begin(TitlePage)
@copyrightnotice(Jeffrey S. Shulman)
@begin(TitleBox)
@Majorheading(TUTOR

System Development Manual)
@end(Titlebox)
@Heading(First Edition
Preliminary Draft)

@value(Month) @value(Year)

@b[Jeffrey S. Shulman]
@comment(for Xerox Corporation)
@end(titlepage)

@Chapter(Introduction)
@Section(Purpose)

@b(TUTOR) is a program whose purpose is to introduce the user to Interlisp
and mainly to the Interlisp-D development environment.  @b(TUTOR) takes the
programmer (who is assumed to have minimal Lisp exposure) through:
@begin(Itemize)
A short introduction to some aspects of the @b(TUTOR) environment and
program interaction.

Keyboard idiosyncrasies, how to use the mouse and what windows are.

Menus and interactive window operations.

Lisp variables, data types and the Record Package.

Basic Lisp and Functions

Function definition

Function editing

The Break package and Data Inspector

MAKEFILE

The compiler
@end(Itemize)

all at a fairly basic level.  It does this in a light, cheerful, and
entertaining manner.  @b(TUTOR) is started by the function @b(TUTOR).

@Section(Environment)
Interlisp-D provides a rich and complete Lisp development environment
which include things like:
@begin(Itemize)
A Mouse

Multiple Windows

Menus

Multi-tasking
@end(Itemize)
which @b(TUTOR) not only teaches, but takes full advantage of in doing
the teaching.

The basic @b(TUTOR) environment consists of:
@begin(Itemize)
Prompt Window - This is @i(standard) to the Interlisp-D programming
environment.  @b(TUTOR) uses this window at times when the user would
normally be interacting with Interlisp-D here.

Top Level Typescript Window - This is also @i(standard) to Interlisp-D.
This is the main window the user would use to communicate with Interlisp-D
through.  For this reason it is also the main window the user interacts with
@b(TUTOR) through.  @b(TUTOR) does most of its @i(talking) and the user most
of his @i(speaking) via this window.

Tutor Help Window - This window is used by @b(TUTOR) to provide additional
help to the user at the users request.  The user can request additional
help either by typing @b(help) to any prompt from @b(TUTOR) or by buttoning
the large @b(HELP) menu located above this window.

Tutor Help Menu - This is a single item menu (the item @b(HELP)) that resides
above the @i(Tutor Help Window).  At any time the user can get additional
help printed in the @i(Tutor Help Window) by buttoning this menu.

Tutor Lesson Window - This window contains the @i(Table of Contents) of all
@i(lessons) available through @b(TUTOR).  The current lesson is shown by
inverting it.  This window can also be used to skip around various lessons
and review past lessons.
@end(Itemize)

When @b(TUTOR) is first started the above five items are grouped together
in a coherent fashion that keeps the users attention within a certain area
of the screen.  This leaves large empty areas to be used by @b(TUTOR)
when necessary.

@b(TUTOR) also provides facilities to suspend the tutoring saving the users
current position for resumption at a later date.

A standard user input interface is provided which first @i(screens) the users
input to see if he needs further help or wishes to suspend the tutoring
session.  Help is available at two levels:  If the user types @b(?) to
a prompt he will get a brief sentence printed right in the @i(Top Level
Typescript Window) explaining what input is requested; if the user types
@b(Help) (or buttons the @b(HELP) menu) he will receive a more detailed
explanation of what is requested in the @i(Tutor Help Window).

The @b(TUTOR) system also @i(protects) the user from accidentally aborting
tutoring by disabling the normal interrupt mechanisms.  It reactivates
the ERROR and RESET interrupt but in a protected shell.

Typing the ERROR interrupt (@b(^E)) at prompt level will cause the
user to be re-prompted.  Typing it during @b(TUTOR) typeout will leave
the user at @b(TUTOREXEC) level.  If the user typed it by accident he
can resume at the beginning of the @i(section) he interrupted by typing
@b(resume).

Typing the RESET interrupt (@b(^D)) will immediately cause the
system to go into a RESET trap.  At this point the user will be
asked (in the system @i(Prompt Window)) whether he really meant to
type the RESET interrupt.  If he answers @b(No) then @b(TUTOR)
will proceeded as if nothing happened.  If he answers @b(Yes) then
@b(TUTOR) will reset itself leaving the user back at Lisp level.

@Chapter(System Description)
This chapter gives an overview of the @b(TUTOR) system; the files it
needs, and the globals and functions it has.  Each global is
then listed along with its purpose.  Following the globals are the
functions that make up @b(TUTOR).  Included are their arguments, returned
value and a description of what they do.

@Section(Files)
@b(TUTOR) is composed of the main file, the lesson files and auxiliary
files.  The student may also have is own suspended lesson file.
They are described as follows:

@subsection(Main File)
The main file (called @B(TUTOR)) contains most all the functions necessary
to run the @b(TUTOR) system.  In addition it contains all the globals, 
variables, records
and the introductory lesson.  This is the file the user must load to
start up the system.

@subsection(Lesson Files)
Each full lesson is kept in its own separate file.  This file is loaded
automatically when it is needed.  The files are named @b(TUTORLESSONx)
where @b(x) is the lesson number.  These files do not have to reside
in the same place as the main file.  The variable @b(TUTORLESSONDIRECTORIES)
is a search list (like the variable DIRECTORIES and LISPUSERSDIRECTORIES)
which should contain the location of the lesson files.

@b(TUTORLESSONDIRECTORIES) is an INITVAR whose initial value is
({DSK} T NIL).  The site administrator should set up the appropriate
value in the site init file if different.

@subsection(Auxiliary files)
Two extra system files and two Lisp User's packages are also necessary
to run the @b(TUTOR) system.  There are @i(PRINTOUT), @i(RECORDER), 
@i(ACTIVEREGIONS) and
@i(ICONW).  These will be loaded when @b(TUTOR) is loaded.  They should be
found in DIRECTORIES (for @i(PRINTOUT)) and in LISPUSERSDIRECTORIES (for
@i(ACTIVEREGIONS) and @i(ICONW).)

@i(PRINTOUT) contains functions that enhance the capabilities of the
@b(printout) package.  @i(RECORDER) is a package the lets mouse and
keyboard actions be played back.
@i(ACTIVEREGIONS) and @i(ICONW) are standard
Lisp User's packages.

@subsection(Student File)
When a student @b(suspend)'s his lesson a file is created to hold
what is necessary to @b(resume) where he left off.  This file is
named @b(TUTOR-username.firstname).  @b(username) is the students
user name and @b(firstname) is his first name.  This file is kept
in the directory described by @b(TUTORSTUDENTDIRECTORY).

@b(TUTORSTUDENTDIRECTORY) is an INITVAR whose initial value is {DSK}.
The site administrator should set up the appropriate value in the
site init file if different.  This variable can be set to anything
a single entry of @i(USERGREETFILES) can be set to and will behave
appropriately.

@Section(Organization)
@b(TUTOR) is organized around the concept of a @i(lesson).  Each main
topic is an entire @i(lesson).  These lessons are further broken up into
@i(sections).  A @i(section) is the smallest unit the user can repeat or
@b(suspend) a tutoring session at.  Except for the introductory lesson
each lesson is kept in its own separate file.  Each file is loaded as
necessary by the system automatically.

@i(Sections) are implemented by separate Lisp functions.  The
convention used in naming these functions is @b(L)@i(lesson#)@b(.)@i(section#).
For example the function that implements @i(lesson) 2, @i(section) 4 would
be called @b(L2.4).

@subsection(Lesson Scheduling)
Section scheduling is handled by the @b(TUTOREXEC) rather then having
each section chain to the next.  @b(TUTOREXEC) provides the @i(protected)
Lisp executive for the entire system.  It handles section scheduling
by evaluating the global variable @b(*NEXT*) which should contain the
function implementing the next @i(section).  Each @i(section) is
responsible for setting the next @i(section) by a call to the function
@b(NEXT.LESSON) which maintains the @i(Tutor Lesson Window), loads
the lesson file if necessary, and sets @b(*NEXT*) appropriately.

@subsection(Standard Output)
The macro @b(MESSAGE) provides the standard output interface for each
@i(section) function.  This macro is used somewhat like the Interlisp
@b(printout) facility (which it does indeed compile into) to provide
both the general @b(TUTOR) dialogue as well as the help messages printed
in the @i(Tutor Help Window).  In addition to excepting @b(printout)
forms it handles bitmaps and strings.

Bitmaps are handled by the .BM @b(printout) command which is among the
extra features added by loading @b(PRINTOUT).

Strings are translated into lists which are used for the @b(printout)
form @b(.PARA).

@subsection(Standard Input)
The standard input function to receive any input from the user is 
@b(USER.INPUT).  This function provides a @i(protected) interface
to @b(PROMPTFORWORD) to trap ERROR interrupts.  This function
also recognizes special user input for help and tutorial suspension
separate from the requested input.

@Section(Globals)
@subsection(System globals)
@paragraph(TUTORLESSONDIRECTORIES)
This variable contains the list of directories to be searched for a
lesson file.  It corresponds to the Interlisp variables @i(DIRECTORIES)
and @i(LISPUSERSDIRECTORIES).  It is an INITVAR whose initial value is
({DSK} T NIL).

@paragraph(TUTORSTUDENTDIRECTORY)
The value of this variable is used to construct the full file name of
where a student's @b(suspend)'ed file is kept.  Its value can be an
atomic HOST/DIRECTORY or a list that is PACK'ed to form an atomic
HOST/DIRECTORY (with this form the atom USER will have the student's
user name substituted before PACKing.)  It corresponds to a single
entry in the Interlisp variable @i(USERGREETFILES).  It is an INITVAR
whose initial value is {DSK}.

@paragraph(*KEYBOARD.WINDOW*)
Window used to display the keyboard layout in.

@paragraph(*LESSON.NAMES*)
An alist of @i(lesson) numbers and titles.  Used in the @i(Tutor Lesson
Window)

@paragraph(*LESSON.WINDOW*)
This is the window that contains the @i(Table of Contents) of the lessons
available in @b(TUTOR).  The window property LESSON is the number of the
current @b(TUTOR) @i(lesson).

@paragraph(*MAIN.WINDOW.REGION*)
This is the region the main tty window is reshaped to by @b(TUTOR.INIT).

@paragraph(*NEXT*)
If non-NIL evaluated by @b(TUTOREXEC) when it gains control.  Used to
schedule the next lesson @i(section).  Set by the function @b(NEXT.LESSON).

@paragraph(*PROMPT.REGION*)
This is the region the prompt window is reshaped to by @b(TUTOR.INIT).

@paragraph(*TUTOR.HELP.MESSAGE*)
Contains the @b(printout) expansion for the current help message.  Set
by the MESSAGE macro and used by the function @b(TUTOR.HELP).

@paragraph(*TUTOR.HELP.WINDOW*)
The @i(Tutor Help Window).

@subsection(Reference Pages)
@paragraph(*PP.INTERRUPT-CHARACTERS*)
Page that describes the interrupt characters.

@paragraph(*PP.MENUS*)
Starting page for description of menus.

@subsection(Bitmaps)
@begin(Description)
2B.MOUSE@\Two button mouse. 9 by 16.

3B.MOUSE@\Three button mouse. 12 by 16.

DLIONKBD@\Dandelion keyboard icon. 72 by 72.

DOLPHINKBD@\Dolphin keyboard icon. 72 by 72.

DORADOKBD@\Dorado keyboard icon. 72 by 72.

DOWN.ARROW@\Downward pointing arrow. 10 by 16.

FROWN@\Frowning face. 16 by 16.

IS.OPR.BM.1@\Smiling I.S. Opr. 83 by 92.

IS.OPR.BM.2@\Normal I.S. Opr. 83 by 92.

IS.OPR.BM.3@\Left I.S. Opr twirler. 83 by 92.

IS.OPR.BM.4@\I.S. Opr beanie.  83 by 92.

IS.OPR.BM.5@\Right I.S. Opr twirler.  83 by 92.

MOUSEBM@\Mouse.  16 by 16.

RIGHT.ARROW@\Right pointing arrow.  16 by 10.

SMALL.GC@\Small G.C. Klisp picture.  24 by 24.

SMILE@\Smiling face.  16 by 16.

TTYKBDMASK@\Mask for keyboard/tty icons.  72 by 72.

UP.ARROW@\Upward pointing arrow.  10 by 16.
@end(Description)

@Section(Functions)
@subsection(CHARSTRING)
@begin(Description)
@i(Arguments):@\
@begin(Description)
@b(ACTION)@\An atomic key action as returned by @b(KEYACTION) or ASCII code.
@end(Description)

@i(Value:)@\String representing how ACTION should be printed.

@i(Description:)@\Converts ACTION into a text string with appropriate
"^" and "#" added if necessary.  Returns the common name of any special
characters (e.g. TAB for ^I, etc.).  Returns ACTION if not a number or
a recognized atomic KEYACTION.
@end(Description)

@subsection(CONTINUE?)
@begin(Description)
@i(Arguments):@\
@begin(Description)
@b(SECTION/LESSONFLG)@\SECTION if a new section is next, LESSON if a new
lesson is next or NIL if in the middle of a section.  The argument is
unevaluated.

@b(LESSON#)@\The lesson number.
@end(Description)

@i(Value:)@\NIL

@i(Description:)@\Asks the uses if he wants to continue.  If it returns to
the caller then continue (@b(USER.INPUT) handles the special cases.)  If
LESSON# is non-NIL then call LOAD.LESSON to load it if we are continuing.
@end(Description)

@subsection(DLION.KEYBOARD)
@begin(Description)

@i(Value:)@\NIL

@i(Description:)@\Draws and labels a picture of the Dandelion keyboard in
@b(*KEYBOARD.WINDOW*).
@end(Description)

@subsection(DOLPHIN.KEYBOARD)
@begin(Description)
@i(Arguments):@\
@begin(Description)
DORADO?@\T if we want a Dorado keyboard instead.
@end(Description)

@i(Value:)@\NIL

@i(Description:)@\Draws and labels a picture of the Dolphin (or Dorado)
keyboard in @b(*KEYBOARD.WINDOW*).
@end(Description)

@subsection(GET.USER.NAME)
@begin(Description)

@i(Value:)@\NIL

@i(Description:)@\Obtains the user;s first and last name setting @b(FIRSTNAME)
and @b(USERNAME).
@end(Description)

@subsection(LESSON.WINDOW.REPAINTFN)
@begin(Description)
@i(Arguments):@\
@begin(Description)
@b(W)@\The @b(*LESSON.WINDOW*)

@b(REGION)@\The region to repaint.  Ignored.

@b(START)@\The number of the first lesson to display.
@end(Description)

@i(Value:)@\NIL

@i(Description:)@\The REPAINTFN for the @i(Tutor Lesson Window).  Titles the
inside of the window and prints each item on @b(*LESSON.NAMES*) starting
with START if given.  Then highlights the current lesson (from W's LESSON 
windowproperty) if within the window.
@end(Description)

@subsection(LESSON.WINDOW.SCROLLFN)
@begin(Description)
@i(Arguments):@\
@begin(Description)
@b(W)@\The @b(*LESSON.WINDOW*)

@b(H)@\How much to scroll horizontally.  Ignored.

@b(V)@\How much to scroll vertically.

@b(CONTINUOUS?)@\T if continuous scrolling.
@end(Description)

@i(Value:)@\NIL

@i(Description:)@\The scroll handler for the lesson window.
@end(Description)

@subsection(LOAD.LESSON)
@begin(Description)
@i(Arguments):@\
@begin(Description)
@b(LESSON#)@\The number of the lesson to load.
@end(Description)

@i(Value:)@\T

@i(Description:)@\Checks to see if the file containing lesson LESSON# is 
loaded. If not load it from TUTORLESSONDIRECTORIES.
@end(Description)

@subsection(NEXT.LESSON)
@begin(Description)
@i(Arguments):@\
@begin(Description)
@b(LESSON)@\The @i(lesson) number.

@b(SECTION)@\The @i(section) number.

@b(LOAD?)@\T to have the file for LESSON loaded.
@end(Description)

@i(Value:)@\NIL

@i(Description:)@\Takes care of setting up for the next lesson and updating
@b(*LESSON.WINDOW*).  If LOAD? is T then make sure the lesson file is loaded. 
Sets @b(*NEXT*) to @b"(L"@i(LESSON)@b(.)@i(SECTION)@b")".
@end(Description)

@subsection(NO.MORE.LESSONS)
@begin(Description)
@i(Value:)@\?

@i(Description:)@\Called by TUTOREXEC when there are no more lessons to
print some final comments.
@end(Description)

@subsection(PRINT.KEYACTIONS)
@begin(Description)
@i(Arguments):@\
@begin(Description)
@b(KEYNAME)@\Internal system KEYACTION keyname.

@b(REGION)@\Region to print in.

@b(FONT)@\Font to print in.  Either a single font or (lowerfont . upperfont).

@b(DISPLAYSTREAM)@\Displaystream to print in.
@end(Description)

@i(Value:)@\NIL

@i(Description:)@\Prints what KEYNAME does (if anything) in DISPLAYSTREAM
in FONT centered appropriately within REGION.  KEYNAMEs that have different
shifted and un-shifted keyactions have each printed one above the other
with the shifted action on top.
@end(Description)

@subsection(PRINTH)
@begin(Description)
@i(Arguments):@\
@begin(Description)
@b(STRING)@\String to print.

@b(REGION)@\Region to print it in.

@b(FONT)@\Font to display in.

@b(DISPLAYSTREAM)@\Displaystream to print in.
@end(Description)

@i(Value:)@\NIL

@i(Description:)@\Prints STRING in DISPLAYSTREAM horizontally centered
in REGION in FONT. If STRING does not fit in REGION it will keep
trying the next size down. This function assumes STRING will fit in a
font no smaller than 5 pixels.
@end(Description)

@subsection(PRINTV)
@begin(Description)
@i(Arguments):@\
@begin(Description)
@b(STRING)@\String to print.

@b(REGION)@\Region to print it in.

@b(FONT)@\Font to display in.

@b(DISPLAYSTREAM)@\Displaystream to print in.
@end(Description)

@i(Value:)@\NIL

@i(Description:)@\Prints STRING in DISPLAYSTREAM vertically centered
in REGION in FONT. If STRING does not fit in REGION it will keep
trying the next size down. This function assumes STRING will fit in a
font no smaller than 5 pixels.
@end(Description)

@subsection(RP.CONTINUE?)
@begin(Description)
@i(Value:)@\CR

@i(Description:)@\Acts like @b(CONTINUE?) called with no arguments but will
work during a @i(RECORDER) playback (i.e. it tests the instantaneous state
of the CR key.
@end(Description)

@subsection(SELECT.LESSON)
@begin(Description)
@i(Arguments):@\
@begin(Description)
@b(WINDOW)@\The @b(*LESSON.WINDOW*).
@end(Description)

@i(Value:)@\NIL

@i(Description:)@\Used as the BUTTONEVENTFN of *LESSON.WINDOW*.  Allows the 
user to select a lesson from the Lesson Window. 
@END(Description)

@subsection(SETUP.LESSON.WINDOW)
@begin(Description)

@i(Value:)@\NIL

@i(Description:)@\Create @b(*LESSON.WINDOW*) and call
@b(LESSON.WINDOW.REPAINTFN) to display it.
@end(Description)

@subsection(STRING.TO.LIST)
@begin(Description)
@i(Arguments):@\
@begin(Description)
@b(STRING)@\The string to convert to a list of atoms.
@end(Description)

@i(Value:)@\The converted list.

@i(Description:)@\Converts a string to a list cleaning up the string
file descriptor afterwards.
@end(Description)

@subsection(TUTOR)
@begin(Description)

@i(Value:)@\NIL

@i(Description:)@\User entry into the tutorial system.  Takes care of
disabling/reimplementing all dangerous interrupts, initializing everything,
starting TUTOREXEC and cleaning up afterwards.
@end(Description)

@subsection(TUTOR.HELP)
@begin(Description)

@i(Value:)@\NIL

@i(Description:)@\Prints @b(*TUTOR.HELP.MESSAGE*) in
@b(*TUTOR.HELP.WINDOW*).  If @b(*TUTOR.HELP.MESSAGE*) is NIL informs the
user that no extra help is currently available.
@end(Description)

@subsection(TUTOR.INIT)
@begin(Description)

@i(Value:)@\NIL

@i(Description:)@\Initialize the tutorial system.  It does things like
setting the correct fontset, shaping/creating the necessary windows
and menus, and getting startup info from the user (resuming any 
suspended lessons.)
@end(Description)

@subsection(TUTOR.QUIT)
@begin(Description)

@i(Value:)@\NIL

@i(Description:)@\Cleanup function when the use exits @b(TUTOR).  Does
things like close all the extra windows.
@end(Description)

@subsection(TUTOR.QUIT?)
@begin(Description)

@i(Value:)@\NIL

@i(Description:)@\The ^D interrupt function.  Checks with the user to
see if he really meant to reset or not.  If not then just return, if
so do a @b(RETFROM TUTOREXEC) so that everything is cleaned up properly.
@end(Description)

@subsection(TUTOR.RESUME)
@begin(Description)

@i(Value:)@\T

@i(Description:)@\Used to resume a suspended lesson.  Looks for
@b(TUTOR-username.firstname) in the directory @b(TUTORSTUDENTDIRECTORY).
If not found tells the student to select from the @b(Tutor Lesson Window).
@end(Description)

@subsection(TUTOR.SUSPEND)
@begin(Description)

@i(Value:)@\T if something was successfully saved, NIL otherwise.

@i(Description:)@\Used to suspend the current lesson and save the users
status.  Saves @b(TUTOR-username.firstname) in the directory 
@b(TUTORSTUDENTDIRECTORY).  Errors if something goes wrong explaining
how to fix.
@end(Description)

@subsection(TUTOREXEC)
@begin(Description)
@b(Arguments):@\
@begin(Description)
@b(LISPXID)@\The optional LISPXID to use.
@end(Description)

@i(Value:)@\NIL

@i(Description:)@\The tutor executive.  Tailored after @b(USEREXEC)
but with added functionality.  Uses the global @b(*NEXT*) as input if
non-NIL.  Calls @b(NO.MORE.LESSONS) when @b(*NEXT*) is **DONE**.
Evaluates input, and if the value is not **FOO**, prints the
value.  Takes care of processing special inputs of QUIT, SUSPEND and
RESUME.
@end(Description)

@subsection(USER.INPUT)
@begin(Description)
@i(Arguments):@\
@begin(Description)
@b(PROMPT)@\Prompt string.

@b(HELP)@\? help string

@b(DEFAULT)@\Possible default value.

@b(TERMINATORS)@\Possible list of terminators.

@b(WHERE)@\Where to print output and get input.
@end(Description)

@i(Value:)@\The users input as a string.

@i(Description:)@\Gets input from user via @b(PROMPTFORWORD) under
"protected" conditions. Also recognizes QUIT, SUSPEND and HELP
separate from requested input performing the appropriate actions.
@end(Description)

@subsection(WAIT)
@begin(Description)
@i(Arguments):@\
@begin(Description)
@b(MS)@\The number of milleseconds to wait.
@end(Description)

@i(Value:)@\?

@i(Description:)@\Waits, in an infinate loop, for MS milleseconds without
BLOCKing.  Used mostly during @i(RECORDER) playbacks to suspend playback
for MS milleseconds.
@end(Description)

@chapter(Macros)
@subsection(MESSAGE)
@begin(Description)
@i(Arguments):@\
@begin(Description)
@b(THE-MESSAGE)@\First item is one of @b(USER), @b(HELP), or a stream.
The following items are in @b(printout) form to be printed as an
indented paragraph with the following additions/exceptions: 1) Strings
are changed into lists which are passed to @b(.PARA); 2) @b(NONE) means don't
indent the paragraph;  3) @b(NOPARA) means don't put an extra CR at the
end; and 4) @b(NORMAL), @b(BOLD) and @b(ITALIC) mean switch fonts.
@end(Description)

@i(Value:)@\NIL

@i(Description:)@\General purpose message facility.  The first argument
of USER means just print THE-MESSAGE in the @i(Top Level Typescript
Window); HELP means set the compiled expansion to @b(*TUTOR.HELP.MESSAGE*); 
a stream means print to that stream.
@end(Description)

@Chapter(Lessons)
This chapter contains descriptions of each @i(lesson), descriptions
of the @i(sections) they are composed of, support functions and
lesson specific globals.  Each full lesson (with the
exception of Lesson 0), along with the support functions and lesson
specific globals,
is kept in its own file called @b(TUTORLESSONx)
where @b(x) is the lesson number.

@section(Lesson 0)
Introduction to the @b(TUTOR) system.

@subsection(Section 0)
Introduce the tutorial, display the keyboard and obtain the users name.

@newpage
@Section(Lesson 1)
Explain the keyboard, interrupt characters, the mouse and windows.

@subsection(Section 0)
Explain the various keys on the keyboard; what the CAPS LOCK, and CTRL key
do; ^E and ^D interrupts;  #A, #B and #C keys.

@subsection(Section 1)
How to use the mouse and cursor; pointing; cursor "hot spot"; mouse buttons;
what is the middle mouse button on two button mouse; buttoning.

@subsection(Section 2)
Windows; what are they?; the @i(Top level typescript) and @i(Prompt) windows;
window operations; icons.

@subsection(Support Functions)
@paragraph(IS.BFN)
@begin(Description)
@i(Arguments):@\
@begin(Description)
@b(WINDOW)@\I.S. Opr's window.
@end(Description)

@i(Value:)@\NIL

@i(Description:)@\Dummy BUTTONFN for I.S. Opr's window.  Each mouse button
press removes a piece of the picture.
@end(Description)

@subsection(Globals)
@paragraph(*COUNT*)
Used by @b(L1.1) to keep track of cursor movement within the I.S. Opr
window.

@section(Lesson 2)
Teach about menu's, getting mouse positions/boxregions/regions and
interactive window operations.

@subsection(Section 0)
Teach about menus.  Gives examples of both pop-up and standard menus.

@subsection(Section 1)
Explains positions and box regions.

@subsection(Section 2)
Explains standard regions.

@subsection(Support Functions)
@paragraph(ADFFE.WHENSELECTEDFN)
@begin(Description)
@i(Arguments):@\
@begin(Description)
@B(ITEM)@\The item selected.

@b(MENU)@\The menu.

@b(BUTTON)@\The mouse button used.
@end(Description)

@i(Value:)@\NIL

@i(Description:)@\The @i(WHENSELECTEDFN) for Aunt DWIM's Fast Food Emporium
of @b(L1.0).
@end(Description)

@paragraph(CLICK.N.SCORE)
@begin(Description)
@i(Arguments):@\
@begin(Description)
@b(WINDOW)@\The target window.

@b(POS)@\The mouse position relative to @b(WINDOW).  If NIL uses @b(GETPOSTION)
to get it.
@end(Description)

@i(Value:)@\The score if within the target,  0 if within the window but not
the target, and -1 if totally outside the window.

@i(Description:)@\Used to play the game of @i(Click'N Score) in @b(L1.1)
or just return the score if given @b(POS).
@end(Description)

@paragraph(DRAWTARGET)
@begin(Description)
@i(Arguments):@\
@begin(Description)
@b(WINDOW)@\The window to draw a target in.
@end(Description)

@i(Value:)@\NIL

@i(Description:)@\Draws a standard "Bull's Eye" target in @b(WINDOW).  Used
in playing the games @i(Click'N Score) and @i(Move'N Win).
@end(Description)

@paragraph(FAST.FOOD.SEQUENCE)
@begin(Description)
@i(Value:)@\NIL

@i(Description:)@\Runs through the @i(Aunt DWIM's Fast Food Emporium)
recorder sequence @b(FF.SEQUENCE) without explaining it.  Used in
@b(L1.0).
@end(Description)

@paragraph(FAST.FOOD.SEQUENCE.EXPLAIN)
@begin(Description)
@i(Value:)@\NIL

@i(Description:)@\Runs through the @i(Aunt DWIM's Fast Food Emporium)
recorder sequence @b(FF.SEQUENCE) but explains the actions step by
step.  Used in @b(L1.0).
@end(Description)

@paragraph(MAKETARGET)
@begin(Description)
@i(Arguments):@\
@begin(Description)
@b(REGION)@\The region for the target window.

@b(TITLE)@\The title for the target window.
@end(Description)

@i(Value:)@\The target window.

@i(Description:)@\Creates a window at @b(REGION) with @b(TITLE) and calls
@b(DRAWTARGET) to draw a target inside.
@end(Description)

@paragraph(MOVE.N.WIN.SEQUENCE.EXPLAIN)
@begin(Description)
@i(Arguments):@\
@begin(Description)
@b(AWINDOW)@\The window containing the arrow.

@b(AWINDOW.ORIGIN)@\The original position of @b(AWINDOW).
@end(Description)

@i(Value:)@\NIL

@i(Description:)@\Runs through the @i(Move'N Win) recording sequence
@b(MOVE.N.WIN.SEQUENCE) with a step by step explaination.  Used by @b(L1.1).
@end(Description)

@paragraph(MOVE.N.WIN)
@begin(Description)
@i(Arguments):@\
@begin(Description)
@b(TWINDOW)@\The target window.

@b(AWINDOW)@\The arrow window.
@end(Description)

@i(Value:)@\The score obtained by calling @b(CLICK.N.SCORE) with the
arrow point as the position.

@i(Description:)@\Plays the game of @b(Move'N Win).
@end(Description)

@subsection(Globals)
@paragraph(FF.SEQUENCE)
The recording for GC @i(ordering) in @i(Aunt DWIM's Fast Food Emporium).

@paragraph(CLICK.N.SCORE.SEQUENCE)
The recording used by GC when @i(playing Click'N Score).

@paragraph(MOVE.N.WIN.SEQUENCE)
The recording used by GC when @i(playing Move'N Win).

@paragraph(Bitmaps)
@begin(description)
AUNT.DWIM.BM@\Aunt DWIM's picture.  24 by 24.

MNW.ARROW@\Arrow used in playing the game @i(Move'N Win).  30 by 7.
@end(description)

@comment[
@paragraph()
@begin(Description)
@i(Arguments):@\
@begin(Description)
@end(Description)

@i(Value:)@\

@i(Description:)@\
@end(Description)
]