@database readme.guide
@rem $date: 93/11/18 18:43:00 $ $Revision: 1.9 $

@node MAIN
@title "Instructions for use"

@{b}@{u}Index@{ub}@{uu}

   1.0 @{" Installation " link installation}
   2.0 @{" Main Menu " link menu}
   3.0 @{" Enter text " link enter}
   4.0 @{" Print text " link print}
   5.0 @{" Load  text " link load}
   6.0 @{" Save  text " link save}
   7.0 @{" View an entry " link view}
   8.0 @{" Exit " link exit}

@endnode

@node installation "1.0 Installation"

Simply @{b}copy siliconjournal to <filename>@{ub} where <filename> is
where you want to put it. For example:

          copy siliconjournal to dh0:c

The program will run from either workbench or CLI. However the machine
must have been booted from workbench or it may not work properly.

The program currently assumes an 80 column display setting (topaz 8
font). It might operate on different settings, but the screen layout
will be pretty chaotic. It is also assumed that all workbench printer
drivers etc. are set up correctly.

@endnode

@node menu "2.0 Main Menu"

When the program is run, a black screen will appear with six large
icons on it. This is the  main  menu. At this point the mouse can be
used to select one of six possible operations :-

   @{" Enter text " link enter} -      shown as a pair of hands typing
                          at a keyboard

   @{" Print text " link print} -     shown as a computer, an arrow
                          pointing to the right and a printer

   @{" Load text "  link  load}  -     shown as a computer, an arrow
                          pointing to the left and a disk drive

   @{" Save text "  link  save}  -     shown as a computer, an arrow
                          pointing to the right and a disk drive

   @{" View entry " link view}  -    shown as a book with a page torn
                          out and an arrow pointing to a screen

   @{" Exit " link exit} - shown as a large exit door.

In all cases, (except  @{" Exit " link exit},) the program then
switches to an 80 column screen which is blue on white for WB1.3 and
grey for WB2 and WB3 users. After the completion of the selected
operation, (again except for @{" Exit " link exit},) the program will
return to Main Menu.

Note: Although it is possible to switch between the two screens using
the standard front/back gadgets, this is not advised because you will
need to return to and reactivate the screen the program was on at the
time, before the program will let you continue.

@endnode

@node enter "3.0 Enter Text"

When selected, this part of the program will first clear any existing
diary entries out of memory in order to prevent multiple copies of an
entry being stored by mistake.

Next the program will ask you for a subject heading to identify the
new entry. This is just to make it easier on yourself when locating it
later. If you give all entries the same subject title it may be harder
identifying which is which. Enter up to fifty characters at this
point. You will be able to use the backspace to delete a character
to the left of the cursor. (Except when on the 50th character when it
will delete the character under the cursor.)

Next the program will attempt to read the time and date from the
system. If your computer is not fitted with a real-time clock, then
this information will probably be completely wrong.

The program will ask if you wish to change the information. If you do
wish to then press the 'Y' key, otherwise the program will proceed to
the @{" editor " link editor} stage where you type in the entry itself.

If you wish to change the date and time, the program will first ask
for a new date and then (if it accepts the former) a new time. The
program will expect exactly 8 characters in each case and the
backspace will behave as with the subject heading, only this time the
backspace key will only delete the character under the cursor when on
the eighth character. The third and sixth characters are ignored.

If the program does not accept the information it will ask you for it
again, otherwise it will ask you to confirm it. (Type 'Y' to confirm)

@endnode

@node editor "3.1 The editor"

The program has a (somewhat) full screen editor. I say somewhat
because it lacks the sort of facilities found in word processors or
other programs of a similar nature. The system operates entirely from
the keyboard (with one exception which is explained shortly.)

The program will automatically attempt to word-wrap any text as it is
typed in. The cursor is moved with the four cursor keys and you can
insert text in a previously typed in paragraph by simply moving the
cursor to where you want it to be and starting to type in you new
text. With the first keypress the line will be split with the text to
the right moved down onto a new line to make room. As you type, new
text will be word-wrapped automatically. When you have finished, just
move the cursor away using one of the cursor keys and the paragraph
will be tidied up again.

If for some reason a paragraph is not correct it is possible to ask
the program to reformat it by pressing the F1 key.

