Fractal Creations (Second Edition)/FRACTALS_2E.iso/frasrc.exe/HC.DOC

Text File | 1992-07-10 | 18KB | 535 lines

... First version documentation is followed by additional notes
... for features added in subsequent versions.


           FRACTINT Help Compiler Source File Format



0. Contents

    1.0     Help compiler input/output.
    1.1       The source input file.
    1.2       The header (.H) output file.
    1.3       The binary (.HLP) output file.
    2.0     Source (.SRC) file format.
    2.1       Comments.
    2.2       Defining the output filenames.
    2.3       Defining the help file version.
    2.4.0     Help topics.
    2.4.1    Starting a help topic.
    2.4.2.0    The help text.
    2.4.2.1      Special characters.
    2.4.3    Starting another page.
    2.5.0     Labels.
    2.5.1    The help index label (HELP_INDEX).
    2.5.2    Private labels.
    2.6.0     Hot-links.
    2.6.1    Special hot-links.
    2.7       Tables.


1.0 Help compiler input/output.

    The Help Compiler converts a source file into two output files: a "C"
  header file which is #included in FRACTINT and a binary file used at run-
  time.


1.1 The source input file.

    The Help compiler takes as input a help source file (.SRC).  See x.x.x
  for the .SRC file format.  HELP.SRC is FRACTINT's help file source.


1.2 The header (.H) output file.

    The header (.H) file contains a #define macro for each non-private label
  (see 2.5.0) and for the help file version (see 2.3).    The .H file is
  included in FRACTINT and the macros are used to set the current help mode.

    The Help Compiler will only modify the .H file when a non-private label
  (see 2.5.0) is added or deleted or when the help file version (see 2.3)
  is changed.  This minimizes the times when FRACTINT will need to be re-
  compiled.  However, when the Help Compiler does modify the .H file it is
  necessary to re-compile FRACTINT.

  In FRACTINT this file is named HELPDEFS.H

1.3 The binary (.HLP) output file.

    The .HLP file is the binary file where compiled help informnation is
  stored.  See HC.C and HELP.C if you're interested in the file format.  In
  FRACTINT the file is named FRACTINT.HLP.  This file may be appended to
  FRACTINT.EXE for distribution, see the Help Compiler command-line help
  (type "HC" at the DOS prompt) more info.


2.0 Source (.SRC) file format.

    The source file defines output files, help file version, topics, labels
  and hypertext-style hot-links with commands and hot-links.  Commands start
  with a tilde ('~') in the first column of a line and continue to the end
  of the line.    Hot-links, defined within the text, are surrounded by curly-
  braces ('{' and '}').  Comment lines, which may appear anywhere in the
  file, start with a semicolon (';') in the first column and continue to
  the end of the line.


2.1 Comments.

    Any line starting with a semicolon (;) is a comment.  The comment
  continues to the end of the line and may appear anywhere in the file.
  The semicolon must be in the first column of the line.


2.2 Defining the output filenames.

    The output filenames are defined in the source file by the following
  commands:

    ~HdrFile=H_FILE
    ~HlpFile=HLP_FILE

  H_FILE is the .H filename and HLP_FILE is the .HLP filename.    These
  commands must appear before the first topic.


2.3 Defining the help file version.

    The help file version number is stored in a special #define in the .H
  file (named HELP_VERSION) and stored in the .HLP file header.  If the
  version number in HELP_VERSION does not match the version in the .HLP file
  the file will not be used.  This is mainly to make sure FRACTINT doesn't
  try to read a help file other than the one the .EXE is expecting.  To
  define the help version:

    ~Version=nnn

  Where nnn is a positive decimal version number.  (Suggested format is 100
  for version 1.00, 150 for version 1.50, etc.)  This command must appear
  before the first help topic.    -1 will be used if the version is not defined
  in the .SRC file.


2.4.0 Help topics.

    The help topics come after the HdrFile=, HlpFile= and Version= commands
  and continue until end-of-file.


