%OP%BON
%OP%HM3
%OP%FM4
%OP%BM0
%OP%LM6
%CO:A,12,72%
%H2%USER NOTES FOR LACKEY                                    %H2%September 1990

%H2%How lackey is used.%H2%

LACKEY is a 'laptop command key' program, or a 'line-address command 
key' interpreter.  It's really called Lackey because within reason it 
will do whatever you need of it.  It is a Basic program that operates 
in the Basic application of your Z88, but can be accessed from any 
other application.  On its own it does nothing useful, as it is a 
'shell' program.  But once you have inserted your favourite command 
line interpreter (CLI) files  into it, the program becomes as useful as 
you like to make it.  

By attaching the CLI files to each of the numeric keys, it turns them 
into 'function keys', that is, keys that will perform familiar 
operations which would otherwise entail striking a long sequence of 
keys or waiting for the Z88 to perform lengthy procedures requiring 
your intervention.  With Lackey, a typical operation from Pipedream 
would be to strike three keys: []B to enter Basic, and a numeric key to 
execute the CLI file (which is now no longer a separate file, of 
course, so it is better called a 'COMMAND LINE').  If you wish, you can 
write command lines that offer 'VARIATIONS', such as a choice of how 
many times the command is repeated.  For these, one or more further 
keystrokes would be needed.

Its use is now described in more detail.  After striking []B, a MENU is 
displayed offering a choice of nine function keys, one for each of the 
numeric keys 1 to 9.  The menu assigns a LABEL to each key, which you 
wrote yourself, saying what it does.  A tenth key quits Lackey.  You 
select a key from the menu and strike it.  But if you can remember what 
key you want, say 7, you strike []B7 without waiting for the menu to 
appear.

If you have more than nine function keys, you will want more menus. 
At the top of the menu is a banner bearing the TITLE of this 
particular menu.  At the foot there is a strip giving the titles of 
the other menus that you have, each associated with a letter key.  From 
this menu you can call any of the others by striking that key instead 
of a number key.  It does not matter whether you use upper or lower 
case.  The titles, again, were written by you.

It follows that you can have up to 26 menus (and therefore 234 command 
lines). When you strike []B to enter Basic, Lackey will automatically 
display menu A, but by striking another letter, you can change that.  
The new menu remains available, however many function keys you select 
from it, until you change it again.

This means that you do not have to press a letter key whenever you use 
one of the function keys.  You just organise things so that all the 
command lines you use together in a particular application or for a 
particular task appear in the same menu.  If you use some command lines 
for several tasks, their labels can be repeated in all the menus 
without neeeding to rewrite the command line itself.

Again, if you can remember the keystrokes, you do not have to wait for 
one menu to appear before changing to another.  You simply use the 
letter key in the way you would use a shift key or control key to 
precede the function key.  So, from another application you could type 
[]BD7 to execute item 7 in menu D.  But if menu D was already installed
you would only need to type []B7.  

If the command you select from the menu is one with variations, a 
prompt will appear on the second line of the menu, with a flashing 
arrow to the left of it, asking you for some reply.  If the command is 
to copy lines between two files, it may ask how many lines you want to 
copy.  If the command loads a file from RAM, the prompt may ask you for 
the name of the file.  In this case the letters you type are displayed 
at the end of the second line. The wording of the prompt is again 
something you write yourself.  

Before you can use Lackey, it must be up and running in Basic.  So 
there is a preliminary step in which you enter Basic, clear any old 
programs by typing NEW, and type CHAIN "LACKEY.BAS" (or, alternatively, 
LOAD "LACKEY.BAS" followed by RUN).  This brings the first menu to the 
screen.  You can then leave this (or any other) menu up and at the 
ready whilst you leave Basic and enter whatever application you are 
engaged in.  You can leave this Basic application as a 'suspended 
activity' permanently, if it suits you, so that the function keys are 
always available.  It is labelled LACKEY in the Index suspended 
activities menu.  This must be your only suspended Basic application if 
you wish to call it repeatedly with []B, although, of course, it can 
always be accessed from the Index menu.


