═══ 1. Introduction ═══ With MakeIPF, you can easily create IPF files. Instead of editing the IPF files directly, you enter a simpler ASCII source text. Links are created automatically; windows of different headings levels can be shown simultaneusly with only one command; at the end of a chapter, links to subchapters are created automatically and a lot of more. The new version 2.0 has got new functions and some minor bugfixes. IPF, INF and HLP-files The contents of IBM INF and HLP files are described in a language called IPF. 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. What MakeIPF does MakeIPF helps you writing IBM INF * and HLP files * . MakeIPF generates IPF * files from a special MakeIPF ASCII format. The automatically generated IPF file is the source file for the IBM program IPFC * . When using MakeIPF, you have only to learn the much more easier MakeIPF source format. You can write MakeIPF files with o an ASCII-editor o or an old DOS WordStar Version 3.4 or 4 * . MakeIPF has some powerful functions: o 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. o Automatic generation of helptables In the MakeIPF source file you can directly enter ID constants like "ID_buttonOK" to associate chapters of your HLP file with buttons of your program. MakeIPF generates a helptable file you can include in your RC file. o Automatic Writing of links to subchapters At the end of a window of a higher heading level, links to all subchapters and to the next chapter of the same level will be created. o Automatic arrangement of several heading level windows With only one command, two or three heading levels are placed simultaneously on the screen. See window arrangement sample output. o Simple creation of footnotes o Automatic line drawing to generate boxes o Short commands - for heading levels - for choosing fonts - to include bitmaps within a line of text - to generate unordered lists and ordered lists. ═══ 2. Writing a file in the MakeIPF format ═══ subchapters: Essentials Beginning Headings Fonts Unordered lists and ordered lists Including Bitmaps Linking and Indexing Line drawing Footnotes Margins and Formatting if-conditions next chapter: Generating helptables and panel ID's ═══ 2.1. Essentials ═══ subchapters: Dot commands Toggles Handling of Returns next chapter: Beginning ═══ 2.1.1. Dot commands ═══ The MakeIPF format uses dot commands like old WordStar. A dot command is a complete line beginning with a dot, for example .SF sets the standard font to default. Dot commands aren't case sensitive. A lot of dot commands are expecting parameters, for example .LM10 will change the left margin to 10. You may write a space between the dot command and the parameter. The line ..comment will be ignored. .:ipfcommand. .:ipfcommand. expression You can enter an IPF command directly (that will be an exception, because most important functions are part of the much easier MakeIPF format). In this hypertext, you will find a dot command summary. ═══ 2.1.2. Toggles ═══ In the ini file you can set some toggle chars. If you have chosen "*" for "underlined" and "@" for italic, you can write: This *part of this sentence* is very important. And you will get: This part of this sentence is very important. You also can mix some toggles: This is *underlined and @also italic* and only italic@. And you will get: This is underlined and also italic and only italic. But be careful. You aren't allowed to use the toggle chars in another way. So you have to think about chars you absolutely won't use in your text. A good choice will be the control chars below 32, if your editor supports them. * ═══ 2.1.3. Handling of Returns ═══ 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 o there are two Returns behind each other (i. e. an empty line) o the last character in the line is . ! ? : ; Using DOS WordStar, such problems don't exist, because WordStar knows both soft and hard Returns. ═══ 2.2. Beginning ═══ Every document has one title. The title will be shown as title of the main window and in the tasklist. .TI Documentation of my program sets the title in INF files. Every MakeIPF INF source text should begin with the title dot command, before the first heading. 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 .<> ═══ 2.3. Headings ═══ Starting an INF file, you will get the contents window where you can open and close sub chapters like a directory tree. The text under every heading fills a seperate window. You can arrange your text with heading levels like you would in a scientific work: first heading first sub heading second sub heading first sub sub heading second sub sub heading third sub heading second heading In the MakeIPF format, the headings are written like .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 Below the dot command for the heading level, you can enter the text appearing in the window with the specific heading. 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 The Text behind a heading dot command is limited to approx. 200 chars * , but you will see only 70 to 120 chars, dependent of the size of the INF window on the screen. At the beginning of a document, normal text can only be written after using the first heading dot command. * You are allowed to use up to 6 heading levels. When a chapter has got subchapters, links to subchapters and a link to the next chapter with the same heading level are automatically created. subchapters: Window arrangement duplication of heading text next chapter: Fonts ═══ 2.3.1. Window arrangement ═══ 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. Arranging two heading levels With the dot command Window Arrangement .WA verti 30 followed by a normal heading level dot command, the main window is divided vertically in 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 behind 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 to leave the automatic link to subchapters function turned on in the ini file. .WA hori 40 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%). It is allowed to enter percent values from 10 to 90. For a sample arrangement of two heading levels see dot command summary and ini file. Arranging three heading levels In the same way, you are allowed to arrange three heading levels. Now you have to enter a hori and a verti value simultaneously. .WA hori 40 verti 30 III 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: verti hori hori verti ┌─────╥──────────┐ ┌────────────────┐ │ ║ II │ │ I │ I │ I ╠══════════╡ ╞═════╦══════════╡ │ ║ III │ │ II ║ III │ │ ║ │ │ ║ │ └─────╨──────────┘ └─────╨──────────┘ ┌─────╥──────────┐ ┌─────╥──────────┐ │ I ║ │ │ I ║ II │ ╞═════╣ │ ╞═════╩══════════╡ III │ ║ III │ │ │ │ II ║ │ │ III │ │ ║ │ │ │ └─────╨──────────┘ └────────────────┘ 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. subchapters: Sample Input Sample Output next chapter: duplication of heading text ═══ 2.3.1.1. Sample Input ═══ .WA verti 50 hori 40 I .4 Sample Output The main chapter with links to subchapters. .5 first sub chapter The first sub chapter with links to sub sub chapters. .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. ═══ 2.3.1.2. Sample Output ═══ The main chapter with links to subchapters. subchapters: first sub chapter second sub chapter next chapter: duplication of heading text ═══ 2.3.1.2.1. first sub chapter ═══ The first sub chapter with links to sub sub chapters. subchapters: first sub sub chapter second sub sub chapter next chapter: second sub chapter ═══ 2.3.1.2.1.1. first sub sub chapter ═══ The first sub sub chapter of the first sub chapter. ═══ 2.3.1.2.1.2. second sub sub chapter ═══ The second sub sub chapter of the first sub chapter. ═══ 2.3.1.2.2. second sub chapter ═══ The second sub chapter. subchapters: first sub sub chapter second sub sub chapter next chapter: duplication of heading text ═══ 2.3.1.2.2.1. first sub sub chapter ═══ The first sub sub chapter of the second sub chapter. ═══ 2.3.1.2.2.2. second sub sub chapter ═══ The second sub sub chapter of the second sub chapter. ═══ 2.3.2. duplication of heading text ═══ It's often necessary to use the heading text as a link target, to place it into the index and to duplicate the heading text in the text window with a bigger font: .3 heading text .IN heading text .snC heading text .sn You can abbreviate this tedious job: Using the new dot command DuPlicate .dp duplicates the heading text at the beginning of the text window, in all heading levels. That's useful if you write long heading text, because in the titlebar only the first 70 characters are shown on average. .dp34 duplicates heading text only in heading level 3 and 4. .dpA uses font A for the duplication of heading text in the text window. .dp- deactivates the duplication of heading text for all heading levels. .dp-234 deactivates the duplication functionality only in the heading levels 2, 3 and 4. .dp# in addition to duplication of heading text at the beginning of the text window, the heading text becomes a target link. Writing the heading text behind the IN dot dommand is no more necessary. Instead of # you can also write the index char you have chosen in the ini file. .dp## 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. And a big index can dramatically slow down a (very big) HLP or INF file! .dp3##, .3 Smith, John in the text window, "John Smith" is shown, and that's also the link target. But in the titlebar, the contents and the index, "Smith, John" is written. You can combinate any of these commands. subchapters: Sample input Sample output next chapter: Fonts ═══ 2.3.2.1. Sample input ═══ .fa verti 30 .dp5R#, .4 Sample output german federal chancellors since 1949 (CDU, SPD and chancellor are external links. Font R is defined in the ini file.) .5 Adenauer, Konrad 1949-1963, CDU, first chancellor after the second world war. His successor was Ludwig Erhard. .5 Erhard, Ludwig 1963-1966, CDU, Successor of Konrad Adenauer. Second chancellor of the Federal Republic of Germany. He was predecessor of Kurt Georg Kiesinger. .5 Kiesinger, Kurt Georg 1966-1969, third chancellor of CDU, leader of the "big coalition" of the parties CDU and SPD. Successor of Ludwig Erhard. .5 Brandt, Willy 1969-1974, first chancellor of the SPD. .5 Schmidt, Helmut 1974-1982, chancellor of the SPD. Successor of Willy Brandt. .5 Kohl, Helmut chancellor of the CDU since 1982 till yet. His predecessor was Helmut Schmidt. ═══ 2.3.2.2. Sample output ═══ german federal chancellors since 1949 (CDU, SPD and chancellor are external links. Font R is defined in the ini file.) subchapters: Adenauer, Konrad Erhard, Ludwig Kiesinger, Kurt Georg Brandt, Willy Schmidt, Helmut Kohl, Helmut next chapter: Fonts ═══ 2.3.2.2.1. Adenauer, Konrad ═══ Konrad Adenauer 1949-1963, CDU, first chancellor after the second world war. His successor was Ludwig Erhard. ═══ 2.3.2.2.2. Erhard, Ludwig ═══ Ludwig Erhard 1963-1966, CDU, Successor of Konrad Adenauer. Second chancellor of the Federal Republic of Germany. He was predecessor of Kurt Georg Kiesinger. ═══ 2.3.2.2.3. Kiesinger, Kurt Georg ═══ Kurt Georg Kiesinger 1966-1969, third chancellor of CDU, leader of the "big coalition" of the parties CDU and SPD. Successor of Ludwig Erhard. ═══ 2.3.2.2.4. Brandt, Willy ═══ Willy Brandt 1969-1974, first chancellor of the SPD. ═══ 2.3.2.2.5. Schmidt, Helmut ═══ Helmut Schmidt 1974-1982, chancellor of the SPD. Successor of Willy Brandt. ═══ 2.3.2.2.6. Kohl, Helmut ═══ Helmut Kohl chancellor of the CDU since 1982 till yet. His predecessor was Helmut Schmidt. ═══ 2.4. Fonts ═══ Standard Font You can choose a font with the dot command standard font .SFX X is a font character from A to Z and from a to z (case sensitive!) which represents a specific o font o size o codepage o foreground color o background color. 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: .SF Alternate font 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: That d o e s n't l o o k very good. 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 to use the default font for normal text, because the default font is a proper font on every screen. A font will be active till the next font dot command, even through headings. Alternate fonts should be only active within a paragraph. To write more than one paragraph in another font, please use the .SF command. subchapters: Font samples Color samples next chapter: Unordered lists and ordered lists ═══ 2.4.1. Font samples ═══ Tms_Rmn 12 Tms_Rmn 15 Tms_Rmn 25 Helv 12 Helv 15 Helv 25 Courier 12 Courier 15 Courier 25 System_VIO 12 System_VIO 15 ═══ 2.4.2. Color samples ═══ foreground default blue cyan green neutral red yellow black background DEFAULT BLUE CYAN GREEN NEUTRAL RED YELLOW BLACK ═══ 2.5. Unordered lists and ordered lists ═══ The following text represents an unordered list: o Style - font (default, Tms_Rmn, Helv, Courier, System_VIO) - size o 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 influence the list chars the IPFC compiler generates. Writing unordered lists depends on your source format. The input of ordered lists is very similar to unordered lists. The IPF command "Definition List" is not supported directly. You can emulate it with the MakeIPF auto margin command. subchapters: Using DOS WordStar Using an ASCII editor Ordered lists next chapter: Including Bitmaps ═══ 2.5.1. Using DOS WordStar ═══ WordStar knows soft spaces ░ . Soft spaces can be created in WordStar with the command ^OG. * There are no definitive list chars for the different list levels like using an ASCII editor. Instead, using soft spaces is necessary. ■░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). 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 MakeIPF: ■░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) After writing a normal paragraph without list function, for the next unordered list you can use other list char characters and positions. ═══ 2.5.2. Using an ASCII editor ═══ In the ini file you can define list chars. List chars have to be at the beginning of a line. To generate the list from the last page, you have to enter ■ 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). The standard list chars in the ini file are ■ (Alt-254) for the first list level, ═ (Alt-205) for the second and ─ (Alt-196) for the third level. You can add list chars for further levels. To enter normal text after writing an unordered list, you have to enter a paragraph. It's allowed to put more spaces behind and in front of the list char, they will be ignored. The same result as above will be: ■ Style ═ font (default, Tms_Rmn, Helv, Courier, System_VIO) ═ size ═══ 2.5.3. Ordered lists ═══ 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 influence 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 .OL .UL 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.6. Including Bitmaps ═══ To include a big bitmap centered, you can use the dot command bitmap .BM filename If you write the filename without extension, ".BMP" will be automatically added. IPFC also supports OS/2-MET-files. * With the second dot command bitmap text, you can include bitmaps in text. .BTX filename 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 need more place 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. You are allowed to define several bitmap chars simultaneously. To deactivate a character-bitmap definition, you can enter .BTX without a filename. ═══ 2.7. Linking and Indexing ═══ Linking * is the most powerful function of MakeIPF. When writing an 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... Automatic linking and indexing with MakeIPF With MakeIPF, 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. Note: Do not use index chars in headings, use automatic duplication of heading text instead. subchapters: Marking a single word, Changing the index char Marking a phrase of several words in the running text Marking a phrase outside the running text Handling of endings, uppercase and lowercase letters Marking a word several times Omitting links External links Launching programs by links next chapter: Line drawing ═══ 2.7.1. Marking a single word, Changing the index char ═══ Marking a single word You can mark a single word for linking and indexing with the index char, defined in the ini file. A #workgroup is a group of people... Changing the index char You also can change the index char in the text by using the dot command index char .IC@ This will change the index char from the actual setting, for example # , to @ . ═══ 2.7.2. 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: Today, the #:security of computers: is... ... Nevertheless, the #:security of mainframes: can be... ... But the #:usability of computers; has to... In the index, it will appear computers, usability of security of computers of mainframes 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 computers usability of the MakeIPF entry in the index will be: computers, usability of You are allowed to use the "colon brackets" to crop endings: The importance of #:computer:s is growing... In the index "computer" will appear without "s", also the link target will be "computer" and not "computers". ═══ 2.7.3. Marking a phrase outside the running text ═══ With the dot command INdex .IN phrase 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 to the leading word like using the brackets colon-semicolon in running text, you can use the dot command index turned. .IT usability of computers 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. ═══ 2.7.4. Handling of endings, uppercase and lowercase letters ═══ Handling of endings What to do when the source link word is "computers" and the marked word is "computer" without "s"? In this case, MakeIPF 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 a ending is not recommended, because when the word occurs without the ending, the link won't be created. To find the correspondent word even in the case "query" "queries", MakeIPF crops the last letter of the word when it's a vocal letter * (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). Uppercase and lowercase letters 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: .IN Word Links are created to Word , word , but not to WORD . ═══ 2.7.5. Marking a word several times ═══ MakeIPF expects that a word or a phrase is marked only one time. When marking it several times, it will appear several times in the index, and the link target will be the first marked phrase. * ═══ 2.7.6. 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. 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. ═══ 2.7.7. External links ═══ External links are links to chapters of other INF or HLP files. To create such external links, you have to edit o the ini file o the file which is shown when using the link (link target file) o the file from where the link is executed (link start file). External links are using the MakeIPF function panel ID. But you need not read the panel ID chapter. 1. Ini file Behind "Panel ID filename =" in the ini file, you have to enter a file extension beginning with *. like Panel ID filename = *.PAN Compiling the link target file with MakeIPF 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 MakeIPF when compiling the link start file. 2. Link target file When indexing headings, MakeIPF 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 .ID Chapter_beginning 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, dependent of the entry in the ini file. This panel ID file is used by MakeIPF when compiling the link start file. 3. Link start file 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. ^@.EX filename.inf ^@.ID Chapter_beginning ^@.IN expression ^@.EX Behind 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 behind 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, MAKEIPF has to compile this file before compiling the link start file - because of updating the panel ID file. When entering a filename .EX filename.inf 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 too, if the directory is placed behind "SET BOOKSHELF" in the file CONFIG.SYS. If these two possibilities does 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: .EX sample.inf .ID chapter_chancellor .IN chancellor .ID chapter_political_parties .IN SPD .IN CDU .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. ═══ 2.7.8. Launching programs by links ═══ Similar to external links, you can create links to external programs, that means launching programs. .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 behind 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. subchapters: Environment variables next chapter: Line drawing ═══ 2.7.8.1. Environment variables ═══ 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: SET MMVIDEO=C:\MMOS2\MOVIES In the MakeIPF source file, you can use this variable: .EX mppm.exe %MMVIDEO%\macaw.avi .IN parrot .EX 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: SET MMBASE=C:\MMOS2; In this case the environment variable does not work and the link won't be created. For environment variables, take a look at chapter "SET" in the OS/2 commandline reference. ═══ 2.8. 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. .LIXYZ ZX X Operating systems Y ZY X X Novell IBM Hardware Y Y X X DOS Netware OS/2 X X .LI The result will be: ╔═══════════════════════════╗ ║ ║ ║ Operating systems ║ ║ ║ ╟─────────────────┼─────────╢ ┌────────────┐ ║ Novell │ IBM ║ │ Hardware │ ╟───────┼─────────┼─────────╢ └────────────┘ ║ DOS │ Netware │ OS/2 ║ ╚═══════╧═════════╧═════════╝ 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. You can change the standard font for line drawing in the ini file, font setting LineStandard. 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. subchapters: Line drawing and WordStar next chapter: Footnotes ═══ 2.8.1. 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. ═══ 2.9. Footnotes ═══ Generating Footnotes with MakeIPF 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 * appears where you can click with the mouse. Other useful footnote bracket chars are [ ], < > or ▄ (Alt-220) ▀ (Alt-223). 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: .BT▀ blob.bmp .FT▀ (see bitmap text.) ═══ 2.10. Margins and Formatting ═══ subchapters: Changing the left margin Turning Formatting off and on Centered Text Auto Margin next chapter: if-conditions ═══ 2.10.1. Changing the left margin ═══ This is a sample text with left margin 1. This is a sample of left margin 10; note that the formatting will be correct. This is a sample of left margin 20; note that the formatting will be correct. You can change the left margin by using the dot command left margin .LM n 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. Using DOS WordStar, you have to use soft spaces instead. * ═══ 2.10.2. Turning Formatting off and on ═══ With the dot commands Formatting off and Formatting on .FM off .FM on you can turn formatting off and on. The standard is Formatting on. 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. * Don't use index chars, only use the index dot command, quoted in formatting dot commands: .fm on .in word1 .in word2 .fm off ═══ 2.10.3. 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 .OC on .OC off ═══ 2.10.4. Auto Margin ═══ To write definition lists for example, * you can simply change the left margin by using spaces and the new dot command Auto Margin .AM on *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. .AM off 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. You are allowed to turn the AM setting on for normal running text. Every spaces 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. The AM default setting ist off. 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. WordStar files don't need the auto margin function. * ═══ 2.11. if-conditions ═══ With if-conditions, you can create slightly different IPF files from the same source text. There are three new dot commands .IF CONDITION .ELSE .END The conditions are not case-sensitive. For compiling the source text, you have to enter in the command line: [C:\myProject] makeipf myDoc.txt #CONDITION You can enter more than one condition in the command line. Note the # character, there is no order of the parameters. Several conditions in the if-command, connected by AND or OR are not supported. ═══ 3. Generating helptables and panel ID's ═══ 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. Pushing a mouse button at your program with simultaneously pushing F1 will activate a chapter (a window) of the hypertext. There are two different kinds of links from a program to a HLP file: o links by using helptables o 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. Without MakeIPF, you would have to write a helptable in the RC file * 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". subchapters: Writing the MakeIPF source file Writing your C program source file Writing your Pascal program source file Writing several HLP files of different languages next chapter: dot command summary ═══ 3.1. Writing the MakeIPF source file ═══ In the MakeIPF file, there are two new dot commands: The command ressource connection .RC ID_window, ID_button_or_Menu_Item 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. ID_window is the constant placed after MENU or DIALOG in your RC file. Note: ID_window is not the constant placed after DLGTEMPLATE. * And with panel ID .ID Chapter_Name 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 * 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 .RC , ID_button_or_Menu_Item This will use the name of the last window ID. You are allowed to generate an INF file with IPFC when the MakeIPF 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 influenced. 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, MakeIPF creates a warning. This sample MakeIPF source file has got ressource connection and Panel ID dot commands: .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. ═══ 3.2. Writing your C program source file ═══ MakeIPF automatically creates a file HLPTABLE.RC: #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 */ } MakeIPF also creates a file PANELID.H: /*****Panel ID's created by MakeIPF*****/ #define PANEL_Introduction 1 #define PANEL_usage_OK 2 The numbers 1, 2 and 3 are the IPF internal heading-ressource-id's. In the helptable file, MakeIPF 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 #include "HLPTABLE.RC" for example after a MENU or a DLGTEMPLATE block in your RC file and #include "PANELID.H" 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 #define HELP_TABLE 7000 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 void InitHelp (hwnd) /*initialize the help process*/ void DestroyHelp () /*destroy the help instance*/ 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 void DisplayHelpPanel (PanelID) 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 * #define INCL_HELP subchapters: C source code with the three help functions next chapter: Writing your Pascal program source file ═══ 3.2.1. C source code with the three help functions ═══ #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 MakeIPF 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."); } ═══ 3.3. Writing your Pascal program source file ═══ MakeIPF automatically creates a file HLPTABLE.RC: 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 MakeIPF also creates a file PANELID.INC: { Panel ID's created by MakeIPF } const PANEL_Introduction = 1; PANEL_usage_OK = 2; The numbers 1, 2 and 3 are the IPF internal heading-ressource-id's. In the helptable file, MakeIPF 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 {$I HLPTABLE.RC} for example after a MENU or a DLGTEMPLATE block in your RC file and {$I PANELID.INC} at the top of your program source file (a PAS file). First, there are two procedures to start the HLP file: DisplayHelpPanel (PanelID) 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. SendHelpMessage (HM_HELP_CONTENTS) 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. subchapters: Creating the help functionality with SpeedPascal OPML Creating the help functionality without OPML next chapter: Writing several HLP files of different languages ═══ 3.3.1. Creating the help functionality with SpeedPascal OPML ═══ In the method TApplication.InitMainWindow you have to append the following line at the end: MainWindow^.InitWindowHelp ('MYPROG.HLP', 'help window title'); That's all. ═══ 3.3.2. Creating the help functionality without OPML ═══ To create the connection between your EXE file and the HLP file, you need two procedures: uses PMHELP; InitHelp (hwnd); {initialize the help process} DestroyHelp; {destroy the help instance} 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: HelpFilename := 'MYPROG.HLP'; HelpWindowTitle := 'heading of the hypertext window'; HELP_TABLE := 1000; The number 1000 is also used in the Helptable created by MakeIPF. If you do not use SpeedPascal 1.5 (or later), you will find the procedures and variables in the subchapter. subchapters: Pascal Help Source next chapter: Writing several HLP files of different languages ═══ 3.3.2.1. Pascal Help Source ═══ {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 MAKEIPF 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; ═══ 3.4. Writing several HLP files of different languages ═══ If you are writing several HLP files of different languages and you have only one EXE file, it is adequate to enter the RC- and ID-dot commands only in one MakeIPF source file. There aren't any problems if you have got exactly the same heading level structure in every MakeIPF source file. MakeIPF simply enumerates the headings from the first heading (res ID 1) to the end. ═══ 4. dot command summary ═══ Here you find a summary of all MakeIPF dot commands. You will find the same structure of subjects in Writing a MakeIPF file. Some dot commands have got synonyms in german language or WordStar synonyms, they are quoted in brackets and interpreted both. subchapters: Essentials Beginning Headings Fonts Lists Bitmaps Linking and Indexing Line drawing Footnotes Margins and Formatting if-conditions Helptables and Panel ID's next chapter: Ini file ═══ 4.1. Essentials ═══ ..comment "comment" is not interpreted. .:ipfcommand. .:ipfcommand. expression You can enter an IPF command directly. ═══ 4.2. Beginning ═══ .TI Title text sets the title of the hypertext in INF files. .<> creates pushbuttons "Contents", "Back" and "Forward" in HLP files, normally only INF files have. ═══ 4.3. Headings ═══ .1 up to .6 sets a heading level .1 Main heading The title of the first heading level is "Main heading". .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. 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. ═══ 4.4. 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. ═══ 4.5. Lists ═══ .OL turns the ordered list setting on .UL turns it off (default, "unordered list"). ═══ 4.6. Bitmaps ═══ .BM filename places a bitmap centered. .BTX filename replaces all occurrences of the bitmap char X by the bitmap filename.bmp. ═══ 4.7. 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. External links .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 Launching programs .EX programname.exe parameter .IN phrase .EX All occurrences of "phrase" become a link to the program "programname.exe", with the parameter "parameter". ═══ 4.8. Line drawing ═══ .LIXYZ X ZY X ┌───╥───┐ │ ║ │ Y result: ├───╫───┤ │ ║ │ X X └───╨───┘ .LI Line drawing generates a box (X are the corners), divided by Y. Z in front of X or Y uses double lines. ═══ 4.9. Footnotes ═══ .FU{} defines brackets to quote footnote text. If you enter you will get {content of the footnote}. you will get * . .FT XXX footnote text: writes "XXX" instead of the default "*". Bitmap chars are allowed. ═══ 4.10. Margins and Formatting ═══ .LM 10 will set the left margin from default 1 to 10. .FM off ( .FM aus ) .FM on ( .FM an ) Formatting turns formatting off and on. Default is on. .OC on ( .OC an ) .OC off ( .OC aus ) turnes 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. ═══ 4.11. if-conditions ═══ .IF CONDITION .ELSE .END is only compiling specific source text to IPF. The conditions are set by using the command line (not case-sensitive) [C:\myProject] makeipf myDoc.txt #CONDITION ═══ 4.12. Helptables and Panel ID's ═══ .RC ID_window .RC ID_window, ID_button_or_Menu_Item .RC , ID_button_or_Menu_Item .ID PanelID RC dot commands create a helptable in the file HELPTABLE.RC, ID dot commands create a file PANELID.H. ═══ 5. 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: Settings of MakeIPF In C++ manner, lines beginning with double slash // won't be interpreted, either. 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. Switches subchapters: Language Registration key Source format List chars Index char no more links in toggles Font endings of words Extended Letters Text for link to Help Subtable Start ID Filenames next chapter: Starting the MakeIPF compiler ═══ 5.1. Language ═══ //possible settings: ENGLISH, GERMAN, C, PASCAL Language = ENGLISH C 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 MakeIPF. 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 If you want to create Panel ID and Helptable files, MakeIPF has to know your programming language C or Pascal. ═══ 5.2. Registration key ═══ Registration key = 0 Here you have to enter your registration code, if you want to compiler bigger sources than 25 kB. see registration ═══ 5.3. Source format ═══ //possible Settings: ASCIIHARDRET, ASCIISOFTRET, WORDSTAR4 Source format = ASCIISOFTRET see handling of Returns ═══ 5.4. List chars ═══ //only ASCII source List chars = ■═─ List chars are necessary to create unordered lists with an ASCII editor. ═══ 5.5. Index char ═══ Index char = # see linking and indexing ═══ 5.6. no more links in ═══ //possible Settings: PARAGRAPH, WINDOW no more links in = PARAGRAPH see Linking, Omitting links ═══ 5.7. toggles ═══ //highlighted char toggles //order: alternate italic bold underlined red cyan blue toggles = *#@№|&¤ Here you can enter toggle chars. You always have to enter all seven toggle chars. Using WordStar, you have to enter the original ASCII characters. * ═══ 5.8. Font ═══ //Font chars from A to Z and from a to z (case-sensitive!) //parameters: Font size codepage foregroundcolor BACKGROUNDCOLOR // Linestandard OmitLinks Font A = 15 Courier Font b = Courier 12 black 437 LineStandard 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 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: o size: all numbers smaller than 200 o codepage: all numbers equal and bigger than 200 o foregroundcolor: all colors in lower case letters: default, blue, cyan, green, neutral, red, yellow, black. o backgroundcolor: all colors in capital letters: DEFAULT, BLUE, CYAN, GREEN, NEUTRAL, RED, YELLOW, BLACK. o Font: 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. The default codepage is defined by the settings in your operating system or by a parameter of IPFC. 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. ═══ 5.9. endings of words ═══ //endings in german words: n en s es ending of words = s es 's See Linking, Handling of endings ═══ 5.10. Extended Letters ═══ //language specific letters besides A...Z, a...z, 0...9 //english '- //german ДФБсОЩЪ extended letters = '- In most languages besides english, there are letters other languages won't use. MakeIPF has to know these letters to distinguish from (possible) toggles. This has an effect on indexing/linking. So if you write This is a sample with a marked german word #KindergДrten. (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. ═══ 5.11. Text for link to ═══ Text for link to subchapters = @subchapters:@ Text for link to next chapter = @next chapter:@ MakeIPF will automatically generate links at the end of a heading to all subchapters and to the next chapter of the same (or higher) 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. I recommend cyan toggle chars like in this document, because this color won't be used often. You can turn off this function by entering NO in capital letters: Text for link to subchapters = NO Text for link to next chapter = NO ═══ 5.12. Help Subtable Start ID ═══ Help Subtable Start ID = 7000 With the Help Subtable Start ID setting you can define a start ID value for Subtables in helptables created by MakeIPF. 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.). ═══ 5.13. Filenames ═══ //files will be overwritten without warning Helptable filename = HLPTABLE.RC Panel ID filename = PANELID.H Here you can change the filenames of the helptable and panel ID file which will be automatically created by MakeIPF. If you enter the filename *.XYZ, the source file name with the extension XYZ is chosen. Note: This files will be overwritten without warning. ═══ 6. Starting the MakeIPF compiler ═══ The MakeIPF program is a compiler started from the command line, like IPFC. Before using MakeIPF, you have to copy MakeIPF.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 a "runtime error 217". There are one or two parameters you have to enter: [C:\myProject] makeipf myDoc.txt my.ini There is no order of the parameters. You have to explicit enter the file extensions. You can enter any extension for the MakeIPF 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 - MakeIPF will search the ini file by itself: [C:\myProject] makeipf myDoc.txt The name of the output file will automatically be the entered source file name with the extension IPF. How MakeIPF works When running MakeIPF, there are six parts of compiling the source file: o Reading ini file o Reading source file The source file is read in one part from the disk into the heap (thanks to flat memory model of OS/2) o Indexing headings All headings will get an internal identification number o Indexing links All words or phrases marked with the index char or dot command will be placed into a list in the heap o Writing IPF file At last, the IPF file 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. o Writing helptable file When using .RC-dot commands in the MakeIPF source file, the accumulated information in the heap about the helptable will be written into the helptable file. When indexing headings, indexing links and writing IPF file, every compiled heading will appear as a dot on the screen. If you hear a deep beep, MakeIPF could not create an IPF file because of a serious error. Writing batch files Because the IPF format isn't interesting anymore, you can start MakeIPF and IPFC in one batch file (with the extension ".CMD"). A useful batchfile for running in the background can be: @echo off rem Generating hypertext with MakeIPF and IPFC makeipf %1.txt %1.ini >makeipf_errors ipfc /inf %1.ipf >ipfc_errors echo  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 makeipf_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 MakeIPF 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. Remember when making a backup on disks or streamer, you need not save the IPF files, because you can reproduce them every time from the MakeIPF source file. ═══ 7. About MakeIPF ═══ subchapters: Registration Contacting the author MakeIPF Versions History and Future plans ═══ 7.1. Registration ═══ This program is shareware if you want to compile bigger source files than 25 kB. You need a registration key to compile such bigger source files. When compiling smaller source files than 25 kB, it will be freeware. Why 25 kB? I think writing an INF or a HLP file for simple freeware programs should be possible without registering. So if you find errors and you are not registered, you also can send me a mail. The registration fee is 50 Dollars or 70 Deutsche Mark . 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 is 9988 . 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! 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 MakeIPF ini files. Disclaimer pmCalc 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. ═══ 7.2. Contacting the author ═══ Press image for information about my person. My mail address is: (use footnote and Ctrl-Ins) Compuserve 100661,626 * You can reach CIS from the Internet. * My postal address is: * Dr. Martin Vieregg Hubertusstr. 26 D-85521 Ottobrunn Germany ═══ 7.3. MakeIPF Versions ═══ Improvements and bugfixes since from beta 0.91 to 1.0: o "access denied" no more occurs. Lower RAM memory demand. o now compiled with final (non-beta) SpeedPascal compiler. (Using a file instead of stdout now works.) o auto margin .AM o if-conditions o improvement of automatic linking (especially endings of words) o several bugfixes bugfixes in 2.0: o Error printing INF/HLP files (in non-proportional fonts, all letters are printed at the same position of the page) o wrong number of carriage returns when formatting is turned off. Also, a lot of minor bugs were fixed. new functions in 2.0: o external links to separate HLP- and INF-files o launching programs by hyperlinks o automatic duplication of heading text in the text window, heading text gets link target and is placed in the index o more detailed error messages, so running IPFC will create fewer error messages o tabs are converted into a number of spaces like an editor does (use only with non-proportional fonts) o improved window arrangement (see last paragraph of that chapter) o registering via Compuserve o lower price ═══ 7.4. History and Future plans ═══ Where you will find MakeIPF You will find the latest version of MakeIPF with the filename MakeIPF.ZIP in Compuserve OS2DF1 7 (development tools). In the internet, the addresses are os2.nmsu.edu, ftp.cdrom.com/pub/os2 and in germany ftp.leo.org/pub/comp/os/os2. Future plans: several platforms It is possible that there will be a Windows95 and a Windows NT version of MakeIPF if IPFC.EXE exists for this platforms. (A fully functional Win 3.1 INF viewer is part of the "Just add Warp" package.) Future plans: MAKEHTML ? The IPF and HTML * formats are very similar. So it's possible to extend MakeIPF to a combinated MakeIPF/MAKEHTML tool. If I get enough feedback, I will do it. Future plans: printing text From 1985 to 1988, I have written a WordStar extending tool "StarExtender" * with footnotes, line drawing, headings, indexing etc. The line drawing function of MakeIPF is completely recycled StarExtender code, most dot commands are identical. Now there is the possibility to port this program to OS/2 and from german to english language. Only the printer driver has to be programmed totally new in OS/2 presentation manager manner, but then you could print and preview - like "Tech". Of course, the source documents could also be written with any ASCII editor instead of WordStar. That would mean, for program documentation you have only to write one source text and you can automatically generate printed documentation and hypertext. What do you think about this? Do you have some ideas for new functions? 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. Postscriptum If you have already used MakeIPF.EXE, you will be astonished by the speed of MakeIPF (I was, too). And now the surprise: I haven't used a C compiler, I have used the TurboPascal compatible SpeedPascal * . Other OS/2 programs I have programmed (all programmed in C): o PMCALC20 PmCalc 2.0, a PM calculator with automatic clipboard function, hex and scientific functions (comes soon, freeware or shareware, I don't know yet) o TINYALRM TinyAlarm 2.1, a clock, countdown with a slider from 1 to 60 and an alarm by entering alarm time (freeware) o ZIPSHELL Simple Zipshell, a handful tiny batchfiles for handling ZIP- and ARJ-files with the WPS (freeware) o CLEAR10E Clear 1.0 Creating file lists for deleting and backup. Works together with Info-Zip (freeware) o 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. end of hypertext ═══ ═══ The IBM Information format is a Hypertext-Format, especially for program documentation. ═══ ═══ 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. ═══ ═══ The IPF format (Information Presentation Facility) is the Source format to generate INF or HLP files. ═══ ═══ IPFC generates INF- and HLP-files from the IPF source. IPFC.EXE is part of every Programming Language 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. ═══ ═══ I have also written a converting tool from WordStar 5 and 6 to WordStar 4 with ^OZ heading conversion. Please let me know if you are interested in it. ═══ ═══ of course, without 0x0A, 0x0D, 0x1A (decimal 10, 13, 26) ═══ ═══ The IPFC compiler would create an error message when using more than 200 chars. ═══ ═══ Every heading represents a window. There cannot be written any text without creating a window. The IPFC compiler would create an error message. ═══ ═══ 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. ═══ ═══ To convert from GIF to BMP, I recommend the freeware GIF2BMP (Graham Welland, September 1989, OS/2 16 bit) ═══ ═══ A link is a connection between two different windows. Clicking a word or a phrase marked as a link (at my screen lightblue color) will activate the associated window. ═══ ═══ letters a e i o u y ═══ ═══ I could program a footnote window where you can choose between the different headings under which the phrase is marked. Do you think it is necessary? If yes, let me know. ═══ ═══ This will be the content of the footnote ═══ ═══ The WordStar dot command left margin .LM will create soft spaces automatically. MakeIPF 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. ═══ ═══ Because of a bug in the IPFC 2.0 compiler. The entries in the index would get an ASCII 10 char at the end. ═══ ═══ It's only a simulation of the IPF definition list command by using the IPF left margin command. ═══ ═══ You can always use an auto margin function by using the ^OG command (soft spaces). ═══ ═══ 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. ═══ ═══ If the constant behind DIALOG and the constant behind DLGTEMPLATE are identical, it's okay. ═══ ═══ you have to use the constant you have entered in the RC file after MENU or DIALOG ═══ ═══ Perhaps that's compiler specific. I use Borland C ═══ ═══ content of the footnote ═══ ═══ For example, to enter ^PA, you have to enter Alt-1 in the ASCII editor. ^PB is Alt-2, ^PS is Alt-19 etc. ═══ ═══ 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" (only german language, just for fun also in IBM INF format). ═══ ═══ Martin Vieregg, 100661,626 ═══ ═══ Martin Vieregg, 100661.626@COMPUSERVE.COM ═══ ═══ Dr. Martin Vieregg Hubertusstr. 26 D-85521 Ottobrunn Germany ═══ ═══ Hypertext Markup Language, used in the Internet World Wide Web ═══ ═══ I have sold StarExtender only in Germany. ═══ ═══ Speedsoft, Chemnitz, Germany