..This is the documentation in the HyperMake (earlier version
..MakeIPF) source format. You can generate a HTML or IPF file
..from this file. See README.1ST.

..If you want to take a look as a "beginner" nevertheless, here
..some hints:
..Dot commands are beginning with a dot and are only interpreted
..if the command is placed at the beginning of a line. A lot of
..dot commands here in this text are placed after a space, so 
..they are printed and not interpreted.
..Chapter headings are placed after a .n command (n is a heading
..level from 1 to 6). The character  marks words for the index and
..as a link target. :word1 word2: marks an expression of several
..words. The other special chars are toggles, e.g. italic font.

.TI Documentation HyperMake 3.00
.fu[]
.bt reddot
.ft
.IC
.1
Introduction

With HyperMake (earlier version "MakeIPF"), you can easily create HTML files or IPF files. Instead of editing the HTML or IPF files directly, you enter a more simple ASCII source text. Links are created automatically; windows of different headings levels can be shown simultaneusly (frames) with only one command; at the end of a chapter, links to subchapters are created automatically and a lot of more.

The version 3.0 is the first major release generating HTML files. From only one ASCII source you can generate both HTML and IPF files.

New in version 3.0 is the tables functionality (both HTML and IPF) and a reverse converting mode from IPF to HyperMake. You can use that if you have already written an IPF file.

Yet there's a Win32 (Windows 95 and NT). Future HyperMake versions will be available on other platforms, too.

HyperMake is not designed for writing a short homepage. It's useful for creating more complex homepages, scientific works or program documentation with content and index.

When using HyperMake, you have only to learn the much easier HyperMake source format. You can write HyperMake files with
 an ASCII-editor with automatic word wrapping
 an ASCII-editor without automatic word wrapping
 or an old DOS WordStar Version 3.4 or 4.

HyperMake has some powerful functions:

 Automatic linking and indexing
Marking a word or a phrase of several words with a special character will generate
- a link from all other occurrences of the word or phrase in the document to the marked position
- an entry in the index.

.IF HTMLDOC
 Automatic division into several HTML files
When creating HTML files, from one source file HyperMake creates several target files in a new folder. This improves the performance while viewing with browsers. Neither the author of the text nor the reader of the files notices the separation into several files.
.END

.IF IPFDOC
 Automatic generation of helptables
For OS/2 HLP files, in the HyperMake source file you can directly enter ID constants like "ID_buttonOK" to associate chapters of your HLP file with buttons of your program. HyperMake generates a helptable file you can include in your RC file.
.END

 Automatic Writing of links to subchapters
.afo
At the end of a window of a higher heading level, links to all  subchapters and to the next chapter at the same level will be created.

 Automatic arrangement of several heading level windows
With only one command, two or three heading levels are placed simultaneously on the screen (Frames). See window arrangement sample output.

 Simple creation of footnotes
The HTML footnotes are realized by frames, IPF footnotes appears in a small footnote window for each footnote text.

 Tables
You enter tables in the source text like in an ASCII text with a fixed font. HyperMake transforms this simple formatting to HTML or IPF tables.

 Automatic line drawing to generate boxes

 Short commands
- for heading levels
- for choosing fonts
- to include bitmaps within a line of text
- to generate unordered lists and ordered lists.

In this version 2.9 the tables functionallity (IPF and HTML) is not implemented yet. This is planned for the 3.0 version.

.2
HTML-files, Web-Browser and Internet

.in format HTML
.in HTML file
The Hypertext-Markup-Language HTML is a text file format where viewers ("browsers") are available for nearly all computer platforms. HTML files are ASCII files containing normal text and commands written in brackets <>. The most important feature of HTML files are links.

Normally, HTML files are placed on the Internet and not on local computers. Nevertheless, it's possible and useful to read local HTML files, e.g. program documentation.

The actual version of HTML is 3.2. HyperMake creates HTML files complying with this version. The most important new feature of HTML 3.2 are frames. HTML files created by HyperMake containing frames can be viewed with older browsers nevertheless, of course without frames functionality.

.2
IPF, INF and HLP-files

.in format IBM INF
.in format IBM HLP
.in format IBM IPF
.in IPF file
HTML browsers are slow. IBM INF and HLP files are compact binary files. The viewers of these files are more compact and very fast. IBM INF viewers are available for OS/2 (of course, that's the format of all OS/2 docu), for Win16 and for DOS. The Win16 viewer is part of the "Just add Warp" package, you need the files LIBIPFX.DLL, VIEW.EXE and VIEWH.HLP. The DOS viewer is part of IBM DOS 7 and there's also a freeware program (VIEW01.ZIP Compuserve OS2DF1).

To create IBM INF files, you need the IBM IPFC Compiler (IPF to INF). It is part of OS/2 development systems, and there's also a Windows version.[It's part of the IBM visual age C++ package.]

In comparison to HTML browsers the IBM INF viewers have got some powerful features with a particular benefits for large documents:

 the Index is part of the binary INF file format
 the content, too. Subchapters can be expanded and re-expanded like in a directory tree
 very fast text searching: Every word has only one occurence in the binary INF format. From this word there are pointers to the location of the text. You can search some MB of text in only one second - the user gets a window with all chapters containing the word.
 Several INF files can be put together by command line parameters of the viewer. The user sees one big help file with one content and one index.

All important HTML functionality like Tables, Frames, Graphics, is also part of the IBM INF format.

The contents of IBM INF and HLP files are described in a language called IPF, similar to HTML. It is powerful and supports nearly everything one might want to do. However, it is verbose and somewhat tedious to write. Hence, for example, people don't use cross-references (links) as often as desirable.

