






                                     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