A new line can be inserted by use of the ENTER key.

Both the 'delete' key and the 'backspace' key work in this editor

The HELP key can be used to call a small 'help' window with a list of
these keys in.

Closing the window with the mouse (select the close window gadget in
the left hand corner of the window that appears) will return you to
the editor.

If you press 'return' at the beginning of a line to insert a blank
line, it may add two lines. This is not a bug, but simply a quirk of
the way the editor works. The second one will vanish when the
paragraph is reformatted.

A more noticeable quirk is that because of the way the word-wrapper
works, if you insert a new piece of text inside an existing word the
program will create an extra space. This might happen if you wanted to
make an existing word into a longer word. Just get rid of this space
by move the cursor over it and using the delete key.

To leave the editor press the ESCape key or holding 'CTRL' and then
pressing '\' .

Because this is meant to be a @{b}diary@{ub} program (of the journal
kind, not one of the hundreds of appointment book programs doing the
rounds) a design decision was taken that once an entry is finalised it
is permanent and the program will not allow you to change the entry
later - so get it right before leaving the editor. The idea being that
a diary is a sort of historical document and that once a thing is
committed to silicon it should stay that way and not be altered at a
future date.

[Of course you CAN change the file on the disk using an ordinary
editor, but this does rather defeat the object of the program, and
unless the record lengths created by the program are also changed to
match, the data thus changed will not load properly]

When you try to leave the editor a warning requester should appear. If
you are happy with what you have typed in click on the 'proceed' box.
If you decide to make some changes at this stage, click on the 'go
back' box.

At the end of all this the program will automatically jump to the
'Save' routine (explained later) to put the entry on the disk.

@endnode

@node print "4.0 Print Text"

If there is no entry currently in memory this routine will first call
the @{" load " link load}to load all the entries into memory so that
it has something to print.

You are first asked if you wish to print all the entries. Press the
'Y' key if you want to print out the lot, otherwise press the 'N' key.

Printing all entries is not recommended if there are a lot of them,
which can all too easily happen if the diary is in use for any length
of time. At present the only way to stop the routine once this has
been selected is to turn off the printer and then when about 30
seconds later the 'printer trouble check cabling' requester comes up
select 'cancel'.

Pressing 'N' invokes the @{" search " link search} routine. Having
identified the entry it will be printed.

Note due to a slight oversight, the program currently assumes that
there are no printer margins set in workbench preferences, so if there
are any, the text will be printed, but may look a bit strange on the
printer.

@endnode

@node search "4.1 Search routine"

This may seem a little complicated at first, but bear with me, it's
actually intended to speed up entry identification for printing (or
viewing.) First a page headed 'Search for Entry' appears with various
boxes which can be selected and typed into.The idea is that you can
use as many or as few of these as you wish. You don't actually have to
type anything into any of them. The program will actually run faster
(sometimes @{b}considerably@{ub} so) if you leave them all blank, but
this may put more work onto you later on and less onto the machine.

The first two boxes are to allow you to narrow the search by not
allowing entries before a given date or after a give date. The
accepted form is in British notation.

