... 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
runtime.
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 recompiled. 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
curlybraces ('{' 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.
best
appearance.
The first and last rows should be blank for the
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.
be produced by the table:
One
Four
Seven
Two
Five
Eight
Three
Six
The following text would
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, FormatTo 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[+/-]
Online[+/-]
Doc[+/-]
printed
L
L
help.
L
turns formatting on/off.
enables/disables display of text in the online
enables/disables display of text in the
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
FormatExclude=
Center[+/-]
effect if "FormatDisable=n" is in effect.
L
Resets FormatExclude to its global value.
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+,CenterModified commands
=================
Label=NAME
FF
replaces the ~(...) command
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
labels name.)
(The equal sign is not part of
Paragraph formatting
====================
The HC determines the end of a paragraph when it encounters:
o
o
o
o
a blank line.
a change of indentation after the second line of a paragraph.
a line ending with a backslash ('\').
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.
topics
and when reading normal topics with read_topic()
~Data=label_name
Starts a topic which contains data.
Used for data
Think of it as a macro for:
~Topic=, Label=label_name, Format-, CompressSpacesData 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.)