home *** CD-ROM | disk | FTP | other *** search
/ DP Tool Club 24 / CD_ASCQ_24_0995.iso / dos / tools / inter47 / int2whlp / i2w_hint.txt < prev    next >
Text File  |  1995-07-30  |  11KB  |  271 lines
  1. This is a sort of a guide to using the INT2WHLP precompiler. INT2WHLP
  2. transfers Ralf Brown's Interrupt List to some RTF (Rich-Text Format) files
  3. which can be used as input for Microsoft's HC31 WINHELP file compiler.
  4.  
  5. This text gives also some hints on using the the results of the compilation.
  6.  
  7.  
  8. COMPILATION
  9.  
  10. The easy way to compile the list is this:
  11.  
  12. Change to the directory where you want your INTWIN.HLP file. There should
  13. be at least 16 Mb free space on the disk. It can be the directory with the
  14. Interrupt List files (which we will call the Source Directory), but it is
  15. better to use a separate directory not to mess up the Source Directory. A
  16. subdirectory under the Source Directory would be fine. Copy the following
  17. files to the directory:
  18.     INTWIN.BAT
  19.     INT2WHLP.EXE
  20.     INT2WHLP.CFG
  21.     SEL_TOPC.RTF
  22.     MISC_INF.RTF
  23.     I2W_HH.RTF
  24.     INTWIN.PH    (see section COMPRESSION)
  25.     BAG.INI
  26. It is handy also to have:
  27.     I2W-FILE.TXT
  28.     I2W-HINT.TXT (this file)
  29.     I2W-CFG.TXT
  30.     I2W-OPT.TXT
  31. in the directory. For a partial compilation of the List, FLT_METH.RTF is
  32. required (see paragraph FLT_METH.RTF in I2W-FILE.TXT).
  33.  
  34. Make sure that the following files are in the Source Directory:
  35.     INTERRUP.LST or INTERRUP.A, INTERRUP.B, ...
  36.     INTERRUP.1ST
  37.     CATEGORY.KEY
  38.     OVERVIEW.LST
  39.     INTERRUP.PRI
  40.     PORTS.LST
  41.     MEMORY.LST
  42.     CMOS.LST
  43.     GLOSSARY.LST
  44. where INTERRUP.LST is the concatenation of INTERRUP.A, INTERRUP.B, ... .
  45.  
  46. Make sure that HC31.EXE is somewhere on the DOS path.
  47.  
  48. Type
  49.     INTWIN
  50. at the DOS prompt to start the compilation. On a 486/33MHz computer it
  51. takes INT2WHLP 1 1/2 minut to precompile release 41 of the List, and it
  52. takes HC31 40 minutes to create the INTWIN.HLP file.
  53.  
  54. Parameters to INTWIN will be passed to INT2WHLP, thus a compilation with
  55. only the compressed interrupt index can be made with
  56.     INTWIN -2-
  57. This will reduce the size of the resulting help file from about 5 Mb to
  58. about 4.85 Mb (release 44).
  59.  
  60.  
  61. PROBLEMS
  62.  
  63. It has happened that the Interrupt List was changed so INT2WHLP failed to
  64. find aliases for some context strings. If this happens, a new INT2WHLP.CFG
  65. file will be included in INTERnnZ.ZIP (see COMPRESSION). If other errors
  66. occur during the compilation of the List, the README file in INTERnnZ.ZIP
  67. will give hints about how to solve the problem.
  68.  
  69.  
  70. ERROR CODES
  71.  
  72. INT2WHLP returns errorlevel 240 - 245 if a fatal error occurs. It returns
  73. errorlevel 1 if one or more warnings are issued (inconsistent Interrupt
  74. List). The INTWIN batch file will let the user bail out (with ^C) if a
  75. warning errorlevel was returned from INT2WHLP's compilation of the List.
  76. It is recommended to terminate the batch file and fix the inconsistency in
  77. the Interrupt List, and compile again.
  78.  
  79.  
  80. CONFIGURATION
  81.  
  82. The INT2WHLP program lets you personalize your INTWIN.HLP file. If you use
  83. high resolution graphics on a large screen, then read the comments in the
  84. [CONFIG] section of the INT2WHLP.CFG file. For more details, see the files
  85. I2W-CFG.TXT and I2W-OPT.TXT.
  86.  
  87.  
  88. COMPRESSION
  89.  
  90. The HC31 program supports three levels of compression: high, medium, and
  91. none. Medium compressed and uncompressed files are about 15% and 100%
  92. longer than highly compressed files, respectively. HC31 can use an existing
  93. Phrases file (a .PH file with compression information), and it needs not to
  94. be exactly up-to-date. Compiling release 41 with a PH file from release 40
  95. gives a file about 4% longer than a compilation with an up-to-date PH file.
  96.  
  97. Compiling the compression information file is very resource consuming. For
  98. Interrupt List release 41 compiled with INT2WHLP v. 1.10:
  99.     631 kb < required DOS RAM < 730 kB
  100.     27 Mb < required free disk space < 50 Mb
  101. The compilation of the compression info took 20 minutes, and the rest of
  102. the compilation took 40 minutes on a 486/33MHx computer. Actually, when
  103. the computer gave up due to insufficient RAM when 631 kb were available,
  104. it had already created an INTWIN.PH file that was identical to the final
  105. file.
  106.  
  107. The INTWIN.PH file included in this package is based on the previous
  108. release of the Interrupt List, with the date and release number updated
  109. to the current release number and the expected release date. Please
  110. verify that the release date from line 1 in INTERRUP.A appears in two
  111. locations of INTWIN.PH, or update the file if needed. This is essential
  112. because the string appears in about 260 locations in the help file.
  113.  
  114. We will compile a Phrases file when a new list is released, and upload
  115. it to SimTel a day or two after the release of the List in file
  116. INTERnnZ.ZIP where nn is the List release number. See INTERRUP.1ST for
  117. SimTel mirror sites.
  118.  
  119.  
  120. HIGH RESOLUTION GRAPHICS
  121.  
  122. The default settings allow you to display the List on a normal 640x480 VGA
  123. screen without the need of horizontal scroll. If you use high resolution
  124. graphics on a large screen, you will want to define another size of the
  125. secondary window used to display the tables, see comments in the [CONFIG]
  126. section in file INT2WHLP.CFG.
  127.  
  128. If you use a high resolution graphics on a screen with small dimensions, you
  129. might want to use a larger font. The file package I2W-TEST.ZIP contains files
  130. that let you experiment with different fonts with very short INT2WHLP and
  131. HC31 compilation times. Unzip the package to a subdirectory under your
  132. INT2WHLP directory and read its README file.
  133.  
  134. Tools are availabe to edit the position and size of the table window in an
  135. already compiled INTWIN.HLP file, e.g. WH_wEdit in the package WH_EDxxx.ZIP
  136. (xxx >= 111) in SimTel directory SimTel/win3/winhelp.
  137.  
  138.  
  139. LIMITATIONS
  140.  
  141. DOS graphics characters where 176 <= code <= 223 are not converted to correct
  142. Windows equivalents. Horizontal and vertical single and double framing
  143. characters are converted to "-" and "|", and other graphics characters are
  144. converted to "+".
  145.  
  146. INT2WHLP cannot handle more than 63 per line of other characters with code
  147. > 126.
  148.  
  149.  
  150. INTWIN's TOPIC SEARCH FACILITIES
  151.  
  152. INTWIN facilitates seaching interrupt topics with many different keys, based
  153. on:
  154.     a. Elements in the interrupt header line.
  155.     b. Keys in the file CATEGORY.KEY for the appropriate interrupt
  156.        category.
  157.     c. Combinations of interrupt number and register contents.
  158.     d. Category letters.
  159.  
  160. For example,
  161.  
  162. --------D-215E01CH00-----------------------------
  163. INT 21 - DOS 3.1+ network - SET MACHINE NAME
  164.     AX = 5E01h
  165.     CH = 00h undefine name (make it invalid)
  166.  
  167. will be listed with the following search keys:
  168.  
  169.     DOS 3.1+ network          \      a
  170.     SET MACHINE NAME          /
  171.     DOS kernal                \ 
  172.     kernal (DOS)               >     b
  173.     operating systems (DOS)   /
  174.     INT 21 AX = 5E01 CH = 00  \
  175.     INT 21 AX = 5E01           \
  176.     INT 21 AH = 5E              \
  177.     INT 21          1)           \
  178.     21 5E01 CH00                  \
  179.     21 5E01                        > c
  180.     21 5E           2)            /
  181.     21              1)           /
  182.     AX = 5E01                   /
  183.     AH = 5E         3)         /
  184.     CH = 00                   /
  185.     D!              4)               d
  186.  
  187. 1) WINHELP lists only the first 400 search hits.
  188. 2) The short form of an interrupt using AL to specify a function has two
  189.    leading dashes in the function number, e.g. the short form of
  190.    INT 2D AL = 10 is 2D --10.
  191.    Two dashes can be appended to the short form of an interrupt using AH for
  192.    funtion number, to distinguish the string from the more general string
  193.    used also as keyword for interrupts with the same value in the high part
  194.    of the AX register, e.g. 10 00-- will give less search hits than 10 00.
  195. 3) Use AH = nn to search for functions called with nn in AH or in the high
  196.    byte of AX. Use AX = nn-- to search for functions called with nn in AH and
  197.    no specific value in AL.
  198. 4) Because WINHELP's search facility does not distinguish between letter case,
  199.    the search keys for capital letter categories are the letter followed by
  200.    an exclamation mark.
  201.  
  202.  
  203. TABLE CROSS-REFERENCES
  204.  
  205. Tables are separate topics in help files compiled with version 1.08+ of
  206. INT2WHLP. When referenced from a "#nnnn" hotspot, the table pops up in a
  207. secondary window, thus the user can easily change between the source in
  208. the main help window and the referenced table in the secondary window.
  209. However, secondary windows are less flexible than the main window: topics
  210. are not recorded in the history list, you cannot browse between topics (<<
  211. and >> pushbuttons), and the topics cannot be copied or printed from the
  212. secondary window. Therefore all tables have a "Copy to Main" hotspot at the
  213. top.
  214.  
  215. The table topic titles include the interrupt number and subfunction where
  216. the table is defined, and there is a hotspot at the end of each table that
  217. pops up the appropriate interrupt in the main window.
  218.  
  219. There are two search keys for each table topic: "#nnnn" where nnnn is the
  220. four digit table number, and the table title as given in the Interrupt List
  221. ("Bitfields for ...", "Call ... with:", "Format of ...", "Values for ...").
  222.  
  223.  
  224. FULL TEXT SEARCH FACILITIES
  225.  
  226. WinHelp's search facility offers search for predefined words or phrases.
  227. Various utilities offer full text search in help files, i.e. search the help
  228. file for any word or phrase the user specifies. These utilities are normally
  229. implememted as one or more dynamic link library files (DLLs), and macros are
  230. inserted in the help file to invoke the text search.
  231.  
  232. Oxford Computer Consultants include a special version of their FTS utility
  233. in the Interrupt List. To use the facility, copy HINTSRCH.DLL from Oxford
  234. Computer Consultants' program package HINTSRCH.ZIP to your Windows SYSTEM
  235. directory. INT2WHLP's configuration file inserts the proper macros in
  236. INTWIN.HLP. One of these macros inserts a "Find Text" pushbutton on
  237. WinHelp's button bar. HINTSRCH.DLL works only with INTWIN, see material in
  238. Oxford Computer Consultant's package for information about their products.
  239.  
  240. Also Microsoft offers an FTS kit. Microsoft's kit uses an index file causing
  241. the search to be extremely fast. A disadvantage is that it takes long time to
  242. compile the index file, and it occupies much disk space (it is 70% longer
  243. than INTWIN.HLP, 8.8 Mb vs. 5.2 Mb for Interrupt List release 45). For the
  244. benefit of those who have access to Microsoft's FTS kit and want to use it,
  245. INT2WHLP's configuration file inserts bag.ini as baggage in INTWIN.HLP, this
  246. file is required by the kit. Utilities are available that can edit the macros
  247. section of INTWIN.HLP to include the macros for Microsoft's kit (WH_wEdit,
  248. see section HIGH RESOLUTION GRAPHICS). The baggage causes no harm if it is 
  249. unused, and it occupies only about 100 bytes.
  250.  
  251.  
  252. HELP WINDOW PUSHBUTTONS
  253.  
  254. The Help Window includes some extra shortcut pushbuttons.
  255.  
  256. "Print" sends the current topic to the currently selected printer. To select
  257. another printer, use "Print Select..." from the "File" menu.
  258.  
  259. "Copy" copies the current topic to the Cllipboard. To copy only part of the
  260. topic, use "Copy..." from the "Edit" menu.
  261.  
  262. "Exit" closes both the main window and an open secodary (table) window.
  263. Selecting "Close" from the control menu or pressing Alt F4 closes only the
  264. main window.
  265.  
  266. "Print" and "Exit" are equivalent to selecting "Print Topic" and "Exit" from
  267. the "File" menu.
  268.  
  269. "Find Text", see FULL TEXT SEARCH FACILITIES.
  270.  
  271.