home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / il2hdk.zip / IL2HDK.DOC < prev    next >
Text File  |  1993-12-30  |  20KB  |  471 lines
  1. *******************************************************************************
  2. *                                   il2hdk                                    *
  3. * Interrupt List to help development kit conversion program.                  *
  4. * Version 3.1, Last Update Dec. 30, 1993.                                     *
  5. *******************************************************************************
  6.  
  7.  
  8. What's New
  9. ----------
  10.  
  11. 1. Added the interrup.pri to the "additional files" category.
  12.  
  13. 2. Created a OS/2 version of il2hdk.
  14.  
  15.  
  16. Overview
  17. --------
  18.  
  19. il2hdk is a conversion program from Ralf Brown's interrupt list to the help
  20. development kit (hlpdk) .HDF source format. 
  21.  
  22. This program will convert the original interrupt list to a hypertext database
  23. that can be converted using the helpC compiler included with the help 
  24. development kit to any one of the target formats supported by this compiler.
  25.  
  26. This generated database is not intended to replace the interrupt list, it is 
  27. just a compilation of the hypertext version. The nice thing about this 
  28. hypertext database is that it includes nice hot-links, and easy to use database
  29. structure with categories, indexes and directories, there are glossary
  30. "hints" in the text, and easy to use keyword search is supported.
  31.  
  32. With the introduction of this tool, and the HPC2HDK conversion program by 
  33. Yaniv Golan, 2 of the most interesting reference tools available to PC 
  34. programmers are introduced in a hypertext format, in a format you might find
  35. useful.
  36.  
  37. You might find NG2HDK that converts from the Norton Guides to HLPDK format 
  38. another alternative to keep your accumalated wizdom up to date, and POPHDK 
  39. that converts from POPHELP to HLPDK as well. (Yaniv Golan's work - again).
  40.  
  41. Requirments
  42. -----------
  43.  
  44. In order to use this program you will need the following things :
  45.  
  46. 1. Ralf Brown's interrupt list - available on your favourite sites on the
  47.    internet as INTERxxn, where xx stands for the latest version of the
  48.    interrupt list (36 is the version number of the list that is available
  49.    on the net when this document is written), and n stands for a part number
  50.    (A, B or C as of today..).
  51.  
  52. 2. This package (obviously).
  53.  
  54. 3. A PC that can run DPMI applications for the conversion program, with as much
  55.    memory as possible. (I have tested this program in an OS/2 VDM restricted
  56.    to 2MB of DPMI memory, so it can be assumed that any PC with more than 3MB
  57.    of memory will be able to run this program. Please notice, however, that 
  58.    future versions of the interrupt list might be much bigger than the current 
  59.    version, so more memory might be needed).
  60.  
  61. 4. The help development kit, a shareware product written by myself, that can
  62.    produce help databases or help databases sources to different environments
  63.    from the same source. The help development kit is available on the internet
  64.    in the simtel hypertext and garbo programming directories, on the WINSDK
  65.    forum, WINHELP section of COMPUSERVE and the JCS Marketing shareware CD-ROM.
  66.    You can probably find it on other CD-ROMS that include the internet archives,
  67.    as well as other sources. The current version is HLPDK 10.0, available as 
  68.    HDK100A.ZIP and HDK100B.ZIP in an archive site/bbs/forum library near you.
  69.  
  70. 5. [OPTIONAL] - A help compiler for your specific environment - if you do not
  71.    generate the code to one of the native help engines included with the 
  72.    help development kit, the code will have to be compiled with the specific
  73.    help compiler.
  74.  
  75. 6. Time, and Disk Space. The interrupt list is BIG, the il2hdk program tries to
  76.    convert this list to a smart database with hot-links, and easy navigational
  77.    structures. This process takes time, and - Disk Space. (As can be seen in
  78.    the 3rd entry of this section above - memory is needed as well).
  79.  
  80. Operation
  81. ---------
  82.  
  83.  
  84. 0. Well - you know - just do it, oh well, I will be more specific.
  85.  
  86. 1. Move the contents of this package to the directory of the interrupt list
  87.    files. (Not mandatory - only recommended).
  88.  
  89. 2. Check the INTLST.LST file provided with this package to see if all the files
  90.    of the interrupt list are specified in it, (or if you use the combine.bat
  91.    file that came with the interrupt list), and modify it if neccesary.
  92.  
  93. 3. execute the convertor by typing IL2HDK on the command line. (I do not 
  94.    promise, but you can say that you heard of a GUI icon ridden version,
  95.    working as a distributed object with 216 bit technology sometime in the
  96.    future).
  97.  
  98. 4. Use to helpC compiler from the help development kit package to compile for
  99.    you target. (e.g. To compile for Windows 3.1 - HELPC /W31 /R- INTRPTS).
  100.  
  101. 5. [Optional] - Use your help compiler for the final pass (e.g. - To compile
  102.    to Windows 3.1 use the Microsoft HCP program - HCP INTRPTS).
  103.  
  104. > Please issue IL2HDK /? for a list of the switches available to the
  105.   conversion program.
  106.  
  107. > You may want to add glossary items to the glossary file, or additional
  108.   glossary files, please consult the Tech-Talk section below.
  109.  
  110. File List
  111. ---------
  112.  
  113. This package contains the following files :
  114.  
  115. IL2HDK  .EXE - The convertor program exexcutable.
  116. DPMI16BI.OVL - Borland's DPMI Server - Needed ONLY with the dos version.
  117. RTM     .EXE - Borland's Dos Extender Run Time Module - req. for dos ver. only.
  118. IL2HDK  .DOC - This File.
  119. CTGCNV  .LST - Category Conversion List Hints file.
  120. INTLST  .LST - Default interrupt list file list.
  121. GLSLST  .LST - Glossary files list.
  122.  
  123. Advertisment
  124. ------------
  125.  
  126. Buy 2,  Get 3 FREE!. (ACT Now!, A limited time offer).
  127.  
  128. Known Bugs
  129. ----------
  130.  
  131. 0. WHAT???, BUGS???, HERE???, IN MY PROGRAM???. Every thing works as 
  132.    advertised. (See above).
  133.  
  134. 1. The database is so BIG that some targets supported by the helpC compiler
  135.    failed to operate.
  136.  
  137.  A. HC31 will not compile the intrpts.hpj and intrpts.rtf sources created by
  138.     helpC. You must use HCP - the protected mode windows help compiler.
  139.  B. Borland's Help Linker 6.10 causes exception 12 when it tries to compile 
  140.     the helpC output using HL -e100 -x -p -i INTRPTS.HL . Maybe Version 6.0
  141.     will work. If anyone knows of a way around this, please tell me. (I was
  142.     told by Borland Rep. that the problem was sent to QA hopefully for a fix ..).
  143.  C. The Native Memory format can not support this database, there are too many
  144.     links. The Naive Paradox based format works. (But it is slow in the current
  145.     implementation).
  146.  D. OS/2 IPF fails, because a topic can have a maximum of 16000 words, and 
  147.     because some of the directories (such as the interrupt 2f directory) can be
  148.     very large, IPFC will fail. IBM's ANN FORD told me on CIS that a future
  149.     version of IPF will be a clean 32 bit version, and will support more words
  150.     per topic.
  151.  E. HCP - Apparantly, if HCP does not have enough memory, it will fail to 
  152.     create the correct contents screen. The database will be created, but,
  153.     the first topic that will be presented is the first topic in the RTF
  154.     file. Compiling with HCP in a 8MB DOS VDM under OS/2 works for me, in 
  155.     a 2MB window, HCP did not create the correct contents topic.
  156.  E. I have not tried any other formats, so if you do, please tell me.
  157.  
  158. 2. The helpC compiler failed with a run-time error 203.
  159.  
  160.  A. Some targets can not be compiled in the shareware version of the help 
  161.     development kit. DV/X, OS/2, POPHELP, Text and Native/Mem targets need
  162.     a symbol table that is built by helpC in memory, the shareware version
  163.     works in real mode and is restricted to 640K (or a bit more ..), which
  164.     is not enough to create the symbol table for such a huge database. Please
  165.     use the registered version helpCX protected mode compiler for these 
  166.     targets.
  167.  
  168. 3. The helpC compiler can not create the Cross Regerence Report.
  169.  
  170.  A. Please use the helpCX protected mode compiler (included with the registered
  171.     version of the help development kit). The cross reference report builds 
  172.     the reference tables in memory, the non-registered version is restricted
  173.     to 640K which is not enough for such a huge database.
  174.  
  175. 6. Please inform me of any problems you encountered using this program.
  176.  
  177. Tech-Talk
  178. ---------
  179.  
  180. This program works like a 2 pass compiler that builds a symbol table on the
  181. first pass, and process the data and hot-links on the 2nd pass. Additional
  182. phases of the convertor create interrupt and category directories that help
  183. the user navigate the database in a heirarchy model.
  184.  
  185. The convertor will create a unique topic name from each interrupt entry in
  186. the interrupt list, and assign it a title. 
  187. The SeeAlso: entries of the list are processed by the convertor, and hot-links
  188. are added. Since the seeAlso: entries do not include direct references to the
  189. topics they should point, a best guess mechanism assisted by a hint list
  190. (included with this package as CTGCNV.LST) tries to associate the entries
  191. with the correct topic. Entries that can not be identified from this data
  192. are being linked to the specific interrupt directory - so even if you will
  193. not be taken to the direct place in the database, you will get close enough.
  194. Index: entries are processed as well, and a link to a menu of all the topics
  195. that has this index is created.
  196.  
  197. Keywords are defined for every topic, when the database will be compiled, The
  198. user will be able to search on these keywords.
  199.  
  200. The glossary file glossary.lst is processed by the il2hdk program to create
  201. glossary hints (popups in the hlpdk terminology). If you want to add popus
  202. (glossary items), add a file in the same format as the glossary.lst to
  203. the glslst.lst list file. Notice that if you want to create multiple 
  204. instances of the same glossary item, (e.g. VM = Virtual Machine) put
  205. 2 entries in your glossary file, and write the text see First Name in the
  206. Second name glossary item. (Look at the glossary.lst file for example).
  207.  
  208. The reason I decided to create a DPMI program is that in order to achieve
  209. the best guess mechanism I needed to hold a lot of information in a way
  210. I could manage fast, both sequentally and randomly. The obvious idea was to
  211. use either a database indexed table (I would have used the Paradox Engine), or
  212. a virtual memory table. The first approach is too slow, and would require 
  213. a lot of disk space, while the 2nd one is fast (as fast as a database as big
  214. as this allows), and more economical in disk space. I figure that if you
  215. are a programmer that needs this kind of information database, you have 
  216. a machine capable of running this program. If you MUST run this program 
  217. on your 640K PC-XT, contact me, and I will provide you with a version
  218. that uses the Paradox Engine. (+ make sure you can leave your XT on for
  219. the next couple of month).
  220.  
  221. Distribution
  222. ------------
  223.  
  224. This program is free. I encourage you to try the help development kit by
  225. compiling the output of this program. Please notice however, that the 
  226. help development kit is not free, it is a shareware product that you
  227. will have to register (for a very reasonable price) if you find it
  228. valuable. (Registered users of the kit are encouraged to use this program
  229. as well, for no additional cost, of course). Please support the shareware 
  230. concept.
  231.  
  232. The distribution of the interrupt list should be as described by Ralf Brown.
  233.  
  234. Suggestions
  235. -----------
  236.  
  237. Please feel free to send me any suggestions, enhancment requests, etc.. for
  238. this program, or the help development kit. 
  239.  
  240. Suggestions for the interrupt list should be sent to Ralf Brown in the address
  241. published in the interrupt list.
  242.  
  243. Future Plans
  244. ------------
  245.  
  246. A lot - just wait for the next release!
  247.  
  248. History
  249. -------
  250.  
  251. - The Jurassic era : A long long time ago.
  252.  
  253. - July 1993        : The first release of this convertor.
  254.  
  255. - July 1993        : V1.1 - Keyword support, Enhanced accuracy, winHelp tabs.
  256.  
  257. 1. Use hlpdk 7.0 to compile/display the output of the il2hdk program, there
  258. is a problem with Microsoft's HCP that does not always recognize RTF Tabs
  259. (\tab) if they are not in a group of their own. V7.0 of helpC goes around this
  260. problem by using a RTF group for every TAB, so some of the text will not 
  261. be flushed left and invisible. The Native Paradox format help engine is able
  262. to display topics of up to 16K lines, Vs. 500 only, so some of the intrpts
  263. database topics that could not be seen before can be used with this release.
  264.  
  265. 2. Increased the accuracy of the list by the ability to parse hex parameters
  266. that do not appear in the list with a 'h' suffix.
  267.  
  268. 3. Added keywords support. il2hdk will create keyword references from this 
  269. version.
  270.  
  271. - Aug. 1993        : V2.0 - Extended Topics, intlist V3.6 support, Index:,
  272.                             category reference in topics, glossary, Needs 
  273.                             hlpdk 8.0.
  274.  
  275. 1. Recognize another category - Expansion Bus Bios.
  276.  
  277. 2. Added support for interrupt list V3.6 !xxx category entries.
  278.  
  279. 3. Added support for index: entries in the interrupt list source.
  280.  
  281. 4. Added a link to relevant Category Directory in every topic.
  282.  
  283. 5. Added Glossary file support, as hints (popups) in the database, because
  284.    of that this version should be compiled with hlpdk V8.0.
  285.  
  286. - Sep. 1993        : V2.1 - Text Attributes, Enhanced Keywords search, Needs
  287.                             hlpdk 9.0.
  288.  
  289. 1. Added keyword search for specific interrupts. If you want to look for 
  290. interrupt 21, ax = abcd, you would specify int_21,ax=abcd from the keyword
  291. search menu. This feature was suggested by Stan Brown.
  292.  
  293. 2. Added text attributes to make the database more readable by providing
  294. in-topic section headings in bold.
  295.  
  296. 3. This version needs hlpdk V9.0 to compile the intrpts.hdf output.
  297.  
  298. - Sep. 1993        : V2.2 - Faster, multi-glossaries per line.
  299.  
  300. 1. il2hdk will give Ralf Brown's special ! topics a more readable title,
  301. and will not take the title from the first topic line.
  302.  
  303. 2. Multiple glossary references can be created on a line.
  304.  
  305. 3. Glossary references will only match complete words. You will not see
  306. a reference to handle as part of the word handler.
  307.  
  308. 4. A glossary item will be created only once per topic, for the first
  309. occurance. You will not have to see (and pay in help file size) for
  310. multiple glossary references of the same link in the same topic.
  311.  
  312. 5. il2hdk pass2 is much faster now. The algorithm is to scan for popups
  313. horizontally vs. vertically as it was done before, so less database access
  314. is needed. (Even when it is in memory it has the price).
  315.  
  316. 6. This version of il2hdk supports "Clash Protection" - Topics that clash
  317. to the same identifier are mapped to unique names, and references are created
  318. between all the topics that clash like that.
  319.  
  320. - Oct. 1993        : V2.3 - Fixed Bug - support Version 37 of the list. 
  321.  
  322. 1. This version was checked on version 37 of the interrupt list, it
  323. fixes a bug, in the il2hdk program, that could (on very rare occasions)
  324. cause a loop while processing the new PCMCIA entries.
  325.  
  326. - Oct. 1993        : V3.0 - Browse Sequences support, external file 
  327.                             incorporation
  328. 1. Added Browse Sequences generation for interrupts and Ralf Brown topics.
  329.  
  330. 2. Incorporate the files MEMORY.LST, PORTS.LST, CMOS.LST AND 86BUGS.LST that
  331.    are shiped with the interrupt list to the hypertext database.
  332.  
  333. 3. This version needs HLPDK Sound & Vision Edition (V10.0) to compile.
  334.  
  335. - Dec. 1993        : V3.1 - OS/2 Version.
  336.  
  337.  
  338. HLPDK
  339. -----
  340.  
  341. The help development kit is a shareware product that allows you to create
  342. your help sources once, and port them to multiple platforms. In V10.0
  343. of the kit, which is the version that was used to test the output of this 
  344. program, the supported targets are :
  345.  
  346. Native (Paradox 4.x & Text)
  347. Native (Memory Tables)
  348. Winhelp 3.0
  349. Winhelp 3.1
  350. MS Multimedia Viewer
  351. OS/2 IPF
  352. THELP (and Borland's IDE)
  353. QuickHelp
  354. POPHELP
  355. TVHC
  356. DESQview/X help
  357. Text Documents with automatic table of contents, Glossary and index entries.
  358. Word Processors that support the RTF format. (W4W, WP4W, AP etc..)
  359.  
  360. HLPDK Supports keywords, links, popups, structural and navigation aids (groups)
  361. text attributes, cross reference reports, conditional defines, the ability to
  362. insert target code into the hlpdk source, exception handling and much more.
  363.  
  364. With HLPDK you can write your documentation once (both for on-line hypertext
  365. documents on several platforms and targets, and for a hard-print as ascii or
  366. fine-print document) once, and re-compile to additional targets.
  367.  
  368. This version is comapible with HLPDK 11.0, currently in Beta, that supports
  369. HTML target for WWW access.
  370.  
  371. Warranty
  372. --------
  373. There is no warranty what so ever, The package is supplied as is,
  374. the author of the conversion program (Loewy Ron), is not, and will not be 
  375. responsible for any damages, lost profits, or inconveniences caused by the use, 
  376. or inability to use this package. The use of the package is at your own risk. 
  377. By using (or attempting to use) the package you agree to this.
  378.  
  379. The following text is by Ralf Brown, from the interrup.1st file :
  380. ---------------------------------------------
  381. DISCLAIMER:  THIS MATERIAL IS PROVIDED "AS IS".     I verify the information
  382. contained in this list to the best of my ability, but I cannot be held
  383. responsible for any problems caused by use or misuse of the information,
  384. especially for those functions not officially documented.  If it is marked
  385. "internal" or undocumented, you should check it carefully to make sure it
  386. works the same way in your version of the software (and please let me know
  387. whether or not it works the same way).    Information marked with "???" is
  388. known to be incomplete or guesswork.
  389. ---------------------------------------------
  390.  
  391. To refer to the warranty, choose Ralf Brown Categories from the Category
  392. Directory screen, and refer to Ralf's words. (This information is taken
  393. from interrup.1st).
  394.  
  395. contact
  396. -------
  397.  
  398.   Please contact :
  399.  
  400.   ISoft D&M,  
  401.   P.O.B 5517
  402.   Coralville IA 52241,
  403.   U.S.A
  404.  
  405.   ISoft D&M e-mail address : Compuserve - 76350,333
  406.  
  407.   To contact the author directly : 
  408.  
  409.   e-mail address : CompuServe - 100274,162
  410.  
  411. Credits
  412. -------
  413.  
  414. The interrupt list copyright notice is :
  415. This compilation is (c) Copyright 1989, 1990, 1991, 1992, 1993 Ralf Brown.
  416.  
  417. Additional interrupt list credits can be found in the interrup.1st file
  418. that comes with the interrupt list.
  419.  
  420. Ralf Brown provided me with description of the interrupt list that allowed
  421. me to create the il2hdk conversion program, he also suggested ideas,
  422. found bugs and informed me of the interrupt list changes.
  423.  
  424. il2hdk is (c) Copyright 1993, Loewy Ron.
  425.  
  426. hlpdk is (c) Copyright 1992,93 Loewy Ron.
  427.  
  428. il2hdk was written using Borland Pascal 7.0, major parts of this program were
  429. created using dbGen - My own case code generator.
  430.  
  431. The OS/2 version was created using the C'.T'. magazine Borland Pascal OS/2 
  432. patch. Thanks folks!.
  433.  
  434. HELPENG, HELPC were written using Turbo Pascal 6.0, and Borland Pascal 7.0,
  435. Paradox Engine 2.0, and Paradox Engine 3.0, 3.01. 
  436. (Trademarks of Borland International).
  437.  
  438. Windows, Microsoft, MM Viewer, HC and Quick Help are trademarks or copyrights
  439. of Microsoft Corp.
  440.  
  441. The HELPENG program was written using the WINTEXT UI library, 
  442. (c) 1991,93 Loewy Ron.
  443.  
  444. THELP, HL and TVHC are Trademarks or copyrights Borland International.
  445.  
  446. POPHELP is a copyright of TurboPower Software.
  447.  
  448. Parts of the Help Engines were generated using Ron Loewy's WTGEN and dbGen
  449. CASE code generators.
  450.  
  451. Parts of the Help Compiler were generated using Ron Loewy's dbGen database 
  452. code generator.
  453.  
  454. Yaniv Golan helped me with beta-testing, debugging and suggestions. He is also
  455. the programmer of the HPC2HDK program (available in an archive site near you)
  456. that convert the HelpPC technical database to the Help Development Kit format.
  457. Yaniv is also the programmer of POPHDK - the POPHELP 2 HLPDK convertor.
  458. (The HelpPC database is a wonderfull hypertext work by David Jurgens).
  459.  
  460. DESQview/X is a trademark of Quarterdeck Office Systems.
  461.  
  462. OS/2 is a registered trademark of International Bussiness Machines.
  463.  
  464. NG2HDK is a Copyright (c) 1993, Ron Loewy.
  465.  
  466. Stan Brown suggested the additional keywords that supports search by interrupt
  467. number.
  468.  
  469. Other products mentioned are copyrights or trademarks of their respective 
  470. holders.
  471.