******************************************************************************* * il2hdk * * Interrupt List to help development kit conversion program. * * Version 2.1, Last Update Sep. 02, 1993. * ******************************************************************************* What's New ---------- 1. Added keyword search for specific interrupts. If you want to look for interrupt 21, ax = abcd, you would specify int_21,ax=abcd from the keyword search menu. This feature was suggested by Stan Brown. 2. Added text attributes to make the database more readable by providing in-topic section headings in bold. 3. This version needs hlpdk V9.0 to compile the intrpts.hdf output. Overview -------- il2hdk is a conversion program from Ralf Brown's interrupt list to the help development kit (hlpdk) .HDF source format. This program will convert the original interrupt list to a hypertext database that can be converted using the helpC compiler included with the help development kit to any one of the target formats supported by this compiler. This generated database is not intended to replace the interrupt list, it is just a compilation of the hypertext version. The nice thing about this hypertext database is that it includes nice hot-links, and easy to use database structure with categories, indexes and directories, there are glossary "hints" in the text, and easy to use keyword search is supported. With the introduction of this tool, and the HPC2HDK conversion program by Yaniv Golan, 2 of the most interesting reference tools available to PC programmers are introduced in a hypertext format, in a format you might find useful. You might find NG2HDK that converts from the Norton Guides to HLPDK format another alternative to keep your accumalated wizdom up to date. Requirments ----------- In order to use this program you will need the following things : 1. Ralf Brown's interrupt list - available on your favourite sites on the internet as INTERxxn, where xx stands for the latest version of the interrupt list (36 is the version number of the list that is available on the net when this document is written), and n stands for a part number (A, B or C as of today..). 2. This package (obviously). 3. A PC that can run DPMI applications for the conversion program, with as much memory as possible. (I have tested this program in an OS/2 VDM restricted to 2MB of DPMI memory, so it can be assumed that any PC with more than 3MB of memory will be able to run this program. Please notice, however, that future versions of the interrupt list might be much bigger than the current version, so more memory might be needed). 4. The help development kit, a shareware product written by myself, that can produce help databases or help databases sources to different environments from the same source. The help development kit is available on the internet in the simtel hypertext and garbo programming directories, on the WINSDK forum, WINHELP section of COMPUSERVE and the JCS Marketing shareware CD-ROM. You can probably find it on other CD-ROMS that include the internet archives, as well as other sources. The current version is HLPDK90, available as HDK90A.ZIP and HDK90B.ZIP in an archive site/bbs/forum library near you. 5. [OPTIONAL] - A help compiler for your specific environment - if you do not generate the code to one of the native help engines included with the help development kit, the code will have to be compiled with the specific help compiler. 6. Time, and Disk Space. The interrupt list is BIG, the il2hdk program tries to convert this list to a smart database with hot-links, and easy navigational structures. This process takes time, and - Disk Space. (As can be seen in the 3rd entry of this section above - memory is needed as well). Operation --------- 0. Well - you know - just do it, oh well, I will be more specific. 1. Move the contents of this package to the directory of the interrupt list files. (Not mandatory - only recommended). 2. Check the INTLST.LST file provided with this package to see if all the files of the interrupt list are specified in it, (or if you use the combine.bat file that came with the interrupt list), and modify it if neccesary. 3. execute the convertor by typing IL2HDK on the command line. (I do not promise, but you can say that you heard of a GUI icon ridden version, working as a distributed object with 216 bit technology sometime in the future). 4. Use to helpC compiler from the help development kit package to compile for you target. (e.g. To compile for Windows 3.1 - HELPC /W31 /R- INTRPTS). 5. [Optional] - Use your help compiler for the final pass (e.g. - To compile to Windows 3.1 use the Microsoft HCP program - HCP INTRPTS). > Please issue IL2HDK /? for a list of the switches available to the conversion program. > You may want to add glossary items to the glossary file, or additional glossary files, please consult the Tech-Talk section below. File List --------- This package contains the following files : IL2HDK .EXE - The convertor program exexcutable. DPMI16BI.OVL - Borland's DPMI Server. RTM .EXE - Borland's Dos Extender Run Time Module. IL2HDK .DOC - This File. CTGCNV .LST - Category Conversion List Hints file. INTLST .LST - Default interrupt list file list. GLSLST .LST - Glossary files list. Advertisment ------------ Buy 2, Get 3 FREE!. (ACT Now!, A limited time offer). Known Bugs ---------- 0. WHAT???, BUGS???, HERE???, IN MY PROGRAM???. Every thing works as advertised. (See above). 1. The database is so BIG that some targets supported by the helpC compiler failed to operate. A. HC31 will not compile the intrpts.hpj and intrpts.rtf sources created by helpC. You must use HCP - the protected mode windows help compiler. B. Borland's Help Linker 6.10 causes exception 12 when it tries to compile the helpC output using HL -e100 -x -p -i INTRPTS.HL . Maybe Version 6.0 will work. If anyone knows of a way around this, please tell me. (I was told by Borland Rep. that the problem was sent to QA hopefully for a fix ..). C. The Native Memory format can not support this database, there are too many links. The Naive Paradox based format works. (But it is slow in the current implementation). D. I have not tried any other formats, so if you do, please tell me. 2. The helpC compiler failed with a run-time error 203. A. Some targets can not be compiled in the shareware version of the help development kit. DV/X, OS/2, POPHELP, Text and Native/Mem targets need a symbol table that is built by helpC in memory, the shareware version works in real mode and is restricted to 640K (or a bit more ..), which is not enough to create the symbol table for such a huge database. Please use the registered version helpCX protected mode compiler for these targets. 3. The helpC compiler can not create the Cross Regerence Report. A. Please use the helpCX protected mode compiler (included with the registered version of the help development kit). The cross reference report builds the reference tables in memory, the non-registered version is restricted to 640K which is not enough for such a huge database. 4. Please inform me of any problems you encountered using this program. 5. There are some topics that are mapped to the same reference name (around 20 out of 5000+), I can not think of a solution that will not require a considerable effort on my side, this seems to be a "data" problem, and I have no desire to build complex algorithms to resolve these colisions. Tech-Talk --------- This program works like a 2 pass compiler that builds a symbol table on the first pass, and process the data and hot-links on the 2nd pass. Additional phases of the convertor create interrupt and category directories that help the user navigate the database in a heirarchy model. The convertor will create a unique topic name from each interrupt entry in the interrupt list, and assign it a title. The SeeAlso: entries of the list are processed by the convertor, and hot-links are added. Since the seeAlso: entries do not include direct references to the topics they should point, a best guess mechanism assisted by a hint list (included with this package as CTGCNV.LST) tries to associate the entries with the correct topic. Entries that can not be identified from this data are being linked to the specific interrupt directory - so even if you will not be taken to the direct place in the database, you will get close enough. Index: entries are processed as well, and a link to a menu of all the topics that has this index is created. Keywords are defined for every topic, when the database will be compiled, The user will be able to search on these keywords. The glossary file glossary.lst is processed by the il2hdk program to create glossary hints (popups in the hlpdk terminology). If you want to add popus (glossary items), add a file in the same format as the glossary.lst to the glslst.lst list file. Notice that if you want to create multiple instances of the same glossary item, (e.g. VM = Virtual Machine) put 2 entries in your glossary file, and write the text see First Name in the Second name glossary item. (Look at the glossary.lst file for example). The reason I decided to create a DPMI program is that in order to achieve the best guess mechanism I needed to hold a lot of information in a way I could manage fast, both sequentally and randomly. The obvious idea was to use either a database indexed table (I would have used the Paradox Engine), or a virtual memory table. The first approach is too slow, and would require a lot of disk space, while the 2nd one is fast (as fast as a database as big as this allows), and more economical in disk space. I figure that if you are a programmer that needs this kind of information database, you have a machine capable of running this program. If you MUST run this program on your 640K PC-XT, contact me, and I will provide you with a version that uses the Paradox Engine. (+ make sure you can leave your XT on for the next couple of month). Distribution ------------ This program is free. I encourage you to try the help development kit by compiling the output of this program. Please notice however, that the help development kit is not free, it is a shareware product that you will have to register (for a very reasonable price) if you find it valuable. (Registered users of the kit are encouraged to use this program as well, for no additional cost, of course). Please support the shareware concept. The distribution of the interrupt list should be as described by Ralf Brown. Suggestions ----------- Please feel free to send me any suggestions, enhancment requests, etc.. for this program, or the help development kit. Suggestions for the interrupt list should be sent to Ralf Brown in the address published in the interrupt list. Future Plans ------------ A lot - just wait for the next release! History ------- - The Jurassic era : A long long time ago. - July 1993 : The first release of this convertor. - July 1993 : V1.1 - Keyword support, Enhanced accuracy, winHelp tabs. 1. Use hlpdk 7.0 to compile/display the output of the il2hdk program, there is a problem with Microsoft's HCP that does not always recognize RTF Tabs (\tab) if they are not in a group of their own. V7.0 of helpC goes around this problem by using a RTF group for every TAB, so some of the text will not be flushed left and invisible. The Native Paradox format help engine is able to display topics of up to 16K lines, Vs. 500 only, so some of the intrpts database topics that could not be seen before can be used with this release. 2. Increased the accuracy of the list by the ability to parse hex parameters that do not appear in the list with a 'h' suffix. 3. Added keywords support. il2hdk will create keyword references from this version. - Aug. 1993 : V2.0 - Extended Topics, intlist V3.6 support, Index:, category reference in topics, glossary, Needs hlpdk 8.0. 1. Recognize another category - Expansion Bus Bios. 2. Added support for interrupt list V3.6 !xxx category entries. 3. Added support for index: entries in the interrupt list source. 4. Added a link to relevant Category Directory in every topic. 5. Added Glossary file support, as hints (popups) in the database, because of that this version should be compiled with hlpdk V8.0. - Sep. 1993 : V2.1 - Text Attributes, Enhanced Keywords search, Needs hlpdk 9.0. HLPDK ----- The help development kit is a shareware product that allows you to create your help sources once, and port them to multiple platforms. In V9.0 of the kit, which is the version that was used to test the output of this program, the supported targets are : Native (Paradox 4.x & Text) Native (Memory Tables) Winhelp 3.0 Winhelp 3.1 OS/2 IPF THELP (and Borland's IDE) QuickHelp POPHELP TVHC DESQview/X help Text Documents with automatic table of contents, Glossary and index entries. Word Processors that support the RTF format. (W4W, WP4W, AP etc..) HLPDK Supports keywords, links, popups, structural and navigation aids (groups) text attributes, cross reference reports, conditional defines, the ability to insert target code into the hlpdk source and much more. With HLPDK you can write your documentation once (both for on-line hypertext documents on several platforms and targets, and for a hard-print as ascii or fine-print document) once, and re-compile to additional targets. Warranty -------- There is no warranty what so ever, The package is supplied as is, the author of the conversion program (Loewy Ron), is not, and will not be responsible for any damages, lost profits, or inconveniences caused by the use, or inability to use this package. The use of the package is at your own risk. By using (or attempting to use) the package you agree to this. The following text is by Ralf Brown, from the interrup.1st file : --------------------------------------------- DISCLAIMER: THIS MATERIAL IS PROVIDED "AS IS". I verify the information contained in this list to the best of my ability, but I cannot be held responsible for any problems caused by use or misuse of the information, especially for those functions not officially documented. If it is marked "internal" or undocumented, you should check it carefully to make sure it works the same way in your version of the software (and please let me know whether or not it works the same way). Information marked with "???" is known to be incomplete or guesswork. --------------------------------------------- To refer to the warranty, choose Ralf Brown Categories from the Category Directory screen, and refer to Ralf's words. (This information is taken from interrup.1st). contact ------- Please contact : ISoft D&M, P.O.B 5517 Coralville IA 52241, U.S.A ISoft D&M e-mail address : Compuserve - 76350,333 To contact the author directly : Contact : Loewy Ron, 9 Haneveem st. Herzeliya, 46465 ISRAEL. e-mail address : CompuServe - 100274,162 Credits ------- The interrupt list copyright notice is : This compilation is (c) Copyright 1989, 1990, 1991, 1992, 1993 Ralf Brown. Additional interrupt list credits can be found in the interrup.1st file that comes with the interrupt list. Ralf Brown provided me with description of the interrupt list that allowed me to create the il2hdk conversion program, he also suggested ideas, found bugs and informed me of the interrupt list changes. il2hdk is (c) Copyright 1993, Loewy Ron. hlpdk is (c) Copyright 1992,93 Loewy Ron. il2hdk was written using Borland Pascal 7.0, major parts of this program were created using dbGen - My own case code generator. HELPENG, HELPC were written using Turbo Pascal 6.0, and Borland Pascal 7.0, Paradox Engine 2.0, and Paradox Engine 3.0, 3.01. (Trademarks of Borland International). Windows, Microsoft, HC and Quick Help are trademarks or copyrights of Microsoft Corp. The HELPENG program was written using the WINTEXT UI library, (c) 1991,93 Loewy Ron. THELP, HL and TVHC are Trademarks or copyrights Borland International. POPHELP is a copyright of TurboPower Software. Parts of the Help Engines were generated using Ron Loewy's WTGEN and dbGen CASE code generators. Parts of the Help Compiler were generated using Ron Loewy's dbGen database code generator. Yaniv Golan helped me with beta-testing, debugging and suggestions. He is also the programmer of the HPC2HDK program (available in an archive site near you) that convert the HelpPC technical database to the Help Development Kit format. (The HelpPC database is a wonderfull hypertext work by David Jurgens). DESQview/X is a trademark of Quarterdeck Office Systems. OS/2 is a registered trademark of International Bussiness Machines. NG2HDK is a Copyright (c) 1993, Ron Loewy. Stan Brown suggested the additional keywords that supports search by interrupt number. Other products mentioned are copyrights or trademarks of their respective holders.