HyperMake helps you write IBM INF[The IBM Information format is a Hypertext-Format, especially for program documentation.] and HLP files[The HLP format is like the INF format, but enables links from the described program to the hypertext. HLP files are part of the program.]. HyperMake generates IPF[The IPF format (Information Presentation Facility) is the Source format to generate INF or HLP files.] files from a special HyperMake ASCII format. The automatically generated IPF file is the source file for the IBM program IPFC[IPFC generates INF- and HLP-files from the IPF source. IPFC.EXE is part of every programming development system for OS/2. At my system, the necessary files are IPFC.EXE, IPFC20.INF and IPFCEXMP.INF; there's also a directory IPFC with language-specific data.].

.1
Writing a file in the HyperMake format

.in Writing a HyperMake file
.FA verti 25
.2
Essentials

.3
Dot commands

The HyperMake format uses :dot command:s like old WordStar. A dot command is a complete line beginning with a dot, for example

.sfb
 .SF
.sf

sets the standard font to default. Dot commands aren't case sensitive. A lot of dot commands require parameters, for example

.sfb
 .LM10
.sf

will change the left margin to 10. You can leave a space between the dot command and the parameter.

The line

.sfb
 ..comment
.sf

will be ignored.

If dot commands have got more than two characters, you can abbreviate them to the first two chars.

If the dot of the dot command isn't placed in column 1, the dot command is not interpreted and is treated as part of the text. 

In this hypertext, you will find a dot command summary.

.IF IPFDOC
.3
IPF-commands

.sfb
 .:ipfcommand.
 .:ipfcommand. expression
.sf

You can enter an IPF command directly (that will be an exception, because most important functions are in the much easier HyperMake format).
.END IPFDOC

.IF HTMLDOC
.3
HTML commands

The following two commands are interesting for you if you are familiar with HTML commands. Perhaps you prefer using original HTML commands sometimes.

.sfb
 .HTML

 <HTML-commands> running HTML text

 .HYPERMAKE
.sf

You can enter HTML text and commands directly, e.g. for :Java-Script:s. The text won't be interpreted as HyperMake source text (e.g. dot commands would be printed) and is placed in the HTML file directly.

The second command to include HTML commands is directly using <HTML tags> in the running HyperMake text. With the dot command

.sfb
 .HC on
 .HC off
.sf

(HTML command) you can use HTML tags by using the HTML specific <HTML tag> syntax.

Between the HTML brackets < > HyperMake won't change the characters. The default setting is off. That means, the < > chars will be printed and are not interpreted as a HTML command. You can turn ~.HC~ on at the beginning of your source text and need not change this setting until you want to use the < > chars in normal text.
.END HTMLDOC

.3
Toggles

.it toggle character
.in toggle
In the ini file you can set some toggle chars. If you have chosen "*" for "bold" and "@" for italic, you can write:

.sfb
This *part of this sentence* is very important.
.sf

And you will get: 

This part of this sentence is very important.

You also can mix some toggles:

.sfb
This is *bold and @also italic* and only italic@.
.sf

And you will get:

This is bold and also italic and only italic.


You have to think about toggle chars you don't need very often in the normal text. If you want to use a toggle char as a normal visible character, you have to type it twice:

.sfb
@My Email Address:@

100661.626@@compuserve.com
.sf

A good choice would be the control chars below 32 when using IBM codepage, if your editor supports them.[of course, without 0x0A, 0x0D, 0x1A (decimal 10, 13, 26)]. For HTML, the chars above ASCII decimal 127 are useful.

.3
Handling of Returns

.in Handling of Returns
.in ASCIISOFTRET
.in ASCIIHARDRET
Writing a text by using an ASCII editor, you can choose between two kinds of handling Returns. With the ASCIIHARDRET setting in the ini file, every Return will be treated as a new line. Use this setting if your editor does not put Returns in wrapped lines. The OS/2 E and EPM editors support this function.

Use ASCIISOFTRET if your editor puts Returns on all line endings. This will only treat a Return as a new line, if
 there are two Returns behind each other (i. e. an empty line)
 the last character in the line is . ! ? : ;

.IF WORDSTARDOC
Using DOS WordStar, such problems don't exist, because WordStar distinguishes between soft and hard Returns.
.END

On my homepage, you will find Macro files for Winword which helps you converting Winword documents to HyperMake source text.

.2
Beginning

Every document has one title. The title will be shown as title of the main window and in the tasklist.

.sfb
 .TI Documentation of my program
.sf

sets the title in HTML files or INF files. Every HyperMake INF source text should begin with the title dot command, before the first heading.

.IF HTMLDOC
HyperMake creates several HTML files from one source text file. All files gets the same title.
.END

.afb
.IF IPFDOC
In HLP files, the title is set in your program source code, see function InitHelp. The TI dot command title is ignored.

By default, HLP files don't have the Pushbuttons "Contents", "Back" and "Forward" that INF files have. If you want to have the same Pushbuttons in HLP files as in INF files, enter the dot command

.sfb
 .<>
.sf
.END

.2
Headings

Starting an IBM INF file or an HTML document created by HyperMake, you will get the content.

.IF IPFDOC
In the contents window of IBM INF files, you can open and close sub-chapters like a directory tree. The text under every heading fills a separate window.
.END

.IF HTMLDOC
When HyperMake creates HTML files, you will get a contents file with the filename INDEX.HTML.
.END

You can arrange your text with heading levels like you would in a scientific work:

.sfA
first heading
    first sub-heading
    second sub-heading
         first sub-sub-heading
         second sub-sub-heading
    third sub-heading
second heading
.sf

In the HyperMake format, the headings are written like

.sfb
 .1
 first heading

 .2
 first sub-heading

 .2
 second sub-heading

 .3
 first sub sub-heading

 .3
 second sub sub-heading

 .2
 third sub-heading

 .1
 second heading
.sf

On the next line after the dot command for the heading level, you can enter the heading text.



Heading text can be longer than one line. Using the ASCIISOFTRET source format, you have to enter two Returns after writing a heading text; the text can be longer than one line.

In a normal document, you would use numeric headings:

1. first heading
   1.1 first sub heading
   1.2 second sub heading
          1.2.1 first sub sub heading
          1.2.2 second sub sub heading
   1.3 third sub heading
2. second heading


.IF IPFDOC
The Text behind a heading dot command is limited to approx. 200 chars[The IPFC compiler would create an error message when using more than 200 chars.], but you will see only 70 to 120 chars, dependent of the size of the INF window on the screen.
.END

At the beginning of a document, normal text can only be written after using the first heading dot command.[Every heading represents a window. There cannot be written any text without creating a window. The IPFC compiler would create an error message.]

You are allowed to use up to 6 heading levels.

.IF HTMLDOC
With the ini file setting content level, you can define the number of levels shown on the content page.

Most HTML browsers are using a very small font for heading text with level 5 and 6 - smaller than the normal text. Of couse, that's not acceptable. If you want to create HTML files with 5 or 6 heading levels, you should use bigger fonts to the level 5 and 6 or for the levels from 4 up to 6.


~.HS 123234~

or

~.HS 112233~

changes the size of the fonts of levels 1 to 6.

The default setting is:

~.HS 123456~
.END

.3
Links to subchapters

.in Link to subchapters
When a chapter has got subchapters, links to subchapters and a link to the next chapter with the same heading level are automatically created. You can set the text "subchapters" and "next chapter" and in the ini file, setting ~text for link to...~.

By default, the heading text links of the sub chapters are written line by line. E.g. in a homepage, it can be useful to save vertical space.[In a German magazine you could read that 90% of the internet surfers don't use scrollbars.] In this case writing the heading texts without Return is recommended.

With the dot command ~.SC~ (Subchapter separation characters) you can change the appearance of the links to subchapters.

~.sc chars~

fits the characters "chars" between the subchapters heading text instead of a Return. The command

~.sc RETURN~

resets the default setting with one Return between each heading text.

.sfb
 .btx blackdot
 .sc  x 
 .2
 heading text of the first sub chapter

 .sc RETURN
.sf

Instead of x, you have to use a character you won't need in your text. These commands will place the graphics file BLACKDOT.GIF in the heading text.

.sfb
 .sc RETURN RETURN
 .sc PARAGRAPH
.sf

The two commands have got the same effect: They force an empty line between each heading text.

.sfb
 .sc LIST
.sf

writes the sub chapter headings as an unsorted list.

.3
Window arrangement (Frames)

.in window arrangement
.in Frames
With only one dot command, you are able to divide the hypertext screen into two or three parts to show two or three heading levels simultaneously.

.sfL
Arranging two heading levels
.sf

With the dot command Window Arrangement

.sfb
 .WA verti 30
.sf

followed by a normal heading level dot command, the main window is divided vertically into a left window (30% of the main window) and a right window (the remaining 70%). The left window contains the chapter with the heading level entered after the WA dot command (called the "main chapter" below). In the right window the first sub chapter of the main chapter appears.

Note the spaces between the parameters of the window arrangement dot command. 

When using window arrangement, I strongly recommend leaving the automatic link to subchapters function turned on in the ini file.

.sfb
 .WA hori 40
.sf

divides the main window horizontally. The main chapter gets the top window (40% of the main window), the subchapter the bottom window (the remaining 60%).

You can enter percent values from 10 to 90.

With the commandline parameter ~/NOFRAMES~, this dot command won't be interpreted.

For a sample arrangement of two heading levels see dot command summary and ini file.

.sfL
Arranging three heading levels
.sf

This functionality is only available so far for creating IPF files.

.IF IPFDOC
In the same way, you are allowed to arrange three heading levels. Now you have to enter a hori and a verti value simultaneously.

.sfb
 .WA hori 40 verti 30 III
.sf

.afb
The first hori/verti value divides the main window completely from left to right / from top to bottom. The second hori/verti value divides again one of the parts into two parts, so you will get three windows: two smaller windows and a bigger window. You can choose which heading level gets the bigger window. Possible settings are ~I~ and ~III~. So you can choose between four kinds of arrangements: 

.liXY

            verti hori           hori verti
       
        Ŀ   Ŀ
                II               I        
  I       I  Ĵ   Ĵ 
                III        II     III    
                                         
           
       
        Ŀ   Ŀ
          I                 I     II     
        Ĵ             Ĵ 
 III            III                       
         II                     III       
                                           
           
.li

~I~ is the main chapter, ~II~ the subchapter of the main chapter, ~III~ the sub sub chapter of the main chapter.

The window arrangement dot command is active for one main chapter with its sub and sub sub chapters.

The window arrangement only works when the main chapter window is activated directly. When linking from somewhere to the sub sub chapter or using the contents window to get directly into the sub sub chapter (~III~), the screen won't be divided. When linking to a ~II~ window, the ~III~ window also appears, but the space for the ~I~ window will not be used.

If you want to arrange three heading levels simultaneously, but not every chapter contains sub chapters, the level ~I~ window should become the bigger window. That means ~I~ and not ~III~ should be used in the WA dot command. Then the window of level II also takes the room of the level III window, if the level III does not exist.

.4
Sample Input

.sfz
 .WA verti 50 hori 40 I
 .4
Sample Output

The main chapter with links to subchapters.

 .5
first sub chapter

The first sub chapter.
3 frames in HTML are not supported in HyperMake 3.0.

 .6
first sub sub chapter

The first sub sub chapter of the first sub chapter.

 .6
second sub sub chapter

The second sub sub chapter of the first sub chapter.

 .5
second sub chapter

The second sub chapter.

 .6
first sub sub chapter

The first sub sub chapter of the second sub chapter.

 .6
second sub sub chapter

The second sub sub chapter of the second sub chapter.
.sf

.FA verti 40 hori 50 I
.4
Sample Output

.in window arrangement sample output
The main chapter with links to subchapters.

.5
first sub chapter

The first sub chapter.
3 frames in HTML are not supported in HyperMake 3.0.

.6
first sub sub chapter

The first sub sub chapter of the first sub chapter.

.6
second sub sub chapter

The second sub sub chapter of the first sub chapter.

.5
second sub chapter

The second sub chapter.

.6
first sub sub chapter

The first sub sub chapter of the second sub chapter.

.6
second sub sub chapter

The second sub sub chapter of the second sub chapter.
.END IPFDOC

.FA verti 75
.2
Fonts

.in font
.sfL
:Standard Font:
.sf

You can choose a font with the dot command standard font

.sfb
 .SFX
.sf

.afb
~X~ is a font character from A to Z and from a to z (case sensitive!) which represents a specific

 font type (only IPF) (Courier, Tms Rmn, Helv...)
 size
 codepage (only IPF)
 Phrase Element (only HTML)
 foreground color
 background color (only IPF).

You can assign different fonts, sizes and colors to each of the 2 x 26 chars in the ini file.

There are two other font attributes (see ini file). ~OmitLinks~ is described in linking, Omitting links; ~LineStandard~ in line drawing.

To set the standard font to default, use the dot command without parameter:

.sfb
 .SF
.sf

.IF HTMLDOC
.sfL
:Phrase Element:s
.sf

HTML Phrase Elements and fonts need some explanation.

When writing a text in typical HTML format, you aren't able to choose fonts like "Courier" or "Helvetica". The concept of HTML is different - perhaps the HTML file is viewed on a computer where the "Courier" font isn't available. The user should choose how the information is shown - the author only defines the purpose of the text, e.g. CODE for program code (a fixed font will be used). The browser chooses a font which harmonizes with the purpose.

Nevertheless, you can define fonts. But this functionallity is not supported by every browser and you can't be sure that the font you have chosen is available on every operating system. To get a realistic chance to hit a font supported by the browser or the operating system, you have to enter more than one fonts, e.g. ~Arial,Helv,Helvetica,Univers~. HyperMake requires at least two fonts, divided by comma, without spaces. If you want to enter a font with a space in the font name like "Tms Rmn", write an underscore _ instead of the space.

I recommend not using HTML fonts, because you don't know whether the font is available on the operating system of the user. And it's patronizing the user who is no more able to choose his favorite font.

HTML knows the following Phrase Elements:
PRE ADDRESS EM STRONG DFN CODE SAMP VAR CITE

PRE has got a special effect: If a font with  Phrase element PRE is chosen, all Carriage Returns of the source text will be shown in the HTML file - automatic formatting of running text is disabled.

And here is the purpose of the other Phrase elements:

~EM~ basic emphasis typically rendered in an italic font 
~STRONG~ strong emphasis typically rendered in a bold font 
~DFN~ defining instance of the enclosed term 
~CODE~ used for extracts from program code 
~SAMP~ used for sample output from programs, and scripts etc. 
~VAR~ used for variables or arguments to commands 
~CITE~ used for citations or references to other sources 

.sfL
Formatting attributes
.sf

You can define a font with a ~center~ attribute in the ini file, so you do not need the output centered dot command.

.IF IPFDOC
For IPF, you can define a font with ~PRE~, so you do not need formatting dot commands. ~PRE~ will turn formatting off.
.END

.sfL
:Alternate Font:
.sf

.it alternate character
.AFb
Like ~.SF~ you can use ~.AF~ alternate font. The alternate font will be activated between two occurrences of the alternate toggle char, assigned in the ini file.

So you can change font and color in one line:

.AFZ
That ~d~o~e~s~n't~ l~o~o~k~ very good.
.AF

.IF IPFDOC
The IPFC compiler won't accept more than 14 fonts in one document.

I recommend using not more than 3 or 4 different fonts. I also recommend you to use the default font for normal text, because the default font is a proper font on every screen.
.END

A font will be active till the next font dot command, even through headings.

.AFb
Alternate fonts should be only active within a paragraph. To write more than one paragraph in another font, please use the ~.SF~ command.

.IF HTML
.3
Phrase element samples

The output of phrase element commands depends on the browser.

.HTML
<ADDRESS>Sample text with Phrase element ADDRESS</ADDRESS><br>
<PRE>Sample text with Phrase element PRE</PRE><br>
<EM>Sample text with Phrase element EM</EM><br>
<STRONG>Sample text with Phrase element STRONG</STRONG><br>
<DFN>Sample text with Phrase element DFN</DFN><br>
<CODE>Sample text with Phrase element CODE</CODE><br>
<SAMP>Sample text with Phrase element SAMP</SAMP><br>
<VAR>Sample text with Phrase element VAR</VAR><br>
<CITE>Sample text with Phrase element CITE</CITE><br>
.HYPERMAKE 
.END

.3
Font samples

.in Font samples
.IF HTMLDOC
HTML only support size, not the font type.
.END

.fm off
.sfc
Tms_Rmn 12
.sfd
Tms_Rmn 17
.sfe
Tms_Rmn 25

.sff
Helv 12
.sfg
Helv 17
.sfh
Helv 25

.sfb
Courier 12
.sfA
Courier 15
.sfk
Courier 25
.sf
.fm on

.3
Color samples

.in Color samples
.IF IPF
IPF Colors: 

foreground

.:color fc=default.
default
.:color fc=blue.
blue
.:color fc=cyan.
cyan
.:color fc=green.
green
.:color fc=neutral.
neutral
.:color fc=red.
red
.:color fc=yellow.
yellow
.:color fc=black.
black
.:color fc=default.

background

DEFAULT
.:COLOR BC=BLUE.
BLUE
.:COLOR BC=CYAN.
CYAN
.:COLOR BC=GREEN.
GREEN
.:COLOR BC=NEUTRAL.
NEUTRAL
.:COLOR BC=RED.
RED
.:COLOR BC=YELLOW.
YELLOW
.:COLOR BC=BLACK.
BLACK
.:color bc=default.
.END IPF

.IF HTMLDOC
HTML colors:
.END

.HTML

</font><br>
<font size=4 color=Black>Black<br></font>
<font size=4 color=Silver>Silver<br></font>
<font size=4 color=Gray>Gray<br></font>
<font size=4 color=White>White<br></font>

<font size=4 color=Maroon>Maroon<br></font>
<font size=4 color=Red>Red<br></font>
<font size=4 color=Purple>Purple<br></font>

<font size=4 color=Fuchsia>Fuchsia<br></font>
<font size=4 color=Green>Green<br></font>
<font size=4 color=Lime>Lime<br></font>

<font size=4 color=Olive>Olive<br></font>
<font size=4 color=Yellow>Yellow<br></font>
<font size=4 color=Navy>Navy<br></font>

<font size=4 color=Blue>Blue<br></font>
<font size=4 color=Teal>Teal<br></font>
<font size=4 color=Aqua><br></font><font>
.HYPERMAKE

Older Browsers don't support colors.

.2
Unordered lists and ordered lists

.it unordered list
The following text represents an unordered list:

 Style
- font (default, Tms_Rmn, Helv, Courier, System_VIO)
- size
 Color
- foreground color (default, blue, cyan, green, neutral, red, yellow, black)
- background color (same colors as foreground color).


Resize the window with your mouse and observe the formatting of the text. You won't get this effect when using normal characters and spaces.

You can't change the list chars the IPFC compiler generates / the HTML browser chooses.

The input of ordered lists is very similar to unordered lists.

The HTML and IPF command "Definition List" is not supported directly. You can emulate it with the HyperMake auto margin command.

.IF WORDSTARDOC
.3
Using DOS WordStar

.afb
WordStar knows :soft space;s ~~. Soft spaces can be created in WordStar with the command ^OG.[Soft spaces are shown in WordStar with "" or a centered dot or another special char. If you reformat a Paragraph by pushing ^B, soft spaces will be deleted. Using Tab (^I) won't produce soft spaces.]

There are no definitive list chars for the different list levels like using an ASCII editor. Instead, using soft spaces is necessary.

.sfb
Style
-font (default, Tms_Rmn, Helv, Courier, System_VIO)
-size
Color
-foreground color (default, blue, cyan, green, 
neutral, red, yellow, black)
-background color (same colors as foreground color).
.sf

All list chars have to be between soft spaces; in the first list level, soft space(s) have to follow the list char. Once position and character of a list char is defined, you aren't allowed to change it. The following two examples would create two error messages while running HyperMake:

.sfb
Style
-font (default, Tms_Rmn, Helv, Courier, System_VIO)
-size (wrong position)
Color
-foreground color (default, blue, cyan, green, 
neutral, red, yellow, black)
*background color (wrong character)
.sf

After writing a normal paragraph without list function, for the next unordered list you can use other list char characters and positions.

.3
Using an ASCII editor

.END WORDSTARDOC
.in unordered list with an ASCII editor
.it list character
In the ini file you can define list chars. List chars have to be at the beginning of a line. If the list chars in the ini file are * for the first list level and = for the second level, then to generate the list from the last page, you have to enter

.sfb
* Style
= font (default, Tms_Rmn, Helv, Courier, System_VIO)
= size
* Color
= foreground color (default, blue, cyan, green, neutral, red, yellow, black)
= background color (same colors as foreground color).
.sf

You can add list chars in the ini file for further levels. Other useful chars are the square Alt-254, the graphical double/single slash Alt-205/Alt-196 and the normal slash -.

To enter normal text after writing an unordered list, you have to enter a paragraph.

You can put more spaces before and after the list char, they will be ignored. The same result as above will be produced by:

.sfb
  *   Style
      =   font (default, Tms_Rmn, Helv, Courier, System_VIO)
      =   size
.sf

.3
Ordered lists

.it ordered list
.afo
An ordered list counts with 1., 2., 3., and, in the second list level, with a., b., c. The third list level will be numeric again and so on. You can't change this.

To create an ordered list, you first have to proceed like writing an unordered list. ~With the dot commands ordered list and unordered list~
.afb

.sfb
 .OL
 .UL

.sf
.afo
you can switch between ordered and unorderd lists. So you can use this two commands as brackets to get an ordered list. The default setting is ~unordered list.~

.2
Including Bitmaps

.in graphic
To include a big bitmap centered, you can use the dot command bitmap

.sfb
 .BM filename
.sf

.IF IPFDOC
If you write the filename without extension, ".BMP" will be automatically added when creating IPF files. IPFC also supports OS/2-MET-files. [To convert from GIF to BMP, I recommend the freeware GIF2BMP (Graham Welland, September 1989, OS/2 16 bit)]
.END

.IF HTMLDOC
When creating HTML files, ".GIF" is automatically added, if you write the filename without extension.
.END

.afb
Instead of a filename, the BM dot command accepts also the keywords ~LEFT~ ~RIGHT~ ~CENTER~ (CENTER only IPF). The default setting is ~LEFT~. The setting is active until you change it a second time. E. g. to include a graphics file with right alignment, enter:

.sfb
 .BM RIGHT
 .BM filename
.sf

With the second dot command :bitmap text:, you can include bitmaps in text.

.sfb
 .BTX filename
.sf

.bt box
~X~ represents a :bitmap char:, a special character you don't need in your text. This character will be replaced in your text by the bitmap "filename". Note that bitmaps  are bigger than characters, so you will get a greater line hight at the lines with included bitmaps, even if the bitmap is as small as a character. Block chars like  (Alt-219),  (Alt-220),  (Alt-223) are useful bitmap chars (IBM codepage).

You are allowed to define several bitmap chars simultaneously.

To deactivate a character-bitmap definition, you can enter

.sfb
 .BTX
.sf

without a filename.

.FA hori 35
.2
Linking and Indexing 

.in Link
.in Index
.3
Automatic linking and indexing

Linking is the most powerful function of HyperMake. When writing an HTML file or IPF file directly, you have to create every link by yourself - so if you write a document of 1 MB about workgroup computing and you have the occurrence of the phrase "workgroup computing" one thousand times, it's your job to create one thousand links...

With HyperMake, your job is only to mark one occurrence of a single word or a phrase of several words with a special character (index char). All other occurrences will get a link to the marked occurrence (:link target:). Simultaneously, it will be placed in the index.

.IF HTMLDOC
When creating HTML files, an index in alphabetic order is written in a seperate HTML file. This index file has got two kinds of appearence: A simple index and an :extended index:. The simple index is for only a few index entries, the extended index is for a bigger number of entries. The extended index has got links for the letters A to Z, the simple index not. You can enter the number of index entries to activate the extended index in the ini file, entries for extended index.
.END

.3
Marking a single word, Changing the index char

.it index char
.sfL
Marking a single word
.sf

You can mark a single word for linking and indexing with the index char, defined in the ini file.

.sfb
A #workgroup is a group of people...
.sf

Note: Do not use index chars in headings, use automatic duplication of heading text instead.

.sfL
Changing the index char
.sf

You also can change the index char in the text by using the dot command index char

.sfb
 .IC@
.sf

This will change the index char from the actual setting, for example ~#~, to ~@~.

.3
Marking a phrase of several words in the running text

When using the index char, only one word will be marked. A word ends with the first character which is not a letter or "-". (Characters which have to be handled like letters can be defined in the ini file, extended letters).

To mark a phrase, you have to use ":" as brackets:

.sfb
Today, the #:security of computers: is...
 ...
Nevertheless, the #:security of mainframes: can be...
 ...
But the #:usability of computers; has to...
.sf

In the index, it will appear

.sfC
computers, usability of
security
    of computers
    of mainframes
.sf

Note the difference between the first/second and the third example: A "#:XXXX:" will use the first word of the phrase as the :leading word:, a "#:XXXX;" the last word. The leading word is the word which determines the alphabetic order in the index. The leading word does not refer to the linking function.

If there is only one occurrence of a leading word like

.sfC
computers
    usability of
.sf

the HyperMake entry in the index will be:

.sfC
computers, usability of
.sf


You are allowed to use the "colon brackets" to crop endings:

.sfb
The importance of #:computer:s is growing...
.sf

In the index "computer" will appear without "s", also the link target will be "computer" and not "computers".

.3
Marking a phrase outside the running text

With the dot command INdex

.sfb
 .IN phrase
.sf

you can place a word or a phrase in the index and define it as a link target. Because it's a dot command, "phrase" won't be printed. You can use this command, when the phrase you want to place in the index and you want to link doesn't appear explicitly in the running text.

Normally, the first word of the phrase will be the leading word. If you want to make the last word the leading word like using the brackets colon-semicolon in running text, you can use the dot command index turned.

.sfb
 .IT usability of computers
.sf

.in index turned
When the phrase in the dot command IN or IT ends with a space, links won't be created, but the phrase is placed into the index. You can use this bug as a feature.

.3
Handling of endings, uppercase and lowercase letters

.sfL
:Handling of endings:
.sf

What to do when the source link word is "computers" and the marked word is "computer" without "s"? In this case, HyperMake will create the link nevertheless, because the ending "s" is defined in the ini file (see endings of words). Note when using other languages you have to edit the ini file with the correct endings.

Marking a word with an ending is not recommended, because when the word occurs without the ending, the link won't be created.

To find the corresponding word even in the case "query" "queries", HyperMake crops the last letter of the word when it's a vowel [letters a e i o u y] (in this case "y"). That's the correct method for the english and german language (and I hope it's okay in the other languages, too).

.sfL
Uppercase and lowercase letters
.sf

Links are created, regardless of whether the first letter in the target link phrase is capitalised. If other chars than the first letter are different, the link won't be created. Sample:

.sfb
 .IN Word
.sf

Links are created to ~Word~, ~word~, but not to ~WORD~.

.3
Marking a word several times

HyperMake expects a word or a phrase to be marked only once. If you mark a word several times, it will appear several times in the index, and the link target will be the first marked phrase.

.3
Omitting links

.in omitting links
Of course, links are omitted when the link would point to the same window (chapter). Links are also omitted when there is more than one occurrence of the target link phrase in the paragraph. For example dot command dot command dot command - only the first occurrence of "dot command" in the paragraph gets the link.

If you want to omit several links of the same phrase in the whole window and not only in the same paragraph, you can edit the ini file, switch no more links in. 

.afb
Sometimes it can be useful to omit links font specific, for example in sample text. You can define fonts which omit links automatically with the Font switch, setting ~OmitLinks~ in the ini file.

Of course you are allowed to define another font with identical parameters, but with the OmitLinks setting. So you can omit links without really changing the font.

.IF IPFDOC
.3
External links (IPF)

:External links: are links to chapters of other INF or HLP files. To create such external links, you have to edit

 the ini file
 the file which is shown when using the link (link target file)
 the file from where the link is executed (link start file).

External links are using the HyperMake function panel ID. But you need not read the panel ID chapter.

.sfL
1. Ini file
.sf

After "Panel ID filename =" in the ini file, you have to enter a file extension beginning with *. like

.sfb
Panel ID filename = *.PAN
.sf

Compiling the link target file with HyperMake automatically generates a panel ID file with the file name of the source text file and the extension PAN. This panel ID file is used by HyperMake when compiling the link start file.

.sfL
2. Link target file
.sf

When indexing headings, HyperMake assigns numbers to the headings automatically beginning with 1. It would be tedious to remember a heading ID number like 237 - and the number changes when a new heading is inserted - so instead of a ID number, you enter an easy to remember constant like Chapter_beginning. With the dot command

.sfb
 .ID Chapter_beginning
.sf

in the link target file, the chapter gets this ID name, e.g. "Chapter_beginning", where the dot command is placed, see file SAMPLE. All these ID names are placed in a file Sourcefilename.PAN, or with another extension, depending on the entry in the ini file. This panel ID file is used by HyperMake when compiling the link start file.

.sfL
3. Link start file
.sf

In the file where the external link is executed from, the ID dot command of the link target file has to be repeated. Then the dot commands for normal links .IN and .IT (index turned) are used as usual. These dot commands are placed between two new .EX dot commands.

.sfb
 .EX filename.inf
 .ID Chapter_beginning
 .IN expression
 .EX
.sf

After the EX dot command, you can enter the filename of the external hypertext file. Note that the extensions INF and HLP are allowed. All following ID, IN and IV dot commands are referenced to the external file until EX is entered with a new filename or without any parameters. You must not write normal text between the two EX commands.

All expressions "expression" in the link start file are getting an external link to the chapter of the file filename.inf, marked with the ID dot command ".ID Chapter_beginning".

It does not matter where the .EX - .EX block is placed in the link start file.

Pascal programmers have to pay attention: the constant following the ID dot command is case sensitive!

Always take a look at the date of the IPF files: If you change the link target file, HyperMake has to compile this file before compiling the link start file - because of updating the panel ID file.

When entering a filename

.sfb
 .EX filename.inf
.sf

you normally should not enter drive letters and directory names, because on several computers the file can be located at different drives and directories. You need not enter any directory names if the link target file is located in the same directory as the link source file. You won't have any problems either, if the directory appears after "SET BOOKSHELF" in the file CONFIG.SYS. If these two possibilities do not work, you should use environment variables.

Try the sample external links or click to the expressions chancellor, SPD and CDU. While writing this hypertext (that's the link start file) I have entered somewhere the following commands:

.sfb
 .EX sample.inf
 .ID chapter_chancellor
 .IN chancellor
 .ID chapter_political_parties
 .IN SPD
 .IN CDU
 .EX
.sf

.EX sample.inf
.ID chapter_chancellor
.IN chancellor
.ID chapter_political_parties
.IN SPD
.IN CDU
.EX E.EXE SAMPLE.TXT
.IN file SAMPLE
.EX

In the file SAMPLE which is the link target, you also can find the two ID dot commands in the specific chapters about chancellor and political parties.
.END IPFDOC

.IF HTMLDOC
.3
External links (HTML)

With HyperMake you can define a word or a phrase getting a link to an URL. That means all specific words/phrases in the document are pointing to a specific internet address. For example if all occurences of "Netscape" and "Netscape-Browser" should point to the Netscape page in the internet, you have to enter: 

.sfb
 .URL http://home.netscape.com
 .IN Netscape
 .IN Netscape-Browser
 .LOCAL
.sf

.URL http://home.netscape.com
.IN Netscape
.IN Netscape-Browser
.LOCAL

Note that the well-known IN-commands have to be placed between a ".URL" and a ".LOCAL" command. So before writing normal text, don't forget the ".LOCAL" command. I recommend to place all these URL links at the beginning or end of the text.
.END HTMLDOC

.IF IPFDOC
.3
Launching programs by links (only IPF)

.it Launching programs
.in launch program
Similar to external links, you can create links to external programs, that means launching programs.

.sfb
 .EX mppm.exe c:\mmos2\movies\macaw.avi
 .IN parrot
 .EX E.EXE SAMPLE.TXT
 .IN file SAMPLE
 .EX
.sf

.EX mppm.exe c:\mmos2\movies\macaw.avi
.IN parrot
.EX E.EXE SAMPLE.TXT
.IN file SAMPLE
.EX 
The parrot is a bird. (The link "parrot" is only activated if you have installed multimedia.) With the link to the file SAMPLE the system editor is started - perhaps you already have noticed this in the last chapter.

If the user clicks to "parrot" or "file SAMPLE", the external program is launched. In the EX dot command, the parameters behind the program filename are optional. Program name and parameter are divided by a space character. The extension ~.EXE~ has to be entered! You can also launch batch files with the extension ~.CMD~ or DOS programs with the suffix ~.BAT~ or ~.COM~.

If the files are not located in the same directory at different computers, you should use environment variables.

You can enter several IN dot commands after one EX command, for example to get links with the expression "parrot" and "bird movie".

To use an expression like "CONFIG.SYS" or "bird (movie)" as a link target, the dot and the parenthesis have to be defined as extended letters.

.4
Environment variables

.in environment variable
When creating external links and when launching programs, environment variables can be useful and necessary.

If you want to use an INF file on different computers, directory names should be substituted by environment variables, e.g. %MMVIDEO%. On every computer using your hypertext, the file CONFIG.SYS should have for example the following entry:

.sfb
SET MMVIDEO=C:\MMOS2\MOVIES
.sf

In the HyperMake source file, you can use this variable:

.sfb
 .EX mppm.exe %MMVIDEO%\macaw.avi
 .IN parrot
 .EX
.sf

OS/2 replaces the expression %MMVIDEO% with the drive and directory name listed in the CONFIG.SYS.

In the same way you can create external links.

But take care of the directory names ending with semicolon:

.sfb
SET MMBASE=C:\MMOS2;
.sf

In this case the environment variable does not work and the link won't be created.

.EX view.exe cmdref.inf
.IN OS/2 commandline reference
.EX
For environment variables, take a look at chapter "SET" in the OS/2 commandline reference.
.END IPFDOC

.2
duplication of heading text

.in duplication of heading text
It's often necessary to use the heading text as a link target, to place it into the index and - interesting for IPF - to duplicate the heading text in the text window with a bigger or colored font:

.sfb
 .3
heading text

 .IN heading text
 .sfX
heading text
 .sf
.sf

You can shorten this tedious job: Using the new dot command DuPlicate

.sfb
 .dpX
.sf

duplicates the heading text at the beginning of the text window, in all heading levels.
.IF IPFDOC
That's useful if you write long heading text, because in the titlebar of INF files only the first 70 characters are shown on average.
.END

You can omit specific characters in the index and when duplicating heading text with the ini file setting index filter.



.sfb
 .dpX34
.sf

duplicates heading text only in heading level 3 and 4.

.sfb
 .dp-
.sf

turns off the duplication of heading text for all heading levels.

.sfb
 .dp-234
.sf

deactivates the duplication functionality only in the heading levels 2, 3 and 4.

.sfb
 .dp#
.sf

the heading text becomes a link target. Writing the heading text after the IN dot dommand is no longer necessary. Instead of # you can also write the index char you have chosen in the ini file.

.sfb
 .dp##
.sf

In addition to the last sample, the heading text is also listed in the index. But be carful with this function, because you will get a redundancy of information in the contents and the index.
.IF IPFDOC
And a big index can dramatically slow down a (very big) HLP or INF file!
.END

.sfb
 .dp3##,
 .3
Smith, John
.sf

in the text window (duplicated text), "John Smith" is shown, and that's also the link target. But in the window heading, the contents and the index, "Smith, John" is written.

You can combine any of these commands, the order makes no difference.

.3
Sample input

.sfz
 .fa verti 30
 .dp4R#,
 .3
Sample output

German federal chancellors since 1949

(CDU, SPD and chancellor are external links. Font R is defined in the ini file.) 

 .4
Adenauer, Konrad

1949-1963, CDU, first chancellor after the second world war. His successor was Ludwig Erhard.

 .4
Erhard, Ludwig

1963-1966, CDU, Successor of Konrad Adenauer. Second chancellor of the Federal Republic of Germany. He was predecessor of Kurt Georg Kiesinger.

 .4
Kiesinger, Kurt Georg

1966-1969, third chancellor of CDU, leader of the "big coalition" of the parties CDU and SPD. Successor of Ludwig Erhard.

 .4
Brandt, Willy

1969-1974, first chancellor of the SPD.

 .4
Schmidt, Helmut

1974-1982, chancellor of the SPD. Successor of Willy Brandt.

 .4
Kohl, Helmut

chancellor of the CDU since 1982 till yet. His predecessor was Helmut Schmidt.
.sf

.fa verti 30
.3
Sample output

.in sample duplication heading text
.in sample external links
.dp4R#,
german federal chancellors since 1949

(CDU, SPD and chancellor are external links. Font R is defined in the ini file.) 

.4
Adenauer, Konrad

1949-1963, CDU, first chancellor after the second world war. His successor was Ludwig Erhard.

.4
Erhard, Ludwig

1963-1966, CDU, Successor of Konrad Adenauer. Second chancellor of the Federal Republic of Germany. He was predecessor of Kurt Georg Kiesinger.

.4
Kiesinger, Kurt Georg

1966-1969, third chancellor of CDU, leader of the "big coalition" of the parties CDU and SPD. Successor of Ludwig Erhard.

.4
Brandt, Willy

1969-1974, first chancellor of the SPD.

.4
Schmidt, Helmut

1974-1982, chancellor of the SPD. Successor of Willy Brandt.

.4
Kohl, Helmut

chancellor of the CDU since 1982. His predecessor was Helmut Schmidt.

.2
Tables

.in Table
HyperMake 3.0 supports easy creation of tables. You enter tables like you do it in an ASCII text with a fixed font:

.sfb
 .TA Sample
 first cell   numbers    -----third and fourth-----
 first cell      97.96   third cell    fourth cell+
 first cell   1.324.90   third cell    2nd line
 first cell       0.00   third cell    hyphen-
 first cell    -123.45   "             append
 .TA
.sf

.TA Sample
first cell    numbers   -----third and fourth-----
first cell      97.96   third cell    fourth cell+
first cell   1.324.90   third cell    2nd line
first cell       0.00   third cell    hyphen-
first cell    -123.45   "             append
.TA

.IF IPFDOC
The IPF table functionality is restricted in comparison to HTML. Don't use " and + chars. HyperMake tries to make it's best, but the result is often not good enough. IPFC only supports fixed fonts within tables.
.END

.afb
A table begins with a ~.TA~ dot command, followed by a title for the table. If the table hasn't got a title, then write ~.TA NO~. ~.TA~, immediately followed by a Return, closes the table.

You principally edit the table like in an ASCII text with fixed font. Please note:

 Between two cells, there have to be two spaces. This is the separation criterion for the two cells. It's not necessary that two rows are completely filled with spaces, only one row is necessary. Right or left formatting makes no difference - formatting is not relevant.
 If you want to extend one cell to the bottom, type a quotation mark " to the line above the cell.
 If a cell has to be spread over two or more cells, fill the area of your choice with hyphen chars - . HyperMake deletes the hyphen chars which are not on their own, as in the negative number -123.45.
 Text in several lines can be concatenated to one large cell by using the plus char + at the end of the line, the + char will be deleted; or by using a single hypen which won't be deleted.

If you can't use the + char, you can change this setting with the dot command

~.tc X~

(table character) will change the default + char setting to a character X of your choice.

By default, cells containing more digits than letters will be right-justified, and in the reverse case left-justified.

With the dot command

~.TT~

Table Tags you can change the HTML table tags. the default setting is

~.TT BORDER CELLPADDING=5~


~.TT BORDER CELLPADDING=5 BGCOLOR="#D0D0D0"~

uses gray background for the tables. This choice can be necessary if you use a background graphic (see ini file, setting body tags) with lines. In this case the combination of table lines and background graphic lines would reduce the visibility of the cells.

.2
Line drawing

As creating boxes is usually a tedious job, a dot command has been defined to facilitate line drawing. The following example illustrates its use.

.in Line drawing
.it line drawing character
.sfb
 .LIXY

      X                           X

            Operating systems

      Y                ZY                X            X
            Novell         IBM              Hardware
      Y       Y                          X            X
          DOS   Netware    OS/2
      X                           X
 .LI
.sf

The result will be:

.sfb
.LIXY

      X                           X

            Operating systems

      Y                 Y                X            X
             Novell        IBM              Hardware
      Y       Y                          X            X
         DOS    Netware    OS/2
      X                           X
.LI
.sf

.afb
In the dot command ~.LIXYZ~, X represents a special character marking the corners of the box, Y a partition of the box. Z, placed in front of X or Y, generates double lines (only IPF).

You can change the standard font for line drawing in the ini file, font setting LineStandard.

.IF IPFDOC
Mixed single/double line characters are only supported by Codepage 437. When using foreign language letters which aren't supported in Codepage 437, don't use double lines.
.END

.IF WORDSTARDOC
.3
Line drawing and WordStar

The Z char in the ~.LIXYZ~ command for producing double lines has to be a ^P-character like ^PE or ^PR. When using the ^OD toggle, you can make the ^P-characters invisible to check the correct orientation of the box.
.END

.2
Footnotes

.in Footnote
.it footnote character
Generating Footnotes with HyperMake is very simple. For example, footnote text can be quoted in brackets like {This will be the content of the footnote} after entering the dot command footnote usage

~.FU{}~

Instead of the brackets and the footnote text, only a [This will be the content of the footnote] appears on which you can click with the mouse.

.fu
Other useful footnote bracket chars are [ ], < > or  (Alt-220)  (Alt-223) (IBM codepage).
.fu[]

.IF HTMLDOC
You can add a font character to the footnote dot command:

~.FU{}sfX~

This will select font X in the HTML footnote window.

With the dot command footnote size

~.FS 30~

you can change the size percent of the footnote window. Default is 15 percent. You have to place this command before beginning a new chapter with the changed window sizes.
.END

You can temporary deactivate the footnote function by using the footnote command without parameters:

~.FU~

or you can define other footnote chars. The default setting is no footnote chars.

If you don't want to get a "*" as a link to the footnote window, you can change the text "*" with the dot command footnote text

~.FT XXX~

Instead of a "*", the text "XXX" will appear. You are allowed to use a bitmap instead of a character or a text:

.sfb
 .BT& filename
 .FT&
.sf

(see bitmap text.)

.IF HTMLDOC
If you don't want to create HTML Frames for the footnote and text window, you can use the commandline parameter ~/NOFRAMES~. This will generate one footnote file with all footnotes which will be numbered.
.END

.FA hori 30
.2
Margins and Formatting

.inMargin
.3
Changing the left margin

This is a sample text with left margin 1.

.LM10
This is a sample of left margin 10; note that the formatting will be correct.

.LM20
This is a sample of left margin 20; note that the formatting will be correct.

.LM1
You can change the left margin by using the dot command left margin

.sfb
 .LM n
.sf

n is a number from 1 to approx. 30. Default setting is 1.

If you enter the left margin dot command without a number, the standard 1 will be active.

.IF HTMLDOC
HTML is not able to change the margin in steps of one column. HyperMake emulates the left margin setting by using HTML definition lists. Left Margin 2 und 3 won't change the margin, 3 will change the margin to approx. 5 (depending on the browser) and then the margin is changed in steps of 5 columns.
.END

.IF WORDSTARDOC
Using DOS WordStar, you have to use soft spaces instead.[The WordStar dot command left margin  .LM will create soft spaces automatically. HyperMake won't interpret the LM dot command directly, but the soft spaces, created by using the LM command. You also can set a Tab with ^OL and get soft spaces with ^OG, or while formatting, with ^OG ^B.]
.END

.3
Turning Formatting off and on

.IF IPFDOC
.in Formatting
(Only IPF) With the dot commands Formatting off and Formatting on

.sfb
 .FM off
.sf
.sfb
 .FM on
.sf

you can turn formatting off and on. The standard is Formatting on. "Off" means the formatting of the source text isn't changed. The setting will be active till the next formatting dot command, even through headings.

Between line drawing dot commands, formatting is automatically turned off.

Don't use the index/linking function when formatting is off.[Because of a bug in the IPFC 2.0 compiler. The entries in the index would get an ASCII 10 char at the end.] Don't use index chars, only use the index dot command, between two formatting dot commands:

.sfb
 .fm on
 .in word1
 .in word2
 .fm off
.sf
.END IPFDOC

.IF HTMLDOC
When creating HTML files, there are no dot commands to turn formatting off and on. To omit formatting, use a font with Phrase element PRE.
.END

.IF IPFDOC
For IPF, you can define a font with ~PRE~ in the ini file, so you do not need separate dot commands.
.END

.3
Centered Text

.in centered text
In centered text, formatting will be off. You can turn centered text on and off with :Output Centered; on and Output Centered off dot command

.sfb
 .OC on
 .OC off
.sf

But you can also define a font with ~center~, so you do not need separate dot commands.

.3
Auto Margin

To write :definition list;s for example, you can simply change the left margin by using spaces:

.sfb
*motherboard*
      The motherboard contents the main processor, the RAM
      memory and some other important parts of your computer.

*screen*
      Computer screens are available from 14 up to 21
      inches; You shouldn't save money with a cheap small
      screen.
.sf

motherboard
      The motherboard contents the main processor, the RAM memory and some other important parts of your computer.

screen
      Computer screens are available from 14 up to 21 inches; You shouldn't save money with a cheap small screen.

With the new dot command :Auto Margin: you can turn off/on the interpretation of the spaces at the beginning of a line.

.sfb
 .AM off
 .AM on
.sf

Default is on.

You can leave the AM setting on for normal running text. Every space at the beginning of a paragraph will change the left margin. You have to turn it off, if you want to have a margin only at the first line of a paragraph.

Using an ASCII editor with ASCIIHARDRET, spaces should only be at the beginning of the first line; of course the following lines wrapped by the editor should not have a margin.

.IF WORDSTARDOC
WordStar files don't need the auto margin function. [You can always use an auto margin function by using the ^OG command (soft spaces).]
.END

.2
if-conditions

.in if-condition
With if-conditions, you can create slightly different IPF or HTML files from the same source text. There are three new dot commands


.sfb
 .IF CONDITION
 .ELSE
 .END
.sf

The conditions are not case-sensitive. It's not necessary to use the ELSE command, of course.

For compiling the source text, you have to enter in the command line:

.sfp
.fu
[C:\myProject] HMAKE myDoc.txt #CONDITION
.fu[]
.sf

You can enter more than one condition in the command line. Note the # character, the parameters can be in any order.

Several conditions in the if-command, connected by AND or OR are not supported.

By default, the conditions #HTML or #IPF are set.

.IF HTMLDOC
.1
HTML-specific functionality

HyperMake offers special HTML functionality for publishing on the WWW. Most commands explained in this chapter aren't activated from the source text using dot commands, they are settings in the ini file and commandline parameters.

If you want to publish HyperMake documents in the WWW, please read this chapter, escpecially the sub chapter about HTML filenames!

.2
Navigation Buttons

You will find a Library of Buttons in the directory BUTTONS.

.in Buttons
.in Navigation Buttons
More complex HTML documents have got buttons at the beginning and the end of a page where the user can navigate from one page of the document to the other. You can define such standard functionality in the ini file: 

.sfb
function for first line = BACK FORWARD CONTENT INDEX
text for first line =     previous next content index
.sf

The four keywords BACK FORWARD CONTENT INDEX have the following meanings:

 BACK goes to the previous page in the order of the source text
 FORWARD goes to the next page
 CONTENT goes to the contents
 INDEX goes to the index.

Corresponding to the keywords BACK, FORWARD, the filenames of the gif files are BACK.GIF, FORWARD.GIF and so on.

For every keyword you can define a text. If "auto load graphics" in the browser is turned off, the text appears instead of the graphic. You can turn off the graphic buttons completely in the ini file, setting ~buttons = NO~. Then you get the text as a link instead of the navigation buttons.

If you don't want to get specific buttons, you can delete the keyword and its text in the line "function for.." and "text for..". You can change these settings separately for the beginning of the page and the end of the page ("first line" and "last line"). You also can change the order of the buttons, but remember to change both function and text.


User-defined Navigation Buttons

.it user button
It's possible to define navigation buttons by yourself, pointing to a chapter of your choice. To do this, you need an entry in the ini file and a dot command in the source text, marking the link target.

In the ini file:

.sfb
function for first line = BACK FORWARD CONTENT INDEX LABEL_A LABEL_B ...
text for first line =     previous next content index chapterA chapterB ...
.sf

and in the source text in the chapters of your choice:

.sfb
 .ID LABEL_A
 .ID LABEL_B
.sf

If the user presses the button LABEL_A.GIF, he will get to the chapter where LABEL_A is placed in the source text. The keyword is not case-sensitive. There's no limitation of the numbers of user buttons.

If you use ~.ID~ dot commands, the HTML file gets e.g. the name LABEL_A.HTML. Normally HyperMake uses filenames N000.HTML, N001.HTML and so on. If you want to use navigation buttons, but don't want to change to fixed filenames, you can use the commandline parameter ~/NOID~.

In the Library of Buttons you will find some user buttons.

Navigation Buttons pointing to URL's

You can use the ~.ID~ dot command within an ~.URL~ external link.

.sfb
 .URL http://www.netscape.com
 .ID NETSCAPE
 .LOCAL
.sf

If you have added the keyword NETSCAPE in the ini file, line "function for...", the button NETSCAPE.GIF gets the link to the netscape homepage in the WWW.

E. g. you can write an offline program documentation where the user can reach your homepage in the WWW from every page by pushing a homepage button or your company logo.

.2
HTML filenames

By default, HyperMake numbers the generated HTML files: N000.HTML, N001.HTML and so on. That means, filenames of a particular chapter can change after updating your document. There are several ways of making HyperMake generate other filenames.

Using a fixed filename

.sfb
 .2
 About me

 .ID AUTHOR
 I'm 31 years old, have studied economics...
.sf

You can mark a particular chapter with an ID. It's the same command you need for user buttons.

If a chapter is marked with ~.ID LABEL_A~, the filename is LABEL_A.HTML and won't change while updating your document. You have to do so for all pages of your document to which other authors in the WWW may want to make a link. If you do not so, the filename of the specific chapter may change when updating your whole document. This procedure can be also useful for you: When updating only a part of your document, you don't need to upload all the HTML files: All chapters with a particular ID can be changed and uploaded separately without the risk of destroying links.


Several HyperMake documents in only one directory

The ini file setting "pre filename" enables you to set a character string in front of all HTML filenames generated by HyperMake, e.g. UserN000.HTML, UserN001.HTML. But for this procedure you need one ini file for each of your projects. To avoid having several ini files, you can use a commandline parameter:

.sfp
.fu
[C:\myProject] HMAKE my.txt /PRE
.fu[]
.sf

creates HTML files ~MY\MY*.HTML~ .

You can copy the files of all your different projects into one single directory.

Using DOS drives, "pre filename" or the source filename must not exeed 3 chars!


8.3 filenames, long filenames, small and capital letters

.in filenames
Different operating systems handle filenames in different ways. DOS only knows short filenames in the 8.3 convention. The PC operating systems DOS, OS/2, Windows 95 and Windows NT are handling filenames not case-sensitive, but Unix systems - most internet servers are Unix machines - distinguish between small and capital letters. So it can happen that the links on your machine work well, but after uploading to the server, the links don't work any more!

To avoid this, HyperMake offers you several methods: A setting in the ini file, a commandline parameter and an automatic recognition of DOS drives.

.sfb
//possible settings: sample.html SAMPLE.HTML Sample.html sample.htm SAMPLE.HTM Sample.htm
filename appearance = sample.html
.sf

You can define the appearance of the filenames in the ini file.

Remember that this decision depends on your drive and your upload program. If your operating system is OS/2 with long filename support, but your upload program is a Windows 3.1 software, you are forced to use the "SAMPLE.HTM" form. If all the programs you need are Windows 95 programs, you should choose "Sample.html".

If you choose an obvious false setting, e.g. "sample.html" on a DOS drive with the 8.3 limitation, HyperMake automatically changes the filename to the extension ".HTM" and the created links are OK.

With the commandline parameter ~/FAT~ (File allocation table, that's the name of the DOS file system) you will get the same result as with the setting ~SAMPLE.HTM~ in the ini file: Even though the drive supports long filenames, HyperMake uses the DOS 8.3 conventions.

You have to get your GIF filenames right (small/capital letters) yourself!


Different languages in only one directory

If you want to place HTML files and graphics in two languages in only one directory, you will get a conflict with the same filenames of the navigation buttons FORWARD.GIF, BACK.GIF and so on.

The commandline parameter ~/_~ (underscore) appends the ~_~ character to all graphics filenames: FORWARD_.GIF, BACK_.GIF, USER_.GIF. For one of the two different languages you have to use this parameter, for the other not. Rembember to rename the GIF buttons of one language.


.2
Title and Meta entries

.in Meta entries
.in Titlebar
At the beginning of every HTML file, a title is defined which appears in the titlebar of the browser.

For this chapter for example, a meaningful title is:

HyperMake 3.0 - Title and Meta entries

You can define which text has to appear in the titlebar of every HTML file:

.sfb
//here you can define the text appearing in the browser titlebar
//enter DOCTITLE and/or HEADING and fixed text, e.g. a slash; NO means no text
file title = DOCTITLE - HEADING
.sf

DOCTITLE is the title of the whole HyperMake document, defined behind the ~.TI~ dot command. HEADING is the actual heading text of the chapter. In addition to the two keywords DOCTITLE and HEADING, you can write text of your choice, e.g.

.sfb
file title = Martin Vieregg: DOCTITLE, chapter HEADING
.sf

At the pages content and index, for the heading text the string defined in the line "text for first/last line" is used. In the footnote file, the heading text defined in the line "notes text" is used.

Like defining a HTML file title, you also can define an automatic meta entry with "meta content":

.sfb
meta content = DOCTITLE - HEADING
.sf

Into the head of the HTML file, HyperMake will place:

.sfb
<META NAME "keywords" CONTENT="...">
<META HTTP-Request "keyword" CONTENT="...">
.sf

These informations aren't visible when viewing the file with a browser. It's interpreted by Internet search machines like Hotbot or Yahoo.


Embedding user-defined HEAD tags

You can write HEAD tags for all HTML files or for specific HTML files. By default, HyperMake only writes:

.sfb
<HEAD>
<META NAME="generator" content="HyperMake 3.00">
<META NAME ="Author" CONTENT="Name of the author">
<title>title of the document</title>
</HEAD>
.sf

Above the <title> tag, other head tags can be embedded. You have to place these lines into text files with specific filenames: If all HTML files are to get the information, you have to place it into a file called ~EVERY.HEAD~. If only a specific file is to get the info, you have to mark the chapter of your choice with ~.ID USERLABEL~ and then place the information into the file ~USERLABEL.HEAD~.

Embedding user-defined head tags or not depends on the existence of the individual *.HEAD files. There's no special setting.

If a "pre filename" (see ini file) is set, the filenames of the HEAD-files have to begin with the pre filename.

If you use a DOS drive or have set the DOS conventions for creating filenames (setting filename appearance), the filename extension has to be ~.HEA~ instead of ~.HEAD~.
.END

.1
Generating helptables and panel ID's

.IF HLPDOC
.in helptable
.in panel ID
The main difference between HLP and INF files is the connection of HLP files to a PM oriented program. The INF file is a "stand alone" solution, in the HLP file you can create links between windows or buttons of your program to chapters of your hypertext. Clicking on a Help button or pressing F1 will activate a chapter (a window) of the hypertext.

There are two different kinds of links from a program to a HLP file:
 links by using helptables
 direct links by using panel ID's.

Links by using helptables are activated when pushing F1 together with a help button; instead of pressing F1, there is the possibility to push a button with the flags BS_HELP | BS_NOPOINTERFOCUS. In the helptable, button ID's are related to chapters (windows) of the hypertext.

Direct links don't use a helptable, they use a function in your program source code which is directly activating a help chapter (window). Direct links can also be used in text oriented programs.
.sf

Without HyperMake, you would have to write a helptable in the RC file[Programmers should know what an RC file is, and if you don't know, you can skip this chapter because you need not create any HLP files.] specifying which window or button will be linked to which chapter of the hypertext. For direct links, you would have to create a panel ID header file with the IPF internal heading resource ID's, related to meaningful constant identifiers like "Panel_Introduction".

.2
Writing the HyperMake source file

.in resource connection
In the HyperMake file, there are two new dot commands: The command resource connection

.sfb
 .RC ID_window, ID_button_or_Menu_Item
.sf

creates a connection between the help chapter and the button or menu item with the ID "ID_button_or_Menu_Item", located in the child window "ID_window": If the button/menu item is pressed with F1 simultaneously, the help chapter is activated where the RC command is located.

.afb
~ID_window~ is the constant placed after MENU or DIALOG in your RC file.

Note: ~ID_window~ is not the constant placed after DLGTEMPLATE.[If the constant behind DIALOG and the constant behind DLGTEMPLATE are identical, it's okay.]

And with panel ID

.sfb
 .ID Chapter_Name
.sf

the chapter where the ID command is located gets the label "Chapter_Name". With DisplayHelpPanel(Chapter_Name) in the program source text, you can activate this help chapter directly.

Pascal programmers have to pay attention: the constant behind the ID dot command is case sensitive!

You can place these dot commands somewhere in the chapter (window) which will be connected to the button or menu item. I recommend placing these dot commands very close to the related paragraph. So if you later create sub chapters and a button has to be linked to the new, special sub chapter, you need not change the position of ID and RC dot commands.

Using the RC dot command, you normally have to enter two ID's: The first ID for the program window[you have to use the constant you have entered in the RC file after MENU or DIALOG] containing the item (a menu item, button, entryfield etc.), and the second ID for the item itself.

If you enter a lot of RC commands, you are allowed to use the shortcut

.sfb
 .RC , ID_button_or_Menu_Item
.sf

This will use the name of the last window ID.

You are allowed to generate an INF file with IPFC when the HyperMake source file includes HLP specific RC dot commands: The only effect of RC and ID dot commands is generating a helptable and a panel ID file, the IPF file won't be affected.

You should always use the RC command one time with only one parameter (the window ID). All items in this window which are not placed in the helptable will get a link to this chapter. If you don't do that, HyperMake creates a warning.

.in helptable file
This sample HyperMake source file has got resource connection and Panel ID dot commands:

.sfb
 .1
Introduction

 .RC ID_childwindow
 .ID PANEL_Introduction
This is the documentation of my prog.

 .1
Usage of the OK button

 .RC ID_childwindow, ID_OK
 .ID PANEL_usage_OK
With the OK button - you'll be surprised - you can press OK.

 .1
Usage of the Cancel button

 .RC ID_childwindow, ID_Cancel
With the Cancel button, you can cancel the operation.
.sf

.2
Writing your C program source file

HyperMake automatically creates a file HLPTABLE.RC:

.sfb
#define SUBTABLE_ID_childwindow 7001

HELPTABLE HELP_TABLE {
  HELPITEM ID_childwindow, SUBTABLE_ID_childwindow, 1 /* Introduction */
}

HELPSUBTABLE SUBTABLE_ID_childwindow {
  HELPSUBITEM ID_OK, 2 /* Usage of the OK button */
  HELPSUBITEM ID_Cancel, 3 /* Usage of the Cancel button */
}
.sf

HyperMake also creates a file PANELID.H:

.sfb
/*****Panel ID's created by HyperMake*****/

#define PANEL_Introduction  1
#define PANEL_usage_OK      2
.sf

The numbers 1, 2 and 3 are the IPF internal heading-ressource-id's. In the helptable file, HyperMake automatically writes the heading text as comment, so you can read this file more easily while debugging. (Normally you don't have any reason to read the Helptable and panel ID file.)

You can change the Help Subtable Start ID value in the ini file, switch ~Help Subtable Start ID~, also you can change the filenames of the two created files.

You can simply include the helptable file and the panel ID file into your program source by typing

.sfb
#include "HLPTABLE.RC"
.sf

for example after a MENU or a DLGTEMPLATE block in your RC file and

.sfb
#include "PANELID.H"
.sf

at the top of your program source file (a C or CPP file).

In your main header file, you have to define a constant HELP_TABLE with an unused value, for example

.sfb
#define HELP_TABLE 7000
.sf

which will be valid in the RC and in the C or CPP source file.

In the C source file you need at least two functions like

.sfb
  void InitHelp (hwnd) /*initialize the help process*/
  void DestroyHelp () /*destroy the help instance*/
.sf

which uses the constant HELP_TABLE.

The function InitHelp needs a parameter: the window handle of your program. Of course, this window handle has already to be valid. If your program is a standardwindow, you should place the function InitHelp between ~WinCreateStdWindow...~ and ~while WinGetMsg...~ and the function DestroyHelp after ~while WinGetMsg...~. If your program is only a dialogbox, you won't have a ~WinCreateStdWindow~ function. In this case, you can place InitHelp into the WM_INITDLG and DestroyHelp into the WM_CLOSE section of your dialogbox message function.

A third function 

.sfb
  void DisplayHelpPanel (PanelID)
.sf

is necessary to create a direct link from your program to a chapter of your hypertext. It's the complement for the panel ID dot command.

I have written a very short version of these functions. To compile these functions, you have to enter [Perhaps that's compiler specific. I use Borland C]

.sfb
#define INCL_HELP
.sf


.3
C source code with the three help functions

.sfb
.in function InitHelp
.in function DestroyHelp
.in function DisplayHelpPanel
#define HelpFilename "FILENAME.HLP"
#define HelpWindowTitle "Title of the Hypertext window"

BOOL fHelpEnabled;
static HWND hwndHelpInstance;

#define InfoBox(st) WinMessageBox (HWND_DESKTOP, HWND_DESKTOP, st, "", 0, MB_OK | MB_ERROR)

/*to be placed in front of the main program message loop*/
VOID InitHelp (HWND hwndClientFrame) {
    HELPINIT hini;
    /* If we return because of an error, Help will be disabled */
    fHelpEnabled = FALSE;
    /* Initialize help init structure */
    hini.cb = sizeof(HELPINIT);
    hini.ulReturnCode = 0;
    /* If tutorial added, add name here */
    hini.pszTutorialName = (PSZ)NULL;
    hini.phtHelpTable = (PHELPTABLE)MAKELONG(HELP_TABLE, 0xFFFF);
    hini.hmodHelpTableModule = 0; hini.hmodAccelActionBarModule = 0;
    hini.idAccelTable = 0; hini.idActionBar = 0;
    hini.pszHelpWindowTitle = HelpWindowTitle;
    hini.fShowPanelId = CMIC_HIDE_PANEL_ID;
    hini.pszHelpLibraryName = HelpFilename;
    /* Creating help instance */
    hwndHelpInstance = WinCreateHelpInstance(hab, &hini);
    if(hwndHelpInstance == 0L || hini.ulReturnCode) {
      InfoBox("Failed to load help manager."); return;
    }
    /* Associate help instance with main frame */
    if(!WinAssociateHelpInstance(hwndHelpInstance, hwndClientFrame)) {
      InfoBox("Failed to load help manager."); return;
    }
    /* Help manager is successfully initialized so set flag to TRUE */
    fHelpEnabled = TRUE;
    return;
}

/*to be placed behind the main program message loop*/
VOID DestroyHelp (VOID) {
    if(hwndHelpInstance != 0L) WinDestroyHelpInstance(hwndHelpInstance);
    return;
}

/*
  some possible parameters:
  HM_HELP_INDEX     shows the index
  HM_HELP_CONTENTS, shows the contents
  HM_DISPLAY_HELP   shows help for help
*/
VOID SendHelpMessage (LONG HelpMessage) {
    if(fHelpEnabled)
      if((LONG)WinSendMsg(hwndHelpInstance, HelpMessage, (MPARAM) 0, (MPARAM) 0))
   InfoBox ("Failed to display help panel.");
}

/*
  parameters are the Panel ID's, defined with ID dot commands
  in the HyperMake source file
*/
VOID DisplayHelpPanel (LONG PanelID) {
    if(fHelpEnabled)
      if((LONG)WinSendMsg(hwndHelpInstance, HM_DISPLAY_HELP,
         MPFROMLONG(MAKELONG(PanelID, NULL)),
         MPFROMSHORT(HM_RESOURCEID))) InfoBox ("Failed to display help panel.");
}
.sf

.2
Writing your Pascal program source file

HyperMake automatically creates a file HLPTABLE.RC:

.sfb
CONST
  SUBTABLE_ID_childwindow = 7001

HELPTABLE 1000
BEGIN
  HELPITEM ID_childwindow, SUBTABLE_ID_childwindow, 1 /* Introduction */
END

HELPSUBTABLE SUBTABLE_ID_childwindow
BEGIN
  HELPSUBITEM ID_OK, 2 /* Usage of the OK button */
  HELPSUBITEM ID_Cancel, 3 /* Usage of the Cancel button */
END
.sf

HyperMake also creates a file PANELID.INC:

.sfb
{     Panel ID's created by HyperMake    }

const
  PANEL_Introduction = 1;
  PANEL_usage_OK = 2;
.sf

The numbers 1, 2 and 3 are the IPF internal heading-resource-id's. In the helptable file, HyperMake automatically writes the heading text as comment, so you can read this file more easily while debugging. (Normally you don't have any reason to read the helptable and panel ID file.)

You can change the Help Subtable Start ID value in the ini file, switch ~Help Subtable Start ID~, also you can change the filenames of the two created files.

You can simply include the helptable file and the panel ID file into your program source by typing

.sfb
{$I HLPTABLE.RC}
.sf

for example after a MENU or a DLGTEMPLATE block in your RC file and

.sfb
{$I PANELID.INC}
.sf

at the top of your program source file (a PAS file).

First, there are two procedures to start the HLP file:

.sfb
DisplayHelpPanel (PanelID)
.sf

is necessary to create a direct link from your program to a chapter of your hypertext. It's the complement for the panel ID dot command.

.sfb
SendHelpMessage (HM_HELP_CONTENTS)
.sf

activates the contents of the HLP file directly. There are other HM_* constants, defined in the SpeedPascal PMHELP.PAS unit.

The following depends on whether you want to use SpeedPascal 1.5 OPML or not.

.3
Creating the help functionality with SpeedPascal OPML

In the method

.sfb
TApplication.InitMainWindow
.sf

you have to append the following line at the end:

.sfb
MainWindow^.InitWindowHelp ('MYPROG.HLP', 'help window title');
.sf

That's all.

.3
Creating the help functionality without OPML

To create the connection between your EXE file and the HLP file, you need two procedures:

.sfb
  uses PMHELP;

  InitHelp (hwnd); {initialize the help process}
  DestroyHelp; {destroy the help instance}
.sf

This procedures are defined in the PMHELP.PAS unit of SpeedPascal 1.5.

The procedure InitHelp needs a parameter: the window handle of your program. Of course, this window handle has already to be valid. If your program is a standardwindow, you should place the function InitHelp between ~WinCreateStdWindow...~ and ~while WinGetMsg...~ and the function DestroyHelp after ~while WinGetMsg...~. If your program is only a dialogbox, you won't have a ~WinCreateStdWindow~ function. In this case, you can place InitHelp into the WM_INITDLG and DestroyHelp into the WM_CLOSE section of your dialogbox message function.

Immidiately before using the procedure "InitHelp" you have to set some values of variables:

.sfb
  HelpFilename := 'MYPROG.HLP';
  HelpWindowTitle := 'heading of the hypertext window';
  HELP_TABLE := 1000;
.sf

The number 1000 is also used in the Helptable created by HyperMake.

If you do not use SpeedPascal 1.5 (or later), you will find the procedures and variables in the subchapter.

.4
Pascal Help Source

.sfb
{Help manager helpers}

FUNCTION InfoBox(st:STRING):LONGINT;
BEGIN
  result:=WinMessageBox (HWND_DESKTOP, HWND_DESKTOP, st,'', 0, MB_OK | MB_ERROR);
END;

{to be placed in front of the main program message loop}
PROCEDURE InitHelp (hwndClientFrame:HWND);
VAR
   hini:HELPINIT;
   { If we return because of an error, Help will be disabled }
BEGIN
     fHelpEnabled := FALSE;
     { Initialize help init structure }
     hini.cb := sizeof(HELPINIT);
     hini.ulReturnCode := 0;
     { If tutorial added, add name here }
     hini.pszTutorialName := NIL;
     hini.phtHelpTable := PHELPTABLE(MAKELONG(HELP_TABLE, $FFFF));
     hini.hmodHelpTableModule := 0;
     hini.hmodAccelActionBarModule := 0;
     hini.idAccelTable := 0;
     hini.idActionBar := 0;
     hini.pszHelpWindowTitle := @HelpWindowTitle;
     hini.fShowPanelId := CMIC_HIDE_PANEL_ID;
     hini.pszHelpLibraryName := @HelpFilename;
     { Creating help instance }
     hwndHelpInstance := WinCreateHelpInstance(AppHandle,hini);
     if ((hwndHelpInstance = 0 )OR(hini.ulReturnCode<>0)) THEN
     BEGIN
          InfoBox('Failed to load help manager.');
          exit;
     END;

     { Associate help instance with main frame }
     if not WinAssociateHelpInstance(hwndHelpInstance, hwndClientFrame) THEN
     BEGIN
          InfoBox('Failed to load help manager.');
          exit;
     END;

     { Help manager is successfully initialized so set flag to TRUE }
     fHelpEnabled := TRUE;
END;

{to be placed behind the main program message loop}
PROCEDURE DestroyHelp;
BEGIN
     IF hwndHelpInstance <> 0 THEN WinDestroyHelpInstance(hwndHelpInstance);
END;

 {
   some possible parameters:
   HM_HELP_INDEX     shows the index
   HM_HELP_CONTENTS, shows the contents
   HM_DISPLAY_HELP   shows help for help
 }
PROCEDURE SendHelpMessage (HelpMessage:LONG);
BEGIN
     if fHelpEnabled THEN
      if WinSendMsg(hwndHelpInstance, HelpMessage, 0, 0)<>0
        then InfoBox ('Failed to display help panel.');
END;

 {
   parameters are the Panel ID's, defined with ID dot commands
   in the HyperMake source file
 }
PROCEDURE DisplayHelpPanel (PanelID:LONG);
BEGIN
     if fHelpEnabled then
       if WinSendMsg(hwndHelpInstance, HM_DISPLAY_HELP,
          MPFROMLONG(MAKELONG(PanelID, 0)),
          MPFROMSHORT(HM_RESOURCEID))<>0
           then InfoBox ('Failed to display help panel.');
END;
.sf

.2
Writing several HLP files in different languages

If you are writing several HLP files in different languages and you have only one EXE file, it is adequate to enter the RC- and ID-dot commands only in one HyperMake source file. There aren't any problems if you have got exactly the same heading level structure in every HyperMake source file. HyperMake simply enumerates the headings from the first heading (res ID 1) to the end.
.ELSE
The format IBM IPF is needed for creating context-senitive OS/2 program documentations (Extension HLP). HyperMake offers some useful functions for the connection Hypertext - EXE program. This docu section is only generated when the #HLPDOC condition was set while creating the docu.

For the new Microsoft Windows HTML program help I'm planning a similar functionality.

.END HLPDOC

.FA verti 40
.1
dot command summary 

.in dot command summary
Here you find a summary of all HyperMake dot commands. You will find the same structure of subjects in Writing a HyperMake file.

Some dot commands have got synonyms in German language or WordStar synonyms, they are quoted in brackets and both are interpreted.

.2
Essentials

.afb
~..comment~

"comment" is not interpreted.

.IF IPFDOC
.sfb
 .:ipfcommand.
 .:ipfcommand. expression
.sf

You can enter an IPF command directly.
.END

.IF HTMLDOC
.sfb
 .HTML

 <HTML-commands> running text

 .HYPERMAKE
.sf

direct writing of HTML text.
.sfb
 .HC on
 .HC off
.sf

Enables embedding <HTML tags> in normal HyperMake source text. Default is off.
.END HTMLDOC

.2
Beginning

~.TI Title~

sets the title of the hypertext to "Title".

.IF IPFDOC
.sfb
 .<>
.sf

creates pushbuttons "Contents", "Back" and "Forward" in HLP files, normally only INF files have. 
.END

.2
Headings

~.1~ up to ~.6~ sets a heading level

~.1~
~Main heading~

The title of the first heading level is "Main heading".

.IF HTMLDOC
(Heading Size) Changing the font size of the heading text (HTML). E.g. Level 4 gets the font size of level 2.

~.HS 123234~
.END

Appearance of links to subchapters

.sfb
 .sc separation text of your choice
 .sc RETURN           (default)
 .sc PARAGRAPH
 .sc LIST
.sf

Window Arrangement (Frames)

~.WA~ (~.FA~)
~.WA hori 30~ 
~.WA hori 30 verti 40 III~

Window arrangement enables showing two or three heading level windows simultaneously. It has to be placed above the first heading level dot command where the arrangement shall begin.

Chapter ID

~.ID NAME~

The chapter where the command is located gets the ID "NAME".

.IF HTMLDOC
The corresponding page gets the name "NAME.HTML" instead of an enumeration. In the ini file, you can enter the keyword "NAME" in the line "function for link for". The navigation button "NAME.HTML" gets a link to the marked chapter. You will find a Library of Buttons in the directory BUTTONS.

.END

.IF IPFDOC
When creating IPF, this command is used for helptables.
.END


.2
Fonts

~.SFX~ (~.SNX~)
~.AFX~ (~.SAX~)

standard font and alternate font changes the font to the font X. X represents a character from A to Z and from a to z (case sensitive). The font chars are defined in the ini file.

The alternate font is active between two alternate toggle chars, also defined in the ini file.

.2
Lists

~.OL~ turns the ordered list setting on
~.UL~ turns it off (default, "unordered list").

.2
Bitmaps

~.BM filename~

places a bitmap centered. The filename extension is ".BMP" (IPF) and ".GIF" (HTML).

~.BTX filename~

replaces all occurrences of the bitmap char X by the bitmap filename.bmp.

.2
Linking and Indexing

~.ICX~  (~.IZX~)

sets the index char to X.

~.IN phrase~

places "phrase" into the index; all occurrences of "phrase" will get a link to the chapter where the IN dot command is placed.

~.IT phrase~  (~.SV~)

Index Turned: same as IN, but uses the last word as leading word.

.IF IPFDOC
External links (IPF)

~.EX extern.inf~
~.ID chapter_beginning~
~.IN phrase~
~.EX~

All occurrences of "phrase" become an external link to the chapter of the file extern.inf which was labeled with the dot command
~.ID chapter_beginning~
.END IPFDOC

.IF HTMLDOC
External links (HTML)

~.URL URL~
~.IN phrase~
~.LOCAL~

All occurrences of "phrase" become an external link to the URL "URL".
.END HTMLDOC

.IF IPFDOC
Launching programs (IPF)

~.EX programname.exe parameter~
~.IN phrase~
~.EX~

All occurrences of "phrase" become a link to the program "programname.exe", with the parameter "parameter".
.END

.2
Duplication of heading text

~.dp34C~

Duplication of heading text at the beginning of the text window in heading level 3 and 4 with font C

~.dp##C~

in all heading levels, headings are duplicated at the beginning of the text window, gets link target (first #) and is placed into the index (second #).

~.dp-34~

deactivates heading duplication at the heading level 3 and 4.

.2
Tables

.sfb
 .TA table heading text
 cell one    cell two  cell three
 2nd line    2nd line   one+
 third cell  "         big cell     
 .TA
.sf

and you will get:

.TA table heading text
cell one    cell two  cell three
2nd line    2nd line   one+
third cell  "         big cell     
.TA

In tables, cells can be expanded with " and with + (only HTML).

~.tc X~

(table character) changes the concatenation-char + to another char.

~.TT~

(Table Tags) default is:
~.TT BORDER CELLPADDING=5~

Gray background without graphics:
~.TT BORDER CELLPADDING=5 BGCOLOR="#D0D0D0"~


.2
Line drawing

.sfb
..LI
 .LIXY
X   Y   X               Ŀ     
                               
Y            result:    Ĵ 
                               
X       X               
 .LI
..li
.sf

Line drawing generates a box (X are the corners), divided by Y. Z in front of X or Y uses double lines (only IPF).

.2
Footnotes

~.FU{}~
~.FU{}sfX~

defines brackets to quote footnote text; selects font X for the footnote window. If you enter

~you will get {content of the footnote}.~

you will get [content of the footnote].

.IF HTMLDOC
~.FS 30~

footnote size: changes the default setting of text window size / footnote window size 85 / 15 to 70 / 30.
.END

~.FT XXX~

footnote text: writes "XXX" instead of the default "*". Bitmap chars are allowed.

.2
Margins and Formatting

~.LM 10~

will set the left margin from default 1 to 10.

.IF IPFDOC
~.FM off~  (~.FM aus~)
~.FM on~  (~.FM an~)

(only IPF) Formatting turns formatting off and on. Default is on.
.END

~.OC on~  (~.OC an~)
~.OC off~  (~.OC aus~)

turns centered text on and off.

~.AM off~  (~.AM aus~)
~.AM on~  (~.AM an~)

Auto Margin let you change the left margin by entering spaces at the beginning of a paragraph. Default is on.

.IF HTMLDOC
In HTML files, the margin can only be changed in steps of 5 spaces.
.END

.2
if-conditions

.sfb
 .IF CONDITION
 .ELSE
 .END
.sf

is only compiling specific source text to IPF. The conditions are set by using the commandline (not case-sensitive)

.sfp
.fu
[C:\myProject] HMAKE myDoc.txt #CONDITION
.fu[]
.sf

.2
Helptables and Panel ID's

(only IPF, to create IBM HLP files)

.sfb
 .RC ID_window
 .RC ID_window, ID_button_or_Menu_Item
 .RC , ID_button_or_Menu_Item

 .ID PanelID
.sf

RC dot commands create a helptable in the file HELPTABLE.RC, ID dot commands create a file PANELID.H.

.FA hori 40
.1
Ini file

.in ini file

The ini file contains important settings. It's useful to create a seperate ini file for every project. You can edit the ini file with an ASCII editor like the OS/2 System Editor (do not use WordStar). The first line of the file won't be interpreted.

For your own ini file, better use a copy of SAMPLE.INI and not DOCU.INI because DOCU.INI has got some exotic ASCII values for the toggle chars.

In C++ manner, lines beginning with double slash // won't be interpreted, either. Also the windows specific comments beginning with ; are allowed. You can change the order of the switches, but all switches have to appear. With a few exceptions, the lines aren't interpreted case sensitive.

You aren't allowed to change the text at the left side of the = (equal) character, because that's the name of the switch. At the right side, you can change the setting.


.2
General settings

Registration code

.in Registration key
.sfb
Registration code = 0
.sf

Here you have to enter your registration key, if you want to compiler bigger sources than 20 kB.

see registration


Language

.sfb
//possible settings: ENGLISH, GERMAN, C, PASCAL
Language = ENGLISH C
.sf

Native Language: Actually, English and German are supported. This document is also available in German language. This switch won't have any effect to the output (the IPF file). It only sets the language of the (error) messages running HyperMake. Some dot commands are different in the german documentation, but they are both interpreted.

When choosing a native language, you also have to set the language specific settings endings of words and extended letters.

Programming Language (only IPF): If you want to create Panel ID and Helptable files, HyperMake has to know your programming language C or Pascal.


beep

.sfb
//beep when finishing compiling - possible settings: YES, NO
beep = YES
.sf

If HyperMake has created the IPF file or the HTML files successfully, you will hear a beep. Here you can turn the beep off.


.2
Format settings

Target

.in target format
.sfb
//possible settings: IPF, HTML
Target = HTML
.sf

Note that you can temporary overwrite this settings by using the commandline parameters IPF or HTML.


Source format

.sfb
//possible Settings: ASCIIHARDRET, ASCIISOFTRET, WORDSTAR4
Source format = ASCIISOFTRET
.sf

see handling of Returns


Codepage

.sfb
//possible Settings: ISO, IBM
source codepage = IBM
.sf

You can choose between two codepages for your source text. ISO (ISO 8859-1 "Latin1") and IBM codepage 437 or 850. ISO is the typical codepage for Windows or Unix, IBM for DOS and OS/2.


.2
specific characters

List chars

.sfb
//only ASCII source
List chars = =-
.sf

List chars are necessary to create unordered lists with an ASCII editor.


Index char

.sfb
Index char = #
.sf

see linking and indexing. The dot command ~.ICX~ overwrites this default setting with the char X.


toggles

.sfb
//highlighted char toggles
//both HTML and IPF: 1 alternate  2 italic 3 bold 4 underlined
//only IPF:          5 red 6 cyan 7 blue
//only HTML:         8 strike 9 big 10 small 11 sub 12 sup
//        123456789012
toggles = ************
.sf

Here you can enter toggle chars. You always have to enter all twelve toggle chars, even you don't use IPF or HTML.

.IF WORDSTARDOC
Using WordStar, you have to enter the original ASCII characters.[For example, to enter ^PA, you have to enter Alt-1 in the ASCII editor. ^PB is Alt-2, ^PS is Alt-19 etc.]
.END


Index Filter
.in index filter
.sfb
//characters not shown in index and duplicated heading
index filter = ().
.sf

You can omit specific characters in the index and when duplicating heading text.


Extended Letters

.in extended letters
.sfb
//language specific letters besides A...Z, a...z, 0...9
//english '- 
//german ᎙ 
extended letters = '- 
.sf

In most languages besides english, there are letters other languages won't use. HyperMake has to know these letters to distinguish from (possible) toggles. This has an effect on indexing/linking. So if you write

.sfb
This is a sample with a marked german word #Kindergrten.
.sf

(That's plural of Kindergarten.) If you haven't defined "" as an extended letter, the index entry and link target is only "Kinderg".

To use an expression like "CONFIG.SYS" or "bird (movie)" as a link target, the dot and the parenthesis have to be defined as extended letters. If you do so, you have to pay attention when marking expressions with the index char, for example you enter (#Word). Not "Word" is the link target and placed in the index, it's "Word)." - that means most of the links you want are not created. Use (#:Word:). in this case.


.2
Font characters

.sfb
//Font chars from A to Z and from a to z (case-sensitive!)
//both HTML and IPF: size Linestandard OmitLinks PRE center
//only IPF: Fontname codepage foregroundcolor BACKGROUNDCOLOR
//only HTML: PHRASEELEMENT Color
Font A = 15 Courier CODE
Font b = Courier 12 CODE black 437 Linestandard OmitLinks
Font B = 30 Helv neutral
Font Z = GREEN 30 Helv yellow 
Font G = 15 Helv black
Font T = 18 Tms_Rmn
Font C = black
Font o = OmitLinks
.sf

Here you can define font chars from A to Z and from a to z. Note that the font char is case sensitive. There is no order of the settings.

The characteristics of the strings are:

 size: all numbers smaller than 200
 codepage: (only IPF) all numbers equal and bigger than 200
 foregroundcolor:
  - IPF: all colors in lower case letters:
    default, blue, cyan, green, neutral, red, yellow, black.
  - HTML: lower case letters, but first char capital letter:
    Black, Silver, Gray, White, Maroon, Red, Purple, Fuchsia, Green, Lime, Olive, Yellow, Navy, Blue, Teal, Aqua.
 backgroundcolor: (only IPF) all colors in capital letters: DEFAULT, BLUE, CYAN, GREEN, NEUTRAL, RED, YELLOW, BLACK.
 Phrase element: (only HTML) ADDRESS PRE EM STRONG DFN CODE SAMP KBD VAR CITE. 
 Font-Type: (only IPF) all strings which are not a color. Note that fonts with two words have to be connected with "_".


You only have to enter the settings which are different from default.

.IF IPFDOC
The default IPF codepage is defined by the settings in your operating system or by a parameter of IPFC.
.END

Note that you can mix HTML and IPF instructions, so one font character defines both HTML and IPF outfit.

See font samples and color samples.

With the LineStandard setting you can choose which font will be standard when activating line drawing. Only one font should have the LineStandard setting, and the font should be not a proportional font.

With the OmitLinks setting, you can omit the automatic linking function in several specific fonts. That can be useful for example when writing sample text.


.2
link specific settings

endings of words

.in endings of words
.sfb
//endings in german words: n en s es
ending of words = s es 's ion ions ing ings
.sf

See Linking, Handling of endings


Text for link to

.sfb
Text for link to subchapters = @subchapters:@
Text for link to next chapter = @next chapter:@
//only HTML frames
text for link to main chapter = to main chapter
.sf

.in link to subchapters
HyperMake will automatically generate links at the end of a heading to all subchapters and to the next chapter of the same (or lower) heading level. Here you can enter the input which will be shown immediately before the links will appear. You are allowed to use toggle chars or bitmaps using bitmap text.

You can turn off this function by entering NO in capital letters:

.sfb
Text for link to subchapters = NO
Text for link to next chapter = NO
.sf

.IF HTMLDOC
If HTML frames are generated, two heading levels are shown simultaneously. The second window (sub chapter) always gets a link to the first window (main chapter). Because the other links like "content" are not created in the second window, the "link to main chapter" is the only connection to the remaining document and can't be disabled.
.END


.2
HTML specific settings (not IPF)

no more links in

.in no more links in
.sfb
//possible Settings: PARAGRAPH, WINDOW
no more links in = PARAGRAPH
.sf

see Linking, Omitting links


title in every file

By default, the title is placed at the beginning of each file. You can change this with the setting:

.sfb
title in every file = NO
.sf

First and last line

.sfb
//only HTML: first and last line in file
title in every file = YES
function for first line = BACK FORWARD CONTENT INDEX
text for first line =     back forward content index
function for last line =  FORWARD CONTENT INDEX
text for last line =      forward content index
.sf

HyperMake creates several HTML files. People viewing the text should be enabled to link to the next file (FORWARD) and to the file backward (BACK). Also a link to the contents window (CONTENT) and to the index (INDEX) should be available. You can choose whether all functions are available both in the first and in the last line or not. Also the words which represents the function can be changed and the order of the functions.


Buttons

.sfb
//you can use buttons BACK.GIF FORWARD.GIF CONTENT.GIF INDEX.GIF instead of text
buttons = YES
.sf

You can choose between textual links and buttons in the first/last line. The graphics file names are fixed.

The GIF files have to be placed in the directory of the HTML files. If the GIF files aren't there, the text you have defined in "text for first/last line" is shown instead. If the files are located on a unix server, the filenames are case sensitive! Use only upper case letters!

You will find a Library of Buttons in the directory BUTTONS.

body tags

.sfb
//enter tags or NO
body tags = NO
.sf

You can enter several HTML body tags. E. g.

.sfb
body tags = background="backgr.gif" TEXT="#00FFFF"
.sf

.IT background color
.IT default text color
Be careful with body tags! For example, if you choose a blue background, the links aren't visible anymore. Remember that other users have perhaps defined other default colors. Only if you choose a gray or white background graphic, there's no risk.


extended index

.in entries for extended index
.sfb
entries for extended index = 30
.sf

Here you can enter the minimal number of index entries where the program has to create the extend index instead of the simple index.


new file level

.sfb
//HTML text file is divided in several files.
//Enter heading level where new file begins (0 means only one HTML text file)
new file level = 3
.sf

HyperMake creates several HTML files from only one source file. This increases the performance of the HTML browsers dramatically. With this setting you can influcence the number of generated HTML files. "3" means that for all chapters of heading level 1, 2 and 3, seperate HTML files are created.

If Frames (window arrangement) is active in a specific area of the text, HyperMake creates a new HTML file for every chapter. 


horizontal rule level

.sfb
//Enter heading level up to which has to be divided by horizontal rules
//  (0 means no rules)
horizontal rule level = 4
.sf

HTML enables generating horizontal rules all over the window. These can be used to seperate different chapters, if they are not placed in different HTML-files. The value of "horizontal rule level" has to be greater than "new file level". "4" means the chapters of level 1, 2, 3 and 4 are seperated by a rule, if they are placed in the same file. 

content level

.in context level
.sfb
//Enter heading level up to which has to be shown in the HTML content file
//  (6 means all levels, 0 means no content)
content level = 6
.sf

With this setting you can enter up to which heading level appears on the content page. If you choose 0, no content page will be created, also the links to the content page are omitted.

HTML Filenames

.sfb
//possible settings: sample.html SAMPLE.HTML Sample.html sample.htm SAMPLE.HTM Sample.htm
filename appearance = sample.html
.sf

Here you can define how the HTML filenames looks like: small, capital letters, short filenames, long filenames. If you want to publish your HTML files in the WWW and make a mistake here, it can be possible that the links are OK on your computer and after uploading on a server, the links won't work anymore! So please read the chapter about HTML filenames.


pre filename

.sfb
//pre filename = XYZ* let all HTML files begin with XYZ
pre filename = *
.sf

(Registration needed) HyperMake creates a lot of files from only one source file. The names of these HTML files are choosen by HyperMake. E.g. it simply enumerates files: N000.HML, N001.HTML and so on. If you want to copy files from several HyperMake source files into one directory, you can enter a string every filename begins with, also INDEX.HTML. For example the input ~XYZ*~ means that the filenames are XYZN000.HTML, XYZN001.HTML and so on. Please be careful that the filenames aren't longer than 8 chars, if you use old FAT drives. (That means the pre filename is limited to 3 chars.)


default frame

.sfb
default frame = _top
.sf

If all HTML pages of your project should appear in a frame of another document, it can be necessary to change this setting. Changing this settings needs experience in HTML, so don't change this if you aren't sure.


titlebar and meta entries

.sfb
//here you can define the text appearing in the browser titlebar
//enter DOCTITLE and/or HEADING and fixed text, e.g. a slash; NO means no text
file title = DOCTITLE - HEADING
meta content = DOCTITLE - HEADING
.sf

Here you can define the text appearing in the browser titlebar and the meta entry. Meta entries are used by internet search machines. DOCTITLE is the text behind the ~.TI~ command, HEADING the heading text of the actual HTML page.


footnotes page heading text

.sfb
notes text = notes
.sf

If a source file is compiled with the commandline parameter "/NOFRAMES", HyperMake creates one single footnote file with all footnotes numbered. Here you can enter the heading of this file. This text can also be used in the titlebar of this HTML page.

.2
IPF specific settings (not HTML)

Help Subtable Start ID

.sfb
Help Subtable Start ID = 7000
.sf

With the Help Subtable Start ID setting you can define a start ID value for Subtables in helptables created by HyperMake. This setting won't be interesting unless you define constants in your (C) source file or header file with the same value (7001, 7002 etc.).


Filenames

.sfb
//files will be overwritten without warning
Helptable filename = HLPTABLE.RC
Panel ID filename  = PANELID.H
.sf

Here you can change the filenames of the helptable and panel ID file which will be automatically created by HyperMake. If you enter the filename *.XYZ, the source file name with the extension XYZ is chosen.

Note: This files will be overwritten without warning.

.1
Starting the HyperMake compiler

The HyperMake program is a compiler started from the command line, like IPFC.

.in Installation
.in compiling
.in commandline parameters
When using OS/2, before using HyperMake, you have to copy HMAKE.EXE into a directory of your PATH statement (in the file CONFIG.SYS); The file KBDVIO32.DLL has to be placed into a directory of your LIBPATH statement. If the EXE file doesn't find the DLL, you will get an OS/2 error message "0005".

There are one or two parameters you have to enter:

.sfp
.fu
[C:\myProject] HMAKE myDoc.txt my.ini
.sf

There is no order of the parameters. You have to explicit enter the file extensions. You can enter any extension for the HyperMake source file, but the extension of the ini file has to be ".INI".

If the name of the ini- and text-file at the left side of the dot is identical like myDoc.txt and myDoc.ini, it is adequate to enter only the name of the text document - HyperMake will search the ini file by itself:

.sfp
[C:\myProject] HMAKE myDoc.txt
.sf

If HyperMake does not find such ini files, it will grab the file HMAKE.INI in the current directory. If this file is also not present, the program stops and you will get an error message.

For your own ini file, better use a copy of SAMPLE.INI and not DOCU.INI because DOCU.INI has got some exotic ASCII values for the toggle chars.

.fu[]
The name of the output file will automatically be the entered source file name with the extension IPF.


.sfL
Many source files
.sf

You can split your source text in many text files. HyperMake will copy them together before compiling. The order of the parameters are relevant. If you don't enter an ini file directly, the first source filename is used for searching the ini file.

.sfL
Creating HTML- or IPF-files
.sf

With the commandline parameters ~HTML~ and ~IPF~ you can temporary overwrite the default setting "target file" in the ini file.

.IF HTMLDOC
.sfL
Creating HTML files without frames functionality
.sf

.fu
.it no frames
~/NOFRAMES~ creates HTML pages without frame functionality. This has got two effects: First, all ~.WA~ (window arrangement) commands aren't interpreted. Second, all footnotes are placed in only one footnote file and the footnotes will be numbered. The link to the footnote will be e.g. [17].
.END
.fu[]

.2
How HyperMake works

When running HyperMake, there are six parts of compiling the source file:

.afo
 Reading ini file
 Reading source file
The source file is read in one part from the disk into the heap
 ~Indexing~ headings
All headings will get an internal identification number
 Indexing links
All words or phrases marked with the index char or dot command will be placed into a list in the heap
 Writing IPF file or HTML files
At last, the IPF file / the HTML files will be written. That's the main work. Every word of the text has to be compared with the index words in the heap. In this part of compiling, the main interpreters of dot commands, toggles and helptable generating are also working. HTML files are placed in a new directory.
.IF HLPDOC
 Writing helptable file
When using .RC-dot commands in the HyperMake source file, the accumulated information in the heap about the helptable will be written into the helptable file.
.END

.sfo
When indexing headings, indexing links and writing IPF file, every compiled heading will appear as a dot on the screen.
.sf

If you hear a deep beep, HyperMake could not create an IPF file / several HTML files, because of a serious error.

.IF HTMLDOC
The extension of the HTML files is ".HTML". Only on FAT drives the extension is ".HTM".
.END

.2
Writing batch files


.IF IPFDOC
Because the IPF format isn't interesting anymore, you can start HyperMake and IPFC in one :batch file: (with the extension ".CMD"). A useful batchfile for running in the background can be:

.sfb
@echo off
rem Generating hypertext with HyperMake and IPFC
HyperMake %1.txt %1.ini >HyperMake_errors
ipfc /inf %1.ipf >ipfc_errors
echo 
.sf

The last line has got two Alt-7-chars, that will create two beeps.

If you find an incorrect output, you can read the ASCII files HyperMake_errors and ipfc_errors (or, if using FAT file system, 8 char shortcuts.).

If you don't enter /inf behind ipfc, you'll get a HLP file instead of an INF file. The IPF file generated by HyperMake can be always used for generating HLP and INF files, even you have used HLP specific ressource connection and Panel ID dot commands.

If you are not familiar with batchfiles, take a look at the chapter "OS/2-commands, batchfiles" in the OS/2 commandline reference.
.END IPFDOC

Remember when making a backup on disks or streamer, you need not save the HTML files or IPF files, because you can reproduce them every time from the HyperMake source file.

.IF HTMLDOC
To create HTML files, you can write a batchfile which deletes the old HTML files and starts HyperMake:

.sfb
del %1\*.html
HMAKE %1.txt #Condition >HyperMake_errors
edit HyperMake_errors
.sf
.END HTMLDOC

.2
Debug mode

.in bugfixing
It can happen that HMAKE interrupts and creates a cryptic error message. Then you have made a mistake I've never thought about or there's a real bug in the program. To locate where exactly the bug has occurred, you can view the actual line numbers by using the commandline parameter ~/count~. Then by using the ~/debug~ parameter, you can get the source text immediately before the program crashes. So you can find the exact position where the bug occurs.

With ~/debugmain~ instead of ~/debug~, the text is only shown when writing the IPF/HTML files.

If you find such a bug, please contact me, even you have found out how to avoid it. Please send me the source text and your ini file, so I can locate the bug and eliminate it in the next version. Thank you.

.1
Reverse converting mode from IPF to HyperMake

If you have already written an IPF file directly, HyperMake helps you to get a HyperMake source file. It's not possible to get a perfect source file, but the rudimentary functions are converted.

The :reverse converting mode: is enabled to convert:

 toggles
 Headings
 unordered lists, ordered lists
 main formatting commands (paragraph, break, formatting on/off)
 index entries (only i1 level), they will also get link target
 graphics

It's not enabled to convert:
 Fonts
 Window arrangement
 Margin
 Footnotes
 definition lists
 Panel ID's, connection to EXE program.

The ini file is used in reverse converting mode, too. So first take a look at the ini file settings "list char", "toggle char" and "Source format". Be sure that you have defined enough list chars (e.g. four list chars if you have got ordered/unordered lists up to four levels).

.afb
The reverse converting mode is activated if you enter a filename with extension ~IPF~. You have to enter both IPF and INI filename.

.sfp
.fu
[C:\myProject] HMAKE myDoc.ipf myDoc.ini
.sf

.fu[]
The file which is generated has always the same name HMSOURCE.TXT.

.WA verti 25
.1
About

.in HyperMake

.2
Registration

.in Registration
.in price
.afL
This program is ~shareware~ if you want to compile bigger source files than 20 kB. You need a registration key to compile such bigger source files. When compiling smaller source files than 20 kB, it will be ~freeware.~

Why 20 kB? I think writing small HTML documents and INF or HLP files for simple HTML documents and freeware programs should be possible without registering. So if you find errors and you are not registered, you also can send me a mail.

There's a small registration key (up to 150 kB source text) and a big one (no limit). The registration fee is ~40 Dollar~ or ~60 Deutsche Mark~ for the small registration key and ~70 Dollar~ or ~120 Deutsche Mark~ for the big one.

When ordering more than one licenses, you will get a 30% discount for every additional license.

You can register this software with Compuserve Software registration. Go ~SWREG~. The Registration ID for the small reg key is ~9988~, and for the big one ~15175~.

The keys fits for all platforms and all future versions.

It's a shame in the age of information superhighways, but the simplest way to send money - besides Compuserve SWREG - is to put banknotes into an envelope! If you would send foreign currency like Dollar to my bank account, I would have to pay 15 DM changing fee! Do not send cheques in foreign currencies, too ! If you can send Deutsche Mark (for example you live in Germany), my banking account Number is:
Dresdner Bank Ottobrunn (Germany), Bank Code 700 800 00, Nr. 075 64 62 400

If you register, you will get a receipt and the registration key. The registration key has to be placed in your HyperMake ini files.

.2
Disclaimer

HyperMake is provided as is and comes with no warranty of any kind, either expressed or implied. In no event will the author be liable for any damages resulting from the use of this software.

.2
Author

.in Author
Martin Vieregg, 30. I've studied economics. My main job is working in my own consulting company. Our special subject is public transport, especially railways. The title of my doctoral (PhD) thesis was "increasing efficiency of railway long-distance passenger traffic".

.in Contacting the author
My mail address is:

Martin Vieregg Compuserve 100661,626
from the Internet:
Martin Vieregg 100661.626@COMPUSERVE.COM

My postal address is:

Dr. Martin Vieregg
Hubertusstr. 26
D-85521 Ottobrunn
Germany

.2
Versions

.sfL
Ideas for future HyperMake versions
.sf

 A graphical user interface, perhaps with editor; if the user saves the source text, the compiler starts automatically in the background
 more platforms
 supporting the new Micosoft context-sensitive HTML format
 WinHelp (I'm not sure)
 RTF to HyperMake reverse converting mode (Richt text format, that's the old input of Windows help).

Take a look at my homepage. Here you will find announcements. If you have ideas, email me!

.in new version
.sfL
new functions in HyperMake 3.0:
.sf

 tables both for IPF and HTML
 user-defined navigation buttons in addition to back, forward, content, index, pointing to specific chapters or URLs
 user head tags (meta entries) copying into every HTML file
 settings for the appearance of filenames (small/capital letters, 8.3 convention)
 settings for the titlebar text in the HTML browser
 commands for bugfixing
 settings for appearance of links to subchapters
 more flexible usage of toggle chars
 HTML fonts
 Library of Buttons.

.sfL
new functions in HyperMake 2.9:
.sf

 target file format HTML in addition to IPF
 reverse converting mode from IPF to HyperMake
 index filter
 many source files (see commandline parameters)
 (2.91) first version also available as a Win32 program
 (2.91) footnotes also for HTML.

.sfL
bugfixes in (new name) HyperMake 2.9:
.sf

 "link to subchapters = NO" created a malfunction
 Together with IPFC Version 2.1 (1993) and the  "ASCIIHARDRET" setting, in larger paragraphs a space was missing after 200 chars.
 With the "ASCIIHARDRET" setting, malfunctions with unsorted lists occured.

.sfL
new functions in MakeIPF 2.0:
.sf

 external links to separate HLP- and INF-files
 launching programs by hyperlinks
 automatic duplication of heading text in the text window, heading text gets link target and is placed in the index

 more detailed error messages, so running IPFC will create fewer error messages
 tabs are converted into a number of spaces like an editor does (use only with non-proportional fonts)
 improved window arrangement (see last paragraph of that chapter)
 registration via Compuserve

.sfL
bugfixes in MakeIPF 2.0:
.sf

 Error printing INF/HLP files (in non-proportional fonts, all letters are printed at the same position of the page)
 wrong number of carriage returns when formatting is turned off.

Also, a lot of minor bugs were fixed.

.sfL
Improvements and bugfixes since from MakeIPF beta 0.91 to 1.0:
.sf

 "access denied" no more occurs. Lower RAM memory demand.
 now compiled with final (non-beta) SpeedPascal compiler. (Using a file instead of stdout now works.)
 auto margin .AM
 if-conditions
 improvement of automatic linking (especially endings of words)
 several bugfixes

.2
Location

You will find the latest OS/2 version of HyperMake in Compuserve OS2USER 4 and OS2BVEN. In the internet, the addresses are os2.nmsu.edu, ftp.cdrom.com/pub/os2 and in germany ftp.leo.org/pub/comp/os/os2.

The win32 locations are ftp.cica.indiana.edu, ftp.coast.net, http://www.coast.net/SimTel/,
ftp.cdrom.com, http://www.cdrom.com/ and in Compuserve WINUSER.


The OS/2 version has got the name Hmakeo*.ZIP.
The Win32 version has got the name HmakeW*.ZIP.

Do you have some ideas for new functions?

.2
Trademarks

IBM and OS/2 is a registered trademark of International Business Machines Corp.
WordStar is a trademark of Micro Pro.
SpeedPascal is a trademark of SpeedSoft GmbH.
TurboPascal is a trademark of Borland Corp.
Windows is a trademark of Microsoft.

.2
Platforms

.it several platforms
You will be astonished by the speed of HyperMake. And now the surprise: I haven't used a C compiler, I have used the TurboPascal/Delphi compatible SpeedPascal[Speedsoft, Chemnitz, Germany]. It's a cross compiler generating both OS/2 and Win32 programs. A Powermac, a Linux and a AIX version is also planned, so HyperMake will be available for these platforms in the future, too.

.2
Other progs

Other programs I have programmed, all OS/2 programs (till yet...).

 PMCALC20 PmCalc 2.0, a PM calculator with automatic clipboard function, hex and scientific functions (shareware)
 TINYALRM TinyAlarm 2.1, a clock, countdown with a slider from 1 to 60 and an alarm by entering alarm time (freeware)
 ZIPSHELL Simple Zipshell, a handful tiny batchfiles for handling ZIP- and ARJ-files with the OS/2 WPS (freeware)
 CLEAR10E Clear 1.0 Creating file lists for deleting and backup. Works together with Info-Zip (freeware)
 CD_SHORT CD Shortcut 2.0, instead of whole directory names you enter only substrings (freeware)

I have placed them in Compuserve OS2USER 4 and you will find them in the internet at ftp-os2.nmsu.edu, ftp.cdrom.com/pub/os2 and in germany at ftp.leo.org/pub/comp/os/os2.

Visit my homepage, here you will find a detailed description and screenshots. I will port pmCalc to Win32.

end of hypertext
..
..external link to my homepage and to the Library of Buttons
.URL http://ourworld.compuserve.com/homepages/vrb/VIEREGG.HTM
.ID HOMEP
.in Homepage
.URL ..\..\buttons\content.htm
.in Library of Buttons
.LOCAL
