home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 5 Edit / 05-Edit.zip / vipf.zip / inf02a.doc next >
Text File  |  1994-02-21  |  20KB  |  466 lines
  1.   OS/2 2.0 Information Presentation Facility (IPF) Data Format - version 2
  2.   ----------------------------------------------------------------------- -
  3.   
  4.   *** introduction to version 1 ***
  5.  
  6.   Having become extremely frustrated by VIEW.EXE's penchant for windows
  7.   that come and go, without even opening large enough to see everything
  8.   in them, I thought I'd try to turn .INF files into something more
  9.   conventional.  While I don't have code to offer, I can tell you what I
  10.   learned about .INF format--it was enough to produce more-or-less
  11.   readable more-or-less plaintext from .INFs.
  12.   
  13.   I offer this in the hope that somebody will give the community a
  14.   really nice, tasteful, convenient, doesn't-use-too-much-screen-real-estate 
  15.   .INF browser to replace VIEW.EXE.
  16.   
  17.   All of this was developed by looking at .INF files without any
  18.   documentation of the format except what VIEW.EXE showed for a
  19.   particular feature.
  20.  
  21.   I don't have a lot of personal interest in refining this document with
  22.   additional escape sequences, etc., but I would be happy to correspond
  23.   with someone who wanted to fill in the details, or to clarify anything
  24.   that may be confusing.  If someone could point us to an official document
  25.   describing the format that would be most helpful.
  26.  
  27.   -- Carl Hauser (chauser.parc@xerox.com)
  28.  
  29.  
  30.   *** introduction to version 2 ***
  31.  
  32.   The original document contained most of the real tricky stuff in the file
  33.   format (especially the compression algorithm) so going on from there was
  34.   mainly a task of creating lots of help files using the IPFC and the
  35.   decompiling them again to see what came out.
  36.  
  37.   I fixed a few minor bugs in the description of the header which was
  38.   extended to describe the entire structure I believe to be the header
  39.   (because variable data starts afterwards).
  40.  
  41.   A number of escape codes have also been added and the descriptions of
  42.   others have been refined. There are still a lot of question marks about
  43.   the format, but this description already allows disassembling the text
  44.   into ASCII form in a fairly true-to-life format (including indentations
  45.   etc.).
  46.  
  47.   Further research should go into the way multiple windows are handled
  48.   (I didn't work on that because I have never required multiple window
  49.   displays in my help files and therefore am not familiar with the concepts).
  50.   Font usage and graphics linking could also use some more fiddling around.
  51.  
  52.   -- Marcus Groeber (marcusg@ph-cip.uni-koeln.de - Fidonet 2:243/8605.1)
  53.  
  54.  
  55.   **** Types ****
  56.  
  57.      All numeric quantities are least-significant-byte first in the file
  58.      (little-endian).
  59.   
  60.      bit1       1 bit boolean           \  used only for explaining
  61.      int4       4 bit unsigned integer  /  packed structures
  62.      char8      8 bit character (ASCII more-or-less)
  63.      int8       8 bit unsigned integer
  64.      int16      16 bit unsigned integer
  65.      int32      32 bit unsigned integer 
  66.      
  67.   **** The File Header ****
  68.   
  69.       Starting at file offset 0 the following structure can overlay the file
  70.       to provide some starting values:
  71.           {
  72.             int16 ID;           // ID magic word (5348h = "HS")
  73.             int8  unknown1;     // unknown purpose, could be third letter of ID
  74.             int8  flags;        // probably a flag word...
  75.                                 //  bit 0: set if INF style file
  76.                                 //  bit 4: set if HLP style file
  77.                                 // patching this byte allows reading HLP files
  78.                                 // using the VIEW command, while help files 
  79.                                 // seem to work with INF settings here as well.
  80.             int16 hdrsize;      // total size of header
  81.             int16 unknown2;     // unknown purpose
  82.             int16 ntoc;         // 16 bit number of entries in the tocarray
  83.             int32 tocstrtablestart;  // 32 bit file offset of the start of the
  84.                                      // strings for the table-of-contents
  85.             int32 tocstrlen;    // number of bytes in file occupied by the
  86.                                 // table-of-contents strings
  87.             int32 tocstart;     // 32 bit file offset of the start of tocarray
  88.             int16 nres;         // number of panels with ressource numbers
  89.             int32 resstart;     // 32 bit file offset of ressource number table
  90.             int16 nname;        // number of panels with textual name
  91.             int32 namestart;    // 32 bit file offset to panel name table
  92.             int16 nindex;       // number of index entries
  93.             int32 indexstart;   // 32 bit file offset to index table
  94.             int32 indexlen;     // size of index table
  95.             int8  unknown3[10]; // unknown purpose
  96.             int32 searchstart;  // 32 bit file offset of full text search table
  97.             int32 searchlen;    // size of full text search table
  98.             int16 nslots;       // number of "slots"
  99.             int32 slotsstart;   // file offset of the slots array
  100.             int32 dictlen;      // number of bytes occupied by the "dictionary"
  101.             int16 ndict;        // number of entries in the dictionary
  102.             int32 dictstart;    // file offset of the start of the dictionary
  103.             int32 imgstart;     // file offset of image data
  104.             int8  unknown4;     // unknown purpose
  105.             int32 nlsstart;     // 32 bit file offset of NLS table
  106.             int32 nlslen;       // size of NLS table
  107.             int32 extstart;     // 32 bit file offset of extended data block
  108.             int8  unknown5[12]; // unknown purpose
  109.             char8 title[48];    // ASCII title of database
  110.           }
  111.     
  112.   **** The table of contents array ****
  113.   
  114.       Beginning at file offset tocstart, this structure can overlay the
  115.       file:
  116.           {
  117.              int32  tocentrystart[ntoc];       // array of file offsets of
  118.                                                // tocentries
  119.           }
  120.   
  121.   **** The table of contents entries ****
  122.   
  123.       Beginning at each file offset, tocentrystart[i]:
  124.           {
  125.              int8 len;          // length of the entry including this byte
  126.              int8 flags;        // flag byte, description folows (MSB first)
  127.              // bit1 haschildren;  // following nodes are a higher level
  128.              // bit1 hidden;       // this entry doesn't appear in VIEW.EXE's
  129.                                    // presentation of the toc
  130.              // bit1 extended;     // extended entry format
  131.              // bit1 stuff;        // ??
  132.              // int4 level;        // nesting level
  133.              int8 ntocslots;    // number of "slots" occupied by the text for
  134.                                 // this toc entry
  135.           }
  136.  
  137.       if the "extended" bit is not 1, this is immediately followed by 
  138.  
  139.           {
  140.              int16 tocslots[ntocslots]; // indices of the slots that make up
  141.                                         // the article for this entry
  142.              char8 title[];             // the remainder of the tocentry
  143.                                         // until len bytes have been used [not
  144.                                         // zero terminated]
  145.           }
  146.  
  147.       if extended is 1 there are intervening bytes that (I think) describe
  148.       the kind, size and position of the window in which to display the
  149.       article.  I haven't decoded these bytes, though in most cases the
  150.       following tells how many there are.  Overlay the following on the next
  151.       two bytes
  152.           { 
  153.              int8 w1;
  154.              int8 w2;
  155.           }
  156.       Here's a C code fragment for computing the number of bytes to skip
  157.           int bytestoskip = 0; 
  158.           if (w1 & 0x8) { bytestoskip += 2 };
  159.           if (w1 & 0x1) { bytestoskip += 5 };
  160.           if (w1 & 0x2) { bytestoskip += 5 };
  161.           if (w2 & 0x4) { bytestoskip += 2 };
  162.  
  163.       skip over bytestoskip bytes (after w2) and find the tocslots and title
  164.       as in the non-extended case.
  165.   
  166.   **** The Slots array ****
  167.   
  168.       Beginning at file offset slotsstart (provided by the file header) find
  169.           {
  170.              int32 slots[nslots];       // file offset of the article
  171.                                         // corresponding  to this slot
  172.           }
  173.   
  174.   **** The Dictionary ****
  175.   
  176.       Beginning at  file offset dictstart (provided by the file header) and
  177.       continuing until ndict entries have been read (and dictlen bytes have
  178.       been consumed from the file) find a sequence of length-preceeded
  179.       strings.  Note that the length includes the length byte (not Pascal
  180.       compatible!).  Build a table mapping i to the ith string.
  181.           {
  182.              char8*     strings[ndict];
  183.           }
  184.   
  185.   **** The Article entries ****
  186.   
  187.       Beginning at file offset slots[i] the following structure can overlay
  188.       the file:
  189.           {
  190.              int8       stuff;          // ?? [always seen 0]
  191.              int32      localdictpos;   // file offset of the local dictionary
  192.              int8       nlocaldict;     // number of entries in the local dict
  193.              int16      ntext;          // number of bytes in the text
  194.              int8       text[ntext];    // encoded text of the article
  195.           }
  196.  
  197.   **** The Local dictionary ****
  198.  
  199.       Beginning at file position localdictpos (for each article) there is an
  200.       array:
  201.           {
  202.              int16      localwords[nlocaldict];
  203.           }
  204.   
  205.   **** The Text ****
  206.   
  207.       The text for an article then consists of words obtained by referencing
  208.       strings[localwords[text[i]]] for i in (0..ntext), with the following
  209.       exceptions.  If text[i] is greater than nlocaldict it means
  210.  
  211.          0xfa => end-of-paragraph, sets spacing to TRUE
  212.          0xfb => [unknown]
  213.          0xfc => spacing = !spacing 
  214.          0xfd => line break (outside an example: ".br",
  215.                    sets spacing to TRUE if not in a
  216.                    monospace example)
  217.          0xfe => space
  218.          0xff => escape sequence                        // see below
  219.          
  220.       When spacing is true, each word needs a space put after it.  When
  221.       false, the words are abutted and spaces are supplied using 0xfe or the
  222.       dictionary.  Examples are entered and left with 0xff escape sequences.  
  223.       The variable "spacing" is initially (start of every article slot) TRUE.
  224.  
  225.   **** 0xff escape sequences ****
  226.  
  227.       These are used to change fonts, make cross references, enter and leave
  228.       examples, etc.  The general format is
  229.           {
  230.              int8       FF;             // always equals 0xff
  231.              int8       esclen;         // length of the sequence (including
  232.                                         // esclen but excluding FF)
  233.              int8       escCode;        // which escape function
  234.           }
  235.  
  236.      escCodes I have partially deciphered are
  237.  
  238.           0x01 =>               unknown
  239.     
  240.           0x02 or 0x11 =>       (esclen==3) set left margin.
  241.                or 0x12          0x11 always starts a new line. Arguments
  242.                                   {
  243.                                      int8  margin;   // in spaces, 0=no margin
  244.                                   }
  245.                                 note: in an IPF source, you must code
  246.                                 :lm margin=256. to reset the left margin.
  247.  
  248.           0x03 =>               (esclen==3) set right margin. Arguments
  249.                                   {
  250.                                      int8  margin;   // in spaces, 1=no margin
  251.                                   }
  252.  
  253.           0x04 =>               (esclen==3) change style. Arguments
  254.                                   {
  255.                                      int8  style;    // 1,2,3: same as :hp#.
  256.                                                      // 4,5,6: same as :hp5,6,7.
  257.                                                      // 0 returns to plain text
  258.                                   }
  259.         
  260.           0x05 =>               (esclen varies) beginning of cross
  261.                                 reference.  The next two bytes of the
  262.                                 escape sequence are an int16 index of
  263.                                 the tocentrystart array.  The
  264.                                 remaining bytes describe the size,
  265.                                 position and characteristics of the
  266.                                 window created when the
  267.                                 cross-reference is followed by VIEW.
  268.                                 I have not decoded this.
  269.  
  270.           0x06 =>               unknown
  271.  
  272.           0x07 =>               (esclen==4) footnote (:fn. tag). Arguments:
  273.                                   {
  274.                                      int16  toc;  // toc entry number of text
  275.                                   }
  276.  
  277.           0x08 =>               (escLen==2) end of cross reference
  278.                                 introduced by escape code 0x05 or 0x07
  279.  
  280.           0x09 =>               unknown
  281.  
  282.           0x0A =>               unknown
  283.         
  284.           0x0B =>               (escLen==2) begin monosp. example.  set
  285.                                 spacing to FALSE
  286.           
  287.           0x0C =>               (escLen==2) end monosp. example.  set
  288.                                 spacing to TRUE
  289.  
  290.           0x0D =>               (escLen==2) special text colors. Arguments:
  291.                                   {
  292.                                      int8  color;   // 1,2,3: same as :hp4,8,9.
  293.                                                     // 0: default color
  294.                                   }
  295.  
  296.           0x0E =>               [bitmap]
  297.           
  298.           0x0F =>               if esclen==5 an inlined cross
  299.                                 reference: the title of the referenced
  300.                                 article becomes part of the text.
  301.                                 This is probably the case even if
  302.                                 esclen is not 5, but I don't know the
  303.                                 decoding.  In the case that esclen is
  304.                                 5, I don't know the purpose of the
  305.                                 byte following the escCode, but the
  306.                                 two bytes after that are an int16
  307.                                 index of the tocentrystart array.
  308.  
  309.           0x10 =>               [special link, reftype=launch]
  310.  
  311.           0x13 or 0x14 =>       (esclen==2) Set foreground (0x13)
  312.                                 and background (0x14) color.  Arguments:
  313.                                   {
  314.                                      int8  color;   
  315.                                   }
  316.  
  317.           0x15 =>               unknown
  318.  
  319.           0x16 =>               [special link, reftype=inform]
  320.  
  321.           0x17 =>               hide text (:hide. tag). Arguments:
  322.                                   {
  323.                                      char8 key[];  // key required to show text
  324.                                   }
  325.  
  326.           0x18 =>               end of hidden text (:ehide.)
  327.  
  328.           0x19 =>               (esclen==3) change font?  I haven't
  329.                                 checked VIEW's decoding of the next
  330.                                 byte.  I used the same decoding as for
  331.                                 0x04
  332.           
  333.           0x1A =>               (escLen==3) begin :lines. sequence.  set
  334.                                 spacing to FALSE.  Arguments
  335.                                   {
  336.                                      int8  alignment; // 1,2,4=left,right,center
  337.                                   }
  338.           
  339.           0x1B =>               (escLen==2) end :lines. sequence.  set
  340.                                 spacing to TRUE
  341.  
  342.           0x1C =>               (escLen==2) Set left margin to current 
  343.                                 position.  Margin is reset at end of
  344.                                 paragraph.
  345.  
  346.           0x1F =>               [special link, reftype=hd database=...]
  347.  
  348.           0x20 =>               (esclen==4) :ddf. tag. Arguments:
  349.                                   {
  350.                                      int16  res;  // value of res attribute
  351.                                   }
  352.       
  353.       The font used in the text is the normal IBM extended character set,
  354.       including line graphics and some of the characters below 32.
  355.  
  356.   **** The ressource number array ****
  357.  
  358.       Beginning at file offset resstart, this structure can overlay the
  359.       file:
  360.           {
  361.               int16  res[nres];         // ressource number of panels
  362.               int16  toc[nres];         // toc entry number of panel
  363.           }
  364.   
  365.   **** The text name array ****
  366.   
  367.       Beginning at file offset namestart, this structure can overlay the
  368.       file:
  369.           {
  370.               int16  name[nres];        // index to panel name in dictionary
  371.               int16  toc[nres];         // toc entry number of panel
  372.           }
  373.  
  374.   **** The index table ****
  375.  
  376.       Beginning at file offset indexstart, a structure like the following
  377.       is stored for each of the nindex words (in alphabetical order).
  378.           {
  379.               int8  nword;              // size of name
  380.               int8  level;              // indent level
  381.                                         // bit 6 set: global entry
  382.               int8  stuff;
  383.               int16 toc;                // toc entry number of panel
  384.               char8 word[nword];        // index word [not zero-terminated]
  385.           }
  386.  
  387.   **** The extended data block ****
  388.  
  389.       Not yet decoded.  This block has a size of 64 bytes and contains various
  390.       pointers to font names, names of externel databases etc.
  391.                           
  392.   **** The full text search table ****
  393.  
  394.       Not yet decoded.  This table is supressed when "/S" is specified on
  395.       the IPFC command line.
  396.  
  397.   **** Image data ****
  398.  
  399.       Not yet decoded. This area contains data for graphics contained in the
  400.       text.
  401.  
  402.   **** NLS table ****
  403.  
  404.       Not yet decoded. This table contains informations specific to the
  405.       language and codepage the document was prepared in. It seems to contain
  406.       some bitfields as well that might be used for character classification.
  407.       
  408. Appendix 1: Some useful translations from IBM Extended ASCII to normal ASCII
  409.  
  410.       One other transformation I had to make was of the character box
  411.       characters of the IBM extended ASCII set.  These characters appear in strings 
  412.       in the dicitonary.  They are given here in octal together with their translation.
  413.       
  414.       020, 021    => blank seems satisfactory
  415.       037         => solid down arrow: used to give direction to
  416.                 a line in the syntax diagrams
  417.       0263         => vertical bar
  418.       0264         => left connector: vertical bar with short
  419.                 horizontal bar extending left from the
  420.                 center
  421.       0277, 0300     => top right or bottom left corner; one is
  422.                 one, the other is the other and I
  423.                 can't tell which from my translation
  424.       0301         => up connector: horizontal line with vertical
  425.                 line extending up from the center
  426.       0302         => down connector: horizontal line with
  427.                 vertical line extending down from the
  428.                 center
  429.       0303         => right connector: vertical bar with short
  430.                 horizontal bar extending right from
  431.                 the center
  432.       0304         => horizontal bar
  433.       0305         => cross connector, i.e. looks like + only
  434.                 slightly larger to connect with
  435.                 adjacent chars
  436.       0331, 0332     => top left or bottom right corner; one is
  437.                 one, the other is the other and I
  438.                 can't tell which from my translation
  439.                 
  440.  
  441. Appendix 2:  Style codes for escCode 0x04 and 0x0D
  442.  
  443.       escCode 0x04 implements font changes associated with the :hp# IPF source tag.  
  444.  
  445.           :hp1 is italic font
  446.           :hp2 is bold font
  447.           :hp3 is bold italic font
  448.           :hp5 is normal underlined font
  449.           :hp6 is italic underlined font
  450.           :hp7 is bold underlined font
  451.  
  452.      tags :hp4, :hp8, and :hp9 introduce different colored text which is encoded in
  453.      the .inf or .hlp file using escCode 0x0D.  On my monitor normal text is dark blue.
  454.      
  455.           :hp4 text is light blue
  456.           :hp8 text is red
  457.           :hp9 text is magenta
  458.  
  459.  
  460.  
  461. History:
  462. October 22, 1992: version for initial posting (inf01.doc)
  463. July 12, 1993: second version (refer to introduction for changes) (inf02.doc)
  464. July 18, 1993: added appendices to the second version (inf02a.doc)
  465.  
  466.