%H2%Do you need Lackey?%H2%

Lackey is based on another program for producing function keys called 
Funkey, by Michael Hey and Barry Green.  The idea originated there.  In 
its current version Funkey offers a single menu for command lines 
without variations.  If you only want to assign simple command lines to 
no more than nine function keys, then you should use FUNKEY, which has 
the great merit of being very much shorter than LACKEY. It is listed in 
Z88 Eprom 4.3.12. 

If you do not have much RAM to spare, space may decide whether you use 
Lackey, as without any command lines it uses 3330 bytes of memory when
compressed as a Basic program (and a couple of menus can double that). 
However, you may not need to load the whole of Lackey.  

If you want more function keys, but only want to assign simple command 
lines to them, then you only need part of Lackey.  You may discard 
PROC_VARY and all following procedures (that is, line 1500 onwards).  
As an alternative, of course, you may have several versions of Funkey 
for different menus.  If "spread" (see later) is the only type of 
variation you need, then you can omit PROC_PROMPT and PROC_INTERP.  


%H2%How to write simple command lines into Lackey.%H2%

The remainder of these notes explain how to fill the shell with the 
command lines you want to use.  If you want more informatiion about 
writing command lines, you should read about CLI files in the Z88 
manual (which does not say very much about them) or the various Z88 
guides, or back issues of Z88 EPROM.  As an alternative to writing 
them, you could adapt command lines from the CLI library run by Michael 
Hey for the Z88 User Club.

The best way of adding your command lines is to load Lackey into 
Pipedream, choosing the "load as plain text" option, where you have 
full editing facilities.  When you have finished, you open a blank 
first line and type in .J, without any line number.  Save the file as 
plain text, move to Basic and type *CLI .*<filename>.  The program will 
then be reeled into Basic, taking an impossibly long time.  To make it 
quicker to load and more economical to store, you can then save it as a 
Basic file with SAVE "<filename>".  In future, this can be loaded as 
described in the last section, in a flash.  To get the program back 
into Pipedream once you have tested it and found all your errors, load 
it into Basic and type LIST[]=S.  The program will scroll through the 
screen, whilst being transferred to file :RAM.-/s.sgn.  When it has 
finished, type []-S, go to Pipedream and load this file as plain text.  
You will need to clean off the bottom line.  Then GO TO THE FILER AND 
ERASE THE FILE :RAM.-/S.SGN, which would otherwise cause the Z88 to 
crash on a reset. 

Having rehearsed these basics, we can now move on to the real subject. 
The first thing to realise is that the shell program begins on line 
1000.  The earlier lines are reserved for your command lines.  Some of 
them have been taken up with demonstration lines.  If you have already 
loaded Lackey, the demonstration program will enable you to get the 
feel of it.  In the explanations below, it will be used to illustrate 
how to write in diferent types of command line.  Remember that key A6 
is executed from program line 6, and key B7 froom line 17, and so on.  

Do not expect the demonstration commands to do much of interest.  They 
are all commands which alter the Panel settings, and are 
self-repetitive and fairly trivial applications of the facilities.  
Their advantage over more realistic applications is that they 
demonstrate the workings of Lackey without the need to set up anything 
else and with minimum effect on your files (just set up the panel as 
you like it when you have finished and erase the stray file in RAM.0 
called PanelA that one of the commands creates).  They can also be 
executed without leaving the menu, which makes demonstration much 
quicker.  If used in this way there is no need to key in []B.  Their 
difference from commands that you would write for normal use is that 
they do not return you to the application you were in when you pressed 
the function key.  The one exception is C1, which will return you to 
whatever application you were in. 

To use Lackey for your own command lines you must begin by erasing all 
lines before line 1000, although you may like to save them first.

Let us first consider SIMPLE command lines without any variations. And 
let us suppose that you only wish to use nine of them, so that they can 
all be in one menu.  The command lines will be put in program lines 1 
to 9, one command line per program line.  There should be no gaps; if 
there empty function keys they should be written like program lines 22 
to 29 in the demonstration.

