home *** CD-ROM | disk | FTP | other *** search
/ Simtel MSDOS - Coast to Coast / simteldosarchivecoasttocoast.iso / dv_x / dvxhlp10.zip / DVXHELP.DOC next >
Text File  |  1992-06-03  |  11KB  |  277 lines
  1.                       The DESQview/X Help File Format
  2.  
  3.                             By Daniel J. Bodoh
  4.  
  5.                      Copyright 1992 by Daniel J. Bodoh
  6.  
  7.         Permission is granted to copy this document free of charge in
  8.         whole or in part, as long as the copyright notice is included.
  9.  
  10. ----------------------------------------------------------------------------
  11. WARNING:  The help file format that I describe in here may not be 100%
  12. accurate.  QOS has not (yet) published the help file spec, so I figured it
  13. out for myself with a binary editor.  Use this information at your own risk!
  14. I cannot be held responsible for any damage caused by the use this
  15. information or the MDVXHELP program.  I AM NOT EMPLOYED BY QUARTERDECK,
  16. AND THIS IS NOT AN OFFICIAL QUARTERDECK DOCUMENT.
  17. ----------------------------------------------------------------------------
  18.  
  19. INTRODUCTION
  20. ------------
  21.  
  22. One of the enhancements offered by DESQview/X is its extensive online help.
  23. Quarterdeck supplies help files for the window manager, file manager, etc. in
  24. the /DVX/HELP directory.  Two programs are used to display the help files:
  25. /DVX/DISPHELP.EXE and /DVX/HELP/DVXHELP.EXE.  The help files are hypertext
  26. documents, which means that a help file can have cross references to other
  27. parts of the document to which the user can jump with the click of a mouse.
  28. The help files allow you to create bold, underlined and highlighted text; to
  29. indent paragraphs; and to include icons created by the DESQview/X icon
  30. editor.  The help file spec is very powerful, although I wish there were more
  31. text formatting options.  For example, I have not found a way to "TAB".
  32.  
  33.  
  34. DEFINITIONS
  35. -----------
  36.  
  37. Let's establish some definitions:
  38.  
  39.      CR             Carriage return, ASCII 13 decimal
  40.  
  41.      DWORD          A 4-byte value.
  42.  
  43.      END            The ASCII value 1Ah
  44.  
  45.      Icon           A .XPM file created by the DESQview/X Icon Editor.
  46.  
  47.      LF             Line feed, ASCII 10 decimal
  48.  
  49.      NL             A CR followed by a LF
  50.  
  51.      Offset         The position in the file, relative to the beginning of
  52.                     the  file, in bytes.  The first byte of the file is at
  53.                     offset 0.  Offsets are expressed in hex numbers.
  54.  
  55.      Section        A synonym of "topic".
  56.  
  57.      Tag            The index marker that you see sticking out the bottom of
  58.                     the notepad on the help screen.
  59.  
  60.      Topic          A logical unit of text.  The topic is the smallest unit
  61.                     of text to which a cross-reference can refer.
  62.  
  63.      WORD           A 2-byte value.
  64.  
  65. OVERVIEW
  66. --------
  67.  
  68. The help files are stored in the \DVX\HELP directory with the extension
  69. ".HLP".  To view a help file, you must run the DISPHELP program:
  70.  
  71.           CD \DVX
  72.           DISPHELP -f <help-file-name>
  73.  
  74. DISPHELP assumes that the help file is in \DVX\HELP, so you should not
  75. specify a path.  For example, to view the Icon Editor help file, type the
  76. following:
  77.  
  78.           CD \DVX
  79.           DISPHELP -f ICONED.HLP
  80.  
  81. DISPHELP actually runs \DVX\HELP\DVXHELP.EXE, the Help Engine, to display the
  82. help file.
  83.  
  84.  
  85. THE HELP FILE FORMAT
  86. --------------------
  87.  
  88. The help file consists of six sections, in the following order:
  89.  
  90.      (1) the header,
  91.      (2) the front cover,
  92.      (3) the body,
  93.      (4) the tags,
  94.      (5) the icons, and
  95.      (6) the directory.
  96.  
  97.      In the following description, text in single quotes appear in the file
  98.      just as typed.  "NL" represents the byte combination 0Ah and 0Dh
  99.      (carriage return and line feed) and "END" represents 1Ah.  Spaces are
  100.      provided for ease of reading and are not part of the format unless they
  101.      are in single quotes.  Descriptions are placed within "<" and ">" signs.
  102.      Optional elements are enclosed in "[" and "]".
  103.  
  104.      HEADER
  105.      ------
  106.      The header gives the position and size of the directory.
  107.  
  108.           OFFSET    SIZE      DESCRIPTION
  109.               0h    DWORD     Offset of directory
  110.               4h    WORD      Size of directory, in bytes.
  111.  
  112.      FRONT COVER
  113.      -----------
  114.      The front cover contains the title and subtitle on the front cover of
  115.      the displayed notebook.  Its name in the directory is "FRCOVER".  The
  116.      front cover starts at offset 6h:
  117.  
  118.           '/FT' <front cover title> NL '/FS' <subtitle> NL END
  119.  
  120.      BODY
  121.      ----
  122.      The body consists of "sections" which are terminated with END.  Each
  123.      section is made up of one or more paragraphs which end with NL.  There
  124.      must be no NL's within a paragraph; DVXHELP formats the text based on
  125.      the width of the help window.
  126.  
  127.      Codes are embedded into the text for formatting and cross-referencing.
  128.      The specification for an individual section is:
  129.  
  130.           [<paragraph text>] NL [[<paragraph text>] NL [...]] END
  131.  
  132.      The body consists of a concatenation of the sections.  Each section is
  133.      given a name in the directory.
  134.  
  135.           CODES
  136.           -----
  137.           Here are the codes that can be embedded in <paragraph text>.
  138.  
  139.           CODE                                   DESCRIPTION
  140.           -----------------------------------------------------------------
  141.           '//'                                   Becomes a single '/'
  142.  
  143.           '/JB' <text> '/' <section name> '/'    Highlights <text>.  If user
  144.                                                  clicks on <text>, jump to
  145.                                                  section <section name>.
  146.  
  147.           '/FH'                                  Turn on a larger, bold font
  148.  
  149.           '/FL'                                  Turn on a bold font
  150.  
  151.           '/FB'                                  Turn off /FH and /FL
  152.  
  153.           '/U'                                   Toggle underlining of text
  154.  
  155.           '/CH'                                  Highlight text
  156.  
  157.           '/CN'                                  Turn off text highlight
  158.  
  159.           '/IL' <icon name> '/'                  Place the icon referenced in
  160.                                                  in the directory as <icon
  161.                                                  name> here.
  162.  
  163.           '/IE' <icon name> '/'                  Similar to /IL, I'm not sure
  164.                                                  what the difference is yet.
  165.  
  166.           '/ML' <n> '/'                          Set the left margin for all
  167.                                                  remaining text in the
  168.                                                  section <n> pixels to the
  169.                                                  right from the current
  170.                                                  margin.  If <n> is negative,
  171.                                                  move the margin left.
  172.      TAGS
  173.      ----
  174.      The tags are shown at the bottom of the notebook, and allow the user to
  175.      jump to one or more sections by clicking on the tag.  The tag section is
  176.      called "BKCOVER" in the directory.  You can specify the color of each
  177.      tag as well as the color of the notebook cover in this section.  The
  178.      first part of the section specifies the notebook cover color, like so:
  179.  
  180.           '/CC' <color> '/' NL
  181.  
  182.      I haven't tried any <color> values besides 'blue'.
  183.  
  184.      Then the tags are listed:
  185.  
  186.           '/CT#' <rrggbb> '/' NL '/JB' <tag text> '/' <section> '/'
  187.            ['/CT#' <rrggbb> '/' NL '/JB' <tag text> '/' <section> '/'
  188.            [...]] END
  189.  
  190.      The <rrggbb> value specifies the red-green-blue color mix for the tag.
  191.      Each primary color is specified with a 2-digit hex value, 00h to FFh.
  192.      For example, a pure red tag would be
  193.  
  194.           '/CT#FF0000/'
  195.  
  196.      which actually turns out to be a pretty dark red.  Quarterdeck's version
  197.      of red tags are
  198.  
  199.           '/CT#FF5555/'.
  200.  
  201.      The <tag text> appears in the tag, and is preceded by an underlined
  202.      digit.  Clicking on that tag will cause a jump to section <section>.
  203.  
  204.      The tags appear from left to right in the order specified in the help
  205.      file, and the width of the notebook is adjusted to fit all the tags.
  206.  
  207.  
  208.      ICONS
  209.      -----
  210.      One of the nicest features of the help file is the ability to place
  211.      icons anywhere using /IL and /IE.  The icons section is simply a
  212.      concatenation of all the .XPM files.  They are NOT delimited with ENDs.
  213.      The name and offset of each icon is stored in the directory.
  214.  
  215.      DIRECTORY
  216.      ---------
  217.      The directory is the most important section of the help file.  It
  218.      associates section and icon names with their offsets into the file.
  219.      Every time DVXHELP encounters a /JB, /IL or /IE, it takes the icon or
  220.      section name and gets the offset of that icon or section from the
  221.      directory.
  222.  
  223.      Each directory element consists of the following.  The offset is
  224.      relative to the beginning of the directory element.
  225.  
  226.           OFFSET         SIZE           DESCRIPTION
  227.           -----------------------------------------
  228.               0h         12 BYTES       The name of the section, padded to
  229.                                         right with 0's.  If the name is
  230.                                         exactly 12 bytes, it is NOT
  231.                                         NULL-terminated.  The section name is
  232.                                         not case-sensitive.
  233.  
  234.              12h         DWORD          Offset of this section
  235.  
  236.      There must be ((number of sections in body)+(number of icons)+4)
  237.      directory elements.  The directory elements must appear in this order:
  238.  
  239.           SECTION NAME                  DESCRIPTION
  240.           -----------------------------------------
  241.           'directory'                   Special directory element.  The
  242.                                         must be the offset this directory
  243.                                         element (the same value as the first
  244.                                         DWORD of the help file).
  245.  
  246.           'FRCOVER'                     Offset of the Front Cover.
  247.  
  248.           'CONTENTS'                    Offset of the first body section.
  249.                                         Note that this section *must* be
  250.                                         named 'CONTENTS'.
  251.  
  252.           Remaining body sections
  253.  
  254.           'BKCOVER'                     Offset of the TAGs section.
  255.  
  256.           Icon names                    Offset of each icon
  257.  
  258.           Terminator                    Directory element is completely
  259.                                         filled with 0's.
  260.  
  261. CORRECTIONS, SUGGESTIONS, ETC.
  262. ------------------------------
  263.  
  264. If you find errors or have any suggestions, please let me know.  I can be
  265. reached from a variety of networks:
  266.  
  267.           From the Internet or Usenet: write to ``bodoh@xraylith.wisc.edu''.
  268.           From Fidonet: write to ``Daniel Bodoh 1:121/99.0''
  269.           From Compuserve: write to ``>INTERNET:bodoh@xraylith.wisc.edu''.
  270.           From DECnet: write to ``cxrl::bodoh''
  271.           From Bitnet: write to ``bodoh@xraylith''
  272.  
  273. And my old-fashioned address is:
  274.  
  275.           1402 Regent #417
  276.           Madison, WI USA 53711
  277.