... 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 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.)