home *** CD-ROM | disk | FTP | other *** search
/ Mega A/V / mega_av.zip / mega_av / GRAPHUTL / FRASR172.ZIP / HC.DOC < prev    next >
Text File  |  1991-06-01  |  18KB  |  535 lines
  1.  
  2. ... First version documentation is followed by additional notes
  3. ... for features added in subsequent versions.
  4.  
  5.  
  6.            FRACTINT Help Compiler Source File Format
  7.  
  8.  
  9.  
  10. 0. Contents
  11.  
  12.     1.0     Help compiler input/output.
  13.     1.1       The source input file.
  14.     1.2       The header (.H) output file.
  15.     1.3       The binary (.HLP) output file.
  16.     2.0     Source (.SRC) file format.
  17.     2.1       Comments.
  18.     2.2       Defining the output filenames.
  19.     2.3       Defining the help file version.
  20.     2.4.0     Help topics.
  21.     2.4.1    Starting a help topic.
  22.     2.4.2.0    The help text.
  23.     2.4.2.1      Special characters.
  24.     2.4.3    Starting another page.
  25.     2.5.0     Labels.
  26.     2.5.1    The help index label (HELP_INDEX).
  27.     2.5.2    Private labels.
  28.     2.6.0     Hot-links.
  29.     2.6.1    Special hot-links.
  30.     2.7       Tables.
  31.  
  32.  
  33. 1.0 Help compiler input/output.
  34.  
  35.     The Help Compiler converts a source file into two output files: a "C"
  36.   header file which is #included in FRACTINT and a binary file used at run-
  37.   time.
  38.  
  39.  
  40. 1.1 The source input file.
  41.  
  42.     The Help compiler takes as input a help source file (.SRC).  See x.x.x
  43.   for the .SRC file format.  HELP.SRC is FRACTINT's help file source.
  44.  
  45.  
  46. 1.2 The header (.H) output file.
  47.  
  48.     The header (.H) file contains a #define macro for each non-private label
  49.   (see 2.5.0) and for the help file version (see 2.3).    The .H file is
  50.   included in FRACTINT and the macros are used to set the current help mode.
  51.  
  52.     The Help Compiler will only modify the .H file when a non-private label
  53.   (see 2.5.0) is added or deleted or when the help file version (see 2.3)
  54.   is changed.  This minimizes the times when FRACTINT will need to be re-
  55.   compiled.  However, when the Help Compiler does modify the .H file it is
  56.   necessary to re-compile FRACTINT.
  57.  
  58.   In FRACTINT this file is named HELPDEFS.H
  59.  
  60. 1.3 The binary (.HLP) output file.
  61.  
  62.     The .HLP file is the binary file where compiled help informnation is
  63.   stored.  See HC.C and HELP.C if you're interested in the file format.  In
  64.   FRACTINT the file is named FRACTINT.HLP.  This file may be appended to
  65.   FRACTINT.EXE for distribution, see the Help Compiler command-line help
  66.   (type "HC" at the DOS prompt) more info.
  67.  
  68.  
  69. 2.0 Source (.SRC) file format.
  70.  
  71.     The source file defines output files, help file version, topics, labels
  72.   and hypertext-style hot-links with commands and hot-links.  Commands start
  73.   with a tilde ('~') in the first column of a line and continue to the end
  74.   of the line.    Hot-links, defined within the text, are surrounded by curly-
  75.   braces ('{' and '}').  Comment lines, which may appear anywhere in the
  76.   file, start with a semicolon (';') in the first column and continue to
  77.   the end of the line.
  78.  
  79.  
  80. 2.1 Comments.
  81.  
  82.     Any line starting with a semicolon (;) is a comment.  The comment
  83.   continues to the end of the line and may appear anywhere in the file.
  84.   The semicolon must be in the first column of the line.
  85.  
  86.  
  87. 2.2 Defining the output filenames.
  88.  
  89.     The output filenames are defined in the source file by the following
  90.   commands:
  91.  
  92.     ~HdrFile=H_FILE
  93.     ~HlpFile=HLP_FILE
  94.  
  95.   H_FILE is the .H filename and HLP_FILE is the .HLP filename.    These
  96.   commands must appear before the first topic.
  97.  
  98.  
  99. 2.3 Defining the help file version.
  100.  
  101.     The help file version number is stored in a special #define in the .H
  102.   file (named HELP_VERSION) and stored in the .HLP file header.  If the
  103.   version number in HELP_VERSION does not match the version in the .HLP file
  104.   the file will not be used.  This is mainly to make sure FRACTINT doesn't
  105.   try to read a help file other than the one the .EXE is expecting.  To
  106.   define the help version:
  107.  
  108.     ~Version=nnn
  109.  
  110.   Where nnn is a positive decimal version number.  (Suggested format is 100
  111.   for version 1.00, 150 for version 1.50, etc.)  This command must appear
  112.   before the first help topic.    -1 will be used if the version is not defined
  113.   in the .SRC file.
  114.  
  115.  
  116. 2.4.0 Help topics.
  117.  
  118.     The help topics come after the HdrFile=, HlpFile= and Version= commands
  119.   and continue until end-of-file.
  120.  
  121.  
  122. 2.4.1 Starting a help topic.
  123.  
  124.   To start a new help topic use the following format:
  125.  
  126.     ~Topic=TITLE
  127.  
  128.   "~Topic=" is the command to start a topic and TITLE is the text to display
  129.   at the top of each page.  The title continues to the '\n' and may contain
  130.   up to 65 characters.
  131.  
  132.     In the example:
  133.  
  134.     ~Title=Command Keys available while in Display Mode
  135.  
  136.   "Command Keys avail..." is the TITLE which would displayed at the top of
  137.   each page.
  138.  
  139.  
  140. 2.4.2.0 The help text.
  141.  
  142.     The help text for each topic can be several pages long. Each page is 22
  143.   rows by 78 columns.  The first and last rows should be blank for the best
  144.   appearance.
  145.  
  146.  
  147. 2.4.2.1 Special characters.
  148.  
  149.     To insert reserved characters (like ';', '~', '\' and '{') into the help
  150.   text precede the character with a backslash ('\').  To insert any character
  151.   (except null) into the text follow a backslash with a decimal (not hex
  152.   or octal) ASCII character code.  For example:
  153.  
  154.     \~  - puts a tilde in the text.
  155.     \24 - places an up-arrow in the text.
  156.  
  157.  
  158. 2.4.3 Starting another page.
  159.  
  160.     To start a new page in the same topic put two tildes (~~) at the start
  161.   of a line.  No other text is allowed on the line.  Each page can be up to
  162.   22 lines long.  (The Help Compiler will warn you if any page gets longer
  163.   than 22 lines.)  For the best appearance the first and last lines should
  164.   be blank.
  165.  
  166.  
  167. 2.5.0 Labels.
  168.  
  169.     A label is a name which in used to refer to a help topic.  A label is
  170.   used in hot-links or in FRACTINT for context-sensitive help.    When help
  171.   goes to a label (when a hot-link is selected or context-sensitive help
  172.   is called from FRACTINT) it goes to the page of the topic where the label
  173.   was defined.
  174.  
  175.     To define a label for a topic insert the following command into the
  176.   topic's text:
  177.  
  178.     ~(NAME)
  179.  
  180.   NAME is the name of the label.  The name follows "C"-style conventions
  181.   for variable names.  Case is significant.  The label should start at the
  182.   beginning of a line and have no text following it on the line.  The line
  183.   line will not appear in the help text.
  184.  
  185.     For example, if this line:
  186.  
  187.   ~(HELPPLASMA)
  188.  
  189.   was placed in page three of a topic using it in a hot-link (see 2.6.0)
  190.   or as context-sensitive help would "go to" page three of that topic.  The
  191.   user would then be free to page up and down through the entire topic.
  192.  
  193.     Each topic must have at least one label otherwise it could not be
  194.   referred to.
  195.  
  196.  
  197. 2.5.1 The help index label (HELP_INDEX).
  198.  
  199.     When the user wants to go to the "help index" (by pressing F1 while
  200.   in help) help will go to a special label named "HELP_INDEX".  Other than
  201.   the requirement that it be in every .SRC file you may treat it as any
  202.   other label.    It can be used in links or as context-sensitive help.
  203.  
  204.  
  205. 2.5.2 Private labels.
  206.  
  207.     A private label is a label which is local to the help file.  It can be
  208.   used in hot-links but cannot be used as context-sensitive help.  A private
  209.   label is a label with an "at sign" ('@') as the first character of its
  210.   name.  The "at sign" is part of the name.  In the example:
  211.  
  212.     ~(@HELPPLASMA)
  213.  
  214.   "@HELPPLASMA" is a private label.
  215.  
  216.     Private labels are not included in the .H file so you may add or delete
  217.   private labels without re-compiling FRACTINT.  Each non-private label
  218.   takes up some memory (4 bytes) in FRACTINT so it's best to use private
  219.   labels whenever possible.  Use private labels except when you want to use
  220.   the label as context-sensitive help.
  221.  
  222.  
  223. 2.6.0 Hot-links.
  224.  
  225.     A hypertext-style hot-link to a label can appear anywhere in the help
  226.     text.  To define a hot-link use the following syntax:
  227.  
  228.     {LABEL TEXT}
  229.  
  230.   LABEL is the label to link to and TEXT is the text that will be highlighted.
  231.   Only the TEXT field will appear on the help screen.  No blanks are allowed
  232.   before the LABEL.  In the sample hot-link:
  233.  
  234.     {HELPMAIN Command Keys in display mode}
  235.  
  236.   "HELPMAIN" is the LABEL and "Command keys in display mode" is the
  237.   TEXT to will be hightlighted.
  238.  
  239.  
  240. 2.6.1 Special hot-links.
  241.  
  242.     In addition to normal hot-links to labels "special" links to custom
  243.   functions (built into HELP.C) are allowed.  These hot-links have a
  244.   negative number (-2..) in place of the LABEL.  No special hot-links are
  245.   currently supported in FRACTINT.
  246.  
  247.  
  248. 2.7 Tables.
  249.  
  250.     A table is a way of arranging a group of hot-links into evenly-spaced
  251.   columns.  The format for a table is:
  252.  
  253.     ~Table=WIDTH COLS INDENT
  254.  
  255.     << LINKS... >>
  256.  
  257.     ~EndTable
  258.  
  259.   WIDTH is the width of each item, COLS is the number of columns in the
  260.   table and INDENT is the number of spaces to indent the table.  LINKS is
  261.   a list of hot-links (see 2.6.0) which will be arranged.  Only blanks and
  262.   new-lines are allowed between the hot-links; other characters generate
  263.   an error.
  264.  
  265.     In the example table:
  266.  
  267.     ~Table=20 3 9
  268.     {@ONE One}
  269.     {@TWO Two}
  270.     {@THREE Three}
  271.     {@FOUR Four}
  272.     {@FIVE Five}
  273.     {SIX Six}
  274.     {SEVEN Seven}
  275.     {EIGHT Eight}
  276.     ~EndTable
  277.  
  278.   20 is the WIDTH, 3 is COLS and INDENT is 9.  The following text would
  279.   be produced by the table:
  280.  
  281.     One            Two         Three
  282.     Four            Five        Six
  283.     Seven            Eight
  284.  
  285.   Each item would be a hot-link linking to its corresponding label (@ONE for
  286.   "One", etc.)  Any legal hot-link (to private or non-private labels) may be
  287.   used in a table.
  288.  
  289.     The same effect could be produced by arranging the hot-links into
  290.   columns yourself but using a table is usually easier (especially if the
  291.   label names vary in length).
  292.  
  293.  
  294.  
  295. ... Second version additional documentation:
  296.  
  297.           New features of the Help Compiler (HC)
  298.           ======================================
  299.  
  300.  
  301. Expanded command format
  302. =======================
  303.  
  304.     Several commands may be "strung together" by separating them with commas.
  305.   For example:
  306.  
  307.        ~Topic=Help on help, Label=HELPONHELP, Format-
  308.  
  309.   To have a comma as part of a command (like in a topic) precede it with a
  310.   backslash.
  311.  
  312.     Commands can be imbedded in the text with the following format:
  313.  
  314.        ~(command)
  315.  
  316.   The text before the tilde and immediately after the ending parend will be
  317.   part of the help text.
  318.  
  319.  
  320. New commands
  321. ============
  322.  
  323.     Format[+/-]        L   turns formatting on/off.
  324.     Online[+/-]        L   enables/disables display of text in the online
  325.                help.
  326.     Doc[+/-]           L   enables/disables display of text in the printed
  327.                document.  (Currently ignored.)
  328.     FormatExclude=NUM  G/L Set the column number in which formatting is
  329.                automatically disabled.  (ie. all text after
  330.                column NUM is unformatted.)    If before any topics
  331.                sets global value, if in a topic sets only for
  332.                that topic.
  333.     FormatExclude=n    G/L Turn this feature off.  This is the default at the
  334.                start of the source file.  Global if before topic,
  335.                local otherwise
  336.     FormatExclude[+/-] G/L Temporarily enable/disable this feature.  Has no
  337.                effect if "FormatDisable=n" is in effect.
  338.     FormatExclude=     L   Resets FormatExclude to its global value.
  339.     Center[+/-]        L   Enable/Disable automatic centering of text.
  340.  
  341.     All commands with a "L" are local in scope -- they effect only the current
  342.   topic.  All commands with a "G" are global in scope.  Commands with "G/L" are
  343.   global if used before any topics are defined and local otherwise.  At the
  344.   start of each topic the following local settings are in effect:
  345.  
  346.        ~Online+,Doc+,FormatExclude=,Format+,Center-
  347.  
  348.  
  349. Modified commands
  350. =================
  351.  
  352.   Label=NAME        replaces the ~(...) command
  353.   FF            replaces the ~~ command
  354.  
  355.  
  356. Hot-Links
  357. =========
  358.  
  359.   Hot-links have been expanded to support "implicit" links.  These are links
  360.   which link to the topic whose title matches the highlighted text.  They have
  361.   no label field.  In the example:
  362.  
  363.        Press <C> to goto {Color Cycling Mode}.
  364.  
  365.   The link will link to the topic whose title is "Color Cycling Mode".  The
  366.   link must match the topics' title exactly except for case and leading or
  367.   trailing blanks.
  368.  
  369.   Normal "explicit" hot-links to labels must now have an equal sign
  370.   immediately after the opening curly-brace.  For example:
  371.  
  372.        {=HELPONHELP How do I use help?}
  373.  
  374.  
  375.   Links to the label named "HELPONHELP".  (The equal sign is not part of the
  376.   labels name.)
  377.  
  378.  
  379. Paragraph formatting
  380. ====================
  381.  
  382.   The HC determines the end of a paragraph when it encounters:
  383.  
  384.     o a blank line.
  385.     o a change of indentation after the second line of a paragraph.
  386.     o a line ending with a backslash ('\').
  387.     o If FormatExclude is enabled any line starting beyond the cut-off
  388.       value.
  389.  
  390.   The HC only looks at the left margin of the text to determine paragraph
  391.   breaks.  If your not sure the HC can determine a paragraph boundry
  392.   append a backslash to the end of the last line of the paragraph.
  393.  
  394.   The following examples illustrate when you need to use a backslash to make
  395.   HC format correctly:
  396.  
  397.   1. Paragraph headings.
  398.  
  399.     Heading
  400.     Text which follows the heading.  This text is supposed
  401.     to be a separate "paragraph" from the heading but the HC
  402.     doesn't know that!
  403.  
  404.   This text would be formatted into a single paragraph.  (The word "Text"
  405.   would immediately follow "Heading".)  To make it format correctly append
  406.   a backslash to the end of "Heading".
  407.  
  408.   2. Single-line bullets.
  409.  
  410.     o Don't branch.
  411.     o Use string instructions, but don't go much out of your way
  412.       to do so.
  413.     o Keep memory accesses to a minimum by avoiding memory operands
  414.       and keeping instructions short.
  415.  
  416.     Since the HC cannot tell that the first bullet is a separate paragraph
  417.   from the second bullet it would put both bullets into one paragraph.    Any
  418.   bullet of two lines or more (assuming the intentation for the second line
  419.   of the bullet is different from the first) is OK.  Always add a backslash
  420.   to the end of single-line bullets.
  421.  
  422.     In general, if you cannot determine where a paragraph boundry is by
  423.   looking at the indentation of each line use a backslash to force a
  424.   paragraph break.
  425.  
  426.  
  427.  
  428.  
  429. ... Third version additional documentation:
  430.  
  431.   New Commands
  432.   ============
  433.  
  434.   ~Comment, ~EndComment
  435.     Use to start/end multi-line comments.
  436.  
  437.   ~CompressSpaces[+/-]
  438.     Turn on/off the automatic compression of spaces.  Used for data topics
  439.     and when reading normal topics with read_topic()
  440.  
  441.   ~Data=label_name
  442.     Starts a topic which contains data.  Think of it as a macro for:
  443.  
  444.       ~Topic=, Label=label_name, Format-, CompressSpaces-
  445.  
  446.     Data labels cannot be part of the document or displayed as online help.
  447.  
  448.   ~BinInc filename
  449.     Includes a file in binray format (no processing) into a data topic.
  450.     This command only works for data topics.  Example:
  451.     ~Data=TPLUS_DAT
  452.     ~BinInc tplus.dat
  453.  
  454.   ~DocContents
  455.     Defines the documents table of contents.  Text is allowed.    Table of
  456.     content entries have the following format:
  457.  
  458.       { id, indent, name, [topic, ...] [, FF] }
  459.  
  460.     id       is it's identification (ie, 1.2.1)
  461.     indent is the indentation level, (ie. 2)
  462.     name   is the text to display to display (ie. Fractint Commands)
  463.        If name is in quotes it is also assumed to also be the
  464.        title of the first topic.
  465.     topic  list of 0 or more topics to print under this item.  Entries
  466.        in quotes are assumed to be the title of a topic, other
  467.        entries are assumed to be labels.
  468.     FF       If this keyword is present the entry will start on a new page in
  469.        the document.
  470.     It isn't as complex as it sounds; see "~DocContents" in HELP.SRC for
  471.     examples.
  472.  
  473.  
  474.   Quoted implicit hot-links
  475.   =========================
  476.  
  477.     HC will ignore quotes areound implicit hot-links when searching for
  478.     the matching title.  This allows hot-links like:
  479.  
  480.       {"Video adapter notes"}
  481.  
  482.     intead of:
  483.  
  484.       "{Video adapter notes}"
  485.  
  486.     This is so that the hot-link page numbers don't end up inside the
  487.     quotes like: "Video adapter notes (p. 21)".  It also keeps quotes from
  488.     being separated from the text in the online-help.
  489.  
  490.  
  491.   Document printing
  492.   =================
  493.  
  494.     The new /p command-line option compiles the .SRC file and prints the
  495.     document.  It does NOT write the .HLP file.
  496.  
  497.     The old /p option (set swap path) has been changed to /r.
  498.  
  499.  
  500.    Printing the document
  501.    =====================
  502.  
  503.    The function prototype (in HELP.C) to print the document is:
  504.  
  505.     void print_document(char *outfname, int (*msg_func)(int,int),
  506.                 int save_extraseg);
  507.  
  508.    outfname is the file to "print" to (usually "FRACTINT.DOC"), msg_func
  509.    is a function which is called at the top of each page, and save_extraseg
  510.    is true if the data in the extraseg should be preserved.
  511.  
  512.    See print_doc_msg_func() in HELP.C for an example of how to use msg_func.
  513.    If msg_func is NULL no msg_func is called.
  514.  
  515.  
  516.    Printing from help
  517.    ==================
  518.  
  519.    There are hooks to print the document from a help topic by selecting a
  520.    "special" hot-link. I suggest a format like:
  521.  
  522.     ~Topic=Generating FRACINT.DOC
  523.  
  524.     Explain that selecting yes will print the document, etc...
  525.  
  526.     {=-2  Yes, generate FRACTINT.DOC now. }
  527.     {=-1  No, do NOT generate FRACTINT.DOC. }
  528.  
  529.    Selecting yes will generate the document and then return to the previous
  530.    topic.  Selecting no will simply return to the previous topic (like
  531.    backspace does.)
  532.  
  533.  
  534.  
  535.