home *** CD-ROM | disk | FTP | other *** search
/ Programmer 7500 / MAX_PROGRAMMERS.iso / CLIPPER / MISC / INTER35C.ZIP / WINHELP.ZIP / WINHELP.DOC < prev   
Encoding:
Text File  |  1993-02-15  |  10.0 KB  |  206 lines
  1.  
  2.                 INTERRUPT LIST TO WINDOWS HELPFILE    12/17/92 first version
  3.                                                       02/08/93 second --"---
  4.  
  5.           Table of contents
  6.                      Disclaimer                       1
  7.                      Preface                          1
  8.                      Tools                            1
  9.                      Work flow and time estimates     2
  10.                      Included files list              3
  11.                      Second version notes             3
  12.                      Making pop-up windows            4
  13.  
  14.           DISCLAIMER
  15.  
  16. I claim only copyright for included files. Use them as you see fit. No money
  17. required -- no warranties. If you make changes and redistrubute mark changes
  18. and comment orginal lines, do not delete. Mail your changes to me too!
  19. Many mentioned products are trademarked or copyrighted by their owners.
  20.  
  21.  
  22.           PREFACE
  23.  
  24. Winhelp.exe is "system hypertext viewer" in windows, it doesn't go TSR and
  25. eat lot of memory, it is fast and reasonably rich in features. Interrupt list
  26. is a good project if you want to study making Windows help files and of course
  27. you need the finished inter.hlp version. What you also need is a FAST machine,
  28. OS/2, about 14MB of disk space and a weekend.
  29. What I have done is essentially only a search and replace filter for Spinellis
  30. int2hlp.bat 15-11-91 version.
  31. This is first version. I might try convert int2hlp.bat to produce format to
  32. hc directly, but not sooner than inter33 is released. This package was made
  33. to inter32 and all major problems stem from int2hlp.bat, apparently it is not
  34. quite able to handle inter32. Another possible improvement is to use hc 3.1
  35. specific features. You are free to do them yourself too. I have tried to format
  36. text with as little rtf commands as possible, yet making it readable. I you do
  37. have monospaced font you might make appropriate changes replacing terminal
  38. font in awk scripts.
  39. I looked also at inthelp package 26-10-91 version but it generated exception
  40. 12h with complete list and it uses units not included, which I do not have.
  41. Otherwise it looked promising, so if you speak Pascal and have Object
  42. Professional you might try increasing stack size and recompile.
  43. Hc offers compression option but 3.00 doesn't compress much so you will want
  44. to place help file on a Stacker or a similar volume.
  45.  
  46.         TOOLS YOU WILL NEED
  47.  
  48. Except for the first item they are PD/SW and available on CD-ROM and internet
  49.  
  50. OS/2 2.0
  51. recommended, you might find tools that work in ms-dos but you will have hard
  52. work finding them.
  53.  
  54. perl intepreter
  55. There is a ms-dos version of perl but the one i have told very soon it was
  56. out of memory, and I gave 716KB. I found OS/2 version from Walnut Creek
  57. CD-ROM OS/2 may 92 \hobbes\os2_1_x\progrmng\perl4010.zoo
  58.  
  59. Sort
  60. OS/2 or MS-DOS sort won't do, use gnu sort. See perl script for requirements.
  61.  
  62.  
  63. HC.EXE, Microsoft help compiler
  64. I found 3.00b (PD?) from CICA july 92 CD-ROM \win3\winword\hc300b.zip and
  65. 3.00 or 3.1 is included with many compilers eg. BC++, TPW and Windows SDK.
  66. 3.00b needs less memory than 3.00 but if you have 3.1 use it. Inter.hpj has
  67. some lines that should work with 3.1 but otherwise no 3.1 specifics are
  68. included. I ran hc in a 729KB OS/2 dos box and it may need more than usual
  69. 600+ KB. Compression=off|0 in inter.hpj eases RAM requirements a little and
  70. file size grows only little. Context strings and titles apparently must be
  71. stored in memory so you will want to keep them short. The best cure for memory
  72. problems though is to run hc in OS/2 as it is bound binary. It also runs faster
  73. in protected mode because it has more memory accessible. It may come as a
  74. surprise to a TPW (1.0 at least) owner that included hc can be run also in
  75. OS/2.
  76.  
  77. MAWK AWK interpreter
  78. Simtel20 june 92 CD-ROM \msdos\awk\mawk10.zip
  79. I have noticed that different AWK implementations find '\' with different
  80. number of \'s, eg. '\v' is found with '\\\\v' and sometimes with '\\v' in mawk.
  81. However, mawk was fastest of three different ones on the disk. A2p included
  82. with perl produced noncompiling, nondoing programs. I am not as familiar with
  83. perl as I am with AWK but actually I should learn also perl. In the meantime
  84. use mawk to slip work.
  85.  
  86. HELPMAKE.EXE if you also want to compile to qh format
  87. This is also bound binary and 4os2 told that 3.5MB of memory had been in use.
  88. It is included in MASM 6.0 and others? Compile time about 3 h, file size about
  89. half of hc format.
  90.  
  91.  
  92.  
  93.         WORK FLOW AND TIME ESTIMATES
  94.  
  95. I used 33MHz 386 with 10MB memory and fast, normal IDE drives and all times
  96. are with this setup.
  97.  
  98. Start with creating a small test file set. Take interrup.a, say up to int 10
  99. video mode set (tables should be monospaced and here is first big table), write
  100. to disk with name interrup.lst and run int2hlp.bat (from interxxc.zip). If no
  101. alarming errors occur other than complaints about false references, rename
  102. resulting files int.* eg to int2.*. All this is not neccessary but you may
  103. spot troubles with less waiting this way.
  104.  
  105. Next follow int2hlp.bat instructions. With inter32 it took about 44 hours so
  106. you have time to check following steps with test file set.
  107.  
  108. Run hlp2rtf.bat to convert from helpmake to hc format. This is fast, about
  109. 5 min.
  110.  
  111. As a final step run hc inter.hpj > inter.err and if it creates inter.hlp file
  112. you are ready. To find trouble spots you must interpret inter.err. The most
  113. serious trouble usually is inequal number of closing and opening braces and
  114. it is told with line: ' ... is not a usable rtf topic file. Warning lines
  115. you may safely ignore but they might give valuable hints, have luck! If you
  116. have editor that handles this big files and can find matching braces just see
  117. if offending file begins and ends with matching brace, if not, either near the
  118. match for ending or beginning brace you will fing erroneus spot. Inter32 had
  119. about 10 topics with same name in int.bot. You should concatenate topics
  120. with same name and remove title (begins with a $), browse sequence (+) and
  121. context string (#) lines from later duplicates. The browse sequence number
  122. ends with same number as hc reports as topic number. Hc ran 1 h 22 min in dos
  123. box and 52 min in OS/2 window.
  124.  
  125.  
  126. As an optional final step you might want to do some formatting with WinWord.
  127. Obvious one is uncommenting wanted deff line in *.awk files, running hlp2rtf
  128. and with WinWord changing all tables to monospaced font in intrtf.* files.
  129. Remember to save in rtf format and you are safer if you don't touch jump
  130. references. Hc 3.00b fixes some problems with WinWord 2.0. WinWord is not in
  131. my experience stable with huge files and giving it 3+ MB might cause a horrible
  132. death. One serious problem with using WinWord is that adding formatting
  133. causes hc to need more memory and file sizes grow quite much.
  134.  
  135. Raimo Koski
  136. Uudenmaantie 23 K 3
  137. 20720 TURKU
  138. FINLAND
  139.  
  140. Files:
  141.  
  142. Name         Desc.
  143. ============
  144. BOT2RTF.AWK  int.bot filter
  145. TOC2RTF.AWK  int.toc filter
  146. FIL2RTF.AWK  int.fil filter
  147. BY2RTF.AWK   int.by? filter
  148. IDX2RTF.AWK  int.idx filter
  149. SCANSHOR.AWK scans for short topics, Win 3.1
  150. POPUPS.BAT   short topics to pop-up windows, Win 3.1
  151. WINHELP.DOC  this file
  152. HLP2HC.BAT   runs filters
  153. INTER.HPJ    hc project file
  154.  
  155.  
  156.  
  157.  
  158. SECOND VERSION NOTES
  159.  
  160. Biggest change is adding and testing of hc version 3.1 specific features. Some
  161. minor fixes in *.awk filters but major ones in inter.hpj. With hc31 inter.hlp
  162. from inter33 is mere 2.3 megs compared with over 4 megs using hc30. I played
  163. with some new features introduced in hc31, you'll find them all in inter.hpj.
  164.  
  165. For conviniency to users of different versions of hc is that same set of files
  166. work with 3.0 and 3.1. Error messages about inter.hpj vary with hc version,
  167. discard all about illegal options, they are meant for other version of hc.
  168.  
  169. As hc31 doesn't run out of memory so easily as hc ver. 3.0 titles and keywords
  170. could be made longer and more descriptive. I was lazy and did not see much
  171. point in doing it.
  172.  
  173. Here are my observations about hc31:
  174. Compression=high needs total of about 15 megs of temporary disk space! Set tmp
  175. environment variable to partition that has that much free space. Run in
  176. dos box, in OS/2 box you'll get silly 'out of file handles' message. No more
  177. memory problems in dos box. If you want to use help files with winhelp 3.0
  178. compile with hc 3.0, incompatibility is propably due to compression method, but
  179. since .hpj files work with either hc version (copy CONTENTS= value to INDEX=
  180. line) switching compilers is easier. I found hc31 from WIN32 SDK CD-ROM, a real
  181. bargain provided you have a CD-ROM drive. Hc30 on that same disk is not same
  182. as earlier versions of hc ver. 3.0, it is similar to hc31 in memory
  183. utilization, so run it in dos box if you compile huge help files.
  184.  
  185.  
  186. MAKING POP-UP WINDOWS
  187.  
  188. Winhelp 3.0 had pop-up windows that were shown only as long as user hold mouse
  189. button down. Proceeding to a topic that had link in a pop-up window was
  190. impossible. Winhelp 3.1 keeps pop-up window until next click and jumping is
  191. possible.
  192. I made an awk script that converts all references to short topics into jumps
  193. to pop-up windows. Short topic is defined by a constant 'ln_limit' in
  194. scanshor.awk. Scanshor.awk is quite strange construction, it scans intrtf.bot
  195. for short topics and when found adds a line to an another awk script. Mawk has
  196. script size limitations and therefore Scanshor.awk must count lines it adds
  197. to a new awk script. When size limit is exceeded it creates yet an another new
  198. script. Calling of new awk scripts is done by a .bat file which is also created
  199. by scanshor.awk. The whole process is most conviniently started with
  200. popups.bat. Disk size need is two times intrtf.* or about 9MB during the run
  201. which takes about 8 hours. I have mixed feelings about scanshor.awk, on the
  202. other hand it avoids awk's limitations rather cleverly but it is so strange
  203. and rather slow that I suspect it is not so clever. Anyway, it works!
  204. Running popups.bat is not required, hc30 handles the results but winhelp 3.0
  205. doesn't (see above).
  206.