
It will give you a series of instructions which you are to follow.

The tutorial file is structured as a set of folds, just like all documents
produced with the occam programming system. So as you work your way through the
tutorial you will be learning how to use the fold operations of the editor!
On starting the tutorial, try to ensure that you press only the keys
instructed. Later on, you will be expected to decide which keys to press.

To start the tutorial, find the cursor moving keys on the terminal you are
with "... Moving around a document". When the cursor has been
placed there, press [ENTER FOLD]. This will start the tutorial section 1.

--{{{  Moving around a document
This section of the tutorial describes the operations available for
opening and closing folds, and for moving around within them.
Folds are the principal means for storing text and other forms of
data produced by the occam programming system.

A fold is just a sequence of lines which have been "folded up" so that the
lines are no longer visible. Instead a single line is displayed, called the
"fold line", which usually contains a comment indicating what the lines were.

An operation called [ENTER FOLD] (which you have already used to get this far!)
makes the lines in the fold available for editing.

The line marked with "...  more in here" below is a fold which contains the
rest of this section of the tutorial.  To continue the tutorial, move the
cursor down until the cursor is on this line. Then press [ENTER FOLD] to
continue the tutorial.

--{{{  more in here
You will have noticed that whenever you press [ENTER FOLD] the screen is
cleared, and a new set of text lines is displayed on the screen. These new
lines are the contents of the fold. These are bracketted between two lines
marked with "{{{" and "}}}". These two lines are called "crease lines", and
the top one of them ("the top crease") also contains the text which was on the
fold line where you pressed [ENTER FOLD].

As well as [ENTER FOLD], there is a function called [EXIT FOLD],
which reverses the effect of the last [ENTER FOLD]. However, don't
press it just yet! First move the cursor down to the line below marked "use
of [EXIT FOLD]" and then press [ENTER FOLD].

--{{{  use of [EXIT FOLD]
Having pressed [ENTER FOLD] again, you have now displayed the contents of the
fold "use of [EXIT FOLD".

[EXIT FOLD] is used to reverse the effect of the last [ENTER FOLD] and put
you back into the position you were in when [ENTER FOLD] was last pressed.

So when you press [EXIT FOLD] now you should see a fold line marked with
"use of [EXIT FOLD]", surrounded by the lines which were there when you
pressed [ENTER FOLD] on that line.

You should then follow the instructions underneath that line.

Press [EXIT FOLD] now.
--}}}

If all has gone well you should have returned to here. Now move onto the
fold line below, and press [ENTER FOLD]. The tutorial will continue there.

--{{{  more in here
As well as [ENTER FOLD] and [EXIT FOLD], there are two more fold operations
available. These are called [OPEN FOLD] and [CLOSE FOLD].

Whereas [ENTER FOLD] clears the screen and makes the contents of the fold the
only lines visible, [OPEN FOLD] makes the contents of a fold visible in the
surrounding context. Think of a fold as a doorway into another room. If you
ENTER the doorway you leave behind the room you were in, and you can only see
the contents of the new room. If you simply OPEN the door you can see the
contents of the other room, but you stay in the first room, and you can still
see its contents.

Now try opening a fold, by moving to the fold below and pressing [OPEN FOLD].

--{{{  use of [OPEN FOLD]
Notice that when the fold is opened the lines below are pushed down
to make room for the contents of this fold.

Now use [CLOSE FOLD] to reverse the effect of the [OPEN FOLD] operation.
--}}}

Now move to the fold below and enter it.

--{{{  more in here
So far you have only moved down the screen. You may use the cursor keys on
your terminal to move around the screen.
These are [CURSOR UP], [CURSOR DOWN], [CURSOR LEFT] and [CURSOR RIGHT].

Move to the fold below and press [OPEN FOLD].

--{{{  moving around the screen
Now use [CURSOR DOWN] and [CURSOR RIGHT] to place the cursor on the 'i' of the
line below. Use [CURSOR LEFT] if you go too far to the right!

        A line of text

A function [START OF LINE] is available to move the cursor to the first
significant character of a line (that is, the first character which is not a
space). Try [START OF LINE] now.

The cursor should now be on the 'A'.
A function [END OF LINE] is available to move the cursor to the end of a line
(that is, just after the last significant character). Try [END OF LINE] now.

The cursor should now follow the final 't'. Now press [CLOSE FOLD].
--}}}

Now enter the fold below and continue the tutorial.

--{{{  scrolling the screen
All the folds you have seen so far you have been able to view by moving around
the screen and making use of the fold operations. Folding provides a way of
structuring some text so that an overall view of the text can be seen on the
screen. The fold operations become the principal means of moving around a
document.

However, sometimes a fold has more lines in it than there are lines on the
screen. This fold is an example. You can tell this because there is no bottom
crease matching the crease at the top of the screen. There are more lines
below the portion of the fold you can see, ending with a bottom crease.

The lines from the top crease to the bottom crease of the last entered fold are
called the current view. The screen can be seen as a window into that view.
There are scrolling functions to move the window up and down the view.

[LINE UP] and [LINE DOWN] move the window up and down the view a line at a
time.

Try pressing [LINE DOWN] a number of times until the screen stops scrolling.

Note that the scrolling stops when the bottom crease of the view becomes the
last line of the screen.

Now move the cursor down to the line below ("more on scrolling") and press
[OPEN FOLD].

--{{{  more on scrolling
When a fold is opened, the lines are inserted into the view between top and
bottom creases. Now press [LINE DOWN] a few more times until scrolling stops.

You may open a number of folds and add their contents to the view.
Try moving the cursor down to the fold below marked "yet more on scrolling"
and press [OPEN FOLD] there.
--}}}

--{{{  yet more on scrolling
Single line scrolling can become tiresome when there are many lines in the
view. The functions [PAGE UP] and [PAGE DOWN] are provided to move the screen
up and down the view a page (that is, a screenful) at a time.

Try pressing [PAGE UP] followed by [PAGE DOWN] now.

If you press [PAGE UP] and then repeat [LINE UP] until the screen stops
scrolling, the top of the view will be reached. This is
indicated by the top line containing the top crease of the view, marked with
the text "scrolling the screen".

Try that now, and then press [PAGE DOWN] twice to get back here.

Now move to the fold below, and open that, using scrolling to view it.

--{{{  finishing up
Folds which you have opened to insert their contents into the view may also be
closed using [CLOSE FOLD]. This function closes the nearest fold surrounding
the line on which the cursor is placed.

Put the cursor here ---> <--- then press [CLOSE FOLD] and [OPEN FOLD].

Notice where the cursor ends up.

You have now finished the section on scrolling. When you now press [EXIT FOLD]
it will reverse the effect of the last [ENTER FOLD]. The folds you have opened
since then will automatically be closed.
Press [EXIT FOLD] now.
--}}}

<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>                          Page 2
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>                          Page 3
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>                          Page 4
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>                          Page 5
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
--}}}
--}}}

When you have finished that, read the contents of the following fold,
which provides a summary of the functions you have seen so far.

--{{{  Summary of moving operations
The functions available for moving around the fold structure are :-

[ENTER FOLD]
  Makes the contents of a fold available for editing.

[EXIT FOLD]
  Reverses the effect of the last [ENTER FOLD].

[OPEN FOLD]
  Inserts the contents of a fold into the current view.

[CLOSE FOLD]
  Removes the contents of an open fold from the view.

[CURSOR UP], [CURSOR DOWN],
[CURSOR LEFT], [CURSOR RIGHT]
  Move the cursor around the screen.

[START OF LINE], [END OF LINE]
  Move the cursor to the start or the end of a line.

[LINE UP], [LINE DOWN]
  Move the screen up and down the view a line at a time.

[PAGE UP], [PAGE DOWN]
  Move the screen up and down the view a page at a time.
--}}}

Once you have finished with this, press [EXIT FOLD].
--}}}

Once you have finished with this, press [EXIT FOLD].
--}}}

Once you have finished with this, press [EXIT FOLD].
--}}}

Once you have finished this , you should press [EXIT FOLD] to return
to the top level of the tutorial. Continue with the other sections in the
same way.
--}}}