DD MM YY (the space character is actually ignored except for alignment
purposes, so you could type 28#03@94 if you like.)

DD is the day (must be two digits in the range 01 to 31)
MM is the month (01 - 12)
YY is the year (00 - 99)

Next is the subject box. I personally prefer not to use this one much,
because the program is case-sensitive (capitals matter) and it's all
to easy for a small typing error to mean that the routine rules out an
entry you actually wanted.

The last six boxes are for up to six optional keywords. However the
program will run more slowly if you use them. In fact, the more
keywords used, the slower the search. If you have a large number of
entries (several hundred say) the program can take several minutes,
just on the one keyword. However this facility is provided
because if you can stand the wait, it can considerably reduced the
number of entries for you to choose from at the next stage.

The big box with the writing in is actually a switch for use with the
aforementioned keywords. You can have it so that either the program
must find entries which contain all of the keywords you have asked
for, or for it to be sufficient for a  entry to contain just one of
them.

The last two icons are the important ones. The tick means 'proceed'
and the cross means 'cancel'..

The easiest thing to do is simply to click on the tick mark as soon as
the page appears. This will use whatever is currently in the boxes. If
there has not been any change to the diary since the last search
operation, then it will also skip over the next section without
wasting time looking for what it found last time it was called.

When the search is complete the screen changes to show a list of all
the entries that fulfil the conditions that you have specified. (If
there weren't any it will be the complete list).

Each entry in the list is represented its subject header, the date and
time it was created, number of lines long and the first line in the
entry.

To select the entry just click the one you want.

IF there are more than nine to choose from, a slider gadget will
appear to the right of the screen. By pulling the slider bar, you can
adjust the position in the list that can be seen on the screen.

At the bottom of the screen is the total number of entries available.

@endnode

@node load "5.0 Load Text"

After checking that there is  nothing  in memory about to be
overwritten, (a warning requester will appear if there is, giving you
one chance to change you mind,) the program will first clear all
entries from memory and then display a file requester asking for the
name that of the disk file that the diary is stored in. The
complete diary is then loaded into memory.

Users of WB1.3 (Older A500s - Not plusses) will have to put up with my
attempt at a file requester. It lacks the little arrows of the ARP one
or the plush look of CBM. It's even rather slow but it does actually
work. If the lack of speed is driving you bananas it is possible with
a bit of practice to short-cut the operation when it first appears by
typing in the path and filename into the string gadgets using the
mouse to select each gadget (@{b}without pressing ENTER@{ub}) and
selecting the tick mark before the requester starts chugging away at
the disk.

The cross symbol means cancel, the tick means proceed, drive really
means DOS device which can be saved to or loaded from and the rest
should be fairly easy to figure out if you have used file requesters
before. You must use the tick mark to proceed. You can't simply double
click on the filename you want to use.

Users of more modern machines get to use CBM's standard new look file
requester instead. It's functionally much better than mine as well as
looking better. The programmers among you will know it's the one in
the asl.library from workbench 2 onwards.

@endnode

@node save "6.0 Save Text"

This routine is actually very similar to the previous one - it uses
the same file requester although WB2+ users get to use CBM's slightly
different 'save requester'.

Apart from the obvious difference except that it saves text to disk
instead of loading it, there are two other small differences.

It doesn't actually 'save' text in the usual fashion. If the file to
be used already exists, as will usually be the case unless you are in
the habit of keeping multiple diaries, it appends the text. ie. it
adds the new entries onto the end of the file immediately after the
old ones.

The other difference is that if the routine is invoked when there are
no entries in the memory, it then invokes the @{" load " link load}
routine first. If the load is cancelled, it gives up and just returns
to the main menu screen.

@endnode

@node view "7.0 View an entry"

There wouldn't be much point in a journal if you couldn't look at what
you've got stored in it, so this is the routine that lets you do just
that.

If there are no entries in memory already the routine will call the
 @{" load "link load} routine first in order to have something to 'view'.

In order to determine which entry you wish to look at the program
first goes through the same @{" search " link search} routine as
explained in section 4.1.

Having told the program which entry you wish to see the program then
invokes the 'viewer' routine.

As with the @{" editor " link editor "} (section 3.1) pressing HELP
will bring up a little window explaining what the various keys which
control it do.

However this are not the quite the same.

The keys that control the viewer are as follows...

HELP                    Brings up list of keys in window (close
                        window to get
                        rid of it)

'Down' cursor key       moves down one line
'Up' cursor key         moves up one line
Shifted 'Up' key        moves up a whole page [33 lines]
Shifted 'Down' key      moves down a whole page
HOME key                Moves to top of entry [first page]
END key                 Moves to end of entry [last page]

ESC key                 leaves viewer and returns to main menu screen

As it happens the following keys also work

      8 and A            = 'up' arrow
      2 and B            = 'down' arrow "
      9                  = Shifted 'Up' arrow
      3                  = Shifted 'down' arrow
      7                  = END
      1                  = HOME

      Q and ENTER both leave the editor

@endnode

@node exit "8.0 Exit"

No prizes for guessing what happens when you select this icon.

The program terminates and returns you to the Workbench screen (if
called from there.) If it closed down the Workbench - as it will do if
there are no other tasks running, although the program should be able
to multitask - it will reopen it.

If you like this program please send £5.00 to...

Bruce Warren

10, North Crescent
Garlieston
NEWTON STEWART
Wigtownshire
DG08 8BA
Scotland

@endnode