;
                                  NUKEY.COM                                   

             Size (recs) CRC   Version    Author/Latest Issue      Disk
                k (  )         2.05       Joe Wright 5/89          Z3COM 

  1- Introduction  2- Getting Started  3- Examples of Usage  4- Customizing   
  5- Requirements  6- NuKey Commands   7- Newword/WordStar   8- Deactivating  

 
   NuKey is an  advanced function key  generator which redefines keyboard keys
with a special lead-in character.

   NuKey is available for $40.00 from..
   
                          Alpha Systems Corporation
                            711 Chatsworth Place
                         San Jose, California 95128
                               (408) 297-5594
:1
 Introduction - 1/3 

   A  keychanger is  a special kind of program that places itself between your
keyboard and the other software running in your computer.   It intercepts what
is typed at the keyboard and can transform  whatever was typed into  something
else,  depending  on  how  you  have it  programmed.   For  example,  using  a
keychanger  you could  redefine your keyboard to be Dvorak layout  instead  of
the standard "QWERTY".

   Most keychangers allow you to  generate an entire string of characters from
a specific keyboard input.   Thus, the string "frequently" could  be generated
whenever  you  type control-F.   This is the real  advantage  of  keychangers:
They  reduce  the amount of typing  you need to do by  providing  "shortcuts".
You can press a key that actually only generates  a single character, and that
single character is redefined to be an entire sentence,  phrase, paragraph, or
sequence of commands.  
 Introduction - 2/3 

In the previous example,  control-F was redefined to be the word "frequently".
This  example  probably  wouldn't be  useful if you  are  using  WordStar,  as
control-F is a command you need under WordStar.   To cope with this situation,
advanced  keychangers  offer what is called an "extend" key.   Only  when  the
extend  key is typed immediately prior to the  desired key (control-F in  this
example) does the redefinition take place.   So, this means that you can still
use  control-F  normally  as  a command  under WordStar,  and  when  you  want
control-F to generate "frequently", you first type the  "extend" key and  then
control-F.  

Other sophisticated features of  professional keychangers include the  ability
to  save  definitions  to disk for later re-use;  and the ability  to  add  or
delete new definitions even while other  programs (like WordStar) are running.
 Introduction - 3/3 

   NuKey is such  a sophisticated keychanger.  It supports  all  the  features
previously  mentioned  and  more.   An  important  feature  of  NuKey  is  the
capability  to  redefine  keys that generate more than  one  character.    For
example, some terminals have arrow  keys that generate more than one character
when  pressed;  using  NuKey,  these  keys  can  be  redefined  to  be  single
characters or any string of characters you desire.
:2
 Getting Started - 1/2 

Before doing anything with NuKey,  make a copy of the master you have recieved 
using a file copy program.   Then put the master in a safe place, and  proceed 
using the copy.  NEVER USE YOUR MASTER FOR ANYTHING OTHER THAN MAKING COPIES.

NUKEY  2.0  consists  of  NUKEY.COM and NUKEY.REL files.   If  you  are  still 
running the older ZCPR30 you must 'install' NUKEY.COM with Z3INS.   If you are 
using ZCPR33+ or NZ-COM, no installation is necessary.

NUKEY.COM  is  the loader and control program.   NUKEY.REL is  the  keychanger 
itself which is loaded as an extended Z3 IOP.   When you invoke NUKEY.COM  for 
the  first  time,  NUKEY.REL will be  loaded and you will be  asked  for  your 
definition of the DEFine and EXTend keys.   These definitions will be  written 
to an otherwise blank NUKEY.KEY file.   When you invoke NUKEY the second  time 
and without a keyfile name, NUKEY.KEY the blank keylist is loaded.
 Getting Started - 2/2 

When  asked  for  the DEFine key,  press any key on  your  keyboard  you  wish 
assigned  to this special function.   Although any key will do, a good  choice 
is the shifted character(s) of a rarely used function key.   My keyboard has a 
PRINT/Send function key which I use.   Shifted PRINT for DEFine and  unshifted 
Send for EXTend.

Once you have answered the DEFine and EXTend key questions,  NuKey is running.  
You may now perform a variety of operations with it.   See the section  "Using 
NuKey" for precise instructions.
:3
 Examples of Usage - 1/3 

   To  get you started  in the  wonderful world of  keychangers,  here's  some
excerpts from an article by Ted Silveira that originally  appeared in PROFILES
magazine.   In the examples,  <SP> means space, <CR> means return,  and  <ESC>
means  the escape key.   A caret (^) before a letter indicates the  succeeding
character  is a control character.   For example ^F indicates control-F.   The
examples are intended for use with WordStar.  Most also work with Newword.

Move to Beginning of Paragraph