All the program lines you enter must begin with the word DATA in 
upper case, which tells the program that this is information to be read 
later.  The entry for each of these lines has two parts, separated by a 
comma:

  DATA "<label>",<command line>

 [see line 1, for function key A1 in the demonstration program]

If you want to keep track of what the program does with this data, you 
may like to know the variable names that the READ statements assign to 
it.  They will always be given as well in the explanations below:

  label$,chain$

The label is for the menu, and can be up to 42 characters long.  It has 
been put between quotation marks to distinguish it from the command 
line.  If the command line begins with a leading blank (this is 
unlikely) or contains commas, quotation marks or inverted commas (this 
is quite possible) it will have to be put between quotes as well. This 
is true of all non-numeric items in DATA lists, called "strings".  The 
safest measure is to always put them in quotes, but this can become 
very tedious.  The convention used in the demonstration program is to 
put labels which will appear on the screen in quotes, but not other 
strings, unless this should be essential.

Line 10 would be written as follows:

  DATA 1,"",0,0

 [see line 30 in the demonstration - the reason for the '3' there will 
  become apparent later]

This tells Lackey that there is only one menu, and that there are no 
menu titles to be considered.

Going on from there, let us consider what happens if you want several 
menus.  The items for each menu go on lines 1-9, 11-19, 21-29, and so 
on as far as you need or at most up to 251-259.  Lines 10, 20, 30 and 
so on up to 260 are the ones that hold the headers and footers for the 
menu in the preceding nine lines.  

You give a title for the header, which will appear in front of the 
words FUCTION KEYS to make a phrase like EDITING FUNCTION KEYS.  And 
you cite the titles (or abbreviations) of the other menus for the 
footer.  These last are displayed with their letter keys, as a kind of 
mini-menu in a banner strip at the foot of the menu, to remind you 
which keys call the other menus.  The complete entry is as follows:

  DATA <number of menus>,"<title of this menu>",<number of cited 
     titles>,<line number of first cited title>,"<title>","<title>",...

  menus%PC%,title$(0),titles%PC%,first%PC%,title$(1),title$(2),...

 [see lines 10, 20 and 30 in the demonstration program; see line 21, 
  for function key C1, for a simple command line in another menu]

The 'number of menus' is the total number of menus that you have in 
use.  You may not want to cite all these in the footer banner, which is 
why the next two numbers have to be entered.  The 'number of cited 
titles' refers to the number of titles that you do cite, listed to the 
right.  The 'line number of first cited title' is the number of the 
program line on which the first of them appears (10, 20, 30 etc).  The 
other titles must follow in their program sequence, omitting the title 
of the current menu. 

One reason why you may not cite all the menus in the footer banner is 
that you may not have room to do so. The banner is 93 characters long, 
and each title requires an additional three spaces for its letter code 
and gaps.  The combined length of your cited titles must be no greater 
than what remains.  Thus, if you have eight menus, there are 93-(8x3) = 
69 characters available for the titles which is, say, one word of about 
eight charcters per title.  


%H2%How to write variations on simple command lines.%H2%

The above is all you need to know to be able to set up several menus of 
simple short command lines.  The rest of this explanation explains how 
to set up VARIATIONS on these lines.  
 
Commands with variations also begin on the opening program lines 1-9, 
11-19, etc. where the menu labels are given.  But they refer the 
program to additional DATA lines written after all the opening lines.  
Lines 261 to 999 would normally be reserved for this purpose.  Unlike 
the opening lines, there can be gaps in the lines for variations.

The first variation is just a way of coping with command strings too 
long to type on one line.  Although Basic will accept very long lines, 
you may wish to keep lines short enough to read on the screen without 
scrolling to left and right.  Lackey will only allocate one opening 
line to each menu item.  If you have longer strings they must be spread 
onto a sequence of the later lines.  This is the variation called 
"spread".  The entry in the opening line leaves a blank instead of the 
command string, followed by the keyword "spread", followed by the 
number of the first additional line to which the program should go for 
the long command string:

  DATA "<label>",,spread,<first line number of variation>

  label$,chain$,VARY$,line%PC%

 [see lines 2 and 11, for function keys A2 & B1, in the demonstration]

