
                        InterDesk Help File Formats

This document describes the formats for InterDesk help files, for both  text 
files and compiled help files.


                          Information File Format

An information file specifies what files to compile, etc.  It consists of at 
least  three  lines.   The first line specifies the filename of the compiled 
help file.  The second line (can be blank) specifies an optional long  title 
for  the  compiled  help  file.   This  title  may  not  be  longer  than 63 
characters.  This title will appear in the title bar of the Help window when 
the file is being viewed.

Any further lines specify text files to be compiled.

Here is an example information file:

MyApp.hlp
My application
MyApp1.txt
MyApp2.txt
MyApp3.txt
MyApp4.txt

The information file is passed to the help compiler in the following manner:

hc < MyApp.inf

Alternatively, you can simply type:

hc

and then type in the information, which is passed to the compiler.  When you 
are done, hit Ctrl+D.


                           Help Text File Formats

One or more help text files are compiled into a single help file.

A  topic  consists  simply  of  lines  of  text.  One line translates to one 
paragraph.  A linefeed character signals the end of a paragraph. In the help 
text file, a paragraph may be spread over several lines with newline escapes 
(see below).

The  backslash  character  ("\")  is  used  as  an escape character for help 
formatting, etc.  A backslash may be explicitly inserted into  the  text  by 
prefixing it with another backslash ("\\").

Escape Sequences:

  \\          Display an actual backslash character in the text.
  
  \NEWLINE    Soft return. The compiler strips the backslash,  newline,  and 
              any  whitespace before or after them, from the text, replacing
              them with a space. Used for convenience in editing help  text, 
              so a paragraph need not be on a single line.

  \!          Begin a new topic.  Only needed between topics --  not  needed 
              before the first or after the last topic in file.

  \l          (Lowercase letter "el").  Left-justify following text.
  
  \r          Right-justify following text (not yet implemented).
  
  \c          Center following text.
  
  \f          Full-justify following text.

  \w          No word wrapping  for  paragraphs.   Useful  for  things  like 
              source code within a help topic.  This is  treated  just  like
              the other justification escapes.
  
  \I          (Uppercase  letter  "eye").   Icrease  the  indent   by   four 
              characters.
  
  \U          Decrease the indent ("unindent") by four characters.
  
  \u          Create a hanging indent -- decrease the first line's indent by
              four characters.
  
  \i          Create a first-line indent -- increase the first line's indent
              by four characters.

  \M          Restore indenting to left margin.

  \m          Restore first-line indenting to left margin.

  \h          Turn bold ("heavy") text on or off.
  
  \s          Turn italic ("slanted") text on or off.
  
  \t TITLE \  Define title of current topic.
  
  \n ID \     Define id ("topic Number") of current topic.
  
  \k KWD \    Define a keyword for this topic.
  
  \b SEQUENCE_IDX "," SEQUENCE_NAME \   Define  a  browse  sequence for this 
                                        topic.  One per  topic  is  allowed.  
                                        Sequence   indexes   need   not   be 
                                        incremental  for  topics -- they can 
                                        be "spaced", and the order  will  be 
                                        resolved at compile time.

              In fact, it is customary to space browse sequence  indexes  in 
              multiples  of  5  or 10.  This way, topics can be added in the 
              middle of a sequence without disturbing the other topics.
  
  \={ JUMP_ID \     Begin text of a "display in same window" hyperlink.
  
  \=}               End text of a "display in same window" hyperlink.
  
  \+{ SHOW_ID \     Begin text of "show in another window" hyperlink.
  
  \+}               End text of a "show in another window" hyperlink.
  
  \S SPACING \      Define line spacing.  "SPACING" should be either 1, 1.5, 
                    or 2.
  
  \P SPACING \      Define   paragraph  spacing  (number  of  lines  between 
                    paragraphs).  "SPACING" should be either 1, 1.5, or 2.

  \*{ TERM_CHAR COMMAND TERM_CHAR

                    Begin text of an "execute command" hyperlink.

                    "Execute command" hyperlinks are like normal hyperlinks, 
                    but they execute a command when the user  selects  them, 
                    rather than viewing to a topic.

                    'TERM_CHAR'  is  the  character  that  will  be  used to 
                    terminate the escape  sequence.   This  gives  the  user 
                    flexibility to use any character, rather than fixing the 
                    escape  terminator as some character which may be needed 
                    within the command text itself.  However, remember  that 
                    whatever character you choose, it may not be included in 
                    the  command itself, or that would be interpreted as the 
                    end of the command.

                    InterHelp uses the system() command to run the  command, 
                    so you can use any complex shell command string that you 
                    would type in at the shell prompt.

                    Example:  \*{|echo \a|

  \*}               End text of an "execute command" hyperlink.

Browse sequences are sequences of related topics which the user can "browse"
through using the '<-' and '->' buttons.  The topics should be ordered in  a 
logical sequence.

Hyperlinks cannot extend across paragraphs (although they may extend  across
lines).   If  they  do so, the sequence will be terminated at the end of the
paragraph.  Hyperlinks cannot be nested.

Escape sequences which require parameter(s) can never extend across multiple
lines.  This includes the "execute command" hyperlink escape.  In other
words, you cannot do the following:

  \*{|/usr/bin/myapp \
  arg1 arg2|

If you wish to  create  a  hyperlink  "execute  command"  escape  to  run  a 
terminal-based  program,  you should explicitly run the program using Wterm.  
Simply prefix the command with /windows/bin/wterm, and Wterm  will  run  the 
command.   You  may  have a little difficulty if the command contains output 
redirection, semicolons, and other complex shell constructs.  It is  easiest 
to put the commands into a shell script, which is run by Wterm.

Justification is not started until the  paragraph  after  the  justification 
escape  is  placed,  unless  the escape is placed at the very beginning of a 
paragraph (even before  any  whitespace).   The  default  justification  (in 
effect at the beginning of each topic) is full justification.

Indentation does not apply to centered and right-justified paragraphs.

For escape sequences which take string/numeric  parameters,  no  spaces  may 
separate  the  escape  and its parameters.  Spaces are given above simply to 
increase readability.  For example, the following are illegal:

  \+{ 170 \
  \b15 , Creating a document\
  \*{ # /windows/bin/wterm my_term_app #

while the following are acceptable:

  \+{170\
  \b15,Creating a document\
  \*{#/windows/bin/wterm my_term_app#

Please note that all  escape  sequences  which  need  parameters  require  a 
backslash  to  terminate  the sequence (except the "execute command" escape, 
which requires a user-defined character to terminate  it).   Such  sequences 
may not have a backslash within their parameter list.

Two special topics are associated with each file:

  Topic id 0.  This topic is the 'Contents' or 'Index' topic.  It MUST exist 
    in the file.  When the help system is not  given  a  specific  topic  to 
    view,  it  displays  this topic.  The user can also conveniently jump to 
    this topic using the 'Contents' button in the Help window's menu bar.

  Topic  id  1.   This  topic  is  an  optional  'Glossary'  topic, in which 
    different terms used in  the  help  file  are  defined.   The  user  can 
    conveniently  jump to this topic using the 'Glossary' button in the Help 
    window's title bar.  If this topic is not defined, the 'Glossary' button 
    is grayed out and disabled.

    The general method for constructing this topic is to make it into a list 
    of terms.  Each  term  is  a  hyperlink  to  the  definition,  which  is 
    displayed in a secondary window.  Thus, the glossary topic itself is not 
    cluttered up.

    If the glossary topic is very large (more than 4-5 screens, perhaps), it
    is advisable to break it down into several alphabetic  sub-topics.   The
    glossary topic itself can merely have hyperlinks to the other sub-topics
    (e.g. A-F, G-L, M-R, S-Z).

    Typically, most help systems  will  also  have  many  words  or  phrases
    defined  'in-place' -- that is, whenever they occur, they are created as
    hyperlinks to show their definition.  Then,  when  the  user  clicks  on
    them,  the  definition is displayed in a secondary window.  This is used
    in addition to defining the word or phrase in the glossary.

These topics should not be used for any other purpose than that given.


                         Compiled Help File Format

The compiled help file consists of a variable-length header followed by  the 
topics  themselves.   The  format for the header is as follows.  Please note 
that all words and dwords are in little-endian.  All words  and  dwords  are 
unsigned, unless otherwise noted.

  Size        Description

  WORD        Magic number -- 0x239C (0x9C 0x23).

  CHAR*64     Long name for help file, appears in  Help's  title.   Must  be
              NULL-terminated.

  DWORD       Number of topics in file.

  ...         Sorted list of topics.  One entry for each topic, sorted in 
              ascending order of their ids.

              DWORD       Topic's id.

              CHAR*64     Topic's title.  Must be NULL-terminated.

              DWORD       Index of topic's text into file.

              DWORD       Length, in bytes, of topic's text,  including  the 
                          terminating NULL.

  DWORD       Number of keywords in keyword list.

  ...         Sorted list of keyword entries.  Sorted alphabetically  (using 
              an  international  sort  sequence)  in ascending order, on the 
              keyword names.  Keywords ARE case-sensitive (ABC != Abc).

              CHAR*64     Keyword's name.  Must be NULL-terminated.

              DWORD       Number of associated topics.

              ...         Sorted   list   of   keyword's   topics.    Sorted 
                          alphabetically   (using   an   international  sort 
                          sequence) in ascending order, on the topic titles.

                          DWORD         ID of this topic.

  DWORD       Number of browse sequences.

  ...         List of browse sequences.  Not sorted in any way.

              DWORD       Number of topics in this browse sequence.

              ...         Sorted list of browse topics.  Sorted in ascending
                          order on each topic's position in the sequence.

                          DWORD         ID of this topic.

  ...         Topics themselves.

After  the  file  header come the topics themselves.  These are delimeted by 
NULL characters, and are in the same format as that for  a  help  text  file 
(see above) except for the following:

  Id escapes are not used.

  Title name escapes are not used.

  Keyword escapes are not used.

  Browse sequence escapes ARE used.  However, the only information given  is 
    the  index  of  the  associated  browse  sequence  in  the file's browse
    sequence array (in the compiled file's header).   A  browse  escape,  if 
    present, is ALWAYS at the immediate beginning of a topic.

  New  topic  escapes are NOT used.  Topics are NULL-terminated instead.  In 
    addition, the length of each topic is specified in the help file header.

Even though topic entries in the topic list (in the file header) are sorted, 
the topics themselves in the file need not be.


                            Help Bookmark Files

Help bookmark files specify  a  list  of  topics  which  the  user  has  set 
'bookmarks'  for  --  topics  to which the user wishes to be able to quickly 
return.

  Byte(s)       Description

  0-1 (WORD)    Number of bookmarks in the bookmark file.

  4-? (DWORDS)  The bookmarks  themselves.   These  are  simply  topic  ids, 
                specifying the topics for which bookmarks are defined.

Currently,  a  bookmark file may not have more than 16 bookmarks defined.  A 
greater number of bookmarks would defeat the very purpose of having them.

A help bookmark file has a filename with the following format: filename.bmk.  
In other words, if there was a help file named

MyApp.hlp

then the bookmark file for that help file would be called

MyApp.bmk
