Getting Started

Summary

1.  Introduction

1a.  Key Press Notation

2.  Starting Up

3.  Documentation

3a.  Written Documentation

3a1.  Unix
3a2.  Emacs
3a3.  A+

3b.  Online Documentation

3b1.  Unix
3b2.  Emacs
3b3.  A+

4.  Exiting

4a.  Ending a Workstation Session

4b.  Ending an A+ Process

4c.  Ending an Emacs Session

4d.  Ending an Xterm Session

5.  The Emacs/A+ Interactive Environment

5a.  A+ Tutorials

5b.  A+ Scripts

5c.  A+ Sessions, Workspaces, and Log Files

5d.  The A+ Buffer in Emacs

5d1.  Setting the A+ Version
5d2.  Setting the A+ Host Machine
5d3.  Setting All Emacs Variables for A+ Mode

5e.  A Sample A+ Session


1.  Introduction

Xterm and Emacs entries, as well as section titles, are enclosed in
double quote marks when it helps to distinguish them from the
surrounding text.  The font in which the these tutorials appear on the
screen is in fact an APL font (kaplgallant); the distinction between
ordinary text and A+ expressions is usually clear from the context and
the use of special symbols.

It is possible that at some point, as you work through this tutorial,
you will find yourself out of step with the text.  Most likely, you
will be in an Emacs session at the time.  If that happens, exit from
the Emacs session and go back to a point in the tutorial where you can
start over.  The tutorial is not so long that this will be burdensome,
and it is definitely worthwhile to complete it successfully.


1a.  Key Press Notation

We will often use the notation Ctrl-, which means press and hold
the Control key and, while holding, press the key specified by .
For example, Ctrl-x means press and hold the Control key, and then
press the x key.  Similarly, Meta- means to press and hold the
Meta key, which is marked with a diamond, or "Left", or "Right." If
you are using an IBM keyboard, use Alt for Meta.

If the dash is omitted, as in Esc x, press and release the first key
(here Escape), and then press the other key (here x).

For the mouse, to "click" a button means to depress it and release it
quickly.  To "press" a button means to depress it and hold it until
you are told to release it. To "double-click" is to click twice in
quick succession.


2.  Starting Up

The purpose of this tutorial is to help people unfamiliar with the A+
system get up and running.

We are interested in two application windows in this tutorial.  One is
an Xterm.  This is an interactive window for executing Unix commands.
If you see an "Xterm" icon on the lower left, double-click on it and
an Xterm window will open.  Or, move the mouse pointer to the
background area, and then press and hold the right mouse-button to see
the main menu of applications.  Move the pointer to Xterm and release
the button, and an Xterm window will open.

You can start an A+ session in an Xterm session by entering:

/usr/local/bin/a+

Even though A+ started in an Xterm can be used interactively, the
preferred use is to run applications.  Interactive use of A+ is best
done in Emacs.

The Emacs editor window is the other application window of interest
here.  Once again, bring up the main menu of applications as you did
for Xterm.  Only now, move the pointer to Emacs/A+ and release the
button.  You can also start an A+ session within Emacs.  See "5. The
Emacs/A+ Interactive Environment".

If you now have both an Xterm and Emacs window on your screen then
most likely one overlaps the other.  


3.  Documentation

3a.  Written Documentation

3a1.  Unix

Unix is the operating system in which we work, and as an A+ programmer
you will most likely have to know the rudiments of the system.  The
following reference is recommended:

	The UNIX Programming Environment, by Kernighan and Pike

 	Prentice-Hall Software Series

It is also possible to display online documentation for Unix; see
"3b.Online Documentation".


3a2.  Emacs

The Emacs editor, which serves as the A+ application development
environment, is described in: 	

 	GNU Emacs Manual, by Richard Stallman

	Free Software Foundation

or

 	Learning GNU Emacs, by Cameron and Rosenblatt

 	O'Reilly and Associates, Inc.

3a3.  A+

3b.  Online Documentation

3b1.  Unix

There is substantial online documentation for Unix.  To view the
documentation on a particular topic from within an Xterm, enter the
command:

man topic

(man stands for manual pages).  For example, information on the Unix
command cp (for copying files) can be viewed as follows:

man cp

A formatted description of the topic will be displayed in the Xterm
window.  Press Ctrl-c to quit the display.  To learn more about manual
page command, enter:

man man

Another way to view manual pages is in a separate window, that can be
initialized from an Xterm by entering

