home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / inf2qh.zip / INF2QH.DOC next >
Text File  |  1995-04-27  |  15KB  |  471 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.      Inf2Qh -- Convert IBM OS/2 *.INF files to Microsoft Quickhelp files
  11.  
  12.  
  13.                         Copyright (C) 1995 A:WARE Inc.
  14.  
  15.   Use  of  this  program requires HelpMake.exe (OS/2 version 1.05 was used)
  16.   and QH.EXE (version 1.8 was used).
  17.  
  18.   [QuickStart - skip ahead to the section called "Running Inf2Qh" on p4]
  19.  
  20.  
  21.   1.1  What is QuickHelp?
  22.  
  23.  
  24.   Long  time  OS/2  programmers (from the 1.x days),  like myself, may have
  25.   become  addicted to a program called QuickHelp  (qh.exe).    This  little
  26.   program is run as a keyboard monitor ("detach qh") and is  available from
  27.   all full-screen OS/2 sessions when you hit ALT-Q.
  28.  
  29.   For several years,  all  Microsoft operating system and language products
  30.   used the QuickHelp format for their  on-line  help.  Most of them shipped
  31.   with HELPMAKE (the QuickHelp  compiler).   Some of the products that come
  32.   to mind are:
  33.  
  34.        MS OS/2 Toolkit 1.2
  35.        MS C 6.0a
  36.        MS PDS Basic
  37.        MS QuickC
  38.  
  39.   Even OS/2 Warp 3.0 has at least one file in this format:
  40.  
  41.        \os2\mdos\qbasic.hlp
  42.  
  43.   Microsoft  did  a  FANTASTIC  job  with  the  OS/2 API  QuickHelp  files.
  44.   Unfortunately, they are for OS/2 1.x.  They were so well done I still use
  45.   them today,  even when I am programming for OS/2 2.0.
  46.  
  47.  
  48.   1.2  About Inf2Qh
  49.  
  50.  
  51.   This program is a generic *.INF to *.QH converter.   After the conversion
  52.   is complete,   you must compile the *.QH file into an *.HLP file with the
  53.   HelpMake program.
  54.  
  55.   Obviously,    since  QH is a text-mode program,  things  like  fonts  and
  56.   bitmaps are not  converted;    but  I  think you'll be impressed with the
  57.   level of sameness achieved with the original *.INF file.
  58.  
  59.  
  60.  
  61.   As mentioned,  this is a generic *.INF to *.QH converter --- if you don't
  62.   like the way the information is arranged in the original *.INF file, this
  63.   program is  not  going  to  help  you  ---  with  a  few  exceptions (see
  64.   Formatting Exceptions, below)
  65.  
  66.  
  67.   1.3  Implementation Problems
  68.  
  69.  
  70.   The INF "Table of Contents",    with  its  collapsible  trees,    was not
  71.   reproducible. The way I handled this was to create list topics (the .list
  72.   command in QH syntax) with names  like  "+Notices".  When you select this
  73.   topic,   it clears the screen and shows the sub-topics for that topic. It
  74.   was the best I could  do.   To get back up to the previous heading-level,
  75.   press 'T' in QH.
  76.  
  77.   If you specify the /t option (include Title),  the  commands  to add your
  78.   help file to the QH "Categories" menu will be created;  note that you can
  79.   only have a limited number of categories (about 23) in  this  menu, and I
  80.   had no trouble at all using them all up. To alleviate this somewhat,  you
  81.   can use the  "File | All Tables of Contents" command to get access to the
  82.   files not in the Categories menu.
  83.  
  84.   Many INF topic titles are too long for the QH '.list' command, which only
  85.   looks  at  the first 50 characters on the line.  The  IOCTLS  section  in
  86.   \toolkit\book\cp3.inf is a good example of this problem.   The  only  way
  87.   around this is to get to the topic using a hyper-link,  or by selecting a
  88.   topic on either  side of it and using the view Next and Back functions to
  89.   get to it.
  90.  
  91.   Another problem with .lists's is that if they encounter a double space on
  92.   the line,   they  treat it as a delimiter and search for a topic based on
  93.   everything before the double space.  For example,    when  you  hit ENTER
  94.   from a list on the line:  "XCOPY  - Copy Subdirectories",  QH will try to
  95.   find a topic named "XCOPY".  Since there is no topic by this name, you'll
  96.   get an error (see the  /c  command,    in  Formatting  Exceptions,  for a
  97.   possible work around).
  98.  
  99.   When compiling the converted file,   you  may receive a few messages like
  100.   this:
  101.  
  102.           System Exceptions
  103.        error H2001: duplicate context string
  104.  
  105.   There was no way to avoid  this.   Explicit hyper-links to the duplicated
  106.   topics will work as intended;  but implicit searches will find which ever
  107.   one is closer (use the 'E'  (continue  search) command,  to cycle through
  108.   the other topics with the same name).
  109.  
  110.   Inf2Qh performs paragraph wrapping,  so that the QH right margin  (76) is
  111.   honoured.  However,  wrapping is turned off while decoding  an "example",
  112.   and a few other INF formats  that  require  that nothing be changed.  For
  113.   this reason,  you may see a few "Line too long" errors from HELPMAKE.
  114.  
  115.  
  116.  
  117.                                     - 2 -
  118.  
  119.  
  120.   IPF "footnotes" are converted into QH ".popup",  unless  they  exceed  21
  121.   lines, in which case they are placed in a new topic.
  122.  
  123.   Explicit  references  to  external  help  files  are  not supported  (for
  124.   example, when CP1.INF has a hyperlink  to  something in CP2.INF, I do not
  125.   create an explicit link -- I simply change the text to BOLD).
  126.  
  127.   The converter will never cause anything to be placed in  the "References"
  128.   menu.
  129.  
  130.  
  131.   1.4  Formatting Exceptions
  132.  
  133.  
  134.   There are some obvious *.INF files  people  are going to want to convert,
  135.   that I have built in a few options for:
  136.  
  137.  
  138.   1.4.1  Option /c -- Command Reference Mode.
  139.  
  140.        This option was created for  \OS2\BOOK\CMDREF.INF,  but can apply to
  141.        others.
  142.  
  143.   In this mode,  all topics with a " -"  are  forced  to  have  "   -" (two
  144.   spaces),  and an alias topic name is set up for everything preceeding the
  145.   "   -".  This alleviates the problem,  described above,  for topics  with
  146.   names like "XCOPY  - Copy Subdirectories".
  147.  
  148.   It also  allows  you  to  search for the commands just by their name (ex:
  149.   COPY, BACKUP, etc),  which is, of course,    what  you  really want to do
  150.   with the command reference,  right?
  151.  
  152.  
  153.  
  154.   1.4.2  Option /a -- AutoCollect mode.
  155.  
  156.        This option was created for any *.INF file that opens more  than one
  157.        window for a help topic.
  158.  
  159.   When the IPF "auto dependent" type of windows are encountered  (these are
  160.   the "Auto Open" variety;    for  example,   when you select DosOpen), the
  161.   converter will not  store  the  windows  as separate topics.  Instead, it
  162.   puts them all into one topic,  with sub-headings to separate them.
  163.  
  164.  
  165.  
  166.   1.4.3  Option /p -- Programmer's Reference mode.
  167.  
  168.        This    option    was   created   for    the    Warp    programmer's
  169.        \toolkit\book\*.inf files (cp*.inf, gpi*.inf, pm*.inf, others).
  170.  
  171.        This option automatically enables /a - Autocollect mode.
  172.  
  173.  
  174.  
  175.  
  176.                                     - 3 -
  177.  
  178.  
  179.   One of the common complaints I see from OS/2  programmers  about  VIEWing
  180.   the online OS/2 API *.INF references  is  that  a topic is split into too
  181.   many panels.  For example,   looking  up "DosOpen" opens up three windows
  182.   --  none of which are the really important ones.  What people tell me  is
  183.   that want it all on ONE panel, so they can just scroll around themselves.
  184.  
  185.   The /a (auto collect) option,   explained  above,   will take you part of
  186.   the way.  The /p option goes one step further --   if  one  of  the "Auto
  187.   Open" panels has "Topics -" in its title,  the converter throws away that
  188.   panel,  but automatically sucks in all of the topics that were referenced
  189.   by  it.   For example,  without /p or /a,  DosBeep would have  EIGHT  (!)
  190.   panels:
  191.  
  192.           1) DosBeep
  193.           2) Syntax - DosBeep
  194.           3) Parameter - freq
  195.           4) Parameter - dur
  196.           5) Return Value - ulrc
  197.           6) Related Functions - DosBeep
  198.           7) Example Code - DosBeep
  199.           8) Topics - DosBeep
  200.  
  201.   With  /p,   this will be turned into one topic under  the  name  DosBeep,
  202.   except for panels they  were  originally defined by IPF as footnotes (the
  203.   "Parameter -" panels) -- they become popup windows.
  204.  
  205.   Since this option removes so many topics (for example:  "Return  Value  -
  206.   ulrc"), it also eliminates many "duplicate topic" errors.
  207.  
  208.   Note: The /p option causes a big organizational improvement for  the OS/2
  209.   programmer, but it is still not as good as the MS OS/2 1.x QH references.
  210.   Doing a job that good is  not  for  this "generic converter";  the topics
  211.   need to be parsed, diced,  reformatted, rearranged,   renamed,  and  have
  212.   better  .list support.   I may release another program to do this in  the
  213.   future;  but not any time soon.
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.                                     - 4 -
  236.  
  237.  
  238.   1.5  Running Inf2Qh
  239.  
  240.  
  241.   If you run Inf2Qh.exe without any parameters,   you  will  get  the usage
  242.   box:
  243.  
  244.  
  245.   █▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀█
  246.   █ Inf2QH    (Convert *.INF to QuickHelp)          95/04/19 █
  247.   █                                             Version 1.99 █
  248.   █                                     by Peter Fitzsimmons █
  249.   █                                                          █
  250.   █ Usage:    inf2qh <input.inf> [title] [options]           █
  251.   █ Purpose:  Convert IPFC files to QuickHelp input files.   █
  252.   █ Options: /v - verbose                                    █
  253.   █          /d - debug                                      █
  254.   █          /a - "AutoCollect Mode"            (see docs)   █
  255.   █          /p - "Programmer's Reference Mode" (see docs)   █
  256.   █          /c - "OS/2 Command Reference Mode" (see docs)   █
  257.   █          /t - Include title for "Categories" menu        █
  258.   █                                                          █
  259.   █            Copyright (c) 1995,  A:WARE Inc.              █
  260.   █▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄█
  261.  
  262.   The  output  file  has  the  same name as the input file,  but  with  the
  263.   extension *.QH.  It will be placed in the current directory.
  264.  
  265.   [title]    is  optional.    It overrides the title contained in the *.INF
  266.              file.  NOTE: Some *.INF files  do  not  have a title;  in this
  267.              case,   Inf2Qh will use the file name of the *.INF file as the
  268.              title (if no title  was  specified  when starting Inf2Qh). For
  269.              more   information   on   the   [options],    see  "Formatting
  270.              Exceptions", earlier in this document.
  271.  
  272.   1.5.1  Example:
  273.  
  274.        Inf2Qh D:\TOOLKIT\BOOK\CP1.INF /p /t
  275.        Inf2Qh D:\TOOLKIT\BOOK\CP2.INF /p "CP Ref vol2"
  276.        Inf2Qh D:\TOOLKIT\BOOK\CP3.INF /p "CP Ref vol3"
  277.        Inf2Qh C:\OS2\BOOK\CMDREF.INF /c /t
  278.  
  279.        (I have discovered that CP1.INF has a title built-in,  and the other
  280.        two do not)
  281.  
  282.   This will create for files in the current dir:  CP1.QH,  CP2.QH,  CP3.QH,
  283.   CMDREF.QH. These files must now be compiled with the MS HelpMake program:
  284.  
  285.        HELPMAKE /W200 /T /E /Ocp1.hlp  cp1.qh
  286.        HELPMAKE /W200 /T /E /Ocp2.hlp  cp2.qh
  287.        HELPMAKE /W200 /T /E /Ocp3.hlp  cp3.qh
  288.        HELPMAKE /W200 /T /E /Ocmdref.hlp  cmdref.qh
  289.  
  290.        NOTE: This will take a while -- 10mins perhaps.  To speed it up, try
  291.        /E0 instead of /E;  this will turn off compression.
  292.  
  293.  
  294.                                     - 5 -
  295.  
  296.  
  297.   1.6  The $Price
  298.  
  299.  
  300.   I think this program  has  a small audience (albeit an appreciative one),
  301.   so I'm not charging anything for using this program at this time.
  302.  
  303.   I may, in the future (see next heading), use the same code base to create
  304.   a product worth selling.
  305.  
  306.   If you  feel  I  have  in some way significantly improved your life,  I'd
  307.   enjoy a thank-you note as remuneration (see the bottom of this file for a
  308.   way to contact me).
  309.  
  310.  
  311.   1.7  The Future
  312.  
  313.  
  314.   I spent more  than a week on this program (probably more like two) -- and
  315.   it turns out  the easy part was decoding the *.INF format.  The hard part
  316.   was  looking at the style that *.INF files were written,  and how to  get
  317.   QuickHelp to do the same thing.  This program is  a  lot more complicated
  318.   then it probably appears.  If I had known what I was getting into, rather
  319.   than  write  a  converter, I may have just written a native QH-like *.INF
  320.   reader.
  321.  
  322.   So there is not much of a future for this program.   What I am interested
  323.   in doing instead (these are not promises,  just ideas) are:
  324.  
  325.        1)    An  *.inf file printer.  A program  that  paginates  an  *.INF
  326.              file,  adds a Table of Contents and   Index  (both  with  page
  327.              numbers), and prints it out in PostScript format.
  328.  
  329.        2)    A native pop-up QH-Like *.inf viewer.
  330.  
  331.        3)    A specialized version of Inf2Qh for the Programmer's Reference
  332.              files (if I do #2,  I won't do this).
  333.  
  334.  
  335.   1.8  Acknowledgements
  336.  
  337.  
  338.   Carl Hauser -    first person that  I  am  aware  of to hack at the *.INF
  339.                    format.
  340.   Colin Thomson -  added to Carl's information.
  341.  
  342.  
  343.  
  344.  
  345.  
  346.  
  347.  
  348.  
  349.  
  350.  
  351.  
  352.  
  353.                                     - 6 -
  354.  
  355.  
  356.   1.9  Contact us for all your OS/2 development needs
  357.  
  358.  
  359.   Device Drivers,  File Systems, Applications,  we do them all. Contact:
  360.  
  361.   Peter Fitzsimmons,
  362.   President,
  363.   A:WARE Inc.
  364.   6056 Cayeswood Court
  365.   Mississauga Ontario
  366.   Canada L5V-1B1.
  367.  
  368.   Voice:  905 858 3222
  369.   Data :  905 858 8488 (BBS)
  370.  
  371.   Fidonet: 1:259/414
  372.   Internet: sol3@olc.gvc.com
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.  
  404.  
  405.  
  406.  
  407.  
  408.  
  409.  
  410.  
  411.  
  412.                                     - 7 -
  413.  
  414.  
  415.  
  416.  
  417.  
  418.  
  419.  
  420.  
  421.                                 Contents
  422.  
  423.  
  424.  
  425.        Chapter 1  Inf2Qh -- Convert IBM OS/2 *.INF files to Microsoft
  426.                   Quickhelp files                                    1
  427.           1.1  What is QuickHelp?  . . . . . . . . . . . . . . . . . 1
  428.           1.2  About Inf2Qh  . . . . . . . . . . . . . . . . . . . . 1
  429.           1.3  Implementation Problems . . . . . . . . . . . . . . . 2
  430.           1.4  Formatting Exceptions . . . . . . . . . . . . . . . . 3
  431.              1.4.1  Option /c -- Command Reference Mode. . . . . . . 3
  432.              1.4.2  Option /a -- AutoCollect mode. . . . . . . . . . 3
  433.              1.4.3  Option /p -- Programmer's Reference mode.  . . . 3
  434.           1.5  Running Inf2Qh  . . . . . . . . . . . . . . . . . . . 5
  435.              1.5.1  Example: . . . . . . . . . . . . . . . . . . . . 5
  436.           1.6  The $Price  . . . . . . . . . . . . . . . . . . . . . 6
  437.           1.7  The Future  . . . . . . . . . . . . . . . . . . . . . 6
  438.           1.8  Acknowledgements  . . . . . . . . . . . . . . . . . . 6
  439.           1.9  Contact us for all your OS/2 development needs  . . . 7
  440.  
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469.  
  470.  
  471.                                       i