--{{{  Creating folds and inserting text
Now that you have learned how to browse around the fold structure, you
should not need to be given explicit instructions on what to do with
each fold in this document. It is generally best to enter each fold to
access its contents, and then exit it when it is finished.

The folds below describe how to insert and edit text, and how to create
and remove folds. Work through them in the order they appear, and then
return to the level above to move on to the next section of the tutorial.

--{{{  Inserting and deleting characters
It is fairly straightforward to insert text. In general any characters typed
are inserted at the cursor position. So for example you can insert some text
on the line below by moving the cursor to the end of the line and typing
" discontent"

    "Now is the winter of our
    made glorious summer by this son of YORK.
                   " Richard III- Shakespeare

There are two character deletion functions :-

[DELETE], which deletes the character to the left of the cursor, and
[DELETE RIGHT], which deletes the character under the cursor. Try deleting
the last few characters of the line and retyping them.

If you type [RETURN] when the cursor is at the end of the line a new line is
created. The cursor is positioned under the first character of the line. This
allows you to create indented text without having to adjust the cursor every
time you make a new line. Try typing [RETURN] now, followed by some text.
--}}}

--{{{  Creating and removing folds
A fold can be created using the [CREATE FOLD] function. Two presses of
[CREATE FOLD] are needed, one to mark the top of the fold and one to mark the
end of a fold.

--{{{  A simple example of fold creation
Try making a fold from the following lines. First put the cursor on the line
marked "line 1", in the first column of the screen, and press [CREATE FOLD].

Then move the cursor down until it is on line 4, and press [CREATE FOLD] again.


line 1
line 2
line 3
line 4

Note that the fold has been made from the line on which [CREATE] fold was first
pressed, up to (but not including), the line on which the second press of
[CREATE FOLD] was done.

The cursor has been placed after the "..." which indicates the fold. Type some
text at the cursor position ; for example "lines 1-3". Whenever a fold is made
it is a good idea to type some text here to indicate what the fold contains.
This text is known as the fold header.

Open and close the fold you have made to confirm that it contains lines 1 to 3.
--}}}

--{{{  Fold indentation
Every fold has an indentation associated with it. The indentation may be
changed by inserting or deleting spaces on the fold line before the
fold marker (that is, the "...").

Try this on the following fold. First open it to see its contents, then close
it. Then, with the cursor in the first column of the screen, type four spaces.

      --{{{  a fold to indent
      There are two lines
      in this fold.
      --}}}

These spaces should appear before the fold marker. Then press [OPEN FOLD]
again. By indenting the fold line, you have indented the contents of the fold
as well!

--{{{  Some comments on insertion and deletion of text in folds
It is not possible to insert or delete text to the left of the leftmost
column of an open fold (that is, the column in which the crease marks "{{{"
and "}}}" begin).

Only spaces may be inserted or deleted before the fold marker of a closed fold.

The markers which indicate fold or crease lines consist of the three characters
("...", "{{{", or "}}}") and two spaces following. Text may not be inserted or
deleted within these markers.

  --{{{  a fold to indent
  There are two lines
  in this fold.
  --}}}

You may wish to try insertions or deletions on the fold above to confirm these
restictions on where text may be inserted or deleted. Try deleting characters
before an indented fold line marker to reduce the indentation of the fold.
--}}}

Try pressing [ENTER FOLD] on the following (indented) fold line :-

  --{{{  This fold indented by two spaces
  Note that the view of the contents of this fold starts at the left-hand
  edge of the screen even though the fold was indented.
  
  Having entered a fold, we are only interested in its contents, not in its
  relation to the surrounding lines. So the indentation is ignored for the
  moment.
  
  This allows us to view quite deeply indented text (such as occam program text)
  without having a large amount of blank space on the left hand side of the
  screen.
  
  [EXIT FOLD] returns us to where we were before.
  --}}}
--}}}

--{{{  Creating indented folds
When a fold is created, the indentation of the newly created fold is taken
from the position of the cursor when [CREATE FOLD] is first pressed.

Try creating a fold within the following program text. To avoid problems,
make sure all the program text is on the screen before starting. First move the
cursor to the 'S' of "SEQ" and press [CREATE FOLD]. Then move beyond the
last line of the program and press [CREATE FOLD] again.

IF
  record[i] = key
    --{{{  found key
    SEQ
      found := TRUE
      position := i
    --}}}
  record[i] <> key
    i := i + 1

The message "Cannot create : lines in fold have incorrect indentation"
will appear. This is because the lines you have asked to be created in the
fold contain one line "record[i] <> key", whose indentation is less than
that of the fold being created. Instead move the cursor to that line and
press [CREATE FOLD] there so that there are three lines in the fold.

Type a comment such as "found key" on the fold you have created.

This example shows how indented folds fit well into occam program text,
in which indentation is significant.

If the indentation of a fold you have made is not right, you can always
adjust it by inserting or deleting spaces before the fold marker, as
previously described.
--}}}

Between the two presses of [CREATE FOLD], the only operations allowed are
cursor moves and screen scrolling operations. The message "Creating fold..."
appears to remind you what you are doing.

A fold can be removed using the [REMOVE FOLD] function.

--{{{  Example of fold removal
A fold may be removed by placing the cursor on the fold line and
pressing [REMOVE FOLD]. The contents of the fold are inserted into the
current view instead of the fold. The indentation of the inserted lines
are the same as when the fold is opened.

For example, try opening the folds in the following text, closing them again
and then removing them using [REMOVE FOLD].

SEQ
  --{{{
  going := TRUE
  WHILE going
    SEQ
      input ? command
      IF
        command = finish
          going := FALSE
        command <> finish
          SKIP
  --}}}

Now try creating the folds again! The result should look like the
contents of this fold :-

--{{{  copy of original program text above
    SEQ
SEQ
  WHILE going
      input ? command
      IF
          SKIP
          SKIP
          SKIP
          going := FALSE
        command <> finish
  going := TRUE
  going := TRUE
  going := TRUE
        command = finish
          SKIP
--}}}
--}}}

--{{{  Altering program indentations
The [CREATE FOLD] and [REMOVE FOLD] functions, along with the ability to
alter the indentation of a fold, are used together to change the indentation
of a block of program.

For example, the following program fragment has a section which is
incorrectly indented.

IF
  traffic.light = red
  SEQ                       --  These lines
    foot.on.brakes ()       --  should be indented
    stopping := TRUE        --  two more spaces
  traffic.light = green
    foot.on.accelerator ()

The lines indicated need to be indented more. Start by creating a fold
around these lines. Put the cursor on the 'S' of "SEQ", press [CREATE FOLD].
Then move down to the 't' of "traffic.light = green" and press it again.

Then indent the created fold by doing [START OF LINE] and inserting two spaces.
Now press [REMOVE FOLD] to insert the correctly indented text into the program.

Although this may seem a bit long-winded at first, it will become much easier
as the fold operations become more familiar!
--}}}
--}}}

--{{{  Inserting and deleting lines
The folds below describe a number of techniques for inserting and deleting
lines in a document.

--{{{  Using [RETURN] and [DELETE]
We have seen above how lines may be created by using [RETURN] at the
end of a line. [RETURN] may also be used to split lines in two. Try placing
the cursor between the arrows on the line below and typing [RETURN].

Try splitting this line here --> <--
Line underneath

The upper line is split into two, with the right-hand section inserted as the
line below. Now try pressing [DELETE]. The lines are joined together again.

However, a fold line may not be split, or joined with another line. Try going
to the line below, and splitting it between the arrows. Also try using [DELETE]
on the 'L' of the line underneath

--{{{  try splitting this fold line here --> <--
[RETURN] at the end of the line above
inserts a line at the start of this fold.
--}}}
Line underneath

Similar restrictions apply to crease lines. However, [RETURN] may be used at
the end of these lines.  Try opening the fold marked "try splitting", moving
to the end of the crease line and pressing [RETURN].
--}}}

--{{{  Using [LINE DELETE] and [LINE UNDELETE]
As well as the functions described above for joining and splitting lines,
there is a function which deletes a line from the document altogether.
To use this, move to the line you want to remove and press [DELETE LINE].

Try moving to the line marked "A line to delete" below and deleting it.

A line
A line to delete
--{{{  a fold line to delete
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
--}}}
Another line

Try pressing [DELETE LINE] again. A fold line may also be deleted! Since there
may be a lot of text contained in the fold, this makes [DELETE LINE] quite a
powerful operation. So it should be used with care!

If you delete a line accidentally you can get it back using [UNDELETE LINE].
Try pressing that now. Undeletion is an "undo" type of operation which should
be used immediately after the deletion, if you had cause to regret it. Any
operations other than cursor moves or screen scrolling operations cause the
line to disappear for good.

A crease line may not be deleted. Try opening the fold below and deleting its
contents. The deletions stop when you reach the end of the fold.

--{{{  a fold line
delete me
and me
--}}}
--}}}
--}}}

--{{{  Moving and copying
The editor provides two functions which may be used together to copy sections

--{{{  Moving lines
[MOVE LINE] can be used twice to move a line from one part of the document to
another.  The first press of [MOVE LINE] is used to pick up the line - it picks
up the line which the cursor is on.  The second press is used to put the line
down - it inserts the picked line above the line which the cursor is on.

Try [MOVE LINE] on the following text - use it to place the lines in order.
First move the cursor to the line marked "March" and press [MOVE LINE].  This
line will disappear - it is now in the move buffer. Now move the cursor to the
line marked "April".  Press [MOVE LINE] again. It will insert the "March" line
in the correct place.

March
January
February
April

Any set of editor functions may be used between the presses of [MOVE LINE].
However, when you finish a session with the occam programming system and return
to operating system level, the contents of the move buffer are lost.

The fact that the move buffer only contains one line means that it is easy to
reverse if you press it accidentally - it doesn't insert a long sequence of
lines into your document.  If you want to move a sequence of lines around, fold
them up first.

[MOVE LINE] can be used on a fold line in exactly the same way as on a
text line. So major reorganisations of a folded document can be done with a
few key presses. For example, try reorganising the following document:

--{{{  The Perils of Pauline
--{{{  Chapter 3
--{{{  the rest of the chapter
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
--}}}
And they both lived happily ever after.

THE END.
--}}}
--{{{  Chapter 2
The tall dark stranger staying at the inn that night introduced
himself to Pauline.
"My name is Ramon" he said, in a husky voice.
--{{{  rest of chapter
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
--}}}
--}}}
--{{{  Chapter 1
It was a cold and rainy night as Pauline set out
on the most momentous journey of her life.
--{{{  the rest of the chapter
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
<blurb>
--}}}
--}}}
--}}}
--}}}

--{{{  Copying lines
The [COPY LINE] key copies the line which the cursor is on, inserts the new

Copy me (a text line)

--{{{  Copy me (a fold line)
All my contents
are copied too!
--}}}
--}}}
--}}}

--{{{  Summary of editing operations
The keys you have used in this section of the tutorial are the following:

Character keys     : insert characters at the cursor position

[RETURN]           : splits a line in two

[DELETE]           : deletes the character to the left of the cursor
                     It may be used at the left edge of a line to join lines.

[DELETE RIGHT]     : deletes the character under the cursor

[DELETE LINE]      : deletes the current line (including fold lines)

[UNDELETE LINE]    : used after a [DELETE LINE], restores the line

[MOVE LINE]        : used twice to move a line; once to pick it up, and
                     once to put it down

[COPY LINE]        : duplicates the current line

[CREATE FOLD]      : used twice to create a fold, once to mark the top of
                     the fold, and once to mark the bottom

[REMOVE FOLD]      : on a fold line, removes the fold and inserts its contents
                     at that position in the document
--}}}
--}}}

You can now press [EXIT FOLD] to return to startup fold.
As you have been making changes to this file as part of the tutorial,
a new copy of the file will be written out as you exit.
