home *** CD-ROM | disk | FTP | other *** search
/ CP/M / CPM_CDROM.iso / jsage / zsus / z3help / 0z3help.doc < prev    next >
Encoding:
Text File  |  1991-11-18  |  5.1 KB  |  85 lines
  1. 12 Dec 88                   A ZCPR3 Help System                    Bill Tishey
  2.  
  3.    Tools and utilities supporting the  Z-System  have been released with great
  4. regularity  over the  past 2-3 years.  Updates appear  so  frequently  that it 
  5. seems development often  gets too far ahead of documentation.  I began putting
  6. this Help system for the Z utilities together in late 1987, therefore, to help
  7. keep track  of the many  new utilities and  new functions being added to older 
  8. ones.  It was patterned  after ALIASES.HLP, a 'Help System for Online Aliases' 
  9. presented in Z-News #507.  
  10.  
  11.    First, I  had to decide what information about  a utility  I wanted to have 
  12. 'on-line' in a Help file.  I came up with the following categories:
  13.  
  14.    1. A quick view of stats about the program:  its size, crc, version number, 
  15.       date of issue, author, and where I could find it in my archived files.  
  16.    2. A brief description of what function the program served. 
  17.    3. A brief explanation of the program's syntax and any available options.
  18.    4. Special 'notes' concerning the program's operation, compatibility with
  19.       other tools, etc.
  20.    5. Explanation of any error messages.
  21.    6. Examples of Use
  22.  
  23.    I then set out to examine existing HLP files, DOC files, the ZNEWS-letters,
  24. and even  source code  and BBS  messages,  to  compile  information  in  these 
  25. categories for each utility.   This was  a monumental task,  to say the least, 
  26. and  I soon decided first to develop  a base of essential data on each utility 
  27. and later to expand on such things as 'Notes' and 'Examples of Use'.  
  28.  
  29.    Next, I wanted to  be  able to access this information quickly  and easily.
  30. An alphabetical sorting by utility name, in a 'user-indexed' help file, seemed 
  31. logical, since this 1) would organize the information, 2) provide an easy menu
  32. with  which to  access  it,  and  3) provide  an extensible system  for future 
  33. additions.  The only question  at this point was whether to provide a separate
  34. help file  for  each  utility or  to include all information in several large,
  35. user-indexed files.
  36.  
  37.    While separate files  might  allow  for  easy updating,  the idea of over a 
  38. hundred .HLP files  in  a directory  was rather distressing.  Then came LBRHLP
  39. from Bob Peddicord - just what the doctor ordered.  This super utility allowed
  40. me  to have separate files without the hassle of over-crowded directories.   I 
  41. simply created an  'A.HLP'  file to serve as a menu,  developed  separate .HLP 
  42. files  for each utility beginning  with  'A', and did  a 'Group Build' on them 
  43. with  VLU to create a crunched 'A.LBR'.   Defining 'D15:'  as my 'default du:' 
  44. for LBRHLP,  I then set  out to create  a similar LBR  for each letter  of the 
  45. alphabet to reside on D15:.   [Note:  Some utilities are released with already 
  46. excellent  .HLP  files and these are included  in the system,  usually  as  an 
  47. additional, more detailed, source of information.]   
  48.  
  49.    To simplify  accessing the files, I created a series of aliases:
  50.  
  51.                A LBRHLP -A A
  52.                B LBRHLP -B B
  53.  
  54. and  a similar one for each letter of the alphabet and placed them in ALIAS.CMD 
  55. in my ROOT directory.  Then Jay Sage showed me how, instead of 26 such aliases,
  56. the following single alias could serve for all:
  57.  
  58.    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
  59.  
  60. ...the $0 equating  to whichever letter I pressed.   Now,  all I had to do was 
  61. type  '<space>A'  in any disk and user area,  and 'A.HLP' would come up with a 
  62. 'menu' of help files for all utilities on the system beginning with 'A'.
  63.  
  64. [Note:  Z3PLUS users must use '/A' since '<space>A' had to  be  omitted as  an 
  65. option under Z3PLUS.  '/A' will work for all Z-System users.  -wat 4/4/89]
  66.  
  67.    Updating the files also proved to be simple.  Using VLU to uncr/extract the
  68. .HLP file  in question, I used VDE to make appropriate changes, recrunched the
  69. file (supplying  a  new date  of update),  opened the .LBR with NULU, and used 
  70. option -R to  replace the  old .HZP with the  new.  This often took  no longer 
  71. than a few minutes.
  72.  
  73.    There you have it.   A simple Help system,  made 'simple'  by the excellent
  74. tools (ARUNZ, VLU, LBRHLP, etc.) available for ZCPR3.  If sysops would like to
  75. make the  various LBRs in  this system  available for use or download on their 
  76. BBSs (preferably in a HELP directory),  I'll be glad to  provide them  on disk 
  77. ($10 for the cost  of the disks - a total of 610k) or they  can  be downloaded  
  78. from Jay Sage's BBS (Z-node #3).   I will  be providing updates for individual
  79. files from time to time  by bundling them into something like Z3HELP02.LBR and 
  80. uploading this file to Jay Sage's BBS.  Comments and suggestions for improving
  81. this system would  also be greatly appreciated.
  82.                                                            Bill Tishey
  83.                                                            8335 Dubbs Dr
  84.                                                            Severn, MD 21144 
  85.                                                            410-551-5082