V I P F A text-mode .INF viewer for OS/2 (c)1994 by red point systems ==== What Is It? VIPF is a text-mode replacement for VIEW.EXE, the IPF file (.INF and .HLP) viewer supplied with OS/2. It was written primarily for use on my ThinkPad 300 running OS/2 2.1 without PM that I do some of my development on (I use CSHELL from IBM's EWS stuff as a ses- sion manager). Since I often just read around in such files, VIPF reads the whole file when started so that the harddisk can be shut down afterwards to conserve battery power and reduce noise. To decode the IPF files, I relied on the information in the INF02A.DOC file enclosed with this program. As this information is not complete, neither is VIPF. Most prominently, it fails for hy- pertext links across multiple files. Single file documents it should work nicely though, except for some style controls that are ignored. Amongst the files I tested VIPF with are CMDREF, REXX, VREXX, PRCP (16-bit core call documentation), GUIREF20 (same for 32-bit core calls) and LATEX. These work fine. ==== How Do I Use It? Starting VIPF To start VIPF on an IPF file (.INF or .HLP), pass the full name (including the extension!) of the file as an argument to VIPF. VIPF shows what it reads and then displays the table of contents. Cursor Control, Help, And Exiting All the views presented by VIPF are controlled alike. The cursor can be moved around freely on the whole screen using the normal cursor control keys. In particular: Arrows Move cursor PgUp/Dn Move pagewise Ctrl-PgUp/Down Move to start/end of document Home/End Move to start/end of line Pressing ? shows a short help screen that describes all the main keys. Some keys may not work in some views though. To leave a view press ESCAPE. Leaving the table of contents ends VIPF (without confirmation!). The Table Of Contents This is the main display of VIPF. It lists all the directly avail- able topics in the file. As in VIEW, subheadings can be folded away under their main headings. To indicate this, a leading " + " marks headings with hidden subheadings, while " - " marks unfolded headings. To fold or unfold the subheadings of a heading, press SPACE on the main heading. To view the text for a particular to- pic, press RETURN on it. This brings up the text of the topic. To see the index, press I. The Text Viewer This displays the text of the currently chosen topic. Hypertext links are inverted. To follow such a link, position the cursor over it and press RETURN. The text viewer keeps a history of the last 20 or so topics viewed. Exiting a text with ESCAPE returns to the previous text or, if there was none, the table of contents or the index, whichever it was chosen from. Some topics have automatic links embedded within them. These links are automatically followed when the topic is shown. There- fore, you initially do not see the main topic, but the last of the automatically linked topics. To return to the previous automatic- ally linked topics, and finally the main topic, press ESCAPE (the normal history of viewed topics is used). The Index This displays the index of the IPF file. It is very much like the table of contents, except that it cannot fold subentries. To disp- lay the text for an entry, press RETURN over it. To return to the table of contents, press ESCAPE. Searching To search for some text in the current view, you must first define the search text. To do this, press S and enter the search text at the prompt popping up. Then, pressing F repeatedly searches for the next occurrence of the text starting at the cursor position. The search text is the same for all views and is preserved when views are changed. NOTE: In the table of contents, hidden subheadings are NOT sear- ched. Unfold the main headings first, or search the index. ==== About The Source Code VIPF was written in Modula-2 and compiled using Clarion's (former JPI's) TopSpeed Modula-2 compiler version 3.10. This compiler at present produces only 16-bit code, so VIPF is a 16-bit applica- tion. It probably runs on OS/2 1.0 too... I do not expect many people to be using Modula-2 to program OS/2 and therefore do not supply the whole source code. I do, how- ever, supply the crucial modules, which are outlined below. For those not familiar with Modula-2, the language is very much like Pascal (it is in fact its successor). The .DEF files are the interfaces of the modules (program parts) and the .MOD files are the implementations. Module VIPF VIPF.MOD is the main module (the main program). It simply checks the command line and then calls the IPF file loader and finally the viewer. Module IPF IPF.DEF and IPF.MOD define the module that reads the IPF file and exports it in convenient structures. Note that all of the arrays are allocated and sized dynamically. The terminology closely fol- lows that used in the INF02A.DOC documentation file. Module IPFView IPFView.DEF and IPFView.MOD define the module that displays the different views of the data exported by IPF. The first section de- fines a general browser with hooks for line display and processing of keys pressed by the user. Then, the hooks for the table-of-con- tents and the index browser follow. They are straightforward. Now comes the tricky part. The procedure BuildLines formats a topic for display. It builds it up line by line doing word-wrap on the way. The displayable text is stored in an array of line poin- ters. The hypertext links are stored in another array giving their starting and ending offsets within the original encoded text. Another array stores the offsets of the starts of the formatted lines to associate links with lines. Finally, a variable AutoStart gives the index of the first link that must be followed automatic- ally (this assumes that such links are consecutive and the last in the document--up to now, it worked). If the decoding VIPF does is wrong, this is the place to look at (in particular, the central case statement on escape sequences). Finally, the text browser hooks are defined. There are two not entirely trivial ones, the first being the line display hook that must correctly invert the links it finds on the line. The second is the main text browser loop that takes care of the history of viewed texts and links that must be followed automatically. Module IPFDump IPFDump.DEF and IPFDump.MOD are not really part of VIPF. They de- fine a module that displays a dump of the decoding of a topic's text for debugging purposes. I have included it for people who want to do some of their own decoding. (Hint: links across files would be nice, though supporting them would change much of the data structures...) Modules Not Supplied As mentioned before, the run-time modules are not supplied. The ones I used are the windowing library supplied with the compiler, the basic console i/o library, and two of our own modules for disk i/o and error handling (rarely used here). I believe the code should be easy to understand all the same. ==== "Thank You" And "Please Thank Me" Many thanks to Carl Hauser and Marcus Groeber for INF02A.DOC. Carl, maybe you will like this here tool of mine better than VIEW.EXE, though it's not so complete. Those of you who feel grateful, please just send me a postcard or a note to cheer me up a little on a rainy day. The postal address is: Peter Arrenbrecht Im Kratten 32 8623 Wetzikon ZH SWITZERLAND Unfortunately, I don't yet have an e-mail address. You might soon want to try parrenbr@unizh.ch though. If you change VIPF, or port it to C or some other such nightmare, please let me know. Also, I'd be interested if someone else has more information on the decoding of IPF files (hey, IBM, this is a hint for your next Developers' Connection edition). ==== The Legal Stuff As usual, I do not accept any responsibility whatsoever for the effects of anything to do with VIPF.EXE that I don't have to by the requirements of the law. The program VIPF.EXE and the publicized source code accompanying it are hereby placed in the public domain and may be used freely by anybody who feels like it. peo, 2 May 1994