xman &

(See the command Emacs & in "6c. More on Xterm" for the meaning of &.)
The effect of this command is to display a new window.  Click on the
"Manual Page" button in that window and a manual-page display will
appear, with help information in it.  Press and hold down the
"Options" button, drag the mouse pointer to search, and release.
Enter the topic whose manual pages you want to see, and press the
Enter key.

This display can also be obtained by pressing the right mouse-button
while the pointer is on the background area, moving the pointer to
"Tools" and then to the right and then down the submenu that appears
to "Manual Pages", and releasing the button.

If for some reason you want a print out of the online documentation,
e.g.  on the Unix command cp, enter the command:

man -t cp

The output should automatically be printed on the default local
printer in your area (see "6c. More on Xterm" regarding setting the
printer name).


3b2.  Emacs

Emacs has an online tutorial and online help.  Press Esc x, which will
move the keyboard cursor to the so-called minibuffer (the last line in
the Emacs window) with the prompt M-x.  Enter help- and press the
space bar.  That is, at the point where you should press the space
bar, the minibuffer should look like:

M-x help-

After you press the space bar you will see displayed the full names of
both the tutorial and online help.  Complete the name of the one you
want and press the Enter key.


3b4.  The Window Manager

The windows on your display are under the control of a program known
as a window manager.  T

4.  Exiting

4a.  Ending a Workstation Session

You can either log off the workstation, so that the next time you will
have to log on again and start from scratch, or you can lock the
workstation, which means that next time you simply unlock it and start
where you left off.


4b.  Ending an A+ Process

To end an A+ process without ending the Xterm or Emacs session in
which it is running, enter:

     $off

