12 Dec 88                   A ZCPR3 Help System                    Bill Tishey

   Tools and utilities supporting the  Z-System  have been released with great
regularity  over the  past 2-3 years.  Updates appear  so  frequently  that it 
seems development often  gets too far ahead of documentation.  I began putting
this Help system for the Z utilities together in late 1987, therefore, to help
keep track  of the many  new utilities and  new functions being added to older 
ones.  It was patterned  after ALIASES.HLP, a 'Help System for Online Aliases' 
presented in Z-News #507.  

   First, I  had to decide what information about  a utility  I wanted to have 
'on-line' in a Help file.  I came up with the following categories:

   1. A quick view of stats about the program:  its size, crc, version number, 
      date of issue, author, and where I could find it in my archived files.  
   2. A brief description of what function the program served. 
   3. A brief explanation of the program's syntax and any available options.
   4. Special 'notes' concerning the program's operation, compatibility with
      other tools, etc.
   5. Explanation of any error messages.
   6. Examples of Use

   I then set out to examine existing HLP files, DOC files, the ZNEWS-letters,
and even  source code  and BBS  messages,  to  compile  information  in  these 
categories for each utility.   This was  a monumental task,  to say the least, 
and  I soon decided first to develop  a base of essential data on each utility 
and later to expand on such things as 'Notes' and 'Examples of Use'.  

   Next, I wanted to  be  able to access this information quickly  and easily.
An alphabetical sorting by utility name, in a 'user-indexed' help file, seemed 
logical, since this 1) would organize the information, 2) provide an easy menu
with  which to  access  it,  and  3) provide  an extensible system  for future 
additions.  The only question  at this point was whether to provide a separate
help file  for  each  utility or  to include all information in several large,
user-indexed files.

   While separate files  might  allow  for  easy updating,  the idea of over a 
hundred .HLP files  in  a directory  was rather distressing.  Then came LBRHLP
from Bob Peddicord - just what the doctor ordered.  This super utility allowed
me  to have separate files without the hassle of over-crowded directories.   I 
simply created an  'A.HLP'  file to serve as a menu,  developed  separate .HLP 
files  for each utility beginning  with  'A', and did  a 'Group Build' on them 
with  VLU to create a crunched 'A.LBR'.   Defining 'D15:'  as my 'default du:' 
for LBRHLP,  I then set  out to create  a similar LBR  for each letter  of the 
alphabet to reside on D15:.   [Note:  Some utilities are released with already 
excellent  .HLP  files and these are included  in the system,  usually  as  an 
additional, more detailed, source of information.]   

   To simplify  accessing the files, I created a series of aliases:

               A LBRHLP -A A
               B LBRHLP -B B

and  a similar one for each letter of the alphabet and placed them in ALIAS.CMD 
in my ROOT directory.  Then Jay Sage showed me how, instead of 26 such aliases,
the following single alias could serve for all:

   A=B=C=D=E=F=G=H=I=J=K=L=M=N=O=P=Q=R=S=T=U=V=W=X=Y=Z LBRHLP -$0 $0


type  '<space>A'  in any disk and user area,  and 'A.HLP' would come up with a 
'menu' of help files for all utilities on the system beginning with 'A'.

[Note:  Z3PLUS users must use '/A' since '<space>A' had to  be  omitted as  an 
option under Z3PLUS.  '/A' will work for all Z-System users.  -wat 4/4/89]

   Updating the files also proved to be simple.  Using VLU to uncr/extract the

file (supplying  a  new date  of update),  opened the .LBR with NULU, and used 
option -R to  replace the  old .HZP with the  new.  This often took  no longer 
than a few minutes.

   There you have it.   A simple Help system,  made 'simple'  by the excellent
tools (ARUNZ, VLU, LBRHLP, etc.) available for ZCPR3.  If sysops would like to
make the  various LBRs in  this system  available for use or download on their 
BBSs (preferably in a HELP directory),  I'll be glad to  provide them  on disk 
($10 for the cost  of the disks - a total of 610k) or they  can  be downloaded  
from Jay Sage's BBS (Z-node #3).   I will  be providing updates for individual
files from time to time  by bundling them into something like Z3HELP02.LBR and 
uploading this file to Jay Sage's BBS.  Comments and suggestions for improving
this system would  also be greatly appreciated.
                                                           Bill Tishey
                                                           8335 Dubbs Dr
                                                           Severn, MD 21144 
                                                           410-551-5082