home *** CD-ROM | disk | FTP | other *** search
/ Programmer 7500 / MAX_PROGRAMMERS.iso / CLIPPER / MISC / GENHELP.ZIP / GENHELP.DOC < prev    next >
Encoding:
Text File  |  1988-04-23  |  7.0 KB  |  156 lines
  1. Documentation for GENHELP.ARC
  2. Written By James J. Orlowski, M.D. & John Willis
  3. Authors Of CLIPSCRN.ARC CLIPSCR2.ARC
  4.  
  5. This submission to NANSIG contains the files needed to make
  6. a generalized help screen system using text files. It is a 
  7. generalization of the program DBUHELP.PRG developed by 
  8. Denny Diaz used in DBU.
  9.  
  10. The main program is GENHELP.EXE which was written in 
  11. Quick Basic 4.0 and converts a textfile to a file that can
  12. be used by the FUNCTION HELPTEXT(), which is copied verbatim
  13. from the DBUHELP.PRG files used by Denny Diaz.
  14.  
  15. The text file MUST be in the format:
  16.  
  17. /01Demonstration Of Help Files  <-- 1 line header used by PROCEDURE genhelp
  18. Write Your Text Here.           <-- help text must begin on next line here
  19. More Text.                      <-- up to the next '/' or EOF()
  20. Still More Text                 <-- (don't skip line between help sections)
  21. /02Demonstration help screen 2  <-- '/' must be 1st character in header line
  22. More Text.                      <-- help text for section 02.
  23.  
  24. It is important that the text file include the '/' as the first character
  25. in the line and followed by a 2 digit number.  The program will allow
  26. up to 64 help messages, and they MUST be in order to proper heading of
  27. new "helpfile".  This is NOT a limitation to the system since multiple
  28. help files can be used by the PROCEDURE genhelp as will be explained
  29. below.  The textfile MUST be in ASCII format, and should have the
  30. same margins that will be used in the MEMOEDIT() function called within
  31. the help.prg.  In the demonstration programs, the margin is 65 characters.
  32.  
  33. Basically GENHELP looks for the '/' within the textfile and assigns the
  34. FOURTH character in this line (i.e. first character after '/01') as the
  35. first 2 byte integer signifying the start of the text and counts 
  36. the length of the text up to the next '/' as the second 2 byte integer
  37. as described in the section at the beginning of helptext() within help.prg.
  38. This also means that the '/01' will not be shown on the screen.
  39. Since ASCII characters are used to signify each of the 2 byte integers, 
  40. this means that you are allowed up to (256 * 256) chars - 1 (approximately
  41. 64K) as the maximum text length of the "helpfile". 
  42.  
  43. I don't know why Mr. Diaz did not use the header information instead of 
  44. making an array of headers for his help system, but this has been corrected
  45. with GENHELP.ARC.
  46.  
  47. GENHELP.EXE asks 3 questions
  48. 1.) Enter Source File:
  49. 2.) Enter Target File:
  50. 3.) Enter Number Of Help Messages
  51.  
  52. In the office.txt file contained in this demo, the answers to these
  53. questions are:
  54. 1.) office.txt
  55. 2.) office.hlp
  56. 3.) 13
  57.  
  58. PLEASE NOTE: THERE IS VIRTUALLY NO ERROR CHECKING WITHIN GENHELP.EXE SO:
  59.    1) IT WILL OVERWRITE ANY FILE LISTED IN ANSWER TO QUESTION # 2, WHICH 
  60.       IS ACTUALLY WHAT YOU WANT IT TO DO ANYWAY WHEN YOU UPDATE YOUR 
  61.       HELP MESSAGES.
  62.    2) RESULTS ARE ENTIRELY UNPREDICTABLE IF YOU ENTER THE WRONG NUMBER OF
  63.       HELP MESSAGES TO QUESTION # 3 OR DO NOT USE THE PROPER FORMAT FOR
  64.       THE SOURCE FILE.
  65. IT IS JUST A QUICK AND DIRTY UTILITY THAT GETS THE JOB DONE.
  66. Quick Basic Does complain if you enter a nonexistent source file to read in.
  67.  
  68. Within your application program, you must include the following
  69. public variables for use with help.prg:
  70.  
  71. PUBLIC helpfile, help_code
  72. helpfile = "OFFICE.HLP"  && name of new help file
  73. help_code = 0            && must correspond to appropriate '/01' section
  74.                          && within help text
  75.  
  76. You can use multiple helpfiles by changing the name of the
  77. helpfile memvar thus allowing an infinite number of help files
  78. for your application each including up to the 64 help messages 
  79. within each approximately 64K helpfile 
  80.  
  81. You must number the help_code within your application, or
  82. you can set the help_code within the help.prg such as I did to
  83. number the help_code to the menunum associated with the 
  84. MENU TO menunum routine used in DEMOHELP.PRG .
  85.  
  86. To get the demonstration to work, you need to link as follows:
  87.  
  88.    1.) TLINK /x /l /n demohelp help, demohelp,,clipper,extend
  89.  
  90. OR 2.) PLINK86 FI demohelp,help LIB clipper,extend
  91.  
  92. DEMOHELP.PRG was written using hard coded colors and I don't know 
  93. if it can be used on a monichrome monitor or with a CGA system, since
  94. it was only tested on an EGA system.
  95. PLEASE NOTE: Both DOWNHELP.OBJ And HELP.OBJ Files Were Compiled 
  96. With The First Version Of SUMMER87 Since I Still Have NOT Received 
  97. The Corrected SUMMER 87 UPDATE After 3 Weeks, Even Though I Live 
  98. Less Than One Hour From Los Angeles.  THUS, You Will Have To Link 
  99. With The First Version Of SUMMER87 To See The DEMOHELP.PRG.
  100.  
  101. I Am Sorry For The Inconvenience Of Not Having The Latest Version, 
  102. But Blame This One On Nantucket. HOWEVER, I have included the source for
  103. help.prg, which for your application can consist only of:
  104.  
  105. PARAMETERS call_prg, line_num, input_var
  106. IF call_prg = "HELP" .OR. call_prg = "MEMOEDIT" .OR. call_prg = "GENHELP" ;
  107.    .OR. help_code = 0
  108.       RETURN
  109. ENDIF
  110. DO genhelp
  111. RETURN
  112. * plus the PROCEDURE genhelp and FUNCTION helptext.
  113.  
  114. This can be compiled and linked with your application under the 
  115. updated version of SUMMER87, and PROCEDURE genhelp does use the 
  116. ISCOLOR() function to set the proper colors for monichrome.
  117.  
  118. ----------------------------------------------------------------------
  119. John and I are releasing demohelp.arc into the public domain. You are 
  120. free to distribute it to other bulletin boards provided that you
  121. include the first five files and check with Nantucket whether
  122. it is OK to include help.prg which contains a portion of Danny Diaz's
  123. HELPTEXT() function within the file DBUHELP.PRG., which is 
  124. copyright 1986,1987 By Nantucket.  We make no guarantees and will not
  125. be responsible for any damages caused by using these programs
  126. except for the usual statment "It worked for us..."
  127.  
  128.    1.) genhelp.doc  (this file)
  129.    2.) genhelp.exe  (utility to convert text files that can be
  130.                      used with helptext() function written by 
  131.                      Denny Diaz of Nantucket)
  132.    3.) office.txt   (sample text file to convert with GENHELP.EXE
  133.                      to office.hlp for use with demohelp.exe example)
  134.    4.) demohelp.obj (obj file containing demonstration menu program 
  135.                      using genhelp system)
  136.    5.) help.obj     (obj file already linked for use with demo)
  137.    6.) help.prg     (text of help.obj)
  138.  
  139. I Am NOT Including The Source Code For DEMOHELP.PRG and GENHELP.EXE Since 
  140. They Add To The Size Of The ARC File And Are Not Really Needed To Use
  141. Genhelp.exe And The Demonstration Program.  For Those Of You Who Feel They 
  142. Must Always Have Source Code For Everything, Please Send A 360 KB Or 
  143. 1.2 MB Floppy Disk And $10 For The Staff Time To Process It.
  144.  
  145. A WORD ABOUT THE AUTHORS
  146. John Willis writes professional oil drilling software programs
  147. for microcomputers.
  148.  
  149. James Orlowski writes medical office programs using Clipper.
  150.  
  151. Any correspondence should be sent to
  152.             James Orlowski, M.D.
  153.             451 West Gonzales Road, # 150
  154.             Oxnard, CA 93030
  155.  
  156.