The next time you start an A+ process, the same log file (see "4c. A+
Sessions, Workspaces, and Log Files") will be active.  If you are also
going to end the Xterm or Emacs session, you may want to save the log
before you end the A+ process.


4c.  Ending an Emacs session

To end an Emacs session, press Ctrl-x followed by Ctrl-c.  You will be
prompted in the minibuffer to save any files that have been modified
since they were last saved.  In particular, if you have run A+ in this
session you will most likely be asked whether or not your A+ session
log should be saved:

Do you want to save .emacs_a? (Y/N)

You may want to answer Y to keep this log, at least for a while.  If
you answer N to any of these prompts, you will then be prompted as
follows:

Modified buffers exist, do you really want to exit? (yes or no)

Answer yes.  If you did not end your A+ session (see "4b. Ending an A+
Process"), you will then be prompted with:

Active processes exist; kill them and exit anyway? (yes or no)

Answer yes, and the Emacs window will disappear.

For a fast exit with no prompting, put the mouse pointer on the title
bar at top of the Emacs window and hold down the right mouse-button.
Move the pointer to "Quit" and release.


4d.  Ending an Xterm session

To end an Xterm session, move the mouse pointer to that window, and
press Ctrl-d.  Or, as with Emacs, put the mouse pointer on the title
bar at the top of the Xterm window and hold down the right mouse-
button.  Move the pointer to Quit and release.


5.  The Emacs/A+ Interactive Environment

The Emacs editor serves as the application development environment for
A+.  Bring up a new Emacs window, as described in the introduction.
The line next to the bottom line contains "Emacs: *scratch*".  The
area above this line is called a buffer.  The title of this buffer is
"*scratch*".  The bottom line of the window is called the minibuffer.

Press the function key F4.  The Emacs window should split into two
buffers.  The top buffer is now the scratch buffer, while the bottom
one is an A+ session with the buffer title "*a*".

The keyboard cursor is the solid, character-sized rectangle that
indicates where the next typed character will go.  The buffer
containing this cursor is called the "selected" buffer.  Pressing the
F6 key (see "5b. More on Emacs for information on the F5, F6 and F7
keys") repeatedly will toggle back and forth between the two buffers,
first selecting one and then the other.  Moving the mouse pointer into
a buffer and pressing the left mouse-button will also select that
buffer.

After you have pressed F4, the bottom buffer holds an interactive A+
session.  Select this buffer and you can enter A+ expressions for
evaluation.  If you were developing an A+ application then typically
you would select the top buffer and open an A+ script file for
editing.  Or, you might select an A+ tutorial instead.

To open a file in the selected buffer, press Ctrl-x followed by
Ctrl-f.  The minibuffer will automatically be selected and will
contain the prefix "Find file: ~/".  To open a file from your HOME
directory, simply enter its name and press the Enter key.  To open a
file in a subdirectory of your HOME directory, say the script
"filetest.+" in the directory "versiontests", enter
"versiontests/filetest.+".  To open a file in any other directory,
enter its full path and name, starting with /.  The initial / causes
Emacs not to include in the path the directory it identified in its
prompt.  For example, to open this tutorial, enter

(Install_Directory)/doc/tutorials/GettingStarted

If the file you name is found, it will be opened and displayed in the
top buffer.  Otherwise, the top buffer will appear to display an empty
file and, in addition, the message "(New File) "will be displayed in
the minibuffer.  In the latter case, the file will not be created at
this point; it will be created if and when you save it for the first
time.

Use the Home, PgUp, PgDn, arrow, and End keys to scroll through an
open file.

It is also possible to open a directory, in order to see the names of
the files it contains.  Once again, press Ctrl-x followed by Ctrl-f,
but in response to the prompt Find file: ~/, enter the directory name.
For example, to open the tutorial directory, enter

(Install_Directory)/doc/tutorials

You should then see a list of file names in the current buffer.  Any
file in the directory can now be opened simply by moving the keyboard
cursor onto the file name and pressing the f key.

Both A+ scripts and the tutorials contain executable A+ expressions
and function definitions.  An A+ expression that stands alone on a
line can be brought into the A+ buffer and executed simply by placing
the keyboard cursor on the expression and pressing F2.  (Once the top
buffer is selected, the keyboard cursor can be moved to the line
holding the expression with the arrow keys; or you can put the mouse
pointer on the expression and press the left mouse button.)  Note that
pressing F2 also causes the keyboard cursor to advance one line,
leaving you in position to bring the next line into the A+ session
with F2.

To bring an entire function definition into the A+ session, place the
keyboard cursor anywhere on the definition and press F3.  (If the
definition has only one line then F2 will do as well as F3.)
Unbalanced punctuation anywhere in the buffer above the function
definition, however, will prevent the function's being brought in.


5a.  A+ Tutorials

The A+ tutorials are located in
(Install_Directory)/doc/tutorials, where, for instance, you
will find the online version of this tutorial:

By default the Install_Directory is /usr/local/aplus-fsf-x.xx 
(where x.xx is version.release)

i.e. /usr/local/aplus-fsf-4.18/doc/tutorials/GettingStarted

Open the file for this tutorial in the top buffer and use the
down-arrow key to scroll down to this point in the file.  You can then
bring the following examples into your A+ session using F2.

	a3 5
	a
	g{x}:x*2
	g a

You will notice that when the first, second, or fourth lines are
executed, the result is displayed immediately below (not shown here).
The third line holds a function definition, and there is no result to
display when the line is executed.  It is sometimes convenient to
display the result of an execution in the tutorial; you shouldn't
execute these lines.  In general, the A+ expressions that should be
executed are indented like those above.


5b.  A+ Scripts

A+ scripts define applications, toolkits, and utilities.  They consist
of global variable and function definitions, as well as expressions
for initialization.

Scripts are loaded into A+ sessions using the $load system command or
the _load system function.  For example, once an A+ session is begun,
if you plan to use the screen management facilities, then load them as
follows:

	$load s

Once a script is loaded, all the functions and global variables
defined in it are available, and all the executable statements it
contains have been executed.  Scripts can themselves include $load
commands and _load statements, so that applications can load the
toolkits and utilities they depend on, and need not incorporate them
directly in their scripts.

The effect of $load is by and large the same as if the script file
were opened in a buffer, the keyboard cursor were placed on the top
line, and F2 were held down until every line was brought into the A+
session.  (See the A+ Reference Manual for the differences.) In
particular, script files are processed line-by-line, starting at the
top.

When developing and maintaining an application you will usually open
its A+ script in the top buffer and selectively bring parts of it into
the A+ session using the F2 and F3 keys.  F2 can also be used to bring
a multi-line function definition into the A+ session, but line by
line.  This is particularly useful during debugging.  Start with the
keyboard cursor on the first line of a function definition and press
F2 for each line.  (Or, simply hold F2 down and it will automatically
go from one line to the next.) As each line is brought in, its display
in the A+ session has a prefix of *'s on the left, one for each level
of unbalanced, nested parentheses, braces, or quotation marks (but not
brackets).

For example, consider the function definition

	penny x:{
	  m0.01;
	  i1;
	  while (m