"Often, when I'm in the middle of a paragraph,  I find I want to jump back and
alter  the  paragraph opening.   Since I start each of my  paragraphs  with  a
five-space indent (that's how WordStar interprets a TAB),  it's easy enough to
find  the  paragraph  beginning.   I  set  up  a  key  to   send  the  command
^QF<SP><SP><SP><SP><SP><CR>B<CR>^F.   After the search backward, WordStar will
leave  me at the beginning of the five-space indent,  so I added a ^F to  move
to the first word."
 Examples of Usage - 2/3 

Reforming Paragraphs

"I love this command.   Any time I start editing a WordStar paragraph - adding 
and  deleting words and so forth - the paragraph formatting  gets  all  messed 
up.    So  I  set  one  key  to  send  the  command    ^QF<SP><SP><SP><SP><SP> 
<CR>B<CR>^B.    This command cleans up the mess by zipping the cursor  to  the 
beginning of the paragraph and then reforming it with ^B."

Mark Paragraph as a Block

"This  command  is  handy  because you can  use it as  a  prelude  to  moving, 
copying,  or deleting your current paragraph.   For paragraphs with  only  one 
carriage   return  at  the  end,  use  the  command    ^QF<SP><SP><SP><SP><SP> 
<CR>B<CR>^KB^B^KK.   And for paragraphs with two carriage returns at the  end, 
use the command ^QF<SP><SP><SP><SP><SP><CR>B<CR>^KB^B^X^KK."
 Examples of Usage - 3/3 

Delete from Cursor to End of Paragraph

"This  command  lets  me  delete everything in a paragraph  from  the  present
cursor position to the end.   I set one key to send the command ^KB^B^A^KK^KY.
To  play it safe, eliminate the ^KY.   Then the command will  mark  everything
from your cursor to the end of the paragraph as a block,  and you can give the
delete  command yourself,  after making sure you haven't marked  anything  you
want to keep."

Print a Marked Block

"Sometimes  it's  handy to be able to print  out a short section of  the  file
you're working on,  without having to exit the file or stop what you're doing.
The   following  command  will   print  any  marked  block  of  text   without
interrupting  you  for  more than  a few seconds.  Set one  key  to  send  the
command ^KWA:PRINT.FIL<CR>Y^KPA:PRINT.FIL<ESC>." 
:4
 Customizing NuKey - 1/4 

Advanced  users can customize  some of the internal characteristics of  NuKey.
This is unnecessary in most circumstances,  but if you have difficulty getting
NuKey to work properly with certain application  programs you should  consider
experimenting  with  the following options.   You make these  selections  from
within  the NUKEY.COM program.   NuKey has three internal delays that  may  be
programmed  with  the Install function.   The default values of  these  delays
were chosen after much testing with many programs  and terminals.  You  should
not have to change them unless NuKey  simply doesn't work in your environment.
These delays are discussed in detail on the following screens.

Typing NUKEY /I will report the current delay  values and allow you to  change
them (A simple <RETURN> will leave them unchanged).   These values are written
into  NUKEY.COM  itself and will be copied to the keychanger each time  it  is
loaded.

Remember: Normally it is not required that any of these options be changed!
 Customizing NuKey - 2/4 

FUNDEL:  You  might think of NuKey as  a 'string' changer.   NuKey  accepts  a
'keystring' (1 to 10 characters) from a  particular key and converts it to yet
another  'string'  (1  to over 500 characters) to  be sent when  that  key  is
pressed.   NuKey assumes  a key may produce more than one character,  and  so,
waits for the next one.   NuKey will wait FUNDEL milliseconds before giving up
and  presuming  the  previous  character to  be the last  one  for  that  key.
Choosing the precise value of FUNDEL is not as easy as one might assume.

Some  terminals send their  function key strings at the baud rate so  that  at
19,200  baud  (1,920  chars per sec) you can  expect  a  character  every  500
microseconds,  or so.   Other terminals might send them at a much lower  rate.
The  Wyse-50, in ADDS emulation mode,  sends function key characters fully  10
milliseconds  apart!   In  selecting  the  default  value  of  FUNDEL  at   35
milliseconds,  NuKey expects to accommodate the slowest of terminals.  If  the
default  doesn't work in your case,  you may change it to any value from 0  to
255 milliseconds.
 Customizing NuKey - 3/4 

CTLDEL:  It is often useful to create a 'string' which invokes a program, then
supplies  its initial commands.   For example, you wish to invoke WordStar  to
edit  a document file named TEXT.   At the keyboard, you would type  'WS<cr>',
wait for WordStar to load, 'D' for document mode,  then 'TEXT<cr>'.   However,
if  you  enter 'D' too quickly,  WordStar discards it because it  flushes  all
keyboard  input  as  soon  as  it loads.    NuKey  will  mislead  WordStar  by
responding 'false' to its console status requests  a few times after sending a
CR  code,  so that it thinks it has flushed the keyboard.   Thus  the  string,
'ws<cr>dtext<cr>' does what you want it to.   The default number of deceptions
is 10.  You may change it to any value from 0 to 255.
 Customizing NuKey - 4/4 

KEYDEL:   Some programs (dBASE II) flush the keyboard after  every  character,
probably  to  treat key 'bounce' problems.   This  laudable  pursuit  discards
every second character in a normal keystring,  causing DISPLAY ALL to come out
as  DSLYAL  which  is not very useful.   So, we mislead  again  by  responding
'false'  a  number of times between characters.  dBASE requires at  least  one
deception.   The default number of deceptions is 5.  You may change it to  any
value from 0 to 255.
:5
 System Requirements for NuKey 

NuKey requires that you run  a ZCPR3 implementation on a Z-80 system with  IOP
space allocated (1.5k-bytes or more).   Further, NuKey requires that your  IOP
and BIOS conform to the Echelon publication "ZCPR3 and IOPs", chapter 5.

NuKey works with Z-Com,  NZ-COM and with Echelon's bootable Z-System disks for
Kaypro and Morrow machines, and Micromint's SB180 computers without change. 

Note:   NuKey itself requires about 1k of code  space in the 1.5k IOP  leaving
just  over  500  bytes for the keybuffer.   If you define a  larger  IOP,  the
increased  size  is allocated to the  buffer allowing  even  more  definitions
and/or longer strings.  A 2.5k IOP will have over 1500 bytes available.
:6
 Using NuKey/Explanation of Commands - 1/3 

View Current Definitions

To  see  a  display of current NuKey definitions, type the DEFine  key  twice.
This can be done within application programs  (eg, WordStar) or at the command
line prompt of the operating system.   CAUTION: If "View Current Definitions",
"Define  New Key", or "Delete Old Key" is  done inside of an application,  the
screen  display  is  altered  from  what the  application  "thinks"  is  being
displayed.   This may necessitate issuing a command to rewrite the screen,  if
the application has such a command.  WordStar 4.0 uses ^\, Newword <ESC>.

Deleting Old Keys

To delete an existing definition,  first type the DEFine key, and then the key
to  be deleted.   If it uses the EXTend prefix, type the EXTend key  prior  to
the  key  being  deleted.   Then type  DEL or  RUB,  which  deletes  the  key.
Deletions  can  be  performed while other applications are running.   See  the
previous caution about the screen display being altered.
 Using NuKey/Explanation of Commands - 2/3 

Defining New Keys

New definitions can be added at any time  from within applications or from the
operating system prompt.   To add a definition to NuKey, type the DEFine  key.
Next,  type the  EXTend key if it is to be used in the new definition.   Next,
type  the key that is to be redefined.   Any key that generates at  least  one
character  can  be  redefined.   Then,  enter  the  characters  you  wish  the
redefined  key  to  generate.   NuKey  initially  has   about  550  characters
available  for  new definitions.   Each redefinition is  allocated  from  this
pool.   You can use the DEL or RUB key or the backspace key to backspace while
entering new definitions.   See the previous caution about the screen  display
being altered.

Redefinition Notes

NuKey  can  redefine  keys that  generate from 1 to 10  characters.   The  new
definition  can  contain  up  to approximately  550  characters.    NuKey  can
distinguish  keys that generate characters with  values in the range of 1  (^A
or  SOH)  to 127 and from  keys that generate characters with  values  in  the
range of 128 to 255, if your computer/terminal can generate them.
 Using NuKey/Explanation of Commands - 3/3 

Key  definitions may be saved to disk.   Suppose you have re-defined a  number
of keys especially for your work with WordStar.   You might save them to  disk
with  the  command,  NUKEY  WS S  which will  create  WS.KEY  in  the  current
directory.   Definitions especially for  dBASE II might be saved in DB.KEY  in
the  same manner.   As noted in Section 2, NUKEY.KEY (blank) was created  when
you  first ran NUKEY.   Now NUKEY<cr> will load NUKEY.KEY, NUKEY  WS<cr>  will
load WS.KEY and, of course, NUKEY DB<cr> will load the dBASE II keys.
:7
 Special Information for Newword and WordStar 4.0 Users 

Newword  and  WordStar have an internal keychanger or 'Macro Generator'  which
can  conflict  with  NuKey.   You should re-install  Newword  or  WordStar  as
follows:  

Invoke  the installation  program (NWINSTAL.COM or WSCHANGE.COM) and find  the
menu  of  'Special Patches' or whatever.   Look for  the  selections  allowing
changes  to  items named "FUNDLY" and "AHEAD".   Set FUNDLY to  0  (zero)  and
AHEAD to FF (decimal 255).

Please  refer  to  the  Newword or  WordStar  installation  documentation  for
precise  instructions  on how to change these values.   Once they are  set  as
indicated above, you will experience no difficulty using NuKey.
:8
 Deactivating NuKey 

As with all ZCPR3/Z-System IOP's,  NuKey is removed by loading another IOP  on
top  of it.   Thus, if you activate another IOP such as BPRINTer or  RECORDer,
NuKey is deactivated,  and any current key definitions not previously saved to
disk are lost.

You may effectively remove  NuKey by clearing the current key definitions with
the command NUKEY /C.

