home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 5 Edit / 05-Edit.zip / vipf.zip / readme.txt < prev    next >
Text File  |  1994-05-03  |  10KB  |  225 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.                                      V I P F
  9.  
  10.                          A text-mode .INF viewer for OS/2
  11.                            (c)1994 by red point systems
  12.  
  13.  
  14.  
  15.  
  16.  
  17.        ====  What Is It?
  18.  
  19.  
  20.        VIPF  is a text-mode  replacement for VIEW.EXE, the  IPF file (.INF
  21.        and  .HLP) viewer supplied with OS/2.  It was written primarily for
  22.        use on  my ThinkPad 300 running OS/2 2.1 without  PM that I do some
  23.        of my  development on (I use CSHELL from IBM's  EWS stuff as a ses-
  24.        sion  manager). Since I often just read  around in such files, VIPF
  25.        reads the whole  file when started so that the harddisk can be shut
  26.        down afterwards to conserve battery power and reduce noise.
  27.  
  28.        To  decode  the IPF  files,  I  relied on  the  information  in the
  29.        INF02A.DOC file  enclosed with this program. As this information is
  30.        not  complete, neither is VIPF. Most  prominently, it fails for hy-
  31.        pertext  links  across  multiple files.  Single  file  documents it
  32.        should work  nicely though, except for some style controls that are
  33.        ignored.  Amongst the files  I tested  VIPF with are  CMDREF, REXX,
  34.        VREXX,  PRCP (16-bit core  call documentation),  GUIREF20 (same for
  35.        32-bit core calls) and LATEX. These work fine.
  36.  
  37.  
  38.  
  39.        ====  How Do I Use It?
  40.  
  41.  
  42.        Starting VIPF
  43.  
  44.        To  start VIPF on  an IPF file (.INF  or .HLP), pass  the full name
  45.        (including  the extension!)  of the  file as  an argument  to VIPF.
  46.        VIPF shows what it reads and then displays the table of contents.
  47.  
  48.        Cursor Control, Help, And Exiting
  49.  
  50.        All  the views presented  by VIPF are controlled  alike. The cursor
  51.        can  be moved around  freely on  the whole screen  using the normal
  52.        cursor control keys. In particular:
  53.  
  54.            Arrows          Move cursor
  55.            PgUp/Dn         Move pagewise
  56.            Ctrl-PgUp/Down  Move to start/end of document
  57.            Home/End        Move to start/end of line
  58.  
  59.        Pressing  ? shows a  short help screen that  describes all the main
  60.        keys. Some keys may  not work in some views though. To leave a view
  61.        press  ESCAPE. Leaving  the  table of  contents ends  VIPF (without
  62.        confirmation!).
  63.  
  64.        The Table Of Contents
  65.  
  66.        This is the  main display of VIPF. It lists all the directly avail-
  67.        able  topics in  the file.  As in  VIEW, subheadings can  be folded
  68.        away  under their main headings. To  indicate this, a leading " + "
  69.        marks headings  with hidden subheadings, while " - " marks unfolded
  70.        headings.  To fold or  unfold the  subheadings of a  heading, press
  71.        SPACE  on the main heading.  To view the text  for a particular to-
  72.        pic, press  RETURN on it. This brings up the  text of the topic. To
  73.        see the index, press I.
  74.  
  75.        The Text Viewer
  76.  
  77.        This  displays the  text of  the currently chosen  topic. Hypertext
  78.        links  are inverted.  To follow  such a  link, position  the cursor
  79.        over  it and press RETURN.  The text viewer keeps  a history of the
  80.        last 20 or  so topics viewed. Exiting a text with ESCAPE returns to
  81.        the previous  text or, if there was none,  the table of contents or
  82.        the index, whichever it was chosen from.
  83.            Some  topics have automatic  links embedded  within them. These
  84.        links  are automatically followed  when the topic  is shown. There-
  85.        fore, you initially do  not see the main topic, but the last of the
  86.        automatically  linked topics. To return  to the previous automatic-
  87.        ally  linked topics, and finally the  main topic, press ESCAPE (the
  88.        normal history of viewed topics is used).
  89.  
  90.        The Index
  91.  
  92.        This displays  the index of the IPF file. It  is very much like the
  93.        table of  contents, except that it cannot fold subentries. To disp-
  94.        lay the  text for an entry, press RETURN over  it. To return to the
  95.        table of contents, press ESCAPE.
  96.  
  97.        Searching
  98.  
  99.        To search for  some text in the current view, you must first define
  100.        the search  text. To do this, press S and  enter the search text at
  101.        the  prompt popping  up. Then,  pressing F repeatedly  searches for
  102.        the  next occurrence of  the text starting at  the cursor position.
  103.        The  search text is  the same for  all views and  is preserved when
  104.        views are changed.
  105.  
  106.        NOTE:  In the table  of contents, hidden subheadings  are NOT sear-
  107.        ched. Unfold the main headings first, or search the index.
  108.  
  109.  
  110.  
  111.        ====  About The Source Code
  112.  
  113.  
  114.        VIPF  was written in Modula-2 and  compiled using Clarion's (former
  115.        JPI's)  TopSpeed Modula-2 compiler  version 3.10.  This compiler at
  116.        present  produces only 16-bit  code, so  VIPF is a  16-bit applica-
  117.        tion. It probably runs on OS/2 1.0 too...
  118.            I  do not expect  many people  to be using  Modula-2 to program
  119.        OS/2 and therefore  do not supply the whole source code. I do, how-
  120.        ever,  supply the  crucial modules,  which are outlined  below. For
  121.        those  not familiar with  Modula-2, the language is  very much like
  122.        Pascal  (it  is in  fact its  successor).  The .DEF  files  are the
  123.        interfaces  of the modules  (program parts) and the  .MOD files are
  124.        the implementations.
  125.  
  126.        Module VIPF
  127.  
  128.        VIPF.MOD  is the main  module (the main program).  It simply checks
  129.        the  command line and  then calls  the IPF file  loader and finally
  130.        the viewer.
  131.  
  132.        Module IPF
  133.  
  134.        IPF.DEF  and IPF.MOD define the module that  reads the IPF file and
  135.        exports  it in convenient  structures. Note that all  of the arrays
  136.        are  allocated and sized dynamically.  The terminology closely fol-
  137.        lows that used in the INF02A.DOC documentation file.
  138.  
  139.        Module IPFView
  140.  
  141.        IPFView.DEF  and IPFView.MOD  define the  module that  displays the
  142.        different views  of the data exported by IPF. The first section de-
  143.        fines a  general browser with hooks for line display and processing
  144.        of keys  pressed by the user. Then, the hooks for the table-of-con-
  145.        tents and the index browser follow. They are straightforward.
  146.            Now comes  the tricky part. The  procedure BuildLines formats a
  147.        topic for display.  It builds it up line by line doing word-wrap on
  148.        the way.  The displayable text is stored in  an array of line poin-
  149.        ters. The  hypertext links are stored in another array giving their
  150.        starting  and  ending  offsets within  the  original  encoded text.
  151.        Another  array stores the  offsets of  the starts of  the formatted
  152.        lines to  associate links with lines. Finally, a variable AutoStart
  153.        gives the  index of the first link that must be followed automatic-
  154.        ally (this  assumes that such links are consecutive and the last in
  155.        the  document--up to now, it worked). If  the decoding VIPF does is
  156.        wrong,  this is the  place to  look at (in  particular, the central
  157.        case statement on escape sequences).
  158.            Finally, the  text browser hooks are defined. There are two not
  159.        entirely  trivial ones, the first being  the line display hook that
  160.        must  correctly invert the  links it finds on  the line. The second
  161.        is  the main text  browser loop that  takes care of  the history of
  162.        viewed texts and links that must be followed automatically.
  163.  
  164.        Module IPFDump
  165.  
  166.        IPFDump.DEF  and IPFDump.MOD are not really  part of VIPF. They de-
  167.        fine  a module that  displays a dump  of the decoding  of a topic's
  168.        text  for debugging  purposes. I  have included  it for  people who
  169.        want  to do some  of their own decoding.  (Hint: links across files
  170.        would  be nice,  though supporting  them would  change much  of the
  171.        data structures...)
  172.  
  173.        Modules Not Supplied
  174.  
  175.        As  mentioned before,  the run-time  modules are not  supplied. The
  176.        ones  I used are the windowing  library supplied with the compiler,
  177.        the basic console  i/o library, and two of our own modules for disk
  178.        i/o  and  error handling  (rarely used  here).  I believe  the code
  179.        should be easy to understand all the same.
  180.  
  181.  
  182.  
  183.        ====  "Thank You" And "Please Thank Me"
  184.  
  185.  
  186.        Many  thanks  to Carl  Hauser  and Marcus  Groeber  for INF02A.DOC.
  187.        Carl,  maybe  you will  like this  here  tool of  mine  better than
  188.        VIEW.EXE, though it's not so complete.
  189.  
  190.        Those of  you who feel grateful, please just  send me a postcard or
  191.        a note  to cheer me up a little on a  rainy day. The postal address
  192.        is:
  193.  
  194.            Peter Arrenbrecht
  195.            Im Kratten 32
  196.            8623 Wetzikon ZH
  197.            SWITZERLAND
  198.  
  199.        Unfortunately,  I don't yet have an  e-mail address. You might soon
  200.        want to try
  201.  
  202.            parrenbr@unizh.ch
  203.  
  204.        though.
  205.  
  206.        If you  change VIPF, or port it to C  or some other such nightmare,
  207.        please  let me know.  Also, I'd  be interested if  someone else has
  208.        more information on  the decoding of IPF files (hey, IBM, this is a
  209.        hint for your next Developers' Connection edition).
  210.  
  211.  
  212.  
  213.        ====  The Legal Stuff
  214.  
  215.  
  216.        As  usual, I do  not accept  any responsibility whatsoever  for the
  217.        effects  of anything to  do with VIPF.EXE  that I don't  have to by
  218.        the requirements of the law.
  219.  
  220.        The  program VIPF.EXE and  the publicized  source code accompanying
  221.        it  are hereby placed in  the public domain and  may be used freely
  222.        by anybody who feels like it.
  223.  
  224.                                                            peo, 2 May 1994
  225.