2.4.1 Starting a help topic.

  To start a new help topic use the following format:

    ~Topic=TITLE

  "~Topic=" is the command to start a topic and TITLE is the text to display
  at the top of each page.  The title continues to the '\n' and may contain
  up to 65 characters.

    In the example:

    ~Title=Command Keys available while in Display Mode

  "Command Keys avail..." is the TITLE which would displayed at the top of
  each page.


2.4.2.0 The help text.

    The help text for each topic can be several pages long. Each page is 22
  rows by 78 columns.  The first and last rows should be blank for the best
  appearance.


2.4.2.1 Special characters.

    To insert reserved characters (like ';', '~', '\' and '{') into the help
  text precede the character with a backslash ('\').  To insert any character
  (except null) into the text follow a backslash with a decimal (not hex
  or octal) ASCII character code.  For example:

    \~  - puts a tilde in the text.
    \24 - places an up-arrow in the text.


2.4.3 Starting another page.

    To start a new page in the same topic put two tildes (~~) at the start
  of a line.  No other text is allowed on the line.  Each page can be up to
  22 lines long.  (The Help Compiler will warn you if any page gets longer
  than 22 lines.)  For the best appearance the first and last lines should
  be blank.


2.5.0 Labels.

    A label is a name which in used to refer to a help topic.  A label is
  used in hot-links or in FRACTINT for context-sensitive help.    When help
  goes to a label (when a hot-link is selected or context-sensitive help
  is called from FRACTINT) it goes to the page of the topic where the label
  was defined.

    To define a label for a topic insert the following command into the
  topic's text:

    ~(NAME)

  NAME is the name of the label.  The name follows "C"-style conventions
  for variable names.  Case is significant.  The label should start at the
  beginning of a line and have no text following it on the line.  The line
  line will not appear in the help text.

    For example, if this line:

  ~(HELPPLASMA)

  was placed in page three of a topic using it in a hot-link (see 2.6.0)
  or as context-sensitive help would "go to" page three of that topic.  The
  user would then be free to page up and down through the entire topic.

    Each topic must have at least one label otherwise it could not be
  referred to.


2.5.1 The help index label (HELP_INDEX).

    When the user wants to go to the "help index" (by pressing F1 while
  in help) help will go to a special label named "HELP_INDEX".  Other than
  the requirement that it be in every .SRC file you may treat it as any
  other label.    It can be used in links or as context-sensitive help.


2.5.2 Private labels.

    A private label is a label which is local to the help file.  It can be
  used in hot-links but cannot be used as context-sensitive help.  A private
  label is a label with an "at sign" ('@') as the first character of its
  name.  The "at sign" is part of the name.  In the example:

    ~(@HELPPLASMA)

  "@HELPPLASMA" is a private label.

    Private labels are not included in the .H file so you may add or delete
  private labels without re-compiling FRACTINT.  Each non-private label
  takes up some memory (4 bytes) in FRACTINT so it's best to use private
  labels whenever possible.  Use private labels except when you want to use
  the label as context-sensitive help.


2.6.0 Hot-links.

    A hypertext-style hot-link to a label can appear anywhere in the help
    text.  To define a hot-link use the following syntax:

    {LABEL TEXT}

  LABEL is the label to link to and TEXT is the text that will be highlighted.
  Only the TEXT field will appear on the help screen.  No blanks are allowed
  before the LABEL.  In the sample hot-link:

    {HELPMAIN Command Keys in display mode}

  "HELPMAIN" is the LABEL and "Command keys in display mode" is the
  TEXT to will be hightlighted.


2.6.1 Special hot-links.

    In addition to normal hot-links to labels "special" links to custom
  functions (built into HELP.C) are allowed.  These hot-links have a
  negative number (-2..) in place of the LABEL.  No special hot-links are
  currently supported in FRACTINT.


2.7 Tables.

    A table is a way of arranging a group of hot-links into evenly-spaced
  columns.  The format for a table is:

    ~Table=WIDTH COLS INDENT

    << LINKS... >>

    ~EndTable

  WIDTH is the width of each item, COLS is the number of columns in the
  table and INDENT is the number of spaces to indent the table.  LINKS is
  a list of hot-links (see 2.6.0) which will be arranged.  Only blanks and
  new-lines are allowed between the hot-links; other characters generate
  an error.

    In the example table:

    ~Table=20 3 9
    {@ONE One}
    {@TWO Two}
    {@THREE Three}
    {@FOUR Four}
    {@FIVE Five}
    {SIX Six}
    {SEVEN Seven}
    {EIGHT Eight}
    ~EndTable

  20 is the WIDTH, 3 is COLS and INDENT is 9.  The following text would
  be produced by the table:

    One            Two         Three
    Four            Five        Six
    Seven            Eight

  Each item would be a hot-link linking to its corresponding label (@ONE for
  "One", etc.)  Any legal hot-link (to private or non-private labels) may be
  used in a table.

    The same effect could be produced by arranging the hot-links into
  columns yourself but using a table is usually easier (especially if the
  label names vary in length).



... Second version additional documentation:

          New features of the Help Compiler (HC)
          ======================================


Expanded command format
=======================

    Several commands may be "strung together" by separating them with commas.
  For example:

       ~Topic=Help on help, Label=HELPONHELP, Format-

  To have a comma as part of a command (like in a topic) precede it with a
  backslash.

    Commands can be imbedded in the text with the following format:

       ~(command)

  The text before the tilde and immediately after the ending parend will be
  part of the help text.


New commands
============

    Format[+/-]        L   turns formatting on/off.
    Online[+/-]        L   enables/disables display of text in the online
               help.
    Doc[+/-]           L   enables/disables display of text in the printed
               document.  (Currently ignored.)
    FormatExclude=NUM  G/L Set the column number in which formatting is
               automatically disabled.  (ie. all text after
               column NUM is unformatted.)    If before any topics
               sets global value, if in a topic sets only for
               that topic.
    FormatExclude=n    G/L Turn this feature off.  This is the default at the
               start of the source file.  Global if before topic,
               local otherwise
    FormatExclude[+/-] G/L Temporarily enable/disable this feature.  Has no
               effect if "FormatDisable=n" is in effect.
    FormatExclude=     L   Resets FormatExclude to its global value.
    Center[+/-]        L   Enable/Disable automatic centering of text.

    All commands with a "L" are local in scope -- they effect only the current
  topic.  All commands with a "G" are global in scope.  Commands with "G/L" are
  global if used before any topics are defined and local otherwise.  At the
  start of each topic the following local settings are in effect:

       ~Online+,Doc+,FormatExclude=,Format+,Center-


Modified commands
=================

  Label=NAME        replaces the ~(...) command
  FF            replaces the ~~ command


Hot-Links
=========

  Hot-links have been expanded to support "implicit" links.  These are links
  which link to the topic whose title matches the highlighted text.  They have
  no label field.  In the example:

       Press <C> to goto {Color Cycling Mode}.

  The link will link to the topic whose title is "Color Cycling Mode".  The
  link must match the topics' title exactly except for case and leading or
  trailing blanks.

  Normal "explicit" hot-links to labels must now have an equal sign
  immediately after the opening curly-brace.  For example:

       {=HELPONHELP How do I use help?}


  Links to the label named "HELPONHELP".  (The equal sign is not part of the
  labels name.)


Paragraph formatting
====================

  The HC determines the end of a paragraph when it encounters:

    o a blank line.
    o a change of indentation after the second line of a paragraph.
    o a line ending with a backslash ('\').
    o If FormatExclude is enabled any line starting beyond the cut-off
      value.

  The HC only looks at the left margin of the text to determine paragraph
  breaks.  If your not sure the HC can determine a paragraph boundry
  append a backslash to the end of the last line of the paragraph.

  The following examples illustrate when you need to use a backslash to make
  HC format correctly:

  1. Paragraph headings.

    Heading
    Text which follows the heading.  This text is supposed
    to be a separate "paragraph" from the heading but the HC
    doesn't know that!

  This text would be formatted into a single paragraph.  (The word "Text"
  would immediately follow "Heading".)  To make it format correctly append
  a backslash to the end of "Heading".

  2. Single-line bullets.

    o Don't branch.
    o Use string instructions, but don't go much out of your way
      to do so.
    o Keep memory accesses to a minimum by avoiding memory operands
      and keeping instructions short.

    Since the HC cannot tell that the first bullet is a separate paragraph
  from the second bullet it would put both bullets into one paragraph.    Any
  bullet of two lines or more (assuming the intentation for the second line
  of the bullet is different from the first) is OK.  Always add a backslash
  to the end of single-line bullets.

    In general, if you cannot determine where a paragraph boundry is by
  looking at the indentation of each line use a backslash to force a
  paragraph break.




... Third version additional documentation:

  New Commands
  ============

  ~Comment, ~EndComment
    Use to start/end multi-line comments.

  ~CompressSpaces[+/-]
    Turn on/off the automatic compression of spaces.  Used for data topics
    and when reading normal topics with read_topic()

  ~Data=label_name
    Starts a topic which contains data.  Think of it as a macro for:

      ~Topic=, Label=label_name, Format-, CompressSpaces-

    Data labels cannot be part of the document or displayed as online help.

  ~BinInc filename
    Includes a file in binray format (no processing) into a data topic.
    This command only works for data topics.  Example:
    ~Data=TPLUS_DAT
    ~BinInc tplus.dat

  ~DocContents
    Defines the documents table of contents.  Text is allowed.    Table of
    content entries have the following format:

      { id, indent, name, [topic, ...] [, FF] }

    id       is it's identification (ie, 1.2.1)
    indent is the indentation level, (ie. 2)
    name   is the text to display to display (ie. Fractint Commands)
       If name is in quotes it is also assumed to also be the
       title of the first topic.
    topic  list of 0 or more topics to print under this item.  Entries
       in quotes are assumed to be the title of a topic, other
       entries are assumed to be labels.
    FF       If this keyword is present the entry will start on a new page in
       the document.
    It isn't as complex as it sounds; see "~DocContents" in HELP.SRC for
    examples.


  Quoted implicit hot-links
  =========================

    HC will ignore quotes areound implicit hot-links when searching for
    the matching title.  This allows hot-links like:

      {"Video adapter notes"}

    intead of:

      "{Video adapter notes}"

    This is so that the hot-link page numbers don't end up inside the
    quotes like: "Video adapter notes (p. 21)".  It also keeps quotes from
    being separated from the text in the online-help.


  Document printing
  =================

    The new /p command-line option compiles the .SRC file and prints the
    document.  It does NOT write the .HLP file.

    The old /p option (set swap path) has been changed to /r.


   Printing the document
   =====================

   The function prototype (in HELP.C) to print the document is:

    void print_document(char *outfname, int (*msg_func)(int,int),
                int save_extraseg);

   outfname is the file to "print" to (usually "FRACTINT.DOC"), msg_func
   is a function which is called at the top of each page, and save_extraseg
   is true if the data in the extraseg should be preserved.

   See print_doc_msg_func() in HELP.C for an example of how to use msg_func.
   If msg_func is NULL no msg_func is called.


   Printing from help
   ==================

   There are hooks to print the document from a help topic by selecting a
   "special" hot-link. I suggest a format like:

    ~Topic=Generating FRACINT.DOC

    Explain that selecting yes will print the document, etc...

    {=-2  Yes, generate FRACTINT.DOC now. }
    {=-1  No, do NOT generate FRACTINT.DOC. }

   Selecting yes will generate the document and then return to the previous
   topic.  Selecting no will simply return to the previous topic (like
   backspace does.)