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