Note that the pair of commas is sufficient to indicate a blank item - a 
more explicit alternative would be to type a pair of quotes <""> 
between these commas.  Note also that the word "spread" can be placed 
between quotes, but need not be.  

The variation is then spread between as many data lines as you need,
beginning with the line that Lackey has been referred to, as follows:

  DATA "",<number of lines>,0,<first part of command string> 
  DATA <next part of command string>
   ...
  DATA <last part of command string>
     
  prompt$,links%PC%,ties%PC%,link$
  link$
   ...
  link$

 [see lines 263 to 265 in the demonstration program]

where 'number of lines' is the number of lines over which the command 
string has been spread.  These lines can be referenced from more than 
one menu.  

 [In the demonstration lines 261 to 263 are used by both the
  opening lines 2 and 11, that is from both the menus A and B]

These command files are executed with a single keystroke from the menu 
in the same way as a simple command line which has not been spread.  In 
contrast, there are several ways in which command lines can be varied 
with further keystrokes given in reply to a prompt.

To do this, the command line is broken into several pieces, separated 
by commas.  This structure can be thought of as a CHAIN composed of 
several LINKS.  The links are held together by TIES, which are the 
pieces that can be varied.  The smallest number of links you can have 
is two, and there is no upper limit.

 "link","tie","tie",...,"link","tie","tie",.........,"link"

It is the number of ties and what happens to them that distinguishes 
between one type of variation and another.  An "option" variation has 
several ties in each location between links, one of which is selected 
by the reply to the prompt.  There must be the same number of ties, up 
to nine, in each location.  When you reply '2', say, Lackey selects the 
second tie from each location and builds a chain using these and the 
links.  That is, it builds the chain up as you have listed it rejecting 
all the ties but those in the one position you have selected.  If you 
reply 0 it misses all the options out of the chain.

In a "repeat" variation there is just one tie in each location which is 
to be repeated the number of times you reply to the prompt.  Your entry 
looks like this:

 "link","tie","link","tie",.........,"link"

Lackey assembles the chain inserting the ties between the links the 
number of times you select.  If you reply 0, it builds it up without 
putting the ties in at all.  

In a "manual" variation you do not put any ties in the program, but 
type one in manually in reply to the prompt.  So your entry looks like 
this:

 "link","link",...,"link"

with the locations between the links being all the places where your 
reply to the prompt will be placed.  There is a maximum length for the 
manual tie, which you must state in the program.

The "spread" variation already described is simply a chain to which 
ties are not added, and the command line entry looks the same as the 
entry for the manual variation, with the links on separate lines.

The form of the opening line is as that for the "spread" variation, 
except that the keyword "repeat", "option", or "manual" replaces 
"spread" as appropriate.  These keywords must be entirely in lower 
case.

  DATA "<label>",,spread|repeat|option|direct,<line number>

  label$,chain$,VARY$,line%PC%(1)

 [for "repeat" see line 4,        for function key A4;
  for "option" see lines 3 and 19 for function keys A3 and B9;
  for "manual" see line 5,        for function key A5, all in the demo]

'Line number' refers to the first line of the variation, later in the 
program, which is set out as follows:

  DATA "<prompt string>",<number of links>,<number of ties* in each 
          location>,<link>,<tie>,<tie>,...,<link>,<tie>,<tie>...,<link>
    
  prompt$,links%PC%,ties%PC%,link$,tie$(1),tie$(2),..,link$,tie$(1),tie$(2),
                                                              ...,link$
  * in the "manual" variation, this is the maximum number of characters 
  that can be entered for the tie; if a lower number is entered it 
  must be made up to the maximum with blank spaces
 [for "repeat" variation see line 270; 
  for "option" variation see lines 268 to 269 and line 279
  for "manual" variation see lines 274 to 275 in the demonstration]

This entry may be spread over as many lines as needed.  To do this you 
break between lines wherever there is a comma, leave the comma out, and 
begin the next line with the word DATA.  

The keystroke in "repeat" or "option" may stand for some aspect of the 
operation being performed by the command file, such as marking a number 
of lines as a block, or selecting a RAM card, but the mechanics of the 
command line may call for different numbers, so that the reply '1' 
(for 1 line) will call for 0 repeats of the down cursor, or the reply 
'0' (for RAM.0) will select the 1st option.  Some interpretation is 
possible by translating the keystroke up or down one unit before it is 
executed.  This is done by appending a '+' (to increase the reply) or a 
'-' (to decrease the reply) to the keyword 'repeat' or 'option'.  

[for option+, see line  6 (key A6) referring to lines 266 to 267;
              and line 16 (key B6) referring to line  280;
              and line 18 (key B8) referring to line  281;
 for repeat-, see line  7 (key A7) referring to line  261;
 for repeat+, see line 15 (key B5) referring to line  277;
 in the demonstration program (option- is covered later)]


%H2%How to combine variations.%H2%

We now move to another level.  Any of the variations that have just 
been described, "spread", "option", repeat", and "manual" can be 
combined together to make a longer command line.  Continuing the same 
terminology, it is possible to build chains up into WEBS.  There can be 
up to nine chains in a web.

Combining them is very litle different from using them individually. 
The opening line in the program has almost the same structure.  The 
keyword that you put in the opening program line to tell Lackey what 
combination you want is simply the keywords for the individual 
variation types joined end to end, to give keywords like "repeatspread" 
or "optionmanual".  You can even include the interpretation signs, as 
in "option-manual" or "repeatoption+".  You then follow this with the 
initial line numbers for each of the variatiions being used in the
combination:

  DATA "<label>",,<keyword>,<line number>,<line number>,...

  label$,chain$,VARY$,line%PC%(1),line%PC%(2),...

 [for "optionoption"  see line  8 and function key A8;  
  for "optionrepeat-" see line  9 and finction key A9;
  for "option-spread" see line 12 and function key B2;
  for "spreadspread"  see line 13 and function key B3
                      and line 14 and function key B4;
  for "option+manual" see line 17 and function key B7
  in the demonstration program; this only demonstrates a small number
  of the possible combinations, which are not limited to two types.
  Note that line 12 also demonstrates the variation "option-".]
    
The entries for the chains which are referred to are just the same as 
before.  Lackey simply builds up the web by executing these chains one 
after the other.  A separate prompt comes to the screen for each chain.  
There is one point to note, however.  The structure for one chain in 
the command line, as we have seen, is l,t,l,t,...,l where l stands for 
a link and t for a tie location.  This is any number of l,t 
combinations followed by a single link.  If you follow that with 
another chain, you get a pair of links at the join: 
l,t,l,t,...,l,l,t,...  If you do not want to split the command string 
into two links, you will have to omit one of them, leaving a blank in 
the DATA list.  If you are not using quotes, a blank at the end of a 
DATA list can be achieved by adding a comma.  

 [see lines 272, 276, and 282 in the demonstration.  The demonstration 
  can now be seen to hold more examples of the variation types:
  For "option"  see lines 271, 272, 276 for function keys A8, A9;
      "spread"  see lines 284, 285, 286 for function keys B2, B3, B4;
      "manual"  see line  283           for function key  B7;
      "repeat-" see line  273           for function key  A9;
      "option-" see line  287           for function key  B2;
      "option+  see line  282           for function key  B7.]

A web does not have to use chains in the order they are listed in the 
program.  In fact, several webs can share the same chain.  This ability 
enables you to reduce the space needed for command lines by writing 
them as modules to be combined in different combinations.  

 [In the demonstration, function keys B2, B3 and B4 share the same 
  spread chain 285, which was written to be a common ending.]
%CO:B,12,60%%CO:C,12,48%%CO:D,12,36%%CO:E,12,24%%CO:F,12,12%