home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / hmake400.zip / English / docu.txt < prev    next >
Text File  |  2002-04-16  |  248KB  |  5,364 lines

  1. ..This is the documentation in the Hypermake source format.
  2. ..You can generate a HTML, IPF or RTF file from this file.
  3. ..
  4. ..    This source text contains a lot of IF conditions. The text enclosed
  5. ..    in these IF conditions is only converted when HMAKE is executed
  6. ..    by typing these conditions as a commandline parameter or by entering
  7. ..    the conditions on the General page in the settings notebook of HYMAKE.
  8. ..    
  9. ..    #HTMLDOC         encloses the parts of the docu with information about creating 
  10. ..                     HTML files
  11. ..    #IPFDOC          IBM IPF files (OS/2 INF files)
  12. ..    #OS2EXEDOC       OS/2 context-sensitive HLP files
  13. ..    #WINEXEDOC       Windows context-sensitive program help
  14. ..                     or RTF Text for exporting to word processing programs
  15. ..    #WINHELPDOC      Winhelp3 and Winhelp4 files
  16. ..    #MSHTMLHELPDOC   Microsoft HTML-Help (Windows 98 Help) files
  17. ..    #WORDSTARDOC     if DOS WordStar 4.0 is used for editing the source text
  18. ..    #OS2 #WIN95 #DOS Usage of specific operating systems
  19. ..                     (#Win95 = all Windows 32 bit versions)
  20. ..
  21. ..
  22. ..If you want to take a look as a "beginner" nevertheless, here
  23. ..some hints:
  24. ..Dot commands are beginning with a dot and are only interpreted
  25. ..if the command is placed at the beginning of a line. A lot of
  26. ..dot commands here in this text are placed after a space, so 
  27. ..they are printed and not interpreted.
  28. ..Chapter headings are placed after a .n command (n is a heading
  29. ..level from 1 to 6). The character µ marks words for the index and
  30. ..as a link target. µ:word1 word2: marks an expression of several
  31. ..words. The other special chars are toggles, e.g. italic font.
  32.  
  33. .TI
  34. Documentation Hypermake 4.00
  35. .fu[]
  36. .bt¥ blackdot
  37. .bt¿ reddot
  38. .ft¿
  39. .<>
  40. .1
  41. Introduction
  42.  
  43. With Hypermake (up to version 2.0 "MakeIPF"), you can easily create HTML files, Winhelp files, MS HTML-Help files (with file extension CHM), OS/2 INF/HLP files and RTF (rich text format) files for exporting to word processing software. Instead of editing the HTML, RTF or IPF files directly, you enter a more simple ASCII source text. Hypermake enables you to write a text in all these Hypertext formats simultaneously. 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.
  44.  
  45. Yet there's an OS/2, a Win32 (Windows 95, 98, ME, NT, 2000, XP) and - only commandline - DOS version. If there's a demand for a Linux version, I will publish it, too.
  46.  
  47. The Hypermake program exists in two different versions: HMAKE.EXE is a commandline program without user interface and written for experts who want to embed it in an external environment. HYMAKE.EXE is the program version with user interface: an integrated editor, a settings notebook and other dialog windows.
  48.  
  49. You can use Hypermake to write a short Homepage (in this case, it's Freeware), but that's not the main job. It's useful for creating more complex Homepages, scientific works or program documentation with content and index. Hypermake points the focus to structured text, not to graphics - nevertheless, you can embed graphic files in various kinds.
  50.  
  51. When using Hypermake, you have only to learn the much easier Hypermake source format. You can write Hypermake files with the integrated Hypermake ASCII editor or an external ASCII editor (with or without wordwrap, ISO or IBM codepage). I have published the integrated Hypermake editor as a separate Freeware: WSedit.
  52.  
  53. Hypermake includes a reverse converting mode from RTF an IPF to Hypermake source format.
  54.  
  55. Hypermake has some powerful functions:
  56.  
  57. ■ Automatic linking and indexing
  58. 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 and an entry in the index. External links are supported in different ways. From OS/2 and Winhelp4 Help files, links to the WWW are possible.
  59.  
  60. ■ Automatic division into several HTML files
  61. 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.
  62.  
  63. ■ Automatic creation of contents
  64. You will get a contents page with links to all chapters. In HTML you can choose between an unordered list view and a Javascript contents tree view where you can open and close subchapters.
  65.  
  66. ■ Automatic generation of helptables and constants
  67. For OS/2 and Windows help 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, C or PAS file.
  68.  
  69. ■ Automatic Writing of links to subchapters
  70. 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.
  71.  
  72. ■ Automatic arrangement of several heading level windows
  73. With only one command, two (IPF three) heading levels are placed simultaneously on the screen (Frames). See window arrangement sample output. Only the target format Winhelp3 does not support window arrangement.
  74.  
  75. ■ Simple creation of footnotes
  76. The HTML footnotes are realized by frames, IPF footnotes appears in a small footnote window for each footnote text.
  77.  
  78. ■ Tables
  79. You enter tables in the source text like in an ASCII text with a fixed font. Hypermake transforms this simple formatting to HTML, RTF or IPF table commands.
  80.  
  81. ■ Automatic line drawing to generate boxes
  82.  
  83. ■ Short commands
  84. - for heading levels
  85. - for choosing fonts
  86. - to include bitmaps within a line of text
  87. - to generate unordered lists and ordered lists.
  88.  
  89. .2
  90. Supported Hypertext formats
  91.  
  92. .in Hypertext formats
  93.  
  94. .3
  95. HTML
  96.  
  97. .in format HTML
  98. .in HTML file
  99. 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.
  100.  
  101. 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.
  102.  
  103. The HTML format is the only Hypermake target format where the files can be viewed directly without compiling with a second compiler.
  104.  
  105. Hypermake creates HTML files complying with the HTML version 3.2. 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.
  106.  
  107. The HTML version 4.0 is not supported yet, but I will support new HTML features in in new versions of Hypermake. I will support Stylesheets in the future.
  108.  
  109. The HTML code generated by Hypermake is always working fine together with Netscape and with Microsoft browsers. I will not support proprietary HTML dialects which are only shown correctly with a specific browser.
  110.  
  111. The W3C consortium defines the official HTML language. A list of current W3C technical reports can be found at:
  112. http://www.w3.org/pub/WWW/TR
  113.  
  114. .3
  115. IPF (IBM Help)
  116.  
  117. .in format INF (IBM)
  118. .in format HLP (IBM)
  119. .in format IPF
  120. .in IPF file
  121. IPF files (Information Presentation Facility) are the source format of the IBM help format. The IPF syntax has got some similarity to HTML. Both languages are part of the SGML markup language family. The IPF syntax is not as clear as the HTML syntax and it is verbose and somewhat tedious to write.
  122.  
  123. IBM help is the help format of OS/2 and IBM PC-DOS 7. It's also used on Windows platforms, especially if IBM programs for platform-independent software development are used. Of all Hypertext formats, it's the fastest and has got the best functionality.
  124.  
  125. IBM help files have got the extension INF or HLP. INF files can be viewed alone. 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.
  126.  
  127. Hypermake generates IPF files. 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. The Windows version is part of the IBM Visual Age C++ for Windows package.].
  128.  
  129. .URL ftp://ftp.leo.org/pub/comp/os/windows/win3.11/utils/viewers
  130. .in Windows IBM INF Viewer
  131. .LOCAL
  132. IBM INF and HLP files are compact binary files. The viewers of these files are 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 Windows IBM INF Viewer for Win 3.1 is available on ftp://ftp.leo.org, filename win_inf.zip (225 kB). The DOS viewer is part of IBM DOS 7 and there's also a freeware program (VIEW01.ZIP Compuserve OS2DF1).
  133.  
  134. If you are a Windows user and interested in this Hypertext format, then you can download the Windows IBM INF Viewer. If you need an Hypermake generated IBM INF file to test with, simply upload my OS/2 Shareware program pmCalc from my Homepage.
  135.  
  136.  
  137.  
  138. In comparison to HTML or Winhelp3 browsers the IBM INF viewers have got some powerful  features with a particular benefits for large documents:
  139.  
  140. ■ the Index is part of the binary INF file format
  141. ■ the content, too. Subchapters can be expanded and re-expanded like in a directory tree
  142. ■ 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.
  143. ■ Several INF files can be put together by commandline parameters of the viewer. The user sees one big help file with one content and one index.
  144.  
  145. All important HTML functionality like Tables, Frames, Graphics, is also part of the IBM INF format.
  146.  
  147. .3
  148. Winhelp
  149.  
  150. .in Winhelp
  151. .in Winhelp3
  152. .in Winhelp4
  153. .in format INF (Mircosoft)
  154. .in format HLP (Microsoft)
  155. .in format RTF
  156. .in format HPJ
  157. .in format CNT
  158. Winhelp is a binary hypertext format. The source format for generating binary Winhelp files is a special RTF text format (Rich Text Format). It's nearly impossible to write RTF files directly. Microsoft has decided to stop development of Winhelp. Instead, MS HTML-Help will be the new Help format for Windows 98, Windows 2000 and later. Anyway, because Winhelp is smaller and faster, a lot of authors/software developer still prefer Winhelp.
  159.  
  160. Winhelp files can be started seperately and can also be part of a program.
  161.  
  162. There are two different versions of Winhelp: Winhelp version 3 and Winhelp version 4. (In this document, it's simply named Winhelp3 and Winhelp4.) Winhelp3 is the help format of Windows 3.1, Winhelp4 is the help format of Windows 95 and Windows NT.
  163.  
  164. The Winhelp viewer of Windows 95 and Windows NT and later can read both Winhelp formats, the Windows 3.1 viewer can only read Winhelp3. But if Win32s in version 1.30 or later is installed, Windows 3.1 can also read Winhelp4 help files.
  165.  
  166. Winhelp4 has got some additional features in comparision to Winhelp3:
  167.  
  168. ■ There's a content file (CNT file) with a tree view of the headings. (You need to ship the CNT file together with the HLP file.)
  169. ■ The Hypermake HTML frames functionality is also interpretated in Winhelp4. Instead of frames, you will get two help windows, one for the main chapter and the other for the subchapter.
  170. ■ Winhelp4 together with Hypermake enables you to make links to HTML pages in the WWW. The HTML browser with the default file association HTM/HTML is started.
  171.  
  172. To create a Winhelp binary file from the Hypermake generated RTF source, you need the Winhelp3 or Winhelp4 compiler. The compiler is executed together with the project file which has got the extension PRJ.
  173.  
  174. The Winhelp3 compiler is a DOS commandline program with the filename hc31.exe or hcp.exe which can be executed from DOS, all Windows versions and OS/2. For OS/2, hc31.exe is recommended.
  175.  
  176. You can download a compact Winhelp3 compiler zipfile (100k) from the Hypermake Homepage.
  177.  
  178. Winhelp4 needs Windows 95 or NT. The compiler hcw.exe has got a graphical interface, but can also be used from the commandline (hcrtf.exe).
  179. http://support.microsoft.com/download/support/mslfiles/HCWSETUP.EXE (1,6 MB)
  180.  
  181. Hypermake includes a reverse converting mode from RTF to Hypermake source.
  182.  
  183. .IF WINHELPDOC
  184. .4
  185. Error messages of the Winhelp Compiler
  186.  
  187. .in topic
  188. .in Winhelp error messages
  189. .in format PH
  190. The Winhelp compiler has got some limitations and it creates often error messages. These problems occur both with the Winhelp3 and the Winhelp4 compiler. The error messages often let you search the "needle in the hay stack".
  191.  
  192. If you use often tables in a longer text, you will get the "32 columns limit" error message. I have no idea yet to omit this - besides changing some tables to normal text with a fixed font.
  193.  
  194. If you get an error message "error at offset...", the shown address is often the end of the file. In this case, the RTF file contents more { "open" than } "close" brackets. You can omit the bug by adding a "}" character at the end. This will be a Hypermake bug. Please send me the source text and the ini file in this case.
  195.  
  196. Sometimes the Winhelp Compiler writes "error in topic..". Hypermake writes comments "ThisIsTopic..." at the beginning of every chapter. Searching this expression will show you the chapter where the error occurs.
  197.  
  198. You will regulary get the warning "using old phrase table". In the file Projectname.ph the Winhelp Compiler saves some data which will speed up the next compile session. You can delete this file sometimes.
  199. .END
  200.  
  201. .3
  202. RTF Rich text format
  203.  
  204. .sw RTF
  205. .sw Rich text format
  206. Since Hypermake 4.0, pure RTF text (Rich text format) can be created in addition to the supported Hypertext formats. RTF covers a lot of word processing softwares and operating systems. For example, you can create a printed manual of a program by using your word processing software in addition to an on-screen hypertext help.
  207.  
  208. Because the Winhelp source format is a specific RTF dialect, the pure RTF text files generated by Hypermake are similarly to the RTF files which Hypermake generates for creating Winhelp: Some Winhelp-specific commands are omitted and some commands which makes no sense in a printed documentation are converted in a more useful way: For example, instead of Winhelp footnote popups, footnotes are created in a classic way: numbered footnotes at the bottom of the printed page.
  209.  
  210. .3
  211. MS HTML-Help
  212.  
  213. .in HTML-Help
  214. .in format HHC
  215. .in format HHK
  216. .in format HHP
  217. .in format CHM
  218. Microsoft HTML-Help replaces Winhelp in Windows 98, Windows 2000 and later - nevertheless Winhelp will be supported in the future. Microsoft HTML-Help is based upon HTML: a number of HTML files with some Microsoft-specific (non-official) HTML extensions are the input for the HTML-Help compiler. This compiler creates a binary file with the extension CHM (compiled HTML). Additional functionality to normal HTML files is tree view contents (HHC file) and an index (HHK file).
  219.  
  220. The project file for executing with the MS HTML-Help compiler has got the extension HHP (HTML Help Project).
  221.  
  222. Because of the ability of Windows 98 and NT 5.0 to run Windows 3.1 and Windows 95 programs, the Winhelp format will be supported too for a long time.
  223.  
  224. You can download the MS HTML-Help compiler:
  225. http://www.microsoft.com
  226. and then search the expression HTML-HELP
  227.  
  228. The HTML-Help viewer HH.EXE is not part of Windows 95 and NT 4.0, but is part of Windows 98 and NT 4.0 SP4 and of course Windows 2000. If you do not write both a Winhelp and a HTML-Help file for your application (not very difficult when using Hypermake!), HH.EXE has to be part of your software package. This file is part of the Microsoft HTML-Help Workshop and resides normally in the Windows directory.
  229.  
  230. Since MS HTML-Help 1.1 you can create a compiled HTML file without need of HH.EXE. But this will not reduce the quantity of data.
  231.  
  232. .2
  233. How Hypermake works
  234.  
  235. .in compilation
  236. Hypermake creates a hypertext from a source text you have to edit before. Creating a hypertext has got the following steps:
  237.  
  238. ■ You write an ASCII text in Hypermake syntax. For this job, you can use the internal Hypermake editor or an arbitrary external editor. The main chapter Writing a Hypermake Source Text describes the syntax of the ASCII file.
  239.  
  240. ■ In the project settings notebook, you can change settings which influence the look of the Hypertext. Here you can also define what Hypertext format you want to get created. 
  241.  
  242. ■ Double clicking into the top message window with the blue text (when using the graphical version) or executing the commandline version will compile the source text to the chosen hypertext format. The compile work is running in one step and cannot be executed in parts.
  243.  
  244. ■ Only HTML can be viewed directly. The other formats need a "second compiler". In this case, Hypermake does not create the final hypertext file, instead it creates only the input for the "second compiler": the Microsoft Winhelp compiler for creating Windows Help, the IBM IPF Compiler for generating IBM Help files, and the Microsoft HTML-Help compiler for generating HTML-Help. You can configure Hypermake to start automatically the "second compiler", so it will look like Hypermake generates the final Hypertext directly.
  245.  
  246. All settings notebook pages besides the "general" page are stored in the "ini file" which you can also edit directly with an ASCII editor. Then there's the HMP file (Hypermake project file, also in ASCII format) where the first page "main" of the project settings notebook is stored. The HMP file stores the name of the source text and the name of the ini file and some other basic settings.
  247.  
  248. When Hypermake compiles a hypertext (target file) from the source text, internally there are six parts of compiling the source file.
  249.  
  250. .afO
  251. ■ Reading ini file
  252. ■ Reading source file
  253. The source file is read in one part from the disk and is hold in memory (not in the DOS version)
  254. ■ ~Indexing~ headings
  255. All headings will get an internal identification number
  256. ■ Indexing links
  257. All words or phrases marked with the index char or dot command will be placed into a list in the memory
  258. ■ Writing IPF/RTF file or HTML files
  259. At last, the IPF/RTF 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 memory. 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.
  260.  
  261. .afB
  262. .sfO
  263. When indexing headings, indexing links and writing the target file, you will see a counter which increments for every compiled chapter.
  264. .sf
  265.  
  266. In the graphical version, when indexing headings and links, only the red sevensegment display is running. When writing the hypertext file, also the green progressbar is executed.
  267.  
  268. If you hear a deep µbeep, Hypermake could not create an IPF/RTF file / several HTML files, because of a serious error.
  269.  
  270. In the graphical version, error messages are shown in red color in the output window in the middle of the Hypermake main window.
  271.  
  272. If Hypermake produces one or more small errors, the target files will be finished, but the second compiler won't be executed.
  273.  
  274. .IF Win95
  275. Windows 95 only beeps by using the sound card, NT and Win 2000 uses the speaker.
  276. .END
  277.  
  278. What are the files generated by Hypermake?
  279.  
  280. .IF HTMLDOC
  281. When the target is HTML, a new folder with the name of the project is created with a number of HTML files. The extension of the HTML files is ".HTML" or ".HTM", dependent on the settings in the ini file and the operating system. An HTML info file with the project name is created which can be used to start viewing the HTML files. This file holds some useful information about the project for the author.
  282. .END
  283.  
  284. .IF IPFDOC
  285. When generating IBM Help, a single IPF file is generated which is the input for the IBM IPFC compiler.
  286. .END
  287.  
  288. .IF WINHELPDOC
  289. When creating Winhelp, a single RTF file is generated. Dependent on the ini file setting contents creation (project settings, page "Winhelp") a CNT content file is generated which cannot be viewed with Windows 3.1. In any case a PRJ Winhelp project file is generated. Double click to the PRJ file activates the Winhelp compiler. When using the commandline, enter the name of the PRJ file as a program parameter of HC, HCW or HCRTF.
  290. .END
  291.  
  292. Similar to Winhelp, creating RTF text creates a RTF file. Graphic files which are part of the document are copied into the same directory. The RTF file begins with content, but without page enumeration which is dependent on the final formatting in the word processing program.
  293.  
  294. .IF HTMLHELPDOC
  295. Creating MS HTML-Help is very similar to creating normal HTML. A new folder with the name of the project is created and the new HTML files are located there. The contents and the index page is different from normal HTML, the extension is HHC and HHK. The MS HTML-Help project file has the extension HHP and is located in the new folder. Double clicking to the HHP file starts the MS HTML-Help compiler.
  296. .END
  297.  
  298. Remember when making a backup on disks or streamer, you need not save the Hypermake output files, because you can reproduce them every time from the Hypermake source file.
  299.  
  300. Target directory and graphics
  301.  
  302. For every target format Hypermake copies the graphic files from the directories located in the graphic path setting (project settings, page "Main") of the HMP file or ini file. The directory where Hypermake places (nearly) all the output and the graphic files is dependent on the target format: The µ:target directory: for HTML and HTMLHELP is the new folder with the name of the project and for IPF or Winhelp it's the same folder where the source file is located.
  303.  
  304. .1
  305. Graphical version HYMAKE.EXE
  306.  
  307. .2
  308. Overview
  309.  
  310. .in graphical version
  311. The graphical version HYMAKE.EXE includes
  312. ■ the Hypertext compiler
  313. ■ an integrated editor for the source text
  314. ■ a project settings notebook.
  315.  
  316. The commandline version HMAKE.EXE holds the compiler functionality alone and is useful for experts. Before Hypermake 4.0, only the commandline version was available.
  317.  
  318. Compiling a Hypertext with Hypermake runs very fast - only a few seconds, also for larger projects. But it takes a lot of time to edit the source text and to choose the lots of settings in the ini file. The graphical version HYMAKE.EXE has got an integrated editor which helps you editing your Hypermake source file and has some specific functionality:
  319.  
  320. ■ syntax highlightning let you distinguish between several Hypermake command types and normal text
  321. ■ context sensitive bubble help explains the commands already typed into the editor
  322. ■ a "function dialog" inserts the Hypermake commands which you can also type manually into the editor
  323. ■ press the right mouse button in the editor and you will get a menu which holds specific Hypermake functionality (e.g. "compile"), but also simple and well-known editor functions.
  324.  
  325. The project settings notebook holds all the settings which have an effect on the functionality and the look of the final hypertext which will be compiled from the source text. These settings are stored in the HMP file (page "Main") and in the ini file (all other pages).
  326.  
  327. Then the graphical version consists of some other dialog windows:
  328.  
  329. ■ a program settings notebook which holds all settings which are not dependent on a specific Hypertext project
  330. ■ contents window and index window helps you to navigating in the source text.
  331.  
  332. You can open all these windows by choosing View in the Hypermake main window menu.
  333.  
  334. The project settings notebook is described separately.
  335.  
  336. .2
  337. Hypermake Main Window
  338.  
  339. .in Hypermake Main Window
  340. .ID P_mainwindow
  341. The Hypermake Main Window is the window which appears when double clicking to a HMP file or executing Hypermake (HYMAKE.EXE). If another window of the Hypermake program is on top, you can reach the Main Window by pressing F6.
  342.  
  343. Main Window Menu
  344.  
  345. ■ Project
  346. - New: let you begin a new Hypermake Project. You are asked to enter a new HMP file (Hypermake Project), an INI file from where to copy the project settings from (e.g. SAMPLE.INI from the Hypermake archive), a name for the new INI file and the name of the source text.
  347. - Open: opens an existing Hypermake project (HMP file).
  348. - Save: saves the current project (HMP file, INI file, source text) if changes were made
  349. - Save as: saves the current project with a new name for the HMP file. If you also want to change the name of the INI file and/or source text, you have to made these changes on the Main page of the Project settings.
  350. - Compile to: starts compiling: the target format you have chosen here will be created from the source text. This selection will overwrite the current setting "Target Format" on the Main page of the project settings. See Compiling. When pressing F9, the target format which is currently selected in the project settings will be created. To start the compiler, you can also doubleclick into the window with blue text (success window).
  351. - 2nd Compile: starts the second compiler separately. The second compiler is necessary for all target formats besides HTML. Note that changes in the source text only appears in the Hypertext if the "first compiler" (Hypermake) and after that the second compiler has been executed. You can automatically run the second compiler (Project settings Main page). See Compiling.
  352. - open text file: The Hypermake editor is very powerful. If you like it, you can also open arbitrary text files. Dependent on the current Hypermake project, the text is loaded in ISO or IBM codepage. Syntax highlightning is turned off. The editor is also available as a separate Freeware program: WSedit.
  353. - import RTF/IPF: see reverse converting mode
  354. - compare HTML dir starts the file comparison mode which will help you locating the HTML files which have changed since the last upload. 
  355. - Exit: closes the Hypermake program.
  356.  
  357.  
  358. ■ View (let you have access to all important windows of Hypermake)
  359. - Project Settings: the settings notebook which has an effect to the functionality and look of the generated Hypertext (stored in HMP file and INI file)
  360. - Source text: opens the editor with the source text of your project. A project can contain several source files. To open the text file, you can also doubleclick to the dropdown window in the Hypermake main window.
  361. - Contents: The contents window shows the contents of your current project source text in a tree view. It helps you navigating in your source text.
  362. - Index: The index window also helps you navigating in the source text and shows the index of the source text: all marked expressions are listed alphabetically.
  363. - Program Settings: the program settings notebook holds all settings which are not related to a specific project, e.g. the filename of your Internet Browser as an default viewer for HTML files.
  364. - Functions tree view: shows the Functions dialog which let you insert Hypermake source file commands to the cursor position of your source text (also editor window popup menu function - tree view).
  365. - Final Output: views the final output of your Hypertext project, dependent on the selected source format: the Internet Browser when HTML was seleted, or the Help Viewer of the selected type.
  366.  
  367.  
  368. ■ Edit is identical with the popup menu in the editor (press the right mouse button inside the text area of the editor). You will find the well-known default editor commands and some Hypermake speciific functionality.
  369.  
  370.  
  371. ■ Help
  372. - About: shows the version number.
  373.  
  374. Other items in the main window
  375.  
  376. (from left to right)
  377.  
  378. Green LED: glows if a compile thread is running. All jobs which take more time than some milliseconds are running in an own "thread". That means you can edit your source text or the project settings while Hypermake compiles a project. But jobs which also run in a thread cannot be executed until the last thread has finished.
  379.  
  380. Stop: stops the current thread ("user break"). Some jobs like the second compiler cannot be interrupted.
  381.  
  382. Dropdown edit field: holds all the names of the source file. Selection or doubleclick starts the editor with the selected source text. The name of the source text is defined on the Main page of the project settings.
  383.  
  384. Red Counter: counts the compiled chapters. Your eyes can only follow the counting process with a big source text and/or a slow computer. While compiling, there are three jobs running. So the red counter counts three times, two times fast and one slow. See Compilation.
  385.  
  386. Green Progress Bar: counts the percentage of writing the target format (the third job), see Compilation. It also shows the target format which is currently selected on the main page of the settings notebook.
  387.  
  388. Success Window: (blue text) While compiling, Hypermake tells you what it is doing. Double click into the success window starts compiling.
  389. .IF OS2
  390. You can drag and drop HMP files into this field which will have the same effect as "project open". Dropping directory icons will start the file comparison mode which will help you locating the HTML files which have changed since the last upload.
  391. .END
  392.  
  393. General Error Window: (red text) When compiling, Errors and Warnings are listed here.
  394.  
  395. Editor Error Window: (white) Hypermake lists here errors and warnings which  refers to a specific line of the source text. Double clicking starts the editor with the line where the error or warning is related to.
  396.  
  397.  
  398. .2
  399. Editor
  400.  
  401. .in integrated editor
  402. .id P_editor
  403. The editor which is part of HYMAKE.EXE is very powerful and works together with ASCII files with a file length up to 15 MB. The only thing you have really to know is that instead of a normal menu, there's only a popup window (press thee right mouse button somewhere in the editor area) which holds the well-known functionality and some special Hypermake functionality. But you can also use the "Edit" menu item in the Hypermake main window which refers to the editor window which is on top.
  404.  
  405. If you navigate the mouse pointer to a Hypermake specific command (dot commands or toggles), you will get a context sensitive bubble help explanation. You can turn off this feature in the program settings notebook, page "Prog".
  406.  
  407. If you like the editor, you are encouraged to download my Freeware program WSedit from my Homepage. WSedit is basically identical with the Hypermake editor in the "Wordstar" key table setting and has got a more detailed explanation about the Control Key commands. WSedit offers you a dialog window with all control key combinations in a tree view and some minor additional functionality.
  408.  
  409. .3
  410. Titlebar
  411.  
  412. The titlebar of the editor window shows a lot of information.
  413.  
  414. (4,226*) in parenthesis means Column 4 and Line 226, the * star shows you that the file is modified in comparison to the last saved state.
  415.  
  416. The "Par" number counts the Hard Returns up to the cursor position, dot commands are also counted. The line number in parenthesis is dependent on the current formatting, so the "Par" number is the only useful orientation!
  417.  
  418. Then, the filename is shown.
  419.  
  420. If the column block mode (^KN) is activated, "COLUMN" is shown. If the file is read-only "READ ONLY" appears.
  421.  
  422. .3
  423. Editor menu
  424.  
  425. There are two different ways of having access to the editor menu: you will find it in the edit menu item of the Hypermake editor window, or you can press the right mouse button in the text area.
  426.  
  427. In the editor menu, you can also see the key combinations which have the same effect. These keys are dependent on the Options - Key table setting. The "Wordstar" setting is the most powerful key table, because you have access to nearly all menu entries from the keyboard by double control codes, e.g. Ctrl-K-R for "Read block from file".
  428.  
  429. In this explanation, only specific commands which are not part of a default editor are explained.
  430.  
  431. Submenu File
  432.  
  433. Import TXT copies a file to the current cursor position and Export TXT writes a selected block to a filename of your choice. There's no conversion functionality.
  434.  
  435. Instead of "Import TXT" you can also drop the file icon to a location inside the editor.
  436.  
  437. Submenu Edit
  438.  
  439. "Edit" has got a lot of well-known commands which are not further described and some interesting additional commands.
  440.  
  441. Undo and Redo is also part of other more comfortable editors. But in the Hypermake editor, the undo/redo functionality is extremly powerful: You have also an Undo slider where you can simply undo and redo hundreds of inputs. In the program settings notebook page "Edit2", you can select a value for maximal undo steps.
  442.  
  443. If you want to go to the text position which was edited last, simply use Undo one time (Alt-Backspace).
  444.  
  445. In addition to the find functionality, where you get a find dialog window, you can also use incremental search without a dialog window. Take a look at the titlebar and type the expression you want to find, character by character.
  446.  
  447. Submenu Extended
  448.  
  449. Here you will find some additional editor functionality.
  450.  
  451. Reformat all reformats the whole document like it would be if you change the width of the editor window. By default, the editor reformats the text automatically while typing, but this behaviour can be modified in the program settings notebook, page "Edit2".
  452.  
  453. cursor always in text area makes a difference when editing e.g. tables. If the cursor keys follow the text, the only possibility to reach a position where no text was before is entering a lot of spaces. If the cursor does not follow the text, you can simply navigate in a not yet edited screen area by cursor keys. You can define the default setting of this switch on the "Edit2" page of the program settings notebook. 
  454.  
  455. Hypermake and WSedit supports two kinds of translation between two languages: Bubble Translation and Dialog Translation. Normally you will use Bubble Translation when reading a text in a foreign language and Dialog Translation when writing a text in a foreign language.
  456.  
  457. To use translation functionality, you have to download the translation dictionary files from the WSedit page of my Homepage. There you will find a link to another page where you can download translation files (yet only German to English and English to German). Then fill out the program settings notebook "Edit1" Page. 
  458.  
  459. Bubble Translation: words or expressions at the cursor position are translated and the result is shown in a yellow bubble help window.
  460.  
  461. Dialog Translation: activates a dialog where you can enter the expression into the edit field. In the Listbox below, several possible translations are shown. If Bubble Translation is also activated, these several possible translations are re-translated in parenthesis so it will be easier to select the correct translation.
  462.  
  463. The re-translation has the effect of a Thesaurus: a single expression translated to another language and re-translated back will show several slightly different expressions.
  464.  
  465. Double clicking to a listbox item or single clicking and pressing OK copies the translated expression into the Trash buffer. It can be copied to the cursor position by typing Ctrl-U.
  466.  
  467. Submenu Function
  468.  
  469. This submenu is related to the Hypermake program: if you are not so familiar with the Hypermake dot commands, you can get these commands inserted on the cursor position. Tree View shows a permanent dialog window where you can doubleclick to the commands and the other menu items of the "Function" submenu are a summary of the most important Hypermake dot commands.
  470.  
  471. Submenu Toggle
  472.  
  473. Toggles are used in pairs and the text between the two toggles gets e.g. bold or underlined. Toggle characters are characters you do not use in your normal text, and often you have got no key on the keyboard for these characters. You can use these menu entries for typing these characters to the current cursor position.
  474.  
  475. There are different key commands for the toggles. E.g. Shift-F2 types one italic toggle, Ctrl-F2 types two toggles, one to the cursor position and the other to the end of the word where the cursor points to. Alt-F2 inserts the toggle at the beginning and the end of the current line.
  476.  
  477. Submenu Program
  478.  
  479. This submenu is only available in the popup menu, not in the Edit menu item of the main window. This submenu contents nearly some items of the "Project" and the "View" menu of the main window does. So you have got access to the Hypermake program without leaving the editor window.
  480.  
  481. Submenu Options
  482.  
  483. The "Options" submenu holds some user defined settings. Some very specific editor settings are hold in the program settings notebook. The more common settings are hold directly in the editor menu "options" section.
  484.  
  485. Bubble Help on/off can be also set in the program settings notebook, page "Prog".
  486.  
  487. Toggle colors let you switch between two different color settings for the text area of the editor.
  488.  
  489. Hypermake remembers the font and the color information for each file separately, also window position and size.
  490.  
  491. The key table setting is very important, because it defines the key codes for the editor functionality. "Wordstar" is the only setting where you have full keyboard access to all editor functions, and "Wordstar" is also the only key table of the WSedit Freeware editor program.
  492.  
  493. .3
  494. Rightmost Column
  495.  
  496. The background of the rightmost column of the editor shows different colors:
  497.  
  498. ..this is a comment line!
  499. ■░░Lines beginning with two dots (comment lines)
  500. ■░░Lines beginning with a single dot (dot commands)
  501. ■░░Lines with a Hard Return at the end
  502. ■░░Lines with a Soft Return at the end.
  503.  
  504. A Hardreturn is the end of a line where you have entered RETURN manually. In any formatting, this Return will exist.
  505.  
  506. A Softreturn disappears if the formatting gets different. If you change the window size of WSedit, the editor let appear and disappear Soft Returns.
  507.  
  508. In a Hypertext, Hard and Soft Returns make a big difference because you do not know the width of the window where the user reads your text. You can switch the current line from Hard to Soft Return and reverse in the popup menu entry extended.
  509.  
  510.  
  511.  
  512. .3
  513. Key commands
  514.  
  515. .in key table
  516. The editor supports three different key tables - that means you have three allocations of keyboard commands (Popup menu - Options - Key Table).
  517.  
  518. If a function in the popup menu can be also activated by the keyboard, the keys are noted in the popup menu.
  519.  
  520. ■ CUA: Common User Interface, that's the key commands all modern graphical programs support. E.g. with Ctrl-Ins, you copy the selected text to the keyboard
  521.  
  522. ■ Mixed: a mixture of CUA and Wordstar
  523.  
  524. ■ Wordstar: the Ctrl-key commands of old DOS Wordstar; this very old command set is supported on some modern editors, e.g. Borland C and Pascal programming environments. Nevertheless, all commands which are not "Ctrl-Letter" are the same like CUA.
  525.  
  526. CUA commands
  527.  
  528. Some of the following Ctrl commands (hold Ctrl down and then press a letter keyboard) are not shown in the popup menu.
  529.  
  530. Ctrl-E: incremental search (without dialog, look to titlebar!)
  531. Ctrl-F: Search dialog
  532. Ctrl-G: Replace dialog
  533. Ctrl-N: search/replace text again
  534.  
  535. (In CUA mode supported Wordstar keys)
  536. Ctrl-K0 (up to 9) set bookmark 0
  537. Ctrl-Q9 (up to 9) "quick" to bookmark 0
  538. Ctrl-T: delete word right from cursor
  539. Ctrl-U: copy trash buffer to cursor position
  540. Ctrl-Y: delete line.
  541.  
  542. Wordstar commands
  543.  
  544. The Wordstar setting is the only setting where you can reach all the editor functionality by the keyboard. Wordstar Ctrl keys have got also double character commands, e.g. Ctrl-K-B for "begin selection". Nevertheless, CUA commands like Ctrl-Ins are also enabled.
  545.  
  546. If you like the integrated Hypermake editor, you are encouraged to download the Freeware editor WSedit from my Homepage. This editor is basically identical with the Hypermake editor in the "Wordstar" key table setting and has got a more detailed explanation about the Control Key commands. WSedit offers you a dialog window with all control key combinations in a tree view and some minor additional functionality, e.g. a macro key recorder to program function keys.
  547.  
  548. If you are interested in the full documentation of Wordstar key commands, please refer to the WSedit program and its help text. In the Ctrl Key Help Window of WSedit, all Control commands which are not supported in the Hypermake editor are marked with a Star. 
  549.  
  550. .3
  551. Special functionality
  552.  
  553. The µ:Trash Buffer:
  554.  
  555. If you use Ctrl-T (delete right word) or Ctrl-Y (delete line), the deleted text part will be stored in a "trash buffer" (that is not the clipboard). With Ctrl-U, you can paste the content of the trash buffer to the current cursor position.
  556.  
  557. Drag and drop
  558.  
  559. You are allowed to drag and drop a marked block to another cursor position or to another Hypermake Editor window or WSedit window. To drag and drop, use the right mouse button. The default function is moving the block. Pressing CTRL while dropping will copy the block. You are also allowed to drag text file icons to a specific position of the text area. This will read the block (Wordstar Ctrl-KR).
  560.  
  561. Undo
  562.  
  563. The Hypermake editor has got a powerful multi undo functionality. You will find these commands in the popup menu edit.
  564.  
  565. You can undo your input by typing Alt-Backspace and redo by typing Shift-Alt-Backspace or you can open the Undo Slider window by pressing Ctrl-OU (Wordstar) or from popup menu - edit - undo slider. 
  566.  
  567. The number of undo events can be set by the user, see Page "Edit2" of the program settings notebook. Useful setting for undo events are from 100 to 10000.
  568.  
  569. .3
  570. Spell Checking
  571.  
  572. The Hypermake editor has got a simple but effective µ:spell checking: function implemented. 
  573. .4
  574. How to get a dictionary
  575.  
  576. To use the spell checking function, you have to create a dictionary by yourself or you can visit the WSedit page on my Homepage http://www.hypermake.com and download the current dictionary collected by Hypermake and WSedit users.
  577.  
  578. All spell checking functionality is available from the popup menu, menu entry "spell checking".
  579.  
  580. You can enter a filename for the dictionary in the "Edit1" Page of the program settings notebook.
  581.  
  582. If you want to create a dictionary by yourself, you need to have existing ASCII files which are already spell-checked or where you can be sure that there are no incorrect words: Load the text file in the editor and choose "spell checking - absorb current file to dictionary". 
  583.  
  584. If you have received another Hypermake/WSedit dictionary file from a friend or from the Internet, you can merge this file with "your" dictionary file by using "import external directory".
  585.  
  586. The principle of the Hypermake/WSedit dictionary is quite simple: If a word has to be absorbed, the endings defined in the Hypermake project settings (page "Link"), normally
  587.  
  588. (english) es ''s s ions ion ings ing
  589.  
  590. are cutted and the first character is converted to lower-case. Then it is compared to the contents of the dictionary. If no similar entry is found, it is placed into the dictionary.
  591.  
  592. The dictionary file is a normal ASCII file in IBM codepage. The words are sorted by an internal sort algorithm, not by the alphabet. You can add manually words at any position.
  593.  
  594. .4
  595. Working with the spell checking function
  596.  
  597. You can turn on and off spell checking by entering Ctrl-QL (Wordstar key table) or popup menu - spell checking - enable/disable. The background of unknown words is getting pink. There's no user interface. With spell checking - absorb into dictionary up to cursor learns all words from the beginning of the file up to the line of the editor cursor. Some marking of words below the cursor will automatically disappear.
  598.  
  599. If you find an incorrect word which is not highlighted and in consequence the wrong word is part of the dictionary, you can correct your dictionary by moving the mouse over the wrong word and choosing remove single word from dictionary in the popup menu.
  600.  
  601. .3
  602. Translation
  603.  
  604. .ID P_editor_translation
  605. The Hypermake editor supports two kinds of translation: µ:Bubble Translation; and µ:Dialog Translation;. Normally you will use Bubble Translation when reading a text in a foreign language and Dialog Translation when writing a text in a foreign language.
  606.  
  607. To use translation functionality, you have to download the translation dictionary files from the WSedit page my Homepage http://www.hypermake.com (yet only German to English and English to German) and fill out the program settings notebook "Edit1" Page. 
  608.  
  609. Bubble Translation: (Popup menu extended, Wordstar Ctrl-OT), words or expressions at the cursor position are translated and the result is shown in a yellow bubble help window.
  610.  
  611. Dialog Translation: (Popup menu extended, Wordstar Ctrl-OD) activates a dialog where you can enter the expression into the edit field. In the Listbox below, several possible translations are shown. If Bubble Translation is also activated, these several possible translations are re-translated in parenthesis so it will be easer to select the correct translation.
  612.  
  613. The re-translation has the effect of a Thesaurus: a single expression translated to another language and re-translated back will show a handful slightly different expressions.
  614.  
  615. Double clicking to a listbox item or single clicking and pressing OK copies the translated expression into the Trash buffer. It can be copied to the cursor position by typing Ctrl-U.
  616.  
  617. .2
  618. Contents and Index Window
  619.  
  620. .in Contents Window
  621. .in Index Window
  622. .ID P_contentwindow
  623. The Contents and index window can be reached from the View menu in the Hypermake main window or the program entry in the editor popup menu or by pressing F3 (contents) or F4 (index). 
  624.  
  625. The main job of these two dialogs is navigating inside your source text. The contents window shows the heading structure in a tree view and the index window shows all marked expressions and has got alphabetic buttons for jumping into the index expression list.
  626.  
  627. The contents and index dialogs have got the following buttons:
  628.  
  629. Go to source needs a selection (single mouse click) first. You can also double click to a heading/an expression, this will have the same effect like clicking to "go to source". The internal editor will be started and the cursor will be set to the chosen heading.
  630.  
  631. Go to HTML has only an effect if you have already compiled the Hypertext to the HTML target format. It will start the browser if the filename of the browser was entered in the program settings, page "view".
  632.  
  633. HTML Ascii (only contents window) shows the "source text" of the generated HTML file. The Hypermake editor will be opened. Because of the extension "HTM" or "HTML", the text is syntax-highlighed. But don't edit this text which was created by Hypermake, because when compiling again, your changes were overwritten by the new generated output.
  634.  
  635. Copy is only available in the index window. Before clicking to "copy", position the cursor in the Hypermake editor to the text location where you want to get the index expression inserted. This functionality is useful to avoid slightly wrong writings of expressions where Hypermake would not create the link.
  636.  
  637. Update saves the current source file in the Hypermake editor and runs again the first compilation steps "Indexing headings", "Indexing links". Then the dialog window content will be updated. If you get to a wrong position when using "go to source", you have to update the contents or index. Hypermake simply remembers the filename and paragraph number, so after inserting new text before the heading/index expression will cause a "go to source" malfunction.
  638.  
  639. Close closes the dialog window.
  640.  
  641. .2
  642. Program settings notebook
  643.  
  644. .in Program Settings
  645.  
  646. The program settings notebook holds all information which is not specific to a hypertext project. To open the program settings notebook, choose View - Program Settings in the Hypermake main window, Program - Program settings or press F8.
  647.  
  648. .3
  649. Prog page
  650.  
  651. .ID P_prog_prog
  652. The Bubble help checkbox turns bubble help on and off. Bubble help is available for nearly all dialog items and context-sensitive inside the integrated editor for explanation of the Hypermake text commands (dot commands and toggles).
  653.  
  654. Normally you won't change the compile priority. This slider changes the priority of the compile thread. Lower the value if the Hypermake program compiles your input with delay while compiling a project. Enlarge the compile priority if the compilation runs slow and has got interrupts.
  655.  
  656. If you don't like the internal editor and instead you have got your favourite editor, you can choose an external editor. But in this case, you cannot use the functionality of jumping to a specific text location. Enter the filename of the editor (which ends normally with ".EXE") and click to the checkbox. Clicking to the search button helps you in entering the correct filename by activating a file dialog window. If the edit field gets green, the file exists, red shows a wrong filename. 
  657.  
  658. Open editors automatically when opening HMP project opens the editor with the source text file automatically when using Project - open in the Hypermake main window or when starting Hypermake by double clicking to a HMP icon.
  659.  
  660. .3
  661. Help page
  662.  
  663. .ID P_prog_help
  664. .it bubble help
  665. The bubble help checkbox on the help page of the program settings notebook enables small yellow fly-over text windows for every dialog item. The are shown if the mouse cursor rests over a dialog item. Principally, each dialog item of the Hypermake program owns a bubble help window.
  666.  
  667. .it context-sensitive help
  668. With the radiobuttons on the help page you can choose between different help formats:
  669.  
  670. .IF OS2
  671. An OS/2 help file (IPF file) is part of the Hypermake archive (ENGLISH\HYMAKE.HLP). Principally, you can also create this file by yourself (compile ENGLISH\HELPDOCU.HMP and run the IPFC compiler). The pre-compiled helpfile was not modified manually.
  672. .END
  673. .IF WIN95
  674. Both MS HTML-Help (ENGLISH\HYMAKE.CHM) and Winhelp (ENGLISH\HYMAKE.HLP) is part of the Hypermake archive. Here you can choose which context-sensitive help format you prefer. This depends first on the target format you want to create.  Principally, you can also create these files by yourself (compile ENGLISH\HELPDOCU.HMP or ENGLISH\HtmlHelpDocu.hmp and run the HCW or HtmlHelp-Compiler). The pre-compiled helpfile was not modified manually.
  675. .END
  676.  
  677. If you choose the HTML format for context-sensitive help, the help will created initially when using the context-sensitive help the first time. This is done automatically by executing ENGLISH\HTMLDOCU.HMP. In a dialog window you can deselct topics which are not interested for you.
  678.  
  679. You can change this setting on-the-fly and execute a second help window of another help format.
  680.  
  681. .3
  682. 2nd Comp page
  683.  
  684. .ID P_prog_comp
  685. If on the main page of the project settings notebook the checkbox also start 2nd compiler is checked, the specific compiler you can enter here will be started when compiling a project. If the edit field gets green, the file exists, red shows a wrong filename.
  686.  
  687. The commandline processor is only necessary if the execution of this program is only possible in a commandline window and the operating system only supports the indirect execution (IPFC with OS/2 needs it, some DOS programs do so, too).
  688.  
  689. To learn more about these compilers, please refer to the chapter about the supported Hypertext formats.
  690.  
  691. .3
  692. View page
  693.  
  694. .ID P_prog_view
  695. On the view page, you can enter the filenames of the Hypertext viewers.
  696.  
  697. The HTML viewer is the Browser. The Netscpape Browser has got a filename something like netscape4\program\netscape.exe, and the Microsoft Internet Explorer IEXPLORE.EXE regulary resides in the "programs" directory.
  698.  
  699. If the edit field gets green, the file exists, red shows a wrong filename. 
  700.  
  701. Pass page location is a specific Netscape feature. Turn this checkbox on if you use Netscape. The Netscape browser supports not only a simple URL or HTML filename for a  commandline parameter, it can also have a #hd location appended. So the Browser starts not only with the correct file, also the correct position in the file will be shown.
  702.  
  703. To learn more about the supported Hypertext formats and its viewers, please refer to the Hypertext formats chapter.
  704.  
  705. .3
  706. Edit1 page
  707.  
  708. .ID P_prog_edit1
  709. The edit pages of the program settings notebook refers to the integrated editor.
  710.  
  711. You need to enter the name of the spell checking file to use the spell checking functionality of the editor. Because you can create your own dictionary, you can enter an arbitrary new filename (full name with drive and directory).
  712.  
  713. The names of translation files refers to the translation functionality. You have to download a dictionary from the WSedit page of my Homepage (yet only german-english and english-german).
  714.  
  715. .3
  716. Edit2 page
  717.  
  718. .ID P_prog_edit2
  719. You can choose the behaviour of word wrapping of text:
  720.  
  721. ■ with time delay is my personal favourite setting. If enabled, you can select a delay time. I prefer 0 quarter seconds.
  722.  
  723. ■ after every keypress is the behaviour of most word wrap editors. Because of the need of reformatting a big paragraph after every keypress, the amount of processor time becomes noticeable. If you type very fast and your computer is not fast, this setting is not recommended.
  724.  
  725. ■ only by hand (Ctrl-B) is the classic old DOS Wordstar behaviour. A lot of people get confused if the text is reformatted automatically while writing. Ctrl-B reformats the paragraph from the cursor to the end of the paragraph. In any case, the paragraph is reformatted if the cursor exceeds the line. (Ctrl-B is always availabe, independent from this setting.)
  726.  
  727. ■ not at all deactivates reformatting. Soft Returns are handled like Hard Returns. Even ^B has no effect.
  728.  
  729. HTML Highlightning activates HTML Syntax Highlightning in a Hypermake source text. If you embed commands in HTML-syntax inside the Hypermake source text, turning this checkbox on will help you writing HTML syntax by showing these commands in colors. Anyway when opening a HTML file (extension HTM or HTML) in the editor, the HTML syntax highlightning is always turned on.
  730.  
  731. The Cursor left/right checkbox influences the behaviour of cursor movement. If disabled, the behaviour is like in a programmers editor: you can reach every point of the screen by using the cursor. If enabled, the cursor follows the text. Where there is no text, you have to fill the line with spaces to reach a position where no text is written yet. You can toggle this behaviour in the Wordstar key table by typing Ctrl-OX. 
  732.  
  733. delete word right from cursor (Ctrl-T) influences the behaviour of the Ctrl-T command. The middle setting is the same as in Wordstar DOS, auto correct spaces is a self-made further development improving changing the position of two words where one word is located near a dot or a comma.
  734.  
  735. Max Undo Steps: The undo slider works more efficient if the editor does not reformat a paragraph too often: if the text is reformatted every second while typing, there are a lot of events to remember for the undo functionality: one event per line and in a 10-lines paragraph for 10 events per second. You can reduce this event amount by using "with time delay" and a higher delay time value, e.g. 4. Useful settings for "Max Undo Steps" are from 100 to 10000.
  736.  
  737. .1
  738. Commandline version HMAKE.EXE
  739.  
  740. .in compiling
  741. .in commandline version
  742. The commandline version of Hypermake (HMAKE.EXE) is a pure compiler without user interface. The majority of users will prefer the graphical version HYMAKE.EXE with user interface (integrated editor, settings notebook and so on). In this chapter, the usage of the commandline version is explained.
  743.  
  744. You can start the commandline version in two different ways: by entering only one parameter - a HMP file Hypermake Project file which contents the parameters, or by entering several parameters behind HMAKE.EXE (especially the a name of source file and ini file).
  745.  
  746. .IF DOS
  747. HMP files are less useful together with DOS and Windows 3.1 because of the lack of some functionality, e.g. starting the second compiler automatically. I recommend writing batch files.
  748. .END
  749.  
  750. .2
  751. Starting by using HMP files
  752.  
  753. .in HMP file
  754. HMP files are new in Hypermake 3.5. They are a substitute for using the commandline and batch files.
  755.  
  756. .IF not DOS
  757. After running of HMINSTAL all HMP files are associated with three programs simultaneously: the default association is open project which will start the graphical HYMAKE.EXE program with user interface. The other two associations are edit project file which starts an Ascii editor and compile project which executes the commandline version of Hypermake HMAKE.EXE.
  758. .END
  759.  
  760. .IF OS2
  761. To see the file associations, click to a HMP file icon with the right mouse button and choose open.
  762. .END
  763. .IF WIN95
  764. To see the file associations, click to a HMP file icon with the right mouse button.
  765. .END
  766.  
  767. The default association (double clicking to the HMP icon) is the compiler.
  768.  
  769. Now choose "edit project file". In each line of a HMP file, there's a setting. On the right side of the = character you are allowed to modify the setting. Comment lines beginning with ; or // are ignored.
  770.  
  771. The following lines should be part of every HMP file:
  772.  
  773. .sfB
  774. ;Hypermake Project file
  775.  
  776. source files = sample.txt
  777. ini file = sample.ini
  778. .sf
  779.  
  780. It's necessary to enter at least one source text and the name of the ini file.
  781.  
  782. .IF DOS
  783. The DOS version only accepts one filename.
  784. .ELSE
  785. You are allowed to enter serveral source filenames, separated by spaces. Hypermake concatenates them in the memory in the chosen order.
  786. .END
  787.  
  788.  
  789. .afB
  790. ~target = HTML~
  791.  
  792. Hypermake creates Hypertext in the format ~IPF, WINHELP3, WINHELP4, HTML, HTMLHELP~. There's also a target= setting in the ini file. The target setting in the ini file is only relevant if there's no target setting in the HMP file. "target" in the HMP file is useful when compiling more than one Hypertext format.
  793.  
  794. ~parameter = noframes noid bigfont~
  795.  
  796. There are some program parameters available.
  797.  
  798. ~conditions = COND1 COND2~
  799.  
  800. You can place if-conditions in the source text. You can enclose parts of the text which will be only compiled to the Hypertext if the condition is set. The source of this documentation contains a lot of if-conditions.
  801.  
  802. Starting the second compiler automatically
  803.  
  804. HTML files generated by Hypermake can be viewed immediately with a browser. All other hypertext formats need a second compiler where the input is the Hypermake output. The second compiler generates a binary hypertext file which can be viewed with a specific viewer. It's useful that the second compiler is started immediately, if Hypermake hasn't generated errors.
  805.  
  806. .IF DOS
  807. Starting the second compiler is not available for the DOS version. Please write batch files by yourself.
  808. .ELSE
  809.  
  810. .it second compiler
  811. .sfB
  812. compile = YES
  813. view = YES
  814. .sf
  815.  
  816. Hypermake can start the second compiler and the viewer automatically. In this case it needs the full filename of the second compiler:
  817.  
  818. .sfB
  819. ipf compiler = C:\IPFC\IPFC.EXE /inf
  820. winhelp3 compiler = C:\WINHELP\HC.EXE
  821. winhelp4 compiler = C:\HELPWORKSHOP\PROGRAM\HCRTF.EXE /x
  822. htmlhelp compiler = C:\HTMLHELP\HHC.EXE
  823. .sf
  824.  
  825. You have to enter the correct directories, if the compiler is not in the PATH statement. You are allowed to enter commandline parameters behind the filename.
  826.  
  827. .sfB
  828. ipf viewer = VIEW.EXE
  829. winhelp3 viewer = WINHELP.EXE
  830. winhelp4 viewer = WINHELP32.EXE
  831. htmlhelp viewer = HH.EXE
  832. .sf
  833.  
  834. You have to enter the correct directories, if the compiler is not located in a directory of the PATH statement.
  835.  
  836. ~command lines = 50~
  837.  
  838. Some second compilers generate a lot of messages. A fast computer don't let you see the first of these messages because the default textual window has only 25 lines. Here you can enter the number of lines for the window where the second compiler writes its output. To try which line number is accepted by your system, open a commandline window and enter MODE 80,50 or another value instead of 50. Some systems accepts 1000 lines, depending on the operating system and the hardware.
  839.  
  840. .END
  841. .IF OS2
  842. ~processor = C:\OS2\CMD.EXE~
  843.  
  844. Hypermake generates a temporary batch file HMTEMP.CMD to execute the commandline compiler and the viewer. OS/2 needs the commandline processor to run batch files. If the commandline processor is not the name above, you can enter another processor.
  845. .END
  846.  
  847. Copying graphic files to the target directory automatically
  848.  
  849. .in graphic path
  850. ~graphic path = fullpathname;fullpathname;fullpathname~
  851.  
  852. Hypermake copies graphic files automatically to the target directory. Here you can enter all the directories where the graphic files are located.
  853.  
  854. The setting graphic path can also be placed in the ini file.
  855.  
  856. .2
  857. Starting by using the commandline
  858.  
  859. .fu
  860. .in commandline parameters
  861. .in commandline
  862. .IF OS2
  863. 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 or in the same path the EXE file is located. If the EXE file doesn't find the DLL, you will get an OS/2 error message "0005" or "SYS3175".
  864. .END
  865. .IF Win95
  866. To execute HMAKE.EXE from every directory, you have to place the file HMAKE.EXE or a file link in a directory which is part of the PATH statement. Enter SET PATH to get a list of these directories.
  867. .END
  868. .IF DOS
  869. To execute HMAKE.EXE from every directory, you have to place the file HMAKE.EXE in a directory which is part of the PATH statement in the file AUTOEXEC.BAT.
  870. .END
  871.  
  872. There are one or two parameters you have to enter:
  873.  
  874. .sfP
  875. [C:\myProject] HMAKE myDoc.txt my.ini
  876. .sf
  877.  
  878. 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".
  879.  
  880. 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:
  881.  
  882. .sfP
  883. [C:\myProject] HMAKE myDoc.txt
  884. .sf
  885.  
  886. 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.
  887.  
  888. 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.
  889.  
  890. The name of the output file will automatically be the entered source file name with the extension IPF.
  891.  
  892. .IF not DOS
  893. Many source files
  894.  
  895. 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.
  896. .END
  897.  
  898. Changing the target format
  899.  
  900. With the commandline parameters ~HTML IPF WINHELP3 WINHELP4 HTMLHELP RTFTEXT~ you can temporary overwrite the default setting "target file" in the ini file. ~RTFTEXTCC~ sets the target format to RTF-text, and turns the color correction setting on. You are also allowed to write a slash for these parameters: ~/HTML~
  901.  
  902. Setting conditions
  903.  
  904. You can place if-conditions in the source text. You can enclose parts of the text and this part will be only compiled to the Hypertext if the condition is set. These conditions can be set by using commandline parameters, beginning with a hash #.
  905.  
  906. .sfP
  907. [C:\myProject] HMAKE MeinDoku.txt #COND1 #COND2
  908. .sf
  909.  
  910. .2
  911. specific program parameters
  912.  
  913. Specific program parameters can be entered in the HMP file, line parameters=, or in the commandline, beginning with a / slash. Normally you won't need these parameters. They are sometimes necessary when compiling to several hypertext formats by using only one ini file. E.g. you can type ~NOFRAMES~ behind the ~parameters =~ line of the HMP file or you enter ~/NOFRAMES~ directly into the commandline. The parameters are not case sensitive.
  914.  
  915. The majority of parameters are also supported in the graphical version HYMAKE.EXE, you will find them in the settings notebook on the page "Main", section "Parameter". They are described in chapter program paramter. The commandline version supports some additional parameters:
  916.  
  917. .IF WORDSTARDOC
  918. WordStar dot commands
  919.  
  920. If you use DOS WordStar to write the source text, it can be useful to use WordStar specific dot commands Hypermake does not know. With ~/q~ (quiet) you can omit the error message "unknown dot command". 
  921. .END
  922.  
  923. Progress indicator
  924.  
  925. The /dots parameter forces dots for each compiled chapter instead of the turning progress symbol.
  926.  
  927. Omit Output and "press any key" query
  928.  
  929. /quit omits the "press any key" query which appears when HMAKE ends and the program parameter was a HMP file.
  930.  
  931. Writing Message Output to a File
  932.  
  933. In addition to the screen output, Hypermake can write all messages or especially error messages to a file. That's useful e.g. to write batch files.
  934.  
  935. .sfB
  936. /MESSAGES:filename
  937. /ERRORS:filename
  938. .sf
  939.  
  940. You can use the general command >NUL at the end of the command line to omit the screen Output of HMAKE.
  941.  
  942. .2
  943. Returncodes
  944.  
  945. .in return code
  946. Since 3.97, HMAKE ends execution with returncodes which represents categorized error types. A program which executes HMAKE can use these returncodes. Hypermake creates lots of different error messages, most of them are from category 31 "source file syntax error". 
  947.  
  948. .sfB
  949.  0: no termination error (but no information about warnings)
  950.  1: internal (should not occur)
  951.  2: external program not found
  952. 11: file not found/file empty/parameter not existing
  953. 12: error writing output file
  954. 13: error writing messagefile/errorfile
  955. 14: registration required
  956. 21: error in ini file
  957. 22: error in hmp file
  958. 31: source file syntax error 
  959. 32: source file syntax error, please contact hmake author
  960. 33: bug in Hypermake, please contact autor
  961. 98: user break
  962. 99: other errors
  963. .sf
  964.  
  965. .2
  966. Writing batch files
  967.  
  968. .in batch file
  969. Batch files are a "macro file" for commandline input. If you enter always the same commands, you can write a batch file instead with a simple editor. The extension of batch files is BAT (DOS, Win95, NT) or CMD (OS/2, NT).
  970.  
  971. .IF not DOS
  972. Principally HMP files are a complete substitute for batch files. But if you are familiar with batch files, you can use them nevertheless.
  973. .END
  974.  
  975. .IF OS2
  976. A useful batchfile for running in the background can be:
  977.  
  978. .sfB
  979. rem Generating hypertext with Hypermake and IPFC
  980. Hypermake my.txt /errors:HyperMake_errors
  981. start /f e HyperMake_errors
  982. ipfc /inf my.ipf >ipfc_errors
  983. start /f e ipfc_errors
  984. echo **
  985. .sf
  986.  
  987. 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.
  988.  
  989. If you are not familiar with batch files, take a look at the chapter "OS/2-commands, batch files" in the OS/2 commandline reference.
  990.  
  991. .ELSE
  992. Using Windows, you can write a batch file e.g. to generate Winhelp:
  993.  
  994. .sfB
  995. rem Generating hypertext with Hypermake and HC.EXE
  996. HMAKE my.txt /errors:hm_error.txt
  997. start notepad hm_error.txt
  998. C:\WINHELP\HC my.hpj >hc_error.txt
  999. start notepad hc_error.txt
  1000. echo **
  1001. .sf
  1002. .END
  1003.  
  1004. In the last line, behind the "echo" command, you can write two Alt-7-chars, that will create two beeps.
  1005.  
  1006. The > command copies the screen output to a text file instead to the screen and works not with the Hypermake Win95/NT and DOS version. Better use ~/MESSAGES:filename~ and ~/ERRORS:filename~ instead.
  1007.  
  1008. Other useful commands in batch files
  1009.  
  1010. ~PAUSE~ interrupts the batch files and the use has to "press any key".
  1011.  
  1012. ~%1~ will be substituted by the first commandline parameter given to the executed batch file.
  1013.  
  1014. Note that drag and drop does not work with such batch files, because if you write e.g. ~%1.IPF~ or ~%1.HPJ~, two extensions are concatenated together.
  1015.  
  1016. .2
  1017. Debug mode
  1018.  
  1019. .in bugfixing
  1020. 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 program 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.
  1021.  
  1022. With ~/debugmain~ instead of ~/debug~, the text is only shown when writing the IPF/RTF/HTML files.
  1023.  
  1024. 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.
  1025.  
  1026. .wa verti 30
  1027. .1
  1028. Reverse Converting Mode from IPF and RTF to Hypermake
  1029.  
  1030. .in reverse converting mode
  1031. .2
  1032. About
  1033.  
  1034. If you have already an IPF or RTF file, 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.
  1035.  
  1036. RTF (Rich Text Format) is not only the source of the Winhelp compiler, it is supported by a lot of word processors like Winword.
  1037.  
  1038. The reverse converting mode shortens 90 or 95% of your work converting files, but not 100%. The formats are too different for programming a perfect conversion. So you should use this functionality only one time. Then you should rest in editing the Hypermake source.
  1039.  
  1040. The ini file (project settings notebook) is used in reverse converting mode, too. So first take a look at the ini file settings "list char" (unordered lists), "toggle char" and "Source format". In the graphical Hypermake program, you will find it on the pages "Format" and "spec. chars" in the project settings. When compiling IPF source, make sure that you have defined enough list chars (e.g. four list chars if you have got ordered/unordered lists up to four levels). 
  1041.  
  1042. .2
  1043. IPF reverse Converting
  1044.  
  1045. The IPF reverse converting mode is enabled to convert:
  1046.  
  1047. ■ toggles
  1048. ■ Headings
  1049. ■ unordered lists, ordered lists
  1050. ■ main formatting commands (paragraph, break, formatting on/off)
  1051. ■ index entries (only i1 level), they will also get link target
  1052. ■ graphics (not graphics in text)
  1053.  
  1054. It's not enabled to convert:
  1055. ■ Fonts
  1056. ■ Window arrangement
  1057. ■ Margin
  1058. ■ Footnotes
  1059. ■ definition lists
  1060. ■ Panel ID's, connection to EXE program.
  1061.  
  1062. .2
  1063. RTF reverse converting
  1064.  
  1065. For reverse converting RTF to Hypermake can choose between two different RTF formats:
  1066. ■ RTF source files for Windows Help
  1067. ■ normal RTF files which are not used for Windows Help (e.g. normal RTF export from Winhelp).
  1068.  
  1069. If you want to convert a RTF file which is not for Windows Help, use the Parameter ~/ISTEXT~ when starting Hypermake from the commandline. The default parameter is ~/ISPROG~ for reverse converting a RTF Winhelp file.
  1070.  
  1071. The RTF reverse converting mode is enabled to convert:
  1072.  
  1073. ■ toggles
  1074. ■ Headings
  1075. ■ main formatting commands (paragraph, break, formatting on/off)
  1076. ■ index entries (only i1 level), they will also get link target
  1077. ■ Margin
  1078. ■ Footnotes
  1079. ■ graphics (also graphics in text).
  1080.  
  1081. It's not enabled to convert:
  1082. ■ Fonts
  1083. ■ Window arrangement
  1084. ■ definition lists
  1085. ■ Panel ID's (connection to EXE program)
  1086. ■ unordered lists, ordered lists.
  1087.  
  1088. The text of the table does not disappear, but the formatting is destroyed. An easy way to convert the tables and its formatting is simply copying the table from the Windows viewer to the clipboard and pasting it into the Hypermake source text between the two ~.TA~ dot commands.
  1089.  
  1090. In RTF syntax, unsorted lists and sorted lists does not exist. So converting cannot work in this point. (In the normal direction Hypermake to RTF, sorted lists and unsorted lists are emulated by other RTF commands.)
  1091.  
  1092. Note that some word processors like Winword normally do not export the heading structure of the document to RTF, but Hypermake needs them in any case! In Winword you have to choose a template like "heading1" instead of the "default" template. Please choose a decimal heading structure like "1 - 1.1 - 1.1.1" and so on. Only this structure is converted to Hypermake heading commands.
  1093.  
  1094. .2
  1095. Start Conversion (graphical version)
  1096.  
  1097. To start the reverse conversion, select Project - Import RTF/IPF. Then you will be asked to select several filenames:
  1098.  
  1099. ■ a filename for the new project (HMP file)
  1100. ■ a filename for the Hypermake source text which Hypermake will create by reverse conversion (If you enter an existing filename, the file will be overwritten.) Don't use the same filename (without extension) which your existing IPF or RTF file has, because later the file which Hypermake will create is sourcefilename.IPF or sourcefilename.RTF and this will overwrite your IPF or RTF source file without warning.
  1101. ■ the name of the IPF or RTF file to be converted
  1102. ■ an existing ini file with settings closest to your new project (Sample.ini of this archive, if you don't have already your own files)
  1103. ■ a name for a new ini file for your new project where the settings are copied from the existing filename above.
  1104.  
  1105. After that, the settings notebook will be opened automatically and you can modify some settings before the reverse conversion will start. Some settings which define the syntax of the Hypermake source text to be generated are interpreted by the reverse conversion, e.g. the selection of the toggles. Take a detailed look at the settings notebook pages "format" and "spec. chars". After you close the settings notebook, Hypermake starts the reverse conversion.
  1106.  
  1107. .2
  1108. Start Conversion (commandline version)
  1109.  
  1110. .afB
  1111. In the main direction you can start Hypermake from the commandline and from HMP files. Here you need to use the commandline ("OS/2 window", "MS-DOS prompt").
  1112.  
  1113. To start the reverse converting mode, you have to enter the ini file you will use later (e. g. a copy of SAMPLE.INI) and a file with the extension ~.IPF~ or ~.RTF~. Several source files are not supported. For RTF files which are not a Windows help source, you have to enter the parameter ~/ISTEXT~.
  1114.  
  1115. .sfP
  1116. .fu
  1117. [C:\myProject] HMAKE myDoc.ipf myDoc.ini
  1118. .sf
  1119.  
  1120. .fu[]
  1121. The file which is generated has always the same name HMSOURCE.TXT.
  1122.  
  1123. .1
  1124. Writing a Hypermake Source Text
  1125.  
  1126. .in Writing a Hypermake source text
  1127. .in source text
  1128. .WA verti 25
  1129. .2
  1130. Essentials
  1131.  
  1132. .ID P_essentials
  1133.  
  1134. .3
  1135. Dot commands
  1136.  
  1137. The Hypermake format uses µ:dot command:s like old WordStar. A dot command is a complete line beginning with a dot, for example
  1138.  
  1139. .sfB
  1140.  .SF
  1141. .sf
  1142.  
  1143. sets the standard font to default. Dot commands aren't case sensitive. A lot of dot commands require parameters, for example
  1144.  
  1145. .sfB
  1146.  .LM10
  1147. .sf
  1148.  
  1149. will change the left margin to 10. You can leave a space between the dot command and the parameter.
  1150.  
  1151. The line
  1152.  
  1153. .sfB
  1154.  ..comment
  1155. .sf
  1156.  
  1157. will be ignored.
  1158.  
  1159. Some dot commands have got more than two characters, but that's only to read it more easily. You can abbreviate them to the first two chars.
  1160.  
  1161. 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. 
  1162.  
  1163. In this hypertext, you will find a dot command summary.
  1164.  
  1165. .IF IPFDOC
  1166. .3
  1167. IPF commands
  1168.  
  1169. .sfB
  1170.  .:ipfcommand.
  1171.  .:ipfcommand. expression
  1172. .sf
  1173.  
  1174. You can enter an IPF command directly (that will be an exception, because most important functions are in the much easier Hypermake format).
  1175. .END IPFDOC
  1176.  
  1177. .IF HTMLDOC
  1178. .3
  1179. HTML commands
  1180.  
  1181. .ID P_essentialshtml
  1182. .it embed commands in HTML-syntax
  1183. There are three ways of embedding HTML commands directly. This is interesting for you if you are familiar with HTML commands. Perhaps you prefer using original HTML commands sometimes or you want to embed Javascript or Java programs. Hypermake will omit these commands if you compile to other formats, of course.
  1184.  
  1185. The first command to include HTML commands is directly using <HTML tags> in the running Hypermake text. With the dot command
  1186.  
  1187. .sfB
  1188.  .HC on
  1189.  .HC off
  1190. .sf
  1191.  
  1192. (HTML command) you can use HTML tags by using the HTML specific <HTML tag> syntax.
  1193.  
  1194. 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 as normal text.
  1195.  
  1196. The second way is to enter HTML text and commands directly, e.g. for Javascript programs. Between the .HTML and the .HYPERMAKE command, 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.
  1197.  
  1198.  
  1199. .sfB
  1200.  .HTML
  1201.  
  1202.  <HTML-commands> running HTML text
  1203.  
  1204.  .HYPERMAKE
  1205. .sf
  1206.  
  1207. The third way of embedding HTML text is for bigger quantities of commands, e.g. writing Javascript programs:
  1208.  
  1209. .sfB
  1210.  .HF filename
  1211. .sf
  1212.  
  1213. The HTML File command will copy the content of the file filename to the location of the dot command.
  1214. .END HTMLDOC
  1215.  
  1216. .3
  1217. Toggles
  1218.  
  1219. .it toggle character
  1220. .in toggle
  1221. In the ini file (project settings, page "spec. chars") you can set some toggle chars. If you have chosen "*" for "bold" and "@" for italic, you can write:
  1222.  
  1223. .sfB
  1224. This *part of this sentence* is very important.
  1225. .sf
  1226.  
  1227. And you will get: 
  1228.  
  1229. This part of this sentence is very important.
  1230.  
  1231. You also can mix some toggles:
  1232.  
  1233. .sfB
  1234. This is *bold and @also italic* and only italic@.
  1235. .sf
  1236.  
  1237. And you will get:
  1238.  
  1239. This is bold and also italic and only italic.
  1240.  
  1241. You can enter these characters in the integrated editor by using popup menu - toggle.
  1242.  
  1243. .IF DOS
  1244. You have to think about toggle chars you don't need in the normal text.
  1245.  
  1246. The 32 bit versions of Hypermake let you use a toggle char as a normal visible character, you have to type it twice. This functionality is NOT part of the DOS version.
  1247.  
  1248. .ELSE
  1249. 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:
  1250.  
  1251. .sfB
  1252. @My E-Mail Address:@
  1253.  
  1254. Martin@@vr-transport.de
  1255. .sf
  1256. .END
  1257.  
  1258. 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.
  1259.  
  1260. The integrated Hypermake Editor supports a second way to enter these characters below 26 when using the Wordstar or Mixed key table: E.g. for the ASCII value 19, you enter Ctrl-P for "printer" and then Ctrl-S or S. (S is the 19th letter of the alphabet.)
  1261.  
  1262. .3
  1263. Handling of Returns
  1264.  
  1265. .in Handling of Returns
  1266. .in ASCIISOFTRET
  1267. .in ASCIIHARDRET
  1268. .in source format
  1269. 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 ("word wrap" in project settings, page "Format"), every Return will be treated as a new line. Use this setting if your editor does not put Returns in wrapped lines. Most editors support this function (often: options - word wrap on/off).
  1270.  
  1271. Use ASCIISOFTRET if your editor puts Returns on all line endings. This will only treat a Return as a new line, if
  1272. ■ there are two Returns behind each other (i. e. an empty line)
  1273. ■ the last character in the line is . ! ? : ;
  1274.  
  1275. .IF WORDSTARDOC
  1276. Using DOS WordStar, such problems don't exist, because WordStar distinguishes between soft and hard Returns.
  1277. .END
  1278.  
  1279. .2
  1280. Beginning
  1281.  
  1282. .ID P_beginning
  1283. Every document has one µtitle. The title will be shown as title of the main window and in the tasklist.
  1284.  
  1285. .sfB
  1286.  .TI
  1287.  Documentation of my program
  1288. .sf
  1289.  
  1290. sets the title in HTML files or INF files. Every Hypermake source text should begin with the title dot command, before the first heading.
  1291.  
  1292. .IF HTMLDOC
  1293. Hypermake creates several HTML files from one source text file. You can define the title of every HTML file with the ini file setting file title (project settings, page "html-2"). 
  1294. .END
  1295.  
  1296. .afB
  1297. .IF IPFDOC
  1298. In OS/2 HLP files, the title is set in your program source code, see function InitHelp. The TI dot command title is ignored.
  1299.  
  1300. 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
  1301.  
  1302. .sfB
  1303.  .<>
  1304. .sf
  1305. .END
  1306.  
  1307. .IF WINHELPDOC
  1308. By default, Winhelp files don't have the Pushbuttons Back << and Forward >>, but they are useful in any case. If you want to have these Pushbuttons, then enter the dot command
  1309.  
  1310. .sfB
  1311.  .<>
  1312. .sf
  1313. .END
  1314.  
  1315. .2
  1316. Chapters and Headings
  1317.  
  1318. .ID P_chapter
  1319. Every Hypermake document is structured by chapters. Every chapter begins with a heading. Starting an Hypertext document created by Hypermake, you will get the content which lists all chapter headings. From the content you can go to every page of the hypertext.
  1320.  
  1321. .IF IPFDOC
  1322. 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.
  1323. .END
  1324.  
  1325. .IF WINHELPDOC
  1326. Every chapter in a Winhelp document gets its own page.
  1327. .END
  1328.  
  1329. .IF HTMLDOC
  1330. When Hypermake creates HTML files, you will get a contents file with the filename INDEX.HTML. Normally every chapter gets its own HTML file. You can turn off the creation of a contents file on the page HTML-0 of the project settings notebook when compiling a very small project with perhaps only one "chapter", that means only one HTML page.
  1331. .END
  1332.  
  1333. You can arrange your text with µheading levels like you would in a scientific work:
  1334.  
  1335. .sfA
  1336. first heading
  1337.     first sub-heading
  1338.     second sub-heading
  1339.          first sub-sub-heading
  1340.          second sub-sub-heading
  1341.     third sub-heading
  1342. second heading
  1343. .sf
  1344.  
  1345. In the Hypermake format, the headings are written like
  1346.  
  1347. .sfB
  1348.  .1
  1349.  first heading
  1350.  
  1351.  .2
  1352.  first sub-heading
  1353.  
  1354.  .2
  1355.  second sub-heading
  1356.  
  1357.  .3
  1358.  first sub sub-heading
  1359.  
  1360.  .3
  1361.  second sub sub-heading
  1362.  
  1363.  .2
  1364.  third sub-heading
  1365.  
  1366.  .1
  1367.  second heading
  1368. .sf
  1369.  
  1370. On the next line after the dot command for the heading level, you can enter the heading text.
  1371.  
  1372.  
  1373. 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.
  1374.  
  1375. In a normal document, you would use numeric headings:
  1376.  
  1377. 1. first heading
  1378.    1.1 first sub heading
  1379.    1.2 second sub heading
  1380.           1.2.1 first sub sub heading
  1381.           1.2.2 second sub sub heading
  1382.    1.3 third sub heading
  1383. 2. second heading
  1384.  
  1385.  
  1386. .IF IPFDOC
  1387. When generating IPF, 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 on the size of the INF window on the screen.
  1388. .END
  1389.  
  1390. At the beginning of a document, normal text can only be written after using the first heading dot command.
  1391.  
  1392. You are allowed to use up to 6 heading levels.
  1393.  
  1394. .IF HTMLDOC
  1395. .3
  1396. HTML specifics
  1397.  
  1398. .ID P_chapterhtml
  1399. With the ini file setting content level ("shown in contents", project settings page "html-1"), you can define the number of levels shown on the content page.
  1400.  
  1401. 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.
  1402.  
  1403.  
  1404. ~.HS 123234~
  1405.  
  1406. or
  1407.  
  1408. ~.HS 112233~
  1409.  
  1410. changes the size of the fonts of levels 1 to 6.
  1411.  
  1412. The default setting is:
  1413.  
  1414. ~.HS 123456~
  1415.  
  1416. Please note the Javascript contents tree view since Hypermake 3.6.
  1417. .END
  1418.  
  1419. .IF WINHELPDOC
  1420. .3
  1421. Winhelp specifics
  1422.  
  1423. You will find all Winhelp-specific ini file settings in the project settings notebook, page "Winhelp".
  1424.  
  1425. With the setting ~heading fonts~ in the ini file, you can choose the font of the heading text by typing a font char for each heading level. Font chars are defined in the ini file. 
  1426.  
  1427. Winhelp allows to get the heading text fixed, so scrolling the page does not hide the heading text. You can turn off and on this setting with ~keep heading~.
  1428.  
  1429. The two Winhelp formats WINHELP3 and WINHELP4 have got a different way of showing the contents: WINHELP3 has no contents functionality, so Hypermake generates a contents on the first page of the Hypertext. WINHELP4 uses CNT files. These contents files have to be shipped together with the HLP file and are in ASCII format. CNT files are pointing to all pages of the HLP file. They have got a tree view of the chapter headings.
  1430.  
  1431. CNT files cannot be read with Windows 3.1. Hypermake enables you generating an internal contents or a CNT file or both, independent from choosing the target format WINHELP3 or WINHELP4, by using the ~contents creation~ setting in the ini file.
  1432.  
  1433. When creating an internal contents page in the HLP file, the normally HTML specific ~contents level~ setting is interpretated. So you can create a contents page with only 2 heading levels. In addition, you can use the program parameter /internal, so you can create an internal contents instead of a CNT file without changing the ini file.
  1434.  
  1435. CNT files have got a very bad design: A main chapter cannot point to a page with normal text before the sub chapters begin. But that's the normal form of text documents. Hypermake creates a new first sub chapter with a heading "general" where this text is placed. You can change the heading text of this first sub chapter with ~contents general text~.
  1436. .END
  1437.  
  1438. .3
  1439. Links to subchapters
  1440.  
  1441. .in Link to subchapters
  1442. .ID P_linktosubch
  1443. 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 (project settings page "Link"), setting ~text for link to...~.
  1444.  
  1445. 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.
  1446.  
  1447. With the dot command ~.SC~ (Subchapter separation characters) you can change the appearance of the links to subchapters.
  1448.  
  1449. ~.sc chars~
  1450.  
  1451. fits the characters "chars" between the subchapters heading text instead of a Return. The command
  1452.  
  1453. ~.sc RETURN~
  1454.  
  1455. resets the default setting with one Return between each heading text.
  1456.  
  1457. .sfB
  1458.  .btx blackdot
  1459.  .sc  x 
  1460.  .2
  1461.  heading text of the first sub chapter
  1462.  
  1463.  .sc RETURN
  1464. .sf
  1465.  
  1466. 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.
  1467.  
  1468. .sfB
  1469.  .sc RETURN RETURN
  1470.  .sc PARAGRAPH
  1471. .sf
  1472.  
  1473. The two commands have got the same effect: They force an empty line between each heading text.
  1474.  
  1475. .sfB
  1476.  .sc LIST
  1477. .sf
  1478.  
  1479. writes the sub chapter headings as an unsorted list.
  1480.  
  1481. .3
  1482. Window arrangement (Frames)
  1483.  
  1484. .in window arrangement
  1485. .in Frames
  1486. .ID P_frames
  1487. 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.
  1488.  
  1489. .sfE
  1490. Arranging two heading levels
  1491. .sf
  1492.  
  1493. With the dot command Window Arrangement
  1494.  
  1495. .sfB
  1496.  .WA verti 30
  1497. .sf
  1498.  
  1499. 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.
  1500.  
  1501. Note the spaces between the parameters of the window arrangement dot command. 
  1502.  
  1503. When using window arrangement, I strongly recommend leaving the automatic link to subchapters function turned on in the ini file (project settings page "Link").
  1504.  
  1505. .sfB
  1506.  .WA hori 40
  1507. .sf
  1508.  
  1509. 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%).
  1510.  
  1511. You can enter percent values from 10 to 90.
  1512.  
  1513. With the commandline parameter ~/NOFRAMES~, this dot command won't be interpreted.
  1514.  
  1515. For a sample arrangement of two heading levels see dot command summary or ini file.
  1516.  
  1517. .IF WINHELPDOC
  1518. Winhelp does not support Frames. Nevertheless, the .WA command is interpretated, but only with WINHELP4. Hypermake separates the help text in two help windows. 
  1519. On the left side of the main window, Hypermake generates a smaller window. The name of the smaller left window is "navi", the name of the normal window is "main". The verti/hori and percent values of the .WA command are not interpreted. I recommend not to write a lot of text in the main chapter because the main chapter gets the small "navi" window. In the smaller "navi" window the automatically generated links to subchapters let the user navigate between several subchapters which are shown in the bigger "main" window.
  1520. .END
  1521.  
  1522. .IF MSHTMLHELPDOC
  1523. When creating HTMLHELP, Hypermake always uses the "hori" setting of the .WA command even "verti" was entered: The MS HTML-Help viewer shows the contents tree at the left side and the normal text at the right side of the help window. Separating the text window vertically again would produce an inacceptable small text window.
  1524. .END
  1525.  
  1526. .sfE
  1527. Arranging three heading levels
  1528. .sf
  1529.  
  1530. This functionality is only available so far for creating IPF files.
  1531.  
  1532. .IF IPFDOC
  1533. In the same way, you are allowed to arrange three heading levels. Now you have to enter a hori and a verti value simultaneously.
  1534.  
  1535. .sfB
  1536.  .WA hori 40 verti 30 III
  1537. .sf
  1538.  
  1539. .afB
  1540. 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: 
  1541.  
  1542. .liXY
  1543.  
  1544.             verti hori           hori verti
  1545.        
  1546.         ┌─────┬──────────┐   ┌────────────────┐
  1547.         │     │   II     │   │       I        │
  1548.   I     │  I  ├──────────┤   ├─────┬──────────┤ 
  1549.         │     │   III    │   │ II  │   III    │
  1550.         │     │          │   │     │          │
  1551.         └─────┴──────────┘   └─────┴──────────┘
  1552.        
  1553.         ┌─────┬──────────┐   ┌─────┬──────────┐
  1554.         │  I  │          │   │  I  │   II     │
  1555.         ├─────┤          │   ├─────┴──────────┤ 
  1556.  III    │     │   III    │   │                │
  1557.         │ II  │          │   │      III       │
  1558.         │     │          │   │                │ 
  1559.         └─────┴──────────┘   └────────────────┘
  1560. .li
  1561.  
  1562. ~I~ is the main chapter, ~II~ the subchapter of the main chapter, ~III~ the sub sub chapter of the main chapter.
  1563.  
  1564. The window arrangement dot command is active for one main chapter with its sub and sub sub chapters.
  1565.  
  1566. 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.
  1567.  
  1568. 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.
  1569.  
  1570. .4
  1571. Sample Input
  1572.  
  1573. .sfC
  1574.  .WA verti 50 hori 40 I
  1575.  .4
  1576. Sample Output
  1577.  
  1578. The main chapter with links to subchapters.
  1579.  
  1580.  .5
  1581. first sub chapter
  1582.  
  1583. The first sub chapter.
  1584. 3 frames are only supported when compiling IPF.
  1585.  
  1586.  .6
  1587. first sub sub chapter
  1588.  
  1589. The first sub sub chapter of the first sub chapter.
  1590.  
  1591.  .6
  1592. second sub sub chapter
  1593.  
  1594. The second sub sub chapter of the first sub chapter.
  1595.  
  1596.  .5
  1597. second sub chapter
  1598.  
  1599. The second sub chapter.
  1600.  
  1601.  .6
  1602. first sub sub chapter
  1603.  
  1604. The first sub sub chapter of the second sub chapter.
  1605.  
  1606.  .6
  1607. second sub sub chapter
  1608.  
  1609. The second sub sub chapter of the second sub chapter.
  1610. .sf
  1611.  
  1612. .WA verti 40 hori 50 I
  1613. .4
  1614. Sample Output
  1615.  
  1616. .in window arrangement sample output
  1617. The main chapter with links to subchapters.
  1618.  
  1619. .5
  1620. first sub chapter
  1621.  
  1622. The first sub chapter.
  1623. 3 frames are only supported when compiling IPF.
  1624.  
  1625. .6
  1626. first sub sub chapter
  1627.  
  1628. The first sub sub chapter of the first sub chapter.
  1629.  
  1630. .6
  1631. second sub sub chapter
  1632.  
  1633. The second sub sub chapter of the first sub chapter.
  1634.  
  1635. .5
  1636. second sub chapter
  1637.  
  1638. The second sub chapter.
  1639.  
  1640. .6
  1641. first sub sub chapter
  1642.  
  1643. The first sub sub chapter of the second sub chapter.
  1644.  
  1645. .6
  1646. second sub sub chapter
  1647.  
  1648. The second sub sub chapter of the second sub chapter.
  1649. .END IPFDOC
  1650.  
  1651. .WA hori 25
  1652. .2
  1653. Fonts
  1654.  
  1655. .in font
  1656. .ID P_font
  1657. .3
  1658. Using fonts
  1659.  
  1660. You can define serveral fonts in the ini file (project settings page "Font"). A "font" has got a specific size, a specific color, a specific fontname (like "Helvetica") and some other attributes. Some attributes are target format specific.
  1661.  
  1662. A font which is defined in the ini file is abbreviated with an upcase or an downcase letter, the "font char". The letters are case-sensitive, so you can use 2 x 26 font char as shortcuts. Every font char represents a font with specific attributes defined in the ini file. Normally you won't use more than 3 or 4 font chars. I recommend using the default font for most of the text (with no attributes). Otherwise the user who views the text has to read a font which is good for you and your screen, but not for him!
  1663.  
  1664.  
  1665. .sfE
  1666. µ:Select Font;
  1667. .sf
  1668.  
  1669. You can choose a font with the dot command select font
  1670.  
  1671. .sfB
  1672.  .SFX
  1673. .sf
  1674.  
  1675. .afB
  1676. ~X~ is a font character from A to Z and from a to z (case sensitive!).
  1677.  
  1678. You can assign different fonts, sizes and colors to each of the 2 x 26 chars in the ini file.
  1679.  
  1680. A font will be active till the next font dot command, even through headings.
  1681.  
  1682. To set the font to default, use the dot command without parameter:
  1683.  
  1684. .sfB
  1685.  .SF
  1686. .sf
  1687.  
  1688. .sfE
  1689. µ:Alternate Font;
  1690. .sf
  1691.  
  1692. .it alternate character
  1693. .afB
  1694. 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 (project settings page "spec. chars").
  1695.  
  1696. So you can change font and color in one line:
  1697.  
  1698. .afC
  1699. That ~d~o~e~s~n't~ l~o~o~k~ very good.
  1700.  
  1701. .afB
  1702. Alternate fonts should be only active within a paragraph. To write more than one paragraph in another font, please use the ~.SF~ command.
  1703.  
  1704. .sfE
  1705. µ:Font Attributes:
  1706. .sf
  1707.  
  1708. Font attributes are defined for every font character:
  1709.  
  1710. .sfB
  1711. font X =
  1712. .sf
  1713.  
  1714. At the right side of the equal char, you can list attributes, seperated by spaces. An attribute must not contain spaces, use underscore instead.
  1715.  
  1716. Fontname
  1717.  
  1718. .IF IPFDOC
  1719. When creating an OS/2 help file, you can choose between all fonts which are part of the default installation of OS/2: You will find a list of the available font in the folder "system configuration", program "font palette": Courier Helv Helvetica Roman System_monospaced System_proportional System_VIO Times_New_Roman Tms_Rmn and since Warp 3 Swiss Warp_Sans. Rembember that instead of spaces you have to enter _ underscore.
  1720. .END
  1721.  
  1722. .IF WINHELPDOC
  1723. Creating Winhelp, fontnames have to be entered together with its family name, e.g. fswiss:Helvetica. There are three font families:
  1724. ■ fmodern: fixed font, that means i has the same width like m (e.g. Courier)
  1725. ■ froman: proportional font with serifs (e.g. Roman)
  1726. ■ fswiss: proportional font without serifs (e.g. Helvetica)
  1727. .END
  1728.  
  1729. .IF HTMLDOC
  1730. For HTML, you can enter fontnames or "phrase elements".
  1731.  
  1732. Assigning fontnames directly 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.
  1733.  
  1734. 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.
  1735.  
  1736. HTML Phrase Element
  1737.  
  1738. .in Phrase Elements
  1739. The concept of HTML is different to Help files. Help files are special files for a specific operating system, HTML files not. 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.
  1740.  
  1741. HTML knows the following Phrase Elements:
  1742. ~PRE ADDRESS EM STRONG DFN CODE SAMP VAR CITE~
  1743.  
  1744. 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.
  1745.  
  1746. And here is the purpose of the other Phrase elements:
  1747.  
  1748. ■ ~EM~ basic emphasis typically rendered in an italic font 
  1749. ■ ~STRONG~ strong emphasis typically rendered in a bold font 
  1750. ■ ~DFN~ defining instance of the enclosed term 
  1751. ■ ~CODE~ used for extracts from program code 
  1752. ■ ~SAMP~ used for sample output from programs, and scripts etc. 
  1753. ■ ~VAR~ used for variables or arguments to commands 
  1754. ■ ~CITE~ used for citations or references to other sources 
  1755. .END
  1756.  
  1757. .IF IPFDOC
  1758. For IPF, you can define a font with ~PRE~, so you do not need formatting dot commands. ~PRE~ will turn formatting off.
  1759. .END
  1760.  
  1761. Font size
  1762.  
  1763. All target formats support font sizes. 10 or 12 (point) is a normal size. It can happen that some target formats gets a too small or too large font in comparison to other target formats when using font sizes. In this case, you can globally influence the size of the fonts which have got a size value in the ini file by using the program parameters bigfont and smallfont (parameter section in project settings page "main"). This will enlarge or reduce the size by 30%.
  1764.  
  1765. .IF HTMLDOC
  1766. Then you can enter relative sizes like 0 +1 -1. In addition to relative size, you can also enter absolute sizes for other Hypertext formats. But the relative HTML size has to be placed in front of the absolute size.
  1767. .END
  1768.  
  1769. .IF IPFDOC
  1770. The IPFC compiler won't accept more than 14 fonts of a specific size in one document.
  1771.  
  1772. Codepage
  1773.  
  1774. For IPF you can enter a codepage number with three digits like ~437~ or ~850~.
  1775. .END
  1776.  
  1777. Colors
  1778.  
  1779. All hypertext formats supports colors. The colors for the different target formats are distinguished by case sensitive color names.
  1780.  
  1781. .IF HTMLDOC or WINHELPDOC
  1782. For HTML and Winhelp, the color names have to begin with a capital letter and the following letters are small ones. There are 16 colors:
  1783.  
  1784. ~Black Silver Gray White Maroon Red Purple Fuchsia Green Lime Olive Yellow Navy Blue Teal Aqua~
  1785. .END
  1786.  
  1787. .IF IPFDOC
  1788. IPF knows the following colors for the font:
  1789. ~default blue cyan green neutral red yellow black~
  1790. Note that the colors are written in small letters. IPF is the only format which lets you define background colors. The background colors are the same, but written completely in capital letters.
  1791. .END
  1792.  
  1793. other attributes
  1794.  
  1795. You can define a font with a ~center~ attribute, so you do not need the output centered dot command.
  1796.  
  1797. There are two other font attributes. ~OmitLinks~ is described in linking, Omitting links; ~LineStandard~ in line drawing.
  1798.  
  1799. .3
  1800. HTML Phrase element samples
  1801.  
  1802. The output of phrase element commands depends on the browser.
  1803.  
  1804. .IF HTML
  1805. .HTML
  1806. <ADDRESS>Sample text with Phrase element ADDRESS</ADDRESS><br>
  1807. <PRE>Sample text with Phrase element PRE</PRE><br>
  1808. <EM>Sample text with Phrase element EM</EM><br>
  1809. <STRONG>Sample text with Phrase element STRONG</STRONG><br>
  1810. <DFN>Sample text with Phrase element DFN</DFN><br>
  1811. <CODE>Sample text with Phrase element CODE</CODE><br>
  1812. <SAMP>Sample text with Phrase element SAMP</SAMP><br>
  1813. <VAR>Sample text with Phrase element VAR</VAR><br>
  1814. <CITE>Sample text with Phrase element CITE</CITE><br>
  1815. .HYPERMAKE 
  1816. .ELSE
  1817. HTML Phrase Elements cannot be shown with this Hypertext format.
  1818. .END
  1819.  
  1820. .3
  1821. Color samples
  1822.  
  1823. .in Color samples
  1824. .IF IPF
  1825. IPF Colors: 
  1826.  
  1827. foreground
  1828.  
  1829. .:color fc=default.
  1830. default
  1831. .:color fc=blue.
  1832. blue
  1833. .:color fc=cyan.
  1834. cyan
  1835. .:color fc=green.
  1836. green
  1837. .:color fc=neutral.
  1838. neutral
  1839. .:color fc=red.
  1840. red
  1841. .:color fc=yellow.
  1842. yellow
  1843. .:color fc=black.
  1844. black
  1845. .:color fc=default.
  1846.  
  1847. background
  1848.  
  1849. DEFAULT
  1850. .:COLOR BC=BLUE.
  1851. BLUE
  1852. .:COLOR BC=CYAN.
  1853. CYAN
  1854. .:COLOR BC=GREEN.
  1855. GREEN
  1856. .:COLOR BC=NEUTRAL.
  1857. NEUTRAL
  1858. .:COLOR BC=RED.
  1859. RED
  1860. .:COLOR BC=YELLOW.
  1861. YELLOW
  1862. .:COLOR BC=BLACK.
  1863. BLACK
  1864. .:color bc=default.
  1865. .END IPF
  1866.  
  1867. .IF HTML OR WINHELP
  1868. HTML and Winhelp colors:
  1869.  
  1870. .sfa
  1871. Black
  1872. .sfb
  1873. Silver
  1874. .sfc
  1875. Gray
  1876. .sfd
  1877. White
  1878. .sfe
  1879. Maroon
  1880. .sff
  1881. Red
  1882. .sfg
  1883. Purple
  1884. .sfh
  1885. Fuchsia
  1886. .sfi
  1887. Green
  1888. .sfj
  1889. Lime
  1890. .sfk
  1891. Olive
  1892. .sfl
  1893. Yellow
  1894. .sfm
  1895. Navy
  1896. .sfn
  1897. Blue
  1898. .sfo
  1899. Teal
  1900. .sfp
  1901. Aqua
  1902. .sf
  1903.  
  1904. .END
  1905.  
  1906. .2
  1907. Unordered lists and ordered lists
  1908.  
  1909. .ID P_list
  1910. .it unordered list
  1911. The following text represents an unordered list:
  1912.  
  1913. ■ Style
  1914. - font (default, Tms_Rmn, Helv, Courier, System_VIO)
  1915. - size
  1916. ■ Color
  1917. - foreground color (default, blue, cyan, green, neutral, red, yellow, black)
  1918. - background color (same colors as foreground color).
  1919.  
  1920.  
  1921. 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.
  1922.  
  1923. .IF IPFDOC or HTMLDOC
  1924. In IPF and HTML format, you can't change the list chars the viewer/browser chooses.
  1925. .END
  1926.  
  1927. .IF WINHELPDOC
  1928. Winhelp has no list functionality included, so Hypermake emulates that functionality. Because Hypermake generates the lists, Winhelp is the only format where you can influence the appearence of the lists:
  1929.  
  1930. ■ The ini file setting ~List indention~ (project settings page "Winhelp") influences the size of the left margin (dot command .LM) and the indention of Lists.
  1931.  
  1932. ■ With "printed listchars" you can choose which character is the left fat dot. Capital O and small o are useful letters. You are allowed here to use bitmap characters (command .BT bitmap text). A Bitmap character is a special character which represents a bitmap file. A fine looking list dot is BLACKDOT.BMP in the Hypermake folder BUTTONS\WINBMP.
  1933. .END
  1934.  
  1935. The HTML and IPF command "Definition List" is not supported directly. You can emulate it with the Hypermake auto margin command.
  1936.  
  1937. .IF WORDSTARDOC
  1938. .3
  1939. Using DOS WordStar
  1940.  
  1941. .afB
  1942. 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.]
  1943.  
  1944. There are no definitive list chars for the different list levels like using an ASCII editor. Instead, using soft spaces is necessary.
  1945.  
  1946. .sfB
  1947. ■░Style
  1948. ░░-░░font (default, Tms_Rmn, Helv, Courier, System_VIO)
  1949. ░░-░░size
  1950. ■░Color
  1951. ░░-░░foreground color (default, blue, cyan, green, 
  1952. ░░░░░neutral, red, yellow, black)
  1953. ░░-░░background color (same colors as foreground color).
  1954. .sf
  1955.  
  1956. 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:
  1957.  
  1958. .sfB
  1959. ■░Style
  1960. ░░-░░font (default, Tms_Rmn, Helv, Courier, System_VIO)
  1961. ░░░-░size α(wrong position)α
  1962. ■░Color
  1963. ░░-░░foreground color (default, blue, cyan, green, 
  1964. ░░░░░neutral, red, yellow, black)
  1965. ░░*░░background color α(wrong character)α
  1966. .sf
  1967.  
  1968. After writing a normal paragraph without list function, for the next unordered list you can use other list char characters and positions.
  1969.  
  1970. .3
  1971. Using an ASCII editor
  1972.  
  1973. .END WORDSTARDOC
  1974. .in unordered list with an ASCII editor
  1975. .it list character
  1976. In the ini file (project settings page "spec. chars") 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
  1977.  
  1978. .sfB
  1979. * Style
  1980. = font (default, Tms_Rmn, Helv, Courier, System_VIO)
  1981. = size
  1982. * Color
  1983. = foreground color (default, blue, cyan, green, neutral, red, yellow, black)
  1984. = background color (same colors as foreground color).
  1985. .sf
  1986.  
  1987. You can add list chars for further levels. Other useful chars are the square Alt-254, the graphical double/single slash Alt-205/Alt-196 and the normal slash -.
  1988.  
  1989. To enter normal text after writing an unordered list, you have to enter a paragraph.
  1990.  
  1991. You can put more spaces before and after the list char, they will be ignored. The same result as above will be produced by:
  1992.  
  1993. .sfB
  1994.   *   Style
  1995.       =   font (default, Tms_Rmn, Helv, Courier, System_VIO)
  1996.       =   size
  1997. .sf
  1998.  
  1999. .3
  2000. Ordered lists
  2001.  
  2002. .it ordered list
  2003. .afO
  2004. 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.
  2005.  
  2006. To create an ordered list, you first have to proceed like writing an unordered list. ~With the dot commands ordered list and unordered list~
  2007. .afB
  2008.  
  2009. .sfB
  2010.  .OL
  2011.  .UL
  2012.  
  2013. .sf
  2014. .afO
  2015. 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.~
  2016.  
  2017. .2
  2018. Including Bitmaps
  2019.  
  2020. .in graphic
  2021. .ID P_bitmap
  2022. To include a big µbitmap centered, you can use the dot command bitmap
  2023.  
  2024. .sfB
  2025.  .BM filename
  2026. .sf
  2027.  
  2028. .IF IPFDOC
  2029. If you write the filename without extension when creating IPF files, ".BMP" will be automatically added. 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)]
  2030. .END
  2031.  
  2032. .IF IPFDOC and WINHELPDOC
  2033. Remember that both IPF and Winhelp are using BMP files, but IPF wants to get OS/2 Bitmap files and Winhelp Windows Bitmap files. Use the graphic path setting to copy the right BMP files for both target formats.
  2034. .END
  2035.  
  2036. .IF WINHELPDOC
  2037. If you write the filename without extension, ".BMP" will be automatically added when creating Winhelp files.
  2038. .END
  2039.  
  2040. .IF HTMLDOC
  2041. When creating HTML files, ".GIF" is automatically added, if you write the filename without extension.
  2042. .END
  2043.  
  2044. .afB
  2045. 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:
  2046.  
  2047. .sfB
  2048.  .BM RIGHT
  2049.  .BM filename
  2050. .sf
  2051.  
  2052. .IF HTMLDOC
  2053. In HTML, with the default stting CENTER you will get a bitmap with left alignment with no floating text.
  2054. .END
  2055.  
  2056. With the second dot command µ:bitmap text:, you can include bitmaps in text.
  2057.  
  2058. .sfB
  2059.  .BTX filename
  2060. .sf
  2061.  
  2062. .bt▒ box
  2063. ~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).
  2064.  
  2065. You are allowed to define several bitmap chars simultaneously.
  2066.  
  2067. To deactivate a character-bitmap definition, you can enter
  2068.  
  2069. .sfB
  2070.  .BTX
  2071. .sf
  2072.  
  2073. without a filename.
  2074.  
  2075. (new in Hypermake 3.65) If the graphics files are not placed in the current directory, you can set a directory with
  2076.  
  2077. .sfB
  2078.  .BD directory/
  2079. .sf
  2080.  
  2081. with µ:bitmap directory:. ~directory/~ is placed in front of every filename in the ~.BM~ and ~.BT~ commands which follows. Don't forget the Backslash ~\~ or Slash ~/~. This command does not affect HTML navigation buttons. Copying graphic files is deactivated when using ~.BD~.
  2082.  
  2083. .WA hori 35
  2084. .2
  2085. Linking and Indexing 
  2086.  
  2087. .in Link
  2088. .in Index
  2089. .in Jump
  2090. .ID P_linking
  2091. .3
  2092. Introduction
  2093.  
  2094. Linking is the most powerful function of Hypermake. When writing an HTML, RTF 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...
  2095.  
  2096. 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.
  2097.  
  2098. .IF HTMLDOC
  2099. 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 (project settings page "html-1").
  2100.  
  2101. On page HTML-0 of the project settings notebook, you can omit the creation of the index page when creating HTML. This can be recommended when compiling a small web page where only a small number index entries wouldn't look adequate.
  2102. .END
  2103.  
  2104. .3
  2105. Marking a single word, Changing the index char
  2106.  
  2107. .it index char
  2108. .sfE
  2109. Marking a single word
  2110. .sf
  2111.  
  2112. You can mark a single word for linking and indexing with the index char, defined in the ini file.
  2113.  
  2114. .sfB
  2115. A #workgroup is a group of people...
  2116. .sf
  2117.  
  2118. Note: Do not use index chars in headings, use automatic duplication of heading text instead.
  2119.  
  2120. .sfE
  2121. Changing the index char
  2122. .sf
  2123.  
  2124. You also can change the index char in the text by using the dot command index char
  2125.  
  2126. .sfB
  2127.  .IC@
  2128. .sf
  2129.  
  2130. This will change the index char from the actual setting, for example ~#~, to ~@~.
  2131.  
  2132. .3
  2133. Marking a phrase of several words in the running text
  2134.  
  2135. 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, project settings page "spec. chars").
  2136.  
  2137. To mark a phrase, you have to use ":" as brackets:
  2138.  
  2139. .sfB
  2140. Today, the #:security of computers: is...
  2141.  ...
  2142. Nevertheless, the #:security of mainframes: can be...
  2143.  ...
  2144. But the #:usability of computers; has to...
  2145. .sf
  2146.  
  2147. In the index, it will appear
  2148.  
  2149. .sfD
  2150. computers, usability of
  2151. security
  2152.     of computers
  2153.     of mainframes
  2154. .sf
  2155.  
  2156. 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.
  2157.  
  2158. If there is only one occurrence of a leading word like
  2159.  
  2160. .sfD
  2161. computers
  2162.     usability of
  2163. .sf
  2164.  
  2165. the Hypermake entry in the index will be:
  2166.  
  2167. .sfD
  2168. computers, usability of
  2169. .sf
  2170.  
  2171.  
  2172. You are allowed to use the "colon brackets" to crop endings:
  2173.  
  2174. .sfB
  2175. The importance of #:computer:s is growing...
  2176. .sf
  2177.  
  2178. In the index "computer" will appear without "s", also the link target will be "computer" and not "computers".
  2179.  
  2180. .3
  2181. Marking a phrase outside the running text
  2182.  
  2183. .ID P_linkingdotc
  2184. With the dot command INdex
  2185.  
  2186. .sfB
  2187.  .IN phrase
  2188. .sf
  2189.  
  2190. 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.
  2191.  
  2192. 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.
  2193.  
  2194. .sfB
  2195.  .IT usability of computers
  2196. .sf
  2197.  
  2198. .in index turned
  2199. 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.
  2200.  
  2201. .3
  2202. Handling of endings, uppercase and lowercase letters
  2203.  
  2204. .ID P_linkingdiff
  2205. .sfE
  2206. µ:Handling of endings:
  2207. .sf
  2208.  
  2209. What to do when the source link word is "computerαsα" 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 (endings of words, project settings page "Link"). Note when using other languages you have to edit the "endings of words". 
  2210.  
  2211. Marking a word with an ending is not recommended, because when the word occurs without the ending, the link won't be created.
  2212.  
  2213. 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).
  2214.  
  2215. .sfE
  2216. Uppercase and lowercase letters
  2217. .sf
  2218.  
  2219. 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:
  2220.  
  2221. .sfB
  2222.  .IN Word
  2223. .sf
  2224.  
  2225. Links are created to ~Word~, ~word~, but not to ~WORD~.
  2226.  
  2227. (new in Hypermake 3.65) With the dot command
  2228.  
  2229. .sfB
  2230.  .IU
  2231. .sf
  2232.  
  2233. (µ:ignore uppercase;) at the beginning of the source text will  ignore uppercase and lowercase letters.
  2234.  
  2235. .3
  2236. Marking a word several times
  2237.  
  2238. 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.
  2239.  
  2240. .3
  2241. Omitting links
  2242.  
  2243. .in omitting links
  2244. 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.
  2245.  
  2246. 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 (project settings page "Link", "paragraph" or "window"). With this setting, you can also turn of the omitting functionality ("always").
  2247.  
  2248. .afB
  2249. 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 (Font Dialog on project settings page "Font").
  2250.  
  2251. 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.
  2252.  
  2253. .IF IPFDOC or WINHELPDOC
  2254. .3
  2255. External links (IPF/Winhelp4)
  2256.  
  2257. .ID P_extlinkwin
  2258. µ:External links: are links to chapters of other INF or HLP files or links to the WWW. You can only create links to other help files if you write the remote help file by yourself or you know the ID names of the pages you want to link to.
  2259. .END
  2260.  
  2261. .IF WINHELPDOC
  2262. External links are not supported by Winhelp3.
  2263. .END
  2264.  
  2265. .IF IPFDOC and WINHELPDOC
  2266. For creating Winhelp, Panel ID files are not used. When compiling IPF, Hypermake gets the information about the link target from the Panel ID file of the remote helpfile. The other steps are identical for both formats.
  2267. .END
  2268.  
  2269. .IF IPFDOC or WINHELPDOC
  2270. To create such external links, you have to edit
  2271. .END
  2272. .IF IPFDOC
  2273. ■ the ini file or project settings, page help (IPF only)
  2274. .END
  2275. .IF IPFDOC or WINHELPDOC
  2276. ■ the file which is shown when using the link (link target file)
  2277. ■ the file from where the link is executed (link start file).
  2278. .END
  2279.  
  2280. .IF IPFDOC
  2281. External links for IPF are using the Hypermake function panel ID. But you need not read the panel ID chapter.
  2282.  
  2283. .sfE
  2284. Ini file
  2285. .sf
  2286.  
  2287. After "Panel ID filename =" in the ini file (project settings page "Helpfile"), you have to enter a file extension beginning with *. like
  2288.  
  2289. .sfB
  2290. Panel ID filename = *.PAN
  2291. .sf
  2292.  
  2293. 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.
  2294.  
  2295. .END
  2296. .IF IPFDOC or WINHELPDOC
  2297. .sfE
  2298. Link target file
  2299. .sf
  2300.  
  2301. 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
  2302.  
  2303. .sfB
  2304.  .ID Chapter_beginning
  2305. .sf
  2306.  
  2307. in the link target file, the chapter gets this ID name, e.g. "Chapter_beginning", where the dot command is placed, see file SAMPLE.
  2308.  
  2309. .END
  2310. .IF IPFDOC
  2311. When creating IPF, 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 for IPF when compiling the link start file.
  2312. .END
  2313. .IF IPFDOC or WINHELPDOC
  2314.  
  2315. .sfE
  2316. Link start file
  2317. .sf
  2318.  
  2319. 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.
  2320.  
  2321. .sfB
  2322.  .EX filename.hlp
  2323.  .ID Chapter_beginning
  2324.  .IN expression
  2325.  .EX
  2326. .sf
  2327.  
  2328. 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.
  2329.  
  2330. All expressions "expression" in the link start file are getting an external link to the chapter of the file filename.inf or filename.hlp, marked with the ID dot command ".ID P_Chapter_beginning".
  2331.  
  2332. It does not matter where the .EX - .EX block is placed in the link start file.
  2333.  
  2334. Pascal programmers have to pay attention: the constant following the ID dot command is case sensitive!
  2335.  
  2336. .END
  2337. .IF IPFDOC
  2338. 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.
  2339.  
  2340. When entering a filename
  2341.  
  2342. .sfB
  2343.  .EX filename.hlp
  2344. .sf
  2345.  
  2346. 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.
  2347.  
  2348. .END
  2349. .IF IPFDOC or WINHELPDOC
  2350. Try the sample external links or click to the expressions chancellor, SPD and CDU (only if this document is a Win95 or OS/2 help file). While writing this hypertext (that's the link start file) I have entered somewhere the following commands:
  2351.  
  2352. .sfB
  2353.  .EX sample.hlp
  2354.  .ID chapter_chancellor
  2355.  .IN chancellor
  2356.  .ID chapter_political_parties
  2357.  .IN SPD
  2358.  .IN CDU
  2359.  .EX
  2360. .sf
  2361.  
  2362. .END
  2363. .IF IPF
  2364. .EX sample.inf
  2365. .ELSE
  2366. .EX sample.hlp
  2367. .END
  2368. .IF IPFDOC or WINHELPDOC
  2369. .ID chapter_chancellor
  2370. .IN chancellor
  2371. .ID chapter_political_parties
  2372. .IN SPD
  2373. .IN CDU
  2374. .END
  2375. .IF OS2
  2376. .EX E.EXE SAMPLE.TXT
  2377. .ELSE
  2378. .EX NOTEPAD.EXE SAMPLE.TXT
  2379. .END
  2380. .IF IPFDOC or WINHELPDOC
  2381. .IN file SAMPLE
  2382. .END
  2383. .EX
  2384. .IF IPFDOC or WINHELPDOC
  2385.  
  2386. 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.
  2387. .END IPFDOC or WINHELPDOC
  2388.  
  2389. .3
  2390. External links to the WWW
  2391.  
  2392. .ID P_extlinkwww
  2393. This functionality is supported by all formats, but not by Winhelp3. From help files, the browser is started automatically.
  2394.  
  2395. .IF IPFDOC
  2396. To use the functionality in OS/2 help files, the user needs to have a browser NETSCAPE.EXE in a directory listed in the PATH statement of the CONFIG.SYS file.
  2397. .END
  2398. .IF WINHELPDOC
  2399. When using Win95/NT and a Winhelp file, the browser with the HTML file default association is started.
  2400.  
  2401. External mailto: links (starting the browser E-Mail program) are neither supported in Winhelp3 nor in Winhelp4.
  2402. .END
  2403.  
  2404. µ:Manual external links;
  2405.  
  2406. If Hypermake locates an expression beginning with a transfer protocol name and a colon like ftp://ftp.leo.org, the link is activated automatically. The end of such a URL address is SPACE or RETURN or , or ) or ;. This feature is always active, but you can turn it off by using a font with ~OmitLinks~ setting.
  2407.  
  2408. .in protocol names
  2409. µ:Transfer protocol names: are:
  2410. .sfO
  2411. http://
  2412. ftp://
  2413. gopher://
  2414. wais://
  2415. news://
  2416. file://
  2417. javascript:
  2418. mailto:
  2419. .sf
  2420.  
  2421. µ:Automatic external links;
  2422.  
  2423. 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: 
  2424.  
  2425. .sfB
  2426.  .URL http://home.netscape.com
  2427.  .IN Netscape
  2428.  .IN Netscape-Browser
  2429.  .LOCAL
  2430. .sf
  2431.  
  2432. .URL http://home.netscape.com
  2433. .IN Netscape
  2434. .IN Netscape-Browser
  2435. .LOCAL
  2436.  
  2437. 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.
  2438.  
  2439. µ:Marking external links;
  2440.  
  2441. You can set a graphics file in the ini file, setting ~URL graphics file~ (project settings page "Link") which is placed in front of every external link. So the user can distinguish between links where he need not to be online and external links where he needs to be online (which are starting a browser from the help file). Please turn off this functionality with ~URL graphics file = NO~ if you want to publish HTML files in the WWW, because external links are here absolutely normal.
  2442.  
  2443. The BMP and GIF files WORLD and WORLD2 In the Hypermake Library of buttons (directory BUTTONS) serves this purpose. 
  2444.  
  2445. .IF IPFDOC OR WINHELPDOC
  2446. .3
  2447. Launching programs by links
  2448.  
  2449. .it Launching program
  2450. .in launch program
  2451. Similar to external links, you can create links from Help files to external programs, that means launching programs.
  2452.  
  2453. This functionality is supported by Winhelp3, Winhelp4 and IPF and does not work with HTML.
  2454.  
  2455. .sfB
  2456.  .EX NOTEPAD.EXE SAMPLE.TXT
  2457.  .IN file SAMPLE for Windows
  2458.  .EX E.EXE SAMPLE.TXT
  2459.  .IN file SAMPLE for OS/2
  2460.  .EX
  2461. .sf
  2462.  
  2463. .EX NOTEPAD.EXE SAMPLE.TXT
  2464. .IN file SAMPLE for Windows
  2465. .EX E.EXE SAMPLE.TXT
  2466. .IN file SAMPLE for OS/2
  2467. .EX
  2468.  
  2469. If the user clicks to file SAMPLE for Windows or file SAMPLE for OS/2, 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~.
  2470.  
  2471. You can enter several IN dot commands after one EX command, for example to get links with the expression "parrot" and "bird movie".
  2472.  
  2473. Winhelp3 has got problems when locating the data file, in this sample SAMPLE.TXT, because it does not remember the current path of the help file, Winhelp4 and IPF does not have these problems. Use environment variables in this case or avoid launching programs with a data file.
  2474.  
  2475. 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.
  2476.  
  2477. If the files are not located in the same directory at different computers, you should use environment variables.
  2478.  
  2479. .4
  2480. Environment variables
  2481.  
  2482. .in environment variable
  2483. When creating external links and when launching programs, environment variables can be useful and necessary.
  2484.  
  2485. If you want to use a help 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 (OS/2) AUTOEXEC.BAT (DOS, Win95) or the Registry (NT) should have for example the following entry:
  2486.  
  2487. .sfB
  2488. SET MMVIDEO=C:\MMOS2\MOVIES
  2489. .sf
  2490.  
  2491. In the Hypermake source file, you can use this variable:
  2492.  
  2493. .sfB
  2494.  .EX mppm.exe %MMVIDEO%\macaw.avi
  2495.  .IN parrot
  2496.  .EX
  2497. .sf
  2498.  
  2499. The operating system replaces the expression %MMVIDEO% with the drive and directory name listed in the SET statement.
  2500.  
  2501. In the same way you can create external links.
  2502.  
  2503. But take care of the directory names ending with semicolon:
  2504.  
  2505. .sfB
  2506. SET MMBASE=C:\MMOS2;
  2507. .sf
  2508.  
  2509. In this case the environment variable does not work (at least with OS/2) and the link won't be created.
  2510. .END IPFDOC and WINHELPDOC
  2511.  
  2512. .2
  2513. duplication of heading text
  2514.  
  2515. .ID P_duplication
  2516. .in duplication of heading text
  2517. The appearance and placement of the headings depends on the target format: IBM Help places the heading into the titlebar, HTML places the heading into the text area. By default, Winhelp doesn't show any heading - in any case Hypermake needs to act here.
  2518.  
  2519. 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:
  2520.  
  2521. .sfB
  2522.  .3
  2523.  heading text
  2524.  
  2525.  .IN heading text
  2526.  .sfX
  2527.  heading text
  2528.  .sf
  2529. .sf
  2530.  
  2531. You can shorten this tedious job: Using the new dot command DuPlicate
  2532.  
  2533. .sfB
  2534.  .dpX
  2535. .sf
  2536.  
  2537. duplicates the heading text at the beginning of the text window, in all heading levels.
  2538. .IF IPFDOC
  2539. That's useful if you write long heading text, because in the titlebar of OS/2 INF files only the first 70 characters are shown on average.
  2540. .END
  2541. .IF WINHELPDOC
  2542. When compiling Winhelp, heading duplication is always activated. Otherwise the heading text would only appear in the search result list. With ~heading fonts~ in the ini file (project settings page "Winhelp") you can choose the font chars of the heading text. Of course these font chars have to be defined in the ini file. In addition, you can choose whether scrolling of the page also let the heading scroll or not. You can turn this setting off and on with ~keep heading~.
  2543. .END
  2544.  
  2545. You can omit specific characters in the index and when duplicating heading text with the ini file setting ~index filter~.
  2546.  
  2547. .sfB
  2548.  .dpX34
  2549. .sf
  2550.  
  2551. duplicates heading text only in heading level 3 and 4.
  2552.  
  2553. .sfB
  2554.  .dp-
  2555. .sf
  2556.  
  2557. turns off the duplication of heading text for all heading levels.
  2558.  
  2559. .sfB
  2560.  .dp-234
  2561. .sf
  2562.  
  2563. deactivates the duplication functionality only in the heading levels 2, 3 and 4.
  2564.  
  2565. .sfB
  2566.  .dp#
  2567. .sf
  2568.  
  2569. 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 (project settings page "spec. chars").
  2570.  
  2571. .sfB
  2572.  .dp##
  2573. .sf
  2574.  
  2575. 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.
  2576. .IF IPFDOC
  2577. And a big index can dramatically slow down a (very big) OS/2 HLP or INF file!
  2578. .END
  2579.  
  2580. .sfB
  2581.  .dp3##,
  2582.  .3
  2583.  Smith, John
  2584. .sf
  2585.  
  2586. 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.
  2587.  
  2588. You can combine any of these commands, the order makes no difference.
  2589.  
  2590. .3
  2591. Sample input
  2592.  
  2593. .sfC
  2594.  .WA verti 40
  2595.  .dp4E#,
  2596.  .3
  2597. Sample output
  2598.  
  2599. German federal chancellors since 1949
  2600.  
  2601. (CDU, SPD and chancellor are external links. Font E is defined in the ini file.) 
  2602.  
  2603.  .4
  2604. Adenauer, Konrad
  2605.  
  2606. 1949-1963, CDU, first chancellor after the second world war. His successor was Ludwig Erhard.
  2607.  
  2608.  .4
  2609. Erhard, Ludwig
  2610.  
  2611. 1963-1966, CDU, Successor of Konrad Adenauer. Second chancellor of the Federal Republic of Germany. He was predecessor of Kurt Georg Kiesinger.
  2612.  
  2613.  .4
  2614. Kiesinger, Kurt Georg
  2615.  
  2616. 1966-1969, third chancellor of CDU, leader of the "big coalition" of the parties CDU and SPD. Successor of Ludwig Erhard.
  2617.  
  2618.  .4
  2619. Brandt, Willy
  2620.  
  2621. 1969-1974, first chancellor of the SPD.
  2622.  
  2623.  .4
  2624. Schmidt, Helmut
  2625.  
  2626. 1974-1982, chancellor of the SPD. Successor of Willy Brandt.
  2627.  
  2628.  .4
  2629. Kohl, Helmut
  2630.  
  2631. chancellor of the CDU from 1982 till 1998. His predecessor was Helmut Schmidt.
  2632.  
  2633.  .4
  2634. Schroeder, Gerhard
  2635.  
  2636. current chancellor of the SPD. His predecessor was Helmut Kohl.
  2637.  
  2638.  
  2639. .sf
  2640.  
  2641. .WA verti 40
  2642. .3
  2643. Sample output
  2644.  
  2645. .in sample duplication heading text
  2646. .in sample external links
  2647. .dp4E#,
  2648. german federal chancellors since 1949
  2649.  
  2650. (CDU, SPD and chancellor are external links. Font R is defined in the ini file.) 
  2651.  
  2652. .4
  2653. Adenauer, Konrad
  2654.  
  2655. 1949-1963, CDU, first chancellor after the second world war. His successor was Ludwig Erhard.
  2656.  
  2657. .4
  2658. Erhard, Ludwig
  2659.  
  2660. 1963-1966, CDU, Successor of Konrad Adenauer. Second chancellor of the Federal Republic of Germany. He was predecessor of Kurt Georg Kiesinger.
  2661.  
  2662. .4
  2663. Kiesinger, Kurt Georg
  2664.  
  2665. 1966-1969, third chancellor of CDU, leader of the "big coalition" of the parties CDU and SPD. Successor of Ludwig Erhard.
  2666.  
  2667. .4
  2668. Brandt, Willy
  2669.  
  2670. 1969-1974, first chancellor of the SPD.
  2671.  
  2672. .4
  2673. Schmidt, Helmut
  2674.  
  2675. 1974-1982, chancellor of the SPD. Successor of Willy Brandt.
  2676.  
  2677. .4
  2678. Kohl, Helmut
  2679.  
  2680. chancellor of the CDU from 1982 till 1998. His predecessor was Helmut Schmidt.
  2681.  
  2682. .4
  2683. Schroeder, Gerhard
  2684.  
  2685. current chancellor of the SPD. His predecessor was Helmut Kohl.
  2686.  
  2687.  
  2688. .2
  2689. Tables
  2690.  
  2691. .ID P_table
  2692. .in Table
  2693. Hypermake 3.0 supports easy creation of tables. You enter tables like you do it in an ASCII text with a fixed font:
  2694.  
  2695. .sfB
  2696.  .TA Sample
  2697.  first cell   numbers    -----third and fourth-----
  2698.  first cell      97.96   third cell    fourth cell+
  2699.  first cell   1.324.90   third cell    2nd line
  2700.  first cell       0.00   third cell    hyphen-
  2701.  first cell    -123.45   "             append
  2702.  .TA
  2703. .sf
  2704.  
  2705. .TA Sample
  2706. first cell    numbers   -----third and fourth-----
  2707. first cell      97.96   third cell    fourth cell+
  2708. first cell   1.324.90   third cell    2nd line
  2709. first cell       0.00   third cell    hyphen-
  2710. first cell    -123.45   "             append
  2711. .TA
  2712.  
  2713. .IF IPFDOC
  2714. 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.
  2715. .END
  2716.  
  2717. .IF WINHELPDOC
  2718. The RTF table functionality does not draw lines, so the " char does not make sense. The + char is supported, but the result is not very good.
  2719. .END
  2720.  
  2721. .afB
  2722. 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.
  2723.  
  2724. .IF WINHELPDOC OR IPFDOC
  2725. Winhelp und IPF don't support table titles. If you want to create this formats, write the title outside the table and then begin the table with ~.TA NO~.
  2726. .END
  2727.  
  2728. You principally edit the table like in an ASCII text with fixed font. Please note:
  2729.  
  2730. ■ 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.
  2731. ■ If you want to extend one cell to the bottom, type a quotation mark " to the line above the cell.
  2732. ■ 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.
  2733. ■ 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.
  2734.  
  2735. If you can't use the + char, you can change this setting with the dot command
  2736.  
  2737. ~.tc X~
  2738.  
  2739. (table character) will change the default + char setting to a character X of your choice.
  2740.  
  2741. .IF HTMLDOC
  2742. With the dot command
  2743.  
  2744. ~.TT~
  2745.  
  2746. Table Tags you can change the HTML table tags. the default setting is
  2747.  
  2748. ~.TT BORDER CELLPADDING=5~
  2749.  
  2750.  
  2751. ~.TT BORDER CELLPADDING=5 BGCOLOR="#D0D0D0"~
  2752.  
  2753. uses gray background for the tables. This choice can be necessary if you use a background graphic (see ini file or project settings page "html-1", setting body tags) with lines. In this case the combination of table lines and background graphic lines would reduce the visibility of the cells.
  2754.  
  2755. Since Hypermake 3.6, there are some useful additional settings especially for HTML tables.
  2756.  
  2757. By default, HTML cells containing more digits than letters will be right-justified, and in the reverse case left-justified. Cells which spread over two or more cells will get centered text. You can override this default mechanism with the ~.TP~ table position command:
  2758.  
  2759. .sfB
  2760.  .TA This is a Table
  2761.  .TP left
  2762. .sf
  2763.  
  2764. Behind ~.TP~ you can enter ~left~, ~right~ or ~center~.
  2765.  
  2766. Then you can add a second new command ~.TE~ table empty.
  2767.  
  2768. .TA Sample with ".TE" command
  2769. .TE
  2770. first cell    numbers   -----third and fourth-----
  2771. first cell      97.96   third cell    fourth cell+
  2772. first cell   1.324.90   third cell    2nd line
  2773. first cell       0.00   third cell    hyphen-
  2774. first cell    -123.45   "             append
  2775. .TA
  2776.  
  2777. Please compare the last column with the sample above. When ~.TE~ is activated, every cell in a row gets the same height; instead you get empty cells. Use this command if you have cells which rests empty.
  2778.  
  2779. The difference is difficult to eplain, you see. Simply use the ~.TE~ command if Hypermake destroys your table otherwise.
  2780.  
  2781. The ~.TP~ and ~.TE~ setting is valid for the actual Table. The next table gets again the default values.
  2782.  
  2783. Hint: If you have something like
  2784.  
  2785. .sfB
  2786. maximal average speed+
  2787. in kilometers per hour         180        240
  2788. .sf
  2789.  
  2790. then you should better write the numbers one line higher to the line where the cell with the two lines begins. In the other case, you will get two different rows.
  2791. .END
  2792.  
  2793. .IF HTMLDOC
  2794. (new in Hypermake 3.65) With the new dot command ~.TW~ µ:Table word wrap:, the table fits the whole window width and RETURN in a cell is changed to SPACE, so you get a new formatting in a cell. Like ~.TE~, also ~.TW~ has to be placed after ~.TA~ in every table.
  2795. .END
  2796.  
  2797. .2
  2798. Line drawing
  2799.  
  2800. .ID P_linedrawing
  2801. Line drawing is best supported by IPF and does not look very good with HTML or Winhelp because of the lack of line drawing characters in the Ansi codepage.
  2802.  
  2803. As creating boxes is usually a tedious job, a dot command has been defined to facilitate line drawing. The following example illustrates its use.
  2804.  
  2805. .in Line drawing
  2806. .it line drawing character
  2807. .sfB
  2808.  .LIXY
  2809.  
  2810.       X                           X
  2811.  
  2812.             Operating systems
  2813.  
  2814.       Y                ZY                X            X
  2815.             Novell         IBM              Hardware
  2816.       Y       Y                          X            X
  2817.           DOS   Netware    OS/2
  2818.       X                           X
  2819.  .LI
  2820. .sf
  2821.  
  2822. The result will be:
  2823.  
  2824. .sfB
  2825. .LIXY
  2826.  
  2827.       X                           X
  2828.  
  2829.             Operating systems
  2830.  
  2831.       Y                 Y                X            X
  2832.              Novell        IBM              Hardware
  2833.       Y       Y                          X            X
  2834.          DOS    Netware    OS/2
  2835.       X                           X
  2836. .LI
  2837. .sf
  2838.  
  2839. .afB
  2840. 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).
  2841.  
  2842. You can change the standard font for line drawing in the ini file (Font Dialog on project settings page "Font"), font setting LineStandard.
  2843.  
  2844. .IF IPFDOC
  2845. With IPF, 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.
  2846. .END
  2847.  
  2848. .IF WORDSTARDOC
  2849. .3
  2850. Line drawing and WordStar
  2851.  
  2852. 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.
  2853. .END
  2854.  
  2855. .2
  2856. Footnotes
  2857.  
  2858. .ID P_footnote
  2859. The help formats IPF and Winhelp supports footnote popup windows. With HTML, Hypermake generates frames to show footnotes.
  2860.  
  2861. .in Popups
  2862. .in Footnote
  2863. .it footnote character
  2864. 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
  2865.  
  2866. ~.FU{}~
  2867.  
  2868. Instead of the brackets and the footnote text, a star character or a graphics file[This will be the content of the footnote] appears on which you can click with the mouse.
  2869.  
  2870. .fu
  2871. Other useful footnote bracket chars are [ ], < > or ■ (Alt-220) ■ (Alt-223) (only IBM codepage).
  2872. .fu[]
  2873.  
  2874. .IF HTMLDOC
  2875. For HTML, you can add a font character to the footnote dot command:
  2876.  
  2877. ~.FU{}sfX~
  2878.  
  2879. This will select font X in the HTML footnote window.
  2880.  
  2881. With the dot command footnote size
  2882.  
  2883. ~.FS 30~
  2884.  
  2885. 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.
  2886. .END
  2887.  
  2888. You can temporary deactivate the footnote function by using the footnote command without parameters:
  2889.  
  2890. ~.FU~
  2891.  
  2892. or you can define other footnote chars. The default setting is no footnote chars.
  2893.  
  2894. If you don't want to get "***" as a link to the footnote window, you can change the text "***" with the dot command footnote text
  2895.  
  2896. ~.FT XXX~
  2897.  
  2898. Instead of "***", the text "XXX" will appear. You are allowed to use a bitmap instead of a character or a text:
  2899.  
  2900. .sfB
  2901.  .BT& filename
  2902.  .FT&
  2903. .sf
  2904.  
  2905. (see bitmap text.)
  2906.  
  2907. .IF HTMLDOC
  2908. When creating HTML, you can choose the appearance of the footnotes. In the ini file, setting ~footnotes~ (project settings page "html-2") you can choose between ~frames~, ~noframes~ and ~activex~. The activex setting forces popup footnotes and is useful together with HTML-Help. For the activex setting, the user needs a Microsoft browser, so don't use this setting to publish in the Web!
  2909.  
  2910. If you don't want to create HTML Frames for the footnote and text window, you can also use the program parameter ~/NOFRAMES~. This will generate one footnote file with all footnotes which will be numbered.
  2911. .END
  2912.  
  2913. .WA hori 30
  2914. .2
  2915. Margins and Formatting
  2916.  
  2917. .in Margin
  2918. .ID P_margin
  2919. .3
  2920. Changing the left margin
  2921.  
  2922. This is a sample text with left margin 1.
  2923.  
  2924. .LM10
  2925. This is a sample of left margin 10; note that the formatting will be correct.
  2926.  
  2927. .LM20
  2928. This is a sample of left margin 20; note that the formatting will be correct.
  2929.  
  2930. .LM1
  2931. You can change the left margin by using the dot command left margin
  2932.  
  2933. .sfB
  2934.  .LM n
  2935. .sf
  2936.  
  2937. n is a number from 1 to approx. 30. Default setting is 1.
  2938.  
  2939. If you enter the left margin dot command without a number, the standard 1 will be active.
  2940.  
  2941. .IF HTMLDOC
  2942. 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.
  2943. .END
  2944.  
  2945. .IF WINHELPDOC
  2946. The Winhelp specific ini file setting ~List indention~ (project settings page "Winhelp") influences the size of the left margin (dot command .LM) and the indention of Lists.
  2947. .END
  2948.  
  2949. .IF WORDSTARDOC
  2950. 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.]
  2951. .END
  2952.  
  2953. .3
  2954. Turning Formatting off and on
  2955.  
  2956. .IF IPFDOC
  2957. .in Formatting
  2958. (Only IPF) With the dot commands Formatting off and Formatting on
  2959.  
  2960. .sfB
  2961.  .FM off
  2962. .sf
  2963. .sfB
  2964.  .FM on
  2965. .sf
  2966.  
  2967. you can turn formatting (word wrap) 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.
  2968.  
  2969. Between line drawing dot commands, formatting is automatically turned off.
  2970.  
  2971. 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:
  2972.  
  2973. .sfB
  2974.  .fm on
  2975.  .in word1
  2976.  .in word2
  2977.  .fm off
  2978. .sf
  2979. .END IPFDOC
  2980.  
  2981. .IF HTMLDOC
  2982. 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.
  2983. .END
  2984.  
  2985. .IF IPFDOC
  2986. For IPF, you can define a font with ~PRE~ in the ini file (Font Dialog on project settings page "Font"), so you do not need separate dot commands.
  2987. .END
  2988.  
  2989. .3
  2990. Centered Text
  2991.  
  2992. .in centered text
  2993. 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
  2994.  
  2995. .sfB
  2996.  .OC on
  2997.  .OC off
  2998. .sf
  2999.  
  3000. But you can also define a font with ~center~ in the ini file (Font Dialog), so you do not need separate dot commands.
  3001.  
  3002. .3
  3003. Auto Margin
  3004.  
  3005. To write µ:definition list;s for example, you can simply change the left margin by using spaces:
  3006.  
  3007. .sfB
  3008. *motherboard*
  3009.       The motherboard contents the main processor, the RAM
  3010.       memory and some other important parts of your computer.
  3011.  
  3012. *screen*
  3013.       Computer screens are available from 14 up to 21
  3014.       inches; You shouldn't save money with a cheap small
  3015.       screen.
  3016. .sf
  3017.  
  3018. motherboard
  3019.       The motherboard contents the main processor, the RAM memory and some other important parts of your computer.
  3020.  
  3021. screen
  3022.       Computer screens are available from 14 up to 21 inches; You shouldn't save money with a cheap small screen.
  3023.  
  3024. With the new dot command µ:Auto Margin: you can turn off/on the interpretation of the spaces at the beginning of a line.
  3025.  
  3026. .sfB
  3027.  .AM off
  3028.  .AM on
  3029. .sf
  3030.  
  3031. Default is on.
  3032.  
  3033. 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.
  3034.  
  3035. 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.
  3036.  
  3037. .IF WORDSTARDOC
  3038. WordStar files don't need the auto margin function. [You can always use an auto margin function by using the ^OG command (soft spaces).]
  3039. .END
  3040.  
  3041. .2
  3042. if-conditions
  3043.  
  3044. .in if-condition
  3045. .ID P_ifcondition
  3046. With if-conditions, you can create slightly different RTF, IPF or HTML files from the same source text. In the Hypermake docu source, you will find a lot of if-conditions. It's easier to write only one documentation file for several platforms or purposes instead of several files.
  3047.  
  3048.  
  3049. There are three dot commands
  3050.  
  3051.  
  3052. .sfB
  3053.  .IF CONDITION
  3054.  .ELSE
  3055.  .END
  3056. .sf
  3057.  
  3058. The conditions are not case-sensitive. It's not necessary to use the ELSE command, of course.
  3059.  
  3060. This means text between these commands is only compiled if the condition is set.
  3061.  
  3062. Hypermake also supports the following expressions:
  3063.  
  3064. .sfB
  3065.  .IF NOT COND
  3066.  .IF COND1 AND COND2
  3067.  .IF COND1 OR COND2
  3068. .sf
  3069.  
  3070. Sorry, but more sophisticated if-conditions with parenthesis are not supported.
  3071.  
  3072. The conditions are set in the HMP file, line ~conditions~.
  3073.  
  3074. For compiling the source text from the commandline, you have to enter:
  3075.  
  3076. .sfP
  3077. .fu
  3078. [C:\myProject] HMAKE myDoc.txt #CONDITION
  3079. .fu[]
  3080. .sf
  3081.  
  3082. You can enter more than one condition in the commandline. Note the # character, the parameters can be in any order.
  3083.  
  3084. Dependent on the target format, Hypermake sets the conditions HTML IPF WINHELP WINHELP3 WINHELP4 HTML HTMLHELP automatically. WINHELP is set when compiling WINHELP3 or WINHELP4. HTML is also set when compiling HTMLHELP.
  3085.  
  3086. The three different Hypermake versions for OS/2, Win95/NT and DOS set the conditions OS2, WIN95 und DOS.
  3087.  
  3088. .IF HTMLDOC
  3089. .1
  3090. HTML-specific functionality
  3091.  
  3092. .ID P_htmlgeneral
  3093. 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 settings notebook (pages HTML-0, HTML-1, HTML-2) respectively ini file and program parameters (settings notebook page Main).
  3094.  
  3095. .in HTML info file
  3096. When creating HTML or HTMLHELP, Hypermake always creates a useful HTML info file with statistic data about your project (length of the text, number of links, error messages...). The filename is the same as the project name and is placed in the same directory where the source file is located and not in the target directory. You can use this document to start with the browser into your project.
  3097.  
  3098. If you want to publish Hypermake documents in the WWW, please read this chapter, escpecially the sub chapter about HTML filenames!
  3099.  
  3100. .2
  3101. Navigation Buttons
  3102.  
  3103. You will find a Library of Buttons in the directory BUTTONS.
  3104.  
  3105. .in Buttons
  3106. .in Navigation Buttons
  3107. 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 settings notebook, page HTML1, respectively ini file: 
  3108.  
  3109. .sfB
  3110. function for first line = BACK FORWARD CONTENT INDEX HOMEF MAX
  3111. text for first line =     previous next content index home max
  3112. .sf
  3113.  
  3114. The four keywords BACK FORWARD CONTENT INDEX have the following meanings:
  3115.  
  3116. ■ BACK goes to the previous page in the order of the source text
  3117. ■ FORWARD goes to the next page
  3118. ■ CONTENT goes to the contents
  3119. ■ INDEX goes to the index
  3120. ■ HOMEF and MAX is used by the Hypermake 4.0 design (see settings notebook page HTML-0)
  3121.  
  3122. Corresponding to the keywords BACK, FORWARD, the filenames of the gif files are BACK.GIF, FORWARD.GIF and so on.
  3123.  
  3124. The CONTENT and INDEX buttons do not appear when compiling HTML-Help because this functionality is supported anyway by the HTML-Help viewer.
  3125.  
  3126. HOMEF and MAX: The Hypermake 4.0 design shows normal text always in frames: in the left frame, the contents tree is shown, and in the right frame the text appears. But if the user activates a text page directly, the text fits the whole browser window. (Only activating the home frame file INDXF.HTML will show the frames view.) With the HOMEF button (Homeframe), the homeframe page will be loaded and the text is shown in frame view. The opposite is the MAX (maximize) button: it will maximize the text window, so the text window will fit the whole browser window. This function is comparable to the "maximize" button of every window of the graphical computer desktop. MAX is not used in the default setting of the predefined Hypermake 4.0 design.
  3127.  
  3128. 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 = TEXT~ ("button type" on project settings page "html-1"). Then you get the text as a link instead of the navigation buttons.
  3129.  
  3130. The setting ~buttons = JAVASCRIPT~ creates buttons based on the Javascript programming language. The program generating the µ:Javascript buttons: is part of the HTML file and much more smaller and faster than separate GIF files. But Javascript is not supported by very old browsers (before Netscape 2) and dependent on the length of the text expression the width of the buttons can be different. But you can omit extremly different length by using the " in pairs and space characters between the two " characters:
  3131.  
  3132. .snB
  3133. previous " next " " home " "  max  " content index 
  3134. .sn
  3135.  
  3136. 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. It can be useful to leave out some functionality in the "last line", e.g. the BACK button.
  3137.  
  3138.  
  3139. User-defined Navigation Buttons
  3140.  
  3141. .it user button
  3142. 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.
  3143.  
  3144. In the ini file: (project settings page "html-1")
  3145.  
  3146. .sfB
  3147. function for first line = BACK FORWARD CONTENT INDEX LABEL_A LABEL_B ...
  3148. text for first line =     previous next content index chapterA chapterB ...
  3149. .sf
  3150.  
  3151. and in the source text in the chapters of your choice:
  3152.  
  3153. .sfB
  3154.  .ID LABEL_A
  3155.  .ID LABEL_B
  3156. .sf
  3157.  
  3158. 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.
  3159.  
  3160. 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~.
  3161.  
  3162. In the Library of Buttons you will find some user buttons.
  3163.  
  3164. Navigation Buttons pointing to URL's
  3165.  
  3166. You can use the ~.ID~ dot command within an ~.URL~ external link.
  3167.  
  3168. .sfB
  3169.  .URL http://www.netscape.com
  3170.  .ID NETSCAPE
  3171.  .LOCAL
  3172. .sf
  3173.  
  3174. If you have added the keyword NETSCAPE in the ini file (project settings page "html-1"), line "function", the button NETSCAPE.GIF gets the link to Netscape in the WWW.
  3175.  
  3176. 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.
  3177.  
  3178. .wa hori 40
  3179. .2
  3180. HTML filenames
  3181.  
  3182. 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. If the page shows a frame, the frame file name is the default name e.g. N003.HTML. The file which is shown in the top or left window gets the filename N003F.HTML and the subchapter page on the bottom or the right gets the next number N004.HTML. If the job ob the frame is showing text with footnotes, the frame file name will be N003.HTML, the text gets the filename N003T.HTML an the footnotes gets N003N.HTML (N for "notes").
  3183.  
  3184.  
  3185. There are several ways of making Hypermake generate other filenames. 
  3186.  
  3187. .3
  3188. Using a fixed filename
  3189.  
  3190. .ID P_idname
  3191. .sfB
  3192.  .2
  3193.  About me
  3194.  
  3195.  .ID AUTHOR
  3196.  I'm 31 years old, have studied economics...
  3197. .sf
  3198.  
  3199. You can mark a particular chapter with an ID. It's the same command you need for user buttons.
  3200.  
  3201. 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.
  3202.  
  3203.  
  3204. .3
  3205. 8.3 filenames, long filenames, small and capital letters
  3206.  
  3207. .in filenames
  3208. 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!
  3209.  
  3210. To avoid this, Hypermake offers you several methods: A setting in the ini file (project settings page "html-2"), a commandline parameter and an automatic recognition of DOS drives.
  3211.  
  3212. .sfB
  3213. //possible settings: sample.html SAMPLE.HTML Sample.html sample.htm SAMPLE.HTM Sample.htm
  3214. filename appearance = sample.html
  3215. .sf
  3216.  
  3217. You can define the appearance of the filenames in the ini file (project settings page "html-2").
  3218.  
  3219. 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".
  3220.  
  3221. 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.
  3222.  
  3223. With the program parameter (project settings page "Main") ~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.
  3224.  
  3225. When publishing in the Web, I recommend that the Hypermake functionality copying graphic files is enabled. In this case Hypermake has got control of the correct notation of your GIF filenames (small/capital letters).
  3226.  
  3227. Hypermake generates a lot of warnings if in the ~filename appearance~ setting a 3 char extension was chosen and Hypermake locates filenames with more than 8 characters length. With the ini file setting ~filenames = long~ ("Warning if Filename not 8.3" on project settings page "html-2") you can omit these warnings.
  3228.  
  3229. .3
  3230. User-defined internal numbering of headings and files
  3231.  
  3232. .ID P_enumeration
  3233. (new in Hypermake 3.65) If you extend a HTML document which is already published in the WWW, you will get a problem with the µ:internal numbering; of headings and files. With two new dot commands, you can fix this problem.
  3234.  
  3235. Hypermake simply numbers the headings of the documents: #hd1, #hd2, #hd3, and also the files: N000.HTML, N001.HTML and so on. If you insert new headings in the middle of your document, all headings and files after the insertion will get a higher internal number. The consequence is the need of uploading all the files of your document to the server again. But now links from other documents in the WWW pointing to a page of your Hypermake document can be obsolete.
  3236.  
  3237. To avoid this, you can control the internal numbering of headings and files. With new commands, you can set the internal counter of headings and files to a higher value. So the insertion of new headings immediately above the new commands won't have an effect on the internal numbering after this command. You have to choose a value which is big enough to fit all future chapters. In the HTML info file, section "Enumeration", Hypermake lets you know if the chosen values are not big enough and the created numbering "space" is depleted.
  3238.  
  3239. With the dot command ~.NR~ you can set the internal file counter and with ~.HD~ the internal heading counter.
  3240.  
  3241. .sfB
  3242.  .NR 10
  3243.  .HD 100
  3244.  .1
  3245.  Heading with fixed internal number
  3246. .sf
  3247.  
  3248. If one file contains several chapters, the value of ~.HD~ has to be greater than the value of ~.NR~. (See ini file, setting new file level, project settings page "html-1"). Otherwise it is sufficient to use ~.NR~. 
  3249.  
  3250. .2
  3251. Title and Meta entries
  3252.  
  3253. .in Meta entries
  3254. .in Titlebar
  3255. .in file title
  3256. At the beginning of every HTML file, a title is defined which appears in the titlebar of the browser.
  3257.  
  3258. For this chapter for example, a meaningful title is:
  3259.  
  3260. Hypermake 4.0 - Title and Meta entries
  3261.  
  3262. You can define which text has to appear in the titlebar of every HTML file: (project settings page "html-2")
  3263.  
  3264. .sfB
  3265. //here you can define the text appearing in the browser titlebar
  3266. //enter DOCTITLE and/or HEADING and fixed text, e.g. a slash; NO means no text
  3267. file title = DOCTITLE - HEADING
  3268. .sf
  3269.  
  3270. 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.
  3271.  
  3272. .sfB
  3273. file title = Martin Vieregg: DOCTITLE, chapter HEADING
  3274. .sf
  3275.  
  3276. It's not possible to use the characters ' and ".
  3277.  
  3278. 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.
  3279.  
  3280. Information for search machines
  3281.  
  3282. Informations for search machines aren't visible when viewing the file with a browser. It's interpreted by Internet search machines like Hotbot or Yahoo.
  3283.  
  3284. Like defining a HTML file title, you also can define an automatic meta entry with "meta content":
  3285.  
  3286. .sfB
  3287. meta content = DOCTITLE - HEADING
  3288. .sf
  3289.  
  3290. Into the head of the HTML file, Hypermake will place:
  3291.  
  3292. .sfB
  3293. <META NAME="description" CONTENT="Hypermake 4.0 - Title and Meta entries">
  3294. .sf
  3295.  
  3296. Hypermake always writes all index expressions of the page which are marked in the Hypermake source file:
  3297.  
  3298. .sfB
  3299. <META NAME="keywords" CONTENT="expression1, expression2">
  3300. .sf
  3301.  
  3302. Embedding user-defined HEAD tags
  3303.  
  3304. You can write HEAD tags for all HTML files or for specific HTML files. By default, Hypermake only writes:
  3305.  
  3306. .sfB
  3307. <HEAD>
  3308. <META NAME="generator" CONTENT="Hypermake 4.00">
  3309. <META NAME ="Author" CONTENT="Martin Vieregg">
  3310. <title>Hypermake 4.0 - Title and Meta entries</title>
  3311. </HEAD>
  3312. .sf
  3313.  
  3314. 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~.
  3315.  
  3316. Embedding user-defined head tags or not depends on the existence of the individual *.HEAD files. There's no special setting.
  3317.  
  3318. If a "pre filename" is set, the filenames of the HEAD-files have to begin with the pre filename.
  3319.  
  3320. 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~.
  3321.  
  3322. .2
  3323. Statusbar Text
  3324.  
  3325. Two settings in the ini file (project settings page "html-2") let you modify the µ:statusbar text: appearing in the gray bottom text field of every HTML-browser.
  3326.  
  3327. .sfB
  3328. statusbar mouseover = to chapter: HEADING (file FILENAME)
  3329. statusbar default = DOCTITLE - visit the Homepage regulary!
  3330. .sf
  3331.  
  3332. If the mouse pointer is over a link, the text under ~statusbar mouseover~ will appear, otherwise the text defined in the ~statusbar default~ setting. Instead of HEADING, the heading of the chapter which is the target link will appear. FILENAME is the filename of the target link file.
  3333.  
  3334. Note that the ~statusbar mouseover~ functionality enlarges the size of the HTML files. Not only the "mouseover" text, also the "default" text will be part of every link command, because when the mouse leaves the link, the default setting has to appear again. When publishing in the WWW, you have to consider carefully the benefit of additional information in comparision to increasing download time.
  3335.  
  3336. The ~statusbar default~ setting increases the length of HTML files nearly not. Here, the FILENAME expression can be useful if you often use Frames because the user can see the filename of the child window - in the location field of the browser only the filename of the frame window is shown.
  3337.  
  3338. It's not possible to use the characters ' and ".
  3339.  
  3340. .2
  3341. Javascript Contents Tree
  3342.  
  3343. .in Javascript Contents Tree
  3344. .in Javascript
  3345. Since Hypermake 3.6 you can choose between the normal contents view (unordered list, subchapters always visible) and a contents tree generated by a Javascript program. The setting in the ini file is ~contents tree~ ("Javascript contents tree" on project settings page "html-1"), here you can also define the concrete explanation text for the Javascript Contents Tree. If the user has got a not Javascript 1.0 enabled browser, he can use a link to the normal unordered list contents view.
  3346.  
  3347. What is Javascript?
  3348.  
  3349. Javascript is a simple programming language you can embed directly into HTML text. Today, the majority of browsers interpretate Javascript. Netscape Navigator 2 can execute Javascript 1.0 programs, Navigator and MS Internet Explorer 3 Javascript 1.1 and Navigator and MS Internet Explorer 4 Javascript 1.2.
  3350.  
  3351. Which Browsers view the Hypermake Javascript Contents Tree?
  3352.  
  3353. The Javascript code Hypermake generates is written for all Browsers supporting Javascript. It's tested on Netscape Navigator 2.02, 3 and 4, Microsoft Internet Explorer 3 and 4.
  3354.  
  3355. Used graphics files
  3356.  
  3357. .in TREEMPTY.GIF
  3358. In the library of buttons \BUTTONS\ICON you will find three files TREECLOS.GIF, TREEOPEN.GIF and TREENO.GIF. If the user clicks to TREECLOS.GIF and TREEOPEN.GIF, the tree will open and close. TREENO.GIF has no link functionality and shows that there are no subchapters.
  3359. Since Hypermake 4.0, a fourth graphics file TREEMPTY.GIF is needed. This graphic has got the width of the other TREE*.GIF graphics, but is invisible and is used for indention.
  3360.  
  3361. The names of these three graphics files Hypermake needs are fixed. If you want to use other GIF files, rename them to the names above. Note that TREECLOS.GIF looks like e.g. a closed book and TREEOPEN.GIF like an open book, but the link functionality is reverse: TREECLOS.GIF opens the subchapter list, TREEOPEN.GIF closes it.
  3362.  
  3363. Special functionality with Netscape / Internet Explorer 4
  3364.  
  3365. Javascript 1.2 has got functions to query and set the position of the scrollbar. The Hypermake generated Javascript program uses this functionality to restore the scrollbar position after a tree was closed or opened. Browsers before Netscape / IE 4 does not remember the vertical scrolbar position. Thats uncomfortable when having long directory trees.
  3366.  
  3367. Filenames
  3368.  
  3369. The filename of the Javascript contents tree page is the same as choosing a normal contents view: INDEX.HTML. This is the file of the main window with the Javascript program code. The small upper window is INDXI.HTML (Index-Info), the alternate normal contents view is INDXA.HTML ("a" for alternate). Before the Javascript program gets active and draws the contents tree, the big lower window is EMPTY.HTML. So EMPTY.HTML has to be uploaded when publishing in the Web!
  3370.  
  3371. Two browser windows
  3372.  
  3373. It's possible that the contents window gets its own browser. You can do that when choosing different names for the ini settings ~default frame~ and ~contents frame~, e.g. "main" and "cont".
  3374.  
  3375. .2
  3376. File comparison
  3377.  
  3378.  
  3379. .END
  3380. .IF DOS AND HTMLDOC
  3381. File comparison is not available in the DOS version. It is used for getting a list of HTML files which have to be updated to the Internet if you have made changes on your project.
  3382.  
  3383. .END
  3384. .IF HTMLDOC
  3385. If you want to publish a big document in the WWW, you have to upload 100 HTML files or more. But if you update your document, only a few HTML files gets changed and have to be uploaded again. The µ:File comparison: (since Hypermake 3.99) can be used to get the information, which files have changed since the last upload.
  3386.  
  3387. How to use file comparison:
  3388.  
  3389. .SL
  3390. ■ Make a copy of the directory where Hypermake has written the HTML files (HTML directory). Choose a expedient name for the copy like projectname_date. You should create a copy after uploading or before changing a project.
  3391. ■ If you delete chapters, delete the current HTML directory.
  3392. ■ After you have made changes on your project and recompiled the project, start the file comparison. You will get a list of the changed files.
  3393. .UL
  3394.  
  3395. You can start file comparison in three different ways:
  3396.  
  3397. In the graphical version, open the current project you want to compare with the old state. Then select project - compare HTML dir and choose the filename of the old HTML directory or simply drop the old HTML directory icon to the success window with the blue font.
  3398.  
  3399. When using the commandline version, enter
  3400.  
  3401. .fu
  3402. .sfP
  3403. [C:\myProject] HMAKE /COMPARE olddir newdir
  3404. .sf
  3405. .fu[]
  3406.  
  3407. The file comparison mode compiles HTML files, but also other files like graphic files. In difference to default file comparison tools like "COMP" in the commandline, the Hypermake file comparison recognices that changes of the version number which are written at the beginning of every HTML file 
  3408.  
  3409.  
  3410. .sfB
  3411. <META NAME="generator" content="Hypermake 4.00">
  3412. .sf
  3413.  
  3414. do not really make a difference. So if only the version number has changed, the files won't get part of the update list.
  3415. .END
  3416.  
  3417. .1
  3418. copying graphic files
  3419.  
  3420. .in copying graphic files
  3421. Nearly every hypertext has got graphics. HTML pages often uses graphical buttons for navigation. Normally they are located all over the disk, but they have to be in the target directory so the HTML browser or the second compiler can find them.
  3422.  
  3423. You can place the setting
  3424.  
  3425. .sfB
  3426. graphic path = D:\HMAKE\Testgrafics;D:\HMAKE\Worldgrafics;D:\HMAKE\Buttons;
  3427. .sf
  3428.  
  3429. in the HMP file ("Graphic files" on project settings page "Main") or in the ini file.
  3430.  
  3431. Here you can enter a list of directories where your graphics files are located. Hypermake automatically copies the graphics files to the target directory, if the graphics files are not already here. If Hypermake does not find the graphics file, then you will get a warning. HTML graphics filenames automatically get the correct notation (small or capital letters, see ini file setting ~filename appearance~, project settings page "html-2").
  3432.  
  3433. This functionality saves you from error messages in the OS/2 or Windows help compiler.
  3434.  
  3435. If the user turns "auto load images" in the HTML browser off, then the name of the graphics file and the size of the file is shown. The size is only shown when using the .BM command, not when using the .BT command or the navigation buttons, because the graphics files used by the .BT command or navigations buttons have a very small size which is not interesting.
  3436.  
  3437. Since Hypermake 3.99, a graphics file are also copied if the needed graphics file already resides in the target directory and the date of the file in the "graphic path" is more current. So it is sufficient to update a graphics file in the "graphic path". 
  3438.  
  3439. .IF IPFDOC AND WINHELPDOC
  3440. Please remember that both Winhelp and OS/2 help compiler uses graphics files with the extension BMP, but theses formats are different! (In the BUTTONS directory, you will find a WINBMP and an OS2BMP directory, with the same graphics but different files.) So if you create both OS/2 and Windows Help files, you have to delete the ("wrong") BMP files in the target directory before creating the other format so Hypermake will copy again the right BMP files.
  3441. .END
  3442.  
  3443. .IF OS2EXEDOC OR WINEXEDOC
  3444. .1
  3445. Context-sensitive Program Help
  3446.  
  3447. .in panel ID
  3448. Most programs with a graphical user interface have got an online help included. If the user presses F1 or a "help" button, he gets automatically to a specific chapter of the hypertext. Hypermake offers some functionality to get this connection between EXE program and hypertext.
  3449.  
  3450. .it generating context-sensitive help
  3451. If you want to write separate hypertext files and no programs, you can skip this chapter.
  3452. .END
  3453.  
  3454. .IF OS2EXEDOC
  3455. .2
  3456. OS/2 Online Help
  3457.  
  3458. .in helptable
  3459. 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.
  3460.  
  3461. There are two different kinds of links from a program to a HLP file:
  3462. ■ links by using helptables
  3463. ■ direct links by using panel ID's.
  3464.  
  3465. 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.
  3466.  
  3467. 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.
  3468. .sf
  3469.  
  3470. 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 context-sensitive help 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".
  3471.  
  3472. .3
  3473. Writing the Hypermake source file
  3474.  
  3475. .in resource connection
  3476. In the Hypermake file, there are two new dot commands: The command resource connection
  3477.  
  3478. .sfB
  3479.  .RC ID_window, ID_button_or_Menu_Item
  3480. .sf
  3481.  
  3482. 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.
  3483.  
  3484. .afB
  3485. ~ID_window~ is the constant placed after MENU or DIALOG in your RC file.
  3486.  
  3487. 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.]
  3488.  
  3489. And with panel ID
  3490.  
  3491. .sfB
  3492.  .ID Chapter_Name
  3493. .sf
  3494.  
  3495. 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.
  3496.  
  3497. Pascal programmers have to pay attention: the constant behind the ID dot command is case sensitive!
  3498.  
  3499. 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.
  3500.  
  3501. 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.
  3502.  
  3503. If you enter a lot of RC commands, you are allowed to use the shortcut
  3504.  
  3505. .sfB
  3506.  .RC , ID_button_or_Menu_Item
  3507. .sf
  3508.  
  3509. This will use the name of the last window ID.
  3510.  
  3511. 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.
  3512.  
  3513. 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.
  3514.  
  3515. .in helptable file
  3516. This sample Hypermake source file has got resource connection and Panel ID dot commands:
  3517.  
  3518. .sfB
  3519.  .1
  3520. Introduction
  3521.  
  3522.  .RC ID_childwindow
  3523.  .ID PANEL_Introduction
  3524. This is the documentation of my prog.
  3525.  
  3526.  .1
  3527. Usage of the OK button
  3528.  
  3529.  .RC ID_childwindow, ID_OK
  3530.  .ID PANEL_usage_OK
  3531. With the OK button - you'll be surprised - you can press OK.
  3532.  
  3533.  .1
  3534. Usage of the Cancel button
  3535.  
  3536.  .RC ID_childwindow, ID_Cancel
  3537. With the Cancel button, you can cancel the operation.
  3538. .sf
  3539.  
  3540. .3
  3541. Writing your C program source file
  3542.  
  3543. Hypermake automatically creates a file HLPTABLE.RC:
  3544.  
  3545. .sfB
  3546. #define SUBTABLE_ID_childwindow 7001
  3547.  
  3548. HELPTABLE HELP_TABLE {
  3549.   HELPITEM ID_childwindow, SUBTABLE_ID_childwindow, 1 /* Introduction */
  3550. }
  3551.  
  3552. HELPSUBTABLE SUBTABLE_ID_childwindow {
  3553.   HELPSUBITEM ID_OK, 2 /* Usage of the OK button */
  3554.   HELPSUBITEM ID_Cancel, 3 /* Usage of the Cancel button */
  3555. }
  3556. .sf
  3557.  
  3558. Hypermake also creates a file PANELID.H:
  3559.  
  3560. .sfB
  3561. /*****Panel ID's created by Hypermake*****/
  3562.  
  3563. #define PANEL_Introduction  1
  3564. #define PANEL_usage_OK      2
  3565. .sf
  3566.  
  3567. 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.)
  3568.  
  3569. You can change the Help Subtable Start ID value in the ini file (project settings page "Helpfile"), switch ~Help Subtable Start ID~, also you can change the filenames of the two created files.
  3570.  
  3571. You can simply include the helptable file and the panel ID file into your program source by typing
  3572.  
  3573. .sfB
  3574. #include "HLPTABLE.RC"
  3575. .sf
  3576.  
  3577. for example after a MENU or a DLGTEMPLATE block in your RC file and
  3578.  
  3579. .sfB
  3580. #include "PANELID.H"
  3581. .sf
  3582.  
  3583. at the top of your program source file (a C or CPP file).
  3584.  
  3585. In your main header file, you have to define a constant HELP_TABLE with an unused value, for example
  3586.  
  3587. .sfB
  3588. #define HELP_TABLE 7000
  3589. .sf
  3590.  
  3591. which will be valid in the RC and in the C or CPP source file.
  3592.  
  3593. In the C source file you need at least two functions like
  3594.  
  3595. .sfB
  3596.   void InitHelp (hwnd) /*initialize the help process*/
  3597.   void DestroyHelp () /*destroy the help instance*/
  3598. .sf
  3599.  
  3600. which uses the constant HELP_TABLE.
  3601.  
  3602. 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.
  3603.  
  3604. A third function 
  3605.  
  3606. .sfB
  3607.   void DisplayHelpPanel (PanelID)
  3608. .sf
  3609.  
  3610. 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.
  3611.  
  3612. 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]
  3613.  
  3614. .sfB
  3615. #define INCL_HELP
  3616. .sf
  3617.  
  3618.  
  3619. .4
  3620. C source code with the three help functions
  3621.  
  3622. .sfB
  3623. .in function InitHelp
  3624. .in function DestroyHelp
  3625. .in function DisplayHelpPanel
  3626. #define HelpFilename "FILENAME.HLP"
  3627. #define HelpWindowTitle "Title of the Hypertext window"
  3628.  
  3629. BOOL fHelpEnabled;
  3630. static HWND hwndHelpInstance;
  3631.  
  3632. #define InfoBox(st) WinMessageBox (HWND_DESKTOP, HWND_DESKTOP, st, "", 0, MB_OK | MB_ERROR)
  3633.  
  3634. /*to be placed in front of the main program message loop*/
  3635. VOID InitHelp (HWND hwndClientFrame) {
  3636.     HELPINIT hini;
  3637.     /* If we return because of an error, Help will be disabled */
  3638.     fHelpEnabled = FALSE;
  3639.     /* Initialize help init structure */
  3640.     hini.cb = sizeof(HELPINIT);
  3641.     hini.ulReturnCode = 0;
  3642.     /* If tutorial added, add name here */
  3643.     hini.pszTutorialName = (PSZ)NULL;
  3644.     hini.phtHelpTable = (PHELPTABLE)MAKELONG(HELP_TABLE, 0xFFFF);
  3645.     hini.hmodHelpTableModule = 0; hini.hmodAccelActionBarModule = 0;
  3646.     hini.idAccelTable = 0; hini.idActionBar = 0;
  3647.     hini.pszHelpWindowTitle = HelpWindowTitle;
  3648.     hini.fShowPanelId = CMIC_HIDE_PANEL_ID;
  3649.     hini.pszHelpLibraryName = HelpFilename;
  3650.     /* Creating help instance */
  3651.     hwndHelpInstance = WinCreateHelpInstance(hab, &hini);
  3652.     if(hwndHelpInstance == 0L || hini.ulReturnCode) {
  3653.       InfoBox("Failed to load help manager."); return;
  3654.     }
  3655.     /* Associate help instance with main frame */
  3656.     if(!WinAssociateHelpInstance(hwndHelpInstance, hwndClientFrame)) {
  3657.       InfoBox("Failed to load help manager."); return;
  3658.     }
  3659.     /* Help manager is successfully initialized so set flag to TRUE */
  3660.     fHelpEnabled = TRUE;
  3661.     return;
  3662. }
  3663.  
  3664. /*to be placed behind the main program message loop*/
  3665. VOID DestroyHelp (VOID) {
  3666.     if(hwndHelpInstance != 0L) WinDestroyHelpInstance(hwndHelpInstance);
  3667.     return;
  3668. }
  3669.  
  3670. /*
  3671.   some possible parameters:
  3672.   HM_HELP_INDEX     shows the index
  3673.   HM_HELP_CONTENTS, shows the contents
  3674.   HM_DISPLAY_HELP   shows help for help
  3675. */
  3676. VOID SendHelpMessage (LONG HelpMessage) {
  3677.     if(fHelpEnabled)
  3678.       if((LONG)WinSendMsg(hwndHelpInstance, HelpMessage, (MPARAM) 0, (MPARAM) 0))
  3679.    InfoBox ("Failed to display help panel.");
  3680. }
  3681.  
  3682. /*
  3683.   parameters are the Panel ID's, defined with ID dot commands
  3684.   in the Hypermake source file
  3685. */
  3686. VOID DisplayHelpPanel (LONG PanelID) {
  3687.     if(fHelpEnabled)
  3688.       if((LONG)WinSendMsg(hwndHelpInstance, HM_DISPLAY_HELP,
  3689.          MPFROMLONG(MAKELONG(PanelID, NULL)),
  3690.          MPFROMSHORT(HM_RESOURCEID))) InfoBox ("Failed to display help panel.");
  3691. }
  3692. .sf
  3693.  
  3694. .3
  3695. Writing your Pascal program source file
  3696.  
  3697. In the ini file (project settings page "General"), setting ~languages~, you can choose between generating Pascal or C source.
  3698.  
  3699. Hypermake automatically creates a file e.g. HLPTABLE.RC:
  3700.  
  3701. .sfB
  3702. CONST
  3703.   SUBTABLE_ID_childwindow = 7001
  3704.  
  3705. HELPTABLE 1000
  3706. BEGIN
  3707.   HELPITEM ID_childwindow, SUBTABLE_ID_childwindow, 1 /* Introduction */
  3708. END
  3709.  
  3710. HELPSUBTABLE SUBTABLE_ID_childwindow
  3711. BEGIN
  3712.   HELPSUBITEM ID_OK, 2 /* Usage of the OK button */
  3713.   HELPSUBITEM ID_Cancel, 3 /* Usage of the Cancel button */
  3714. END
  3715. .sf
  3716.  
  3717. Hypermake also creates a file e.g. PANELID.INC:
  3718.  
  3719. .sfB
  3720. {     Panel ID's created by Hypermake    }
  3721.  
  3722. const
  3723.   PANEL_Introduction = 1;
  3724.   PANEL_usage_OK = 2;
  3725. .sf
  3726.  
  3727. 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.)
  3728.  
  3729. You can change the Help Subtable Start ID value in the ini file (project settings page "Helpfile"), switch ~Help Subtable Start ID~, also you can change the filenames of the two created files.
  3730.  
  3731. You can simply include the helptable file and the panel ID file into your program source by typing
  3732.  
  3733. .sfB
  3734. {$I HLPTABLE.RC}
  3735. .sf
  3736.  
  3737. for example after a MENU or a DLGTEMPLATE block in your RC file and
  3738.  
  3739. .sfB
  3740. {$I PANELID.INC}
  3741. .sf
  3742.  
  3743. at the top of your program source file (a PAS file).
  3744.  
  3745. First, there are two procedures to start the HLP file:
  3746.  
  3747. .sfB
  3748. DisplayHelpPanel (PanelID)
  3749. .sf
  3750.  
  3751. 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.
  3752.  
  3753. .sfB
  3754. SendHelpMessage (HM_HELP_CONTENTS)
  3755. .sf
  3756.  
  3757. activates the contents of the HLP file directly. There are other HM_* constants, defined in the SpeedPascal PMHELP.PAS unit.
  3758.  
  3759. The following depends on whether you want to use SpeedPascal 1.5 OPML or not.
  3760.  
  3761. .4
  3762. Creating the help functionality with SpeedPascal OPML
  3763.  
  3764. In the method
  3765.  
  3766. .sfB
  3767. TApplication.InitMainWindow
  3768. .sf
  3769.  
  3770. you have to append the following line at the end:
  3771.  
  3772. .sfB
  3773. MainWindow^.InitWindowHelp ('MYPROG.HLP', 'help window title');
  3774. .sf
  3775.  
  3776. That's all.
  3777.  
  3778. .4
  3779. Creating the help functionality without OPML
  3780.  
  3781. To create the connection between your EXE file and the HLP file, you need two procedures:
  3782.  
  3783. .sfB
  3784.   uses PMHELP;
  3785.  
  3786.   InitHelp (hwnd); {initialize the help process}
  3787.   DestroyHelp; {destroy the help instance}
  3788. .sf
  3789.  
  3790. This procedures are defined in the PMHELP.PAS unit of SpeedPascal 1.5.
  3791.  
  3792. 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.
  3793.  
  3794. Immidiately before using the procedure "InitHelp" you have to set some values of variables:
  3795.  
  3796. .sfB
  3797.   HelpFilename := 'MYPROG.HLP';
  3798.   HelpWindowTitle := 'heading of the hypertext window';
  3799.   HELP_TABLE := 1000;
  3800. .sf
  3801.  
  3802. The number 1000 is also used in the Helptable created by Hypermake.
  3803.  
  3804. If you do not use SpeedPascal 1.5 (or later), you will find the procedures and variables in the subchapter.
  3805.  
  3806. .5
  3807. Pascal Help Source
  3808.  
  3809. .sfB
  3810. {Help manager helpers}
  3811.  
  3812. FUNCTION InfoBox(st:STRING):LONGINT;
  3813. BEGIN
  3814.   result:=WinMessageBox (HWND_DESKTOP, HWND_DESKTOP, st,'', 0, MB_OK | MB_ERROR);
  3815. END;
  3816.  
  3817. {to be placed in front of the main program message loop}
  3818. PROCEDURE InitHelp (hwndClientFrame:HWND);
  3819. VAR
  3820.    hini:HELPINIT;
  3821.    { If we return because of an error, Help will be disabled }
  3822. BEGIN
  3823.      fHelpEnabled := FALSE;
  3824.      { Initialize help init structure }
  3825.      hini.cb := sizeof(HELPINIT);
  3826.      hini.ulReturnCode := 0;
  3827.      { If tutorial added, add name here }
  3828.      hini.pszTutorialName := NIL;
  3829.      hini.phtHelpTable := PHELPTABLE(MAKELONG(HELP_TABLE, $FFFF));
  3830.      hini.hmodHelpTableModule := 0;
  3831.      hini.hmodAccelActionBarModule := 0;
  3832.      hini.idAccelTable := 0;
  3833.      hini.idActionBar := 0;
  3834.      hini.pszHelpWindowTitle := @HelpWindowTitle;
  3835.      hini.fShowPanelId := CMIC_HIDE_PANEL_ID;
  3836.      hini.pszHelpLibraryName := @HelpFilename;
  3837.      { Creating help instance }
  3838.      hwndHelpInstance := WinCreateHelpInstance(AppHandle,hini);
  3839.      if ((hwndHelpInstance = 0 )OR(hini.ulReturnCode<>0)) THEN
  3840.      BEGIN
  3841.           InfoBox('Failed to load help manager.');
  3842.           exit;
  3843.      END;
  3844.  
  3845.      { Associate help instance with main frame }
  3846.      if not WinAssociateHelpInstance(hwndHelpInstance, hwndClientFrame) THEN
  3847.      BEGIN
  3848.           InfoBox('Failed to load help manager.');
  3849.           exit;
  3850.      END;
  3851.  
  3852.      { Help manager is successfully initialized so set flag to TRUE }
  3853.      fHelpEnabled := TRUE;
  3854. END;
  3855.  
  3856. {to be placed behind the main program message loop}
  3857. PROCEDURE DestroyHelp;
  3858. BEGIN
  3859.      IF hwndHelpInstance <> 0 THEN WinDestroyHelpInstance(hwndHelpInstance);
  3860. END;
  3861.  
  3862.  {
  3863.    some possible parameters:
  3864.    HM_HELP_INDEX     shows the index
  3865.    HM_HELP_CONTENTS, shows the contents
  3866.    HM_DISPLAY_HELP   shows help for help
  3867.  }
  3868. PROCEDURE SendHelpMessage (HelpMessage:LONG);
  3869. BEGIN
  3870.      if fHelpEnabled THEN
  3871.       if WinSendMsg(hwndHelpInstance, HelpMessage, 0, 0)<>0
  3872.         then InfoBox ('Failed to display help panel.');
  3873. END;
  3874.  
  3875.  {
  3876.    parameters are the Panel ID's, defined with ID dot commands
  3877.    in the Hypermake source file
  3878.  }
  3879. PROCEDURE DisplayHelpPanel (PanelID:LONG);
  3880. BEGIN
  3881.      if fHelpEnabled then
  3882.        if WinSendMsg(hwndHelpInstance, HM_DISPLAY_HELP,
  3883.           MPFROMLONG(MAKELONG(PanelID, 0)),
  3884.           MPFROMSHORT(HM_RESOURCEID))<>0
  3885.            then InfoBox ('Failed to display help panel.');
  3886. END;
  3887. .sf
  3888.  
  3889. .END OS2EXEDOC
  3890.  
  3891. .IF WINEXEDOC
  3892. .2
  3893. Windows Online Help
  3894.  
  3895. To create context-sensitive program help, there has to be a connection between the EXE file and the hypertext. Hypermake helps you doing that.
  3896.  
  3897. Relating ID's to chapters in the Hypermake source text
  3898.  
  3899. You can define ID constant names in a chapter.
  3900.  
  3901. .sfB
  3902.  .1
  3903.  My Chapter
  3904.  
  3905.  .ID ID_MY_CHAPTER
  3906.  This is my chapter.
  3907. .sf
  3908.  
  3909. Hypermake creates a file PANELID.H, or another filename you can define in the ini file (project settings page "Helpfile"), setting ~Panel ID filename"~. In this file, contant names are getting values.
  3910.  
  3911. In the ini file (project settings page "General"), setting ~languages~, you can choose between generating Pascal or C source.
  3912.  
  3913. Creating Help in C programs
  3914.  
  3915. The Panel ID file looks like the following:
  3916.  
  3917. .sfB
  3918. /*****Help Panel ID's created by Hypermake*****/
  3919.  
  3920. #define ID_MY_CHAPTER 27
  3921. .sf
  3922.  
  3923. You can include this file in your C program source:
  3924.  
  3925. ~#include "panelid.h"~
  3926.  
  3927. Creating Help in Pascal programs
  3928.  
  3929. The Panel ID file gets the Pascal syntax:
  3930.  
  3931. .sfB
  3932. {     Panel ID's created by Hypermake    }
  3933.  
  3934. const
  3935.   ID_MY_CHAPTER = 27;
  3936. .sf
  3937.  
  3938. You can include this file in your Pascal program source:
  3939.  
  3940. ~{$I PANELID.PAS}~
  3941.  
  3942. Access from the EXE source to the help file
  3943.  
  3944. With
  3945.  
  3946. ~WinHelp (hwnd, "MYPROG.HLP", HELP_CONTEXT, ID_MY_CHAPTER);~
  3947.  
  3948. you can activate the specific help page.
  3949.  
  3950. In addition, there are two other important kinds of using this API function:
  3951.  
  3952. ~WinHelp (hwnd, "MYPROG.HLP", HELP_FINDER, 0);~
  3953. activates the help window with the contents, index, search pages (you cannot get directly to these pages)
  3954.  
  3955. ~WinHelp (hwnd, "MYPROG.HLP", HELP_HELPONHELP, 0);~
  3956. activates the "help on help" page of the Windows operating system.
  3957. .END WINEXEDOC
  3958.  
  3959. .IF WINEXEDOC AND MSHTMLHELPDOC
  3960. HTML-Help functionality
  3961.  
  3962. The way of creating the connection between EXE and help file is very similar to Winhelp. But Hypermake does not relate integer values to the constant names. The constant names represent strings, comparible to URL locations. These constants are used in the new HTML-Help function.
  3963.  
  3964. To include HTML-Help in your program, you need to link the library HHCTRL.LIB or HTMLHELP.LIB. The function call is very similar to the WinHelp function.
  3965.  
  3966. ~HtmlHelp (hwnd, "MYPROG.CHM:://N000.HTML", HH_DISPLAY_TOPIC, 0);~
  3967.  
  3968. Because the parameter is a HTML filename string, there's no need for a Panel ID file which assigns integer values to chapters. It is useful to offer both help formats in your program, so you should write a function where both a Panel ID constant name and a string is defined.
  3969.  
  3970. .END WINEXEDOC AND MSHTMLHELPDOC
  3971.  
  3972. .IF OS2EXEDOC OR WINEXEDOC
  3973. .2
  3974. Writing several HLP files in different languages
  3975.  
  3976. If you are writing several help files in different languages and you have only one EXE file, it is adequate to enter the ID- (and OS/2 RC-) 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.
  3977. .END
  3978.  
  3979. .WA verti 40
  3980. .1
  3981. dot command summary 
  3982.  
  3983. .in dot command summary
  3984.  
  3985. .2
  3986. About
  3987.  
  3988. Here you find a summary of all Hypermake dot commands. You will find the same structure of subjects in Writing a Hypermake source text.
  3989.  
  3990. Some dot commands have got synonyms in German language or WordStar synonyms, they are quoted in brackets and both are interpreted.
  3991.  
  3992. .2
  3993. Essentials
  3994.  
  3995. .afB
  3996. ~..comment~
  3997.  
  3998. "comment" is not interpreted.
  3999.  
  4000. .IF IPFDOC
  4001. .sfB
  4002.  .:ipfcommand.
  4003.  .:ipfcommand. expression
  4004. .sf
  4005.  
  4006. You can enter an IPF command directly.
  4007. .END
  4008.  
  4009. .IF HTMLDOC
  4010. .sfB
  4011.  .HC on
  4012.  .HC off
  4013. .sf
  4014.  
  4015. Enables embedding <HTML tags> in normal Hypermake source text. Default is off.
  4016.  
  4017. .sfB
  4018.  .HTML
  4019.  <HTML-commands> running text
  4020.  .HYPERMAKE
  4021. .sf
  4022.  
  4023. enables direct writing of HTML text.
  4024.  
  4025. .sfB
  4026.  .HF filename
  4027. .sf
  4028.  
  4029. copies the content of the file filename to the location of the dot command when creating HTML.
  4030. .END HTMLDOC
  4031.  
  4032. .2
  4033. Beginning
  4034.  
  4035. .sfB
  4036.  .TI
  4037.  Title
  4038. .sf
  4039.  
  4040. sets the title of the hypertext to "Title".
  4041.  
  4042. .IF IPFDOC OR WINHELPDOC
  4043. .sfB
  4044.  .<>
  4045. .sf
  4046.  
  4047. creates pushbuttons "Back" and "Forward" in Winhelp and OS/2 HLP files and "Contents" in OS/2 HLP files. 
  4048. .END
  4049.  
  4050. .2
  4051. Headings
  4052.  
  4053. ~.1~ up to ~.6~ sets a heading level
  4054.  
  4055. ~.1~
  4056. ~Main heading~
  4057.  
  4058. The title of the first heading level is "Main heading".
  4059.  
  4060. .IF HTMLDOC
  4061. (Heading Size) Changing the font size of the heading text (HTML). E.g. Level 4 gets the font size of level 2.
  4062.  
  4063. ~.HS 123234~
  4064. .END
  4065.  
  4066. Appearance of links to subchapters
  4067.  
  4068. .sfB
  4069.  .sc separation text of your choice
  4070.  .sc RETURN           (default)
  4071.  .sc PARAGRAPH
  4072.  .sc LIST
  4073. .sf
  4074.  
  4075. Window Arrangement (Frames)
  4076.  
  4077. ~.WA~ (~.FA~)
  4078. ~.WA hori 30~ 
  4079. ~.WA hori 30 verti 40 III~
  4080.  
  4081. 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.
  4082.  
  4083. Chapter ID
  4084.  
  4085. ~.ID NAME~
  4086.  
  4087. The chapter where the command is located gets the ID "NAME".
  4088.  
  4089. .IF HTMLDOC
  4090. The corresponding page gets the name "NAME.HTML" instead of an enumeration. In the ini file (project settings page "link"), 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.
  4091.  
  4092. .END
  4093.  
  4094. .IF OS2EXEDOC OR WINEXEDOC
  4095. This command is used for creating context-sensitive help.
  4096. .END
  4097.  
  4098.  
  4099. .2
  4100. Fonts
  4101.  
  4102. ~.SFX~ (~.SNX~)
  4103. ~.AFX~ (~.SAX~)
  4104.  
  4105. 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 (project settings page "Font").
  4106.  
  4107. The alternate font is active between two alternate toggle chars, also defined in the ini file.
  4108.  
  4109. .2
  4110. Lists
  4111.  
  4112. ~.OL~ turns the ordered list setting on
  4113. ~.UL~ turns it off (default, "unordered list").
  4114.  
  4115. .2
  4116. Bitmaps
  4117.  
  4118. ~.BM filename~
  4119.  
  4120. places a bitmap centered. The filename extension is ".BMP" (IPF, Winhelp) and ".GIF" (HTML).
  4121.  
  4122. ~.BTX filename~
  4123.  
  4124. replaces all occurrences of the bitmap char X by the bitmap filename.bmp.
  4125.  
  4126. ~.BD directory/~
  4127.  
  4128. bitmap directory defines a default directory for all ~.BM~ and ~.BT~ commands which follows.
  4129.  
  4130. .2
  4131. Linking and Indexing
  4132.  
  4133. ~.ICX~  (~.IZX~, ~.STX~)
  4134.  
  4135. sets the index char to X.
  4136.  
  4137. ~.IN phrase~  (~.SW~)
  4138.  
  4139. places "phrase" into the index; all occurrences of "phrase" will get a link to the chapter where the IN dot command is placed.
  4140.  
  4141. ~.IT phrase~  (~.IV~, ~.SV~)
  4142.  
  4143. Index Turned: same as IN, but uses the last word as leading word.
  4144.  
  4145. ~.IU~ ignore uppercase
  4146.  
  4147. at the beginning of the source text ignores upper and lowercase letters when creating links
  4148.  
  4149. .IF IPFDOC OR WINHELPDOC
  4150. External links (IPF, Winhelp)
  4151.  
  4152. ~.EX extern.hlp~
  4153. ~.ID chapter_beginning~
  4154. ~.IN phrase~
  4155. ~.EX~
  4156.  
  4157. All occurrences of "phrase" become an external link to the chapter of the file extern.hlp which was labeled with the dot command
  4158. ~.ID chapter_beginning~
  4159. .END
  4160.  
  4161. External links (HTML)
  4162.  
  4163. ~.URL internetaddress~
  4164. ~.IN phrase~
  4165. ~.LOCAL~
  4166.  
  4167. All occurrences of "phrase" become an external link to the URL "internetaddress".
  4168.  
  4169. .IF IPFDOC OR WINHELPDOC
  4170. Launching programs (IPF, Winhelp)
  4171.  
  4172. ~.EX programname.exe parameter~
  4173. ~.IN phrase~
  4174. ~.EX~
  4175.  
  4176. All occurrences of "phrase" become a link to the program "programname.exe", with the parameter "parameter".
  4177. .END
  4178.  
  4179. .2
  4180. Duplication of heading text
  4181.  
  4182. ~.dp34C~
  4183.  
  4184. Duplication of heading text at the beginning of the text window in heading level 3 and 4 with font C
  4185.  
  4186. ~.dp##C~
  4187.  
  4188. 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 #).
  4189.  
  4190. ~.dp-34~
  4191.  
  4192. deactivates heading duplication at the heading level 3 and 4.
  4193.  
  4194. .IF WINHELPDOC
  4195. In Winhelp, duplication of heading text is always activated and the fonts are set in the ini file instead of the dot command.
  4196. .END
  4197.  
  4198. .2
  4199. Tables
  4200.  
  4201. .sfB
  4202.  .TA table heading text
  4203.  cell one    cell two  cell three
  4204.  2nd line    2nd line   one+
  4205.  third cell  "         big cell     
  4206.  .TA
  4207. .sf
  4208.  
  4209. and you will get:
  4210.  
  4211. .TA table heading text
  4212. cell one    cell two  cell three
  4213. 2nd line    2nd line   one+
  4214. third cell  "         big cell     
  4215. .TA
  4216.  
  4217. In tables, cells can be expanded with " and with + (only HTML).
  4218.  
  4219. ~.tc X~
  4220.  
  4221. (table character) changes the concatenation-char + to another char.
  4222.  
  4223. ~.TT~
  4224.  
  4225. (Table Tags) default is:
  4226. ~.TT BORDER CELLPADDING=5~
  4227.  
  4228. Gray background without graphics:
  4229. ~.TT BORDER CELLPADDING=5 BGCOLOR="#D0D0D0"~
  4230.  
  4231. ~.TW~
  4232. Table word wrap (only HTML): table fits the whole window width and the text in the cells is reformatted.
  4233.  
  4234. .2
  4235. Line drawing
  4236.  
  4237. .sfB
  4238. ..LI▄▌
  4239.  .LIXY
  4240. X   Y   X               ┌───┬───┐     
  4241.                         │   │   │ 
  4242. Y            result:    ├───┼───┤ 
  4243.                         │   │   │ 
  4244. X       X               └───┴───┘
  4245.  .LI
  4246. ..li
  4247. .sf
  4248.  
  4249. Line drawing generates a box (X are the corners), divided by Y. Z in front of X or Y uses double lines (only IPF).
  4250.  
  4251. .2
  4252. Footnotes
  4253.  
  4254. ~.FU{}~
  4255. ~.FU{}sfX~
  4256.  
  4257. defines brackets to quote footnote text; selects font X for the footnote window. If you enter
  4258.  
  4259. ~you will get {content of the footnote}.~
  4260.  
  4261. you will get [content of the footnote].
  4262.  
  4263. .IF HTMLDOC
  4264. ~.FS 30~
  4265.  
  4266. footnote size: changes the default setting of text window size / footnote window size 85 / 15 to 70 / 30.
  4267. .END
  4268.  
  4269. ~.FT XXX~
  4270.  
  4271. footnote text: writes "XXX" instead of the default "*". Bitmap chars are allowed.
  4272.  
  4273. .2
  4274. Margins and Formatting
  4275.  
  4276. ~.LM 10~
  4277.  
  4278. will set the left margin from default 1 to 10.
  4279.  
  4280. .IF IPFDOC OR WINHELPDOC
  4281. ~.FM off~  (~.FM aus~)
  4282. ~.FM on~  (~.FM an~)
  4283.  
  4284. (only IPF and Winhelp) Formatting turns formatting (word wrap) off and on. Default is on.
  4285. .END
  4286.  
  4287. ~.OC on~  (~.OC an~)
  4288. ~.OC off~  (~.OC aus~)
  4289.  
  4290. turns centered text on and off.
  4291.  
  4292. ~.AM off~  (~.AM aus~)
  4293. ~.AM on~  (~.AM an~)
  4294.  
  4295. Auto Margin let you change the left margin by entering spaces at the beginning of a paragraph. Default is on.
  4296.  
  4297. .IF HTMLDOC
  4298. In HTML files, the margin can only be changed in steps of 5 spaces.
  4299. .END
  4300.  
  4301. .2
  4302. if-conditions
  4303.  
  4304. .sfB
  4305.  .IF CONDITION
  4306.  .ELSE
  4307.  .END
  4308. .sf
  4309.  
  4310. is only compiling specific source text to the output file. The conditions are set in the HMP file or from the commandline with #CONDITION (not case-sensitive). Also accepted expressions:
  4311.  
  4312. .sfB
  4313.  .IF not CONDITION
  4314.  .IF COND1 and COND2
  4315.  .IF COND1 or COND2
  4316. .sf
  4317.  
  4318. .2
  4319. HTML specific commands
  4320.  
  4321. .sfB
  4322.  .ID LABEL
  4323. .sf
  4324.  
  4325. the actual HTML file will get the name LABEL.HTML instead of e.g. N001.HTML.
  4326.  
  4327. .sfB
  4328.  .NR 10
  4329.  .HD 100
  4330.  .1
  4331.  Heading with fixed internal number 
  4332. .sf
  4333.  
  4334. (internal numbering) sets the interal counter for headings and files to a higher value, so additional chapters can be inserted later above these commands without affecting the enumeration which is following.
  4335.  
  4336. .WA hori 40
  4337. .1
  4338. Project Settings (Ini file)
  4339.  
  4340. .in ini file
  4341. .in project settings
  4342.  
  4343. .2
  4344. Introduction
  4345.  
  4346. The project settings notebook contains settings which influences the design and functionality of the hypertext files Hypermake generates. The settings on the "Main" page are saved in the HMP file (HyperMake Project file) and all the other pages in the ini file. Every hypertext project has always its own HMP file, but several projects can share the same ini file, if the design and functionality of these projects are the same.
  4347.  
  4348. Principally, you can edit the HMP and the ini file with an ASCII editor. This is necessary if you don't use the graphical HYMAKE.EXE program and prefer running HMAKE.EXE. The first line of HMP and ini files won't be interpreted.   
  4349. 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.
  4350.  
  4351. In the sub chapters below, the corresponding line in the ini file is written in typewriter font. If you use the settings notebook exclusively, this information won't be interested for you.
  4352.  
  4353. If you want to edit HMP and ini files instead of using the settings notebook
  4354.  
  4355. In the manner of the C++ and Java programming languages, text at the right side of a double slash // won't be interpreted. Also the windows specific comments beginning with ; are allowed, but ; has to be at at column 1. You can change the order of the switches, but all switches have to appear exactly one time. With a few exceptions, the lines aren't interpreted case sensitive.
  4356.  
  4357. .fu
  4358. In comparison to Windows ini files, the headings in brackets like ~[general settings]~ aren't interpretated and helps you only grouping the switches.
  4359. .fu[]
  4360.  
  4361. 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.
  4362.  
  4363. .2
  4364. Main (HMP) settings
  4365.  
  4366. .ID P_proj_main
  4367. The "Main" page holds all settings which are stored in the HMP file (Hypermake project file). The most important information here is the name of the source file and the name of the ini file - this is the file which stores all the information of the following pages of the settings notebook.
  4368.  
  4369. The reason for storing into two different files is the ability to use one single ini file for several projects where the functionality and the look are similar.
  4370.  
  4371. Source files
  4372.  
  4373. You can use only one or several source files. If you enter several source files here, they were handled like the text would be stored in a single file with the order you have chosen here.
  4374.  
  4375. It can be a useful decision to separate specific parts of your source file into separate files, e.g. all external link (external WWW addresses) which have to be controled separately. If you have got very large files, a separation can also be useful. (But the Hypermake editor works with files up to 15 MB.) If different persons are responsible for concrete chapters, a separation can be also useful.
  4376.  
  4377. If no drive letter and directory is entered, the souce file has to be located in the same directory where the current HMP file resides.
  4378.  
  4379. Ini File
  4380.  
  4381. The settings on the "Main" page are stored in the HMP file and all other pages are stored in the ini file you can select here. You can select the same ini file for projects with similar look and functionality.
  4382.  
  4383. It would be extremely tedious to fill out all settings of the settings notebook when starting a new Hypertext project. Instead, when pressing New, Hypermake let you select an existing ini file and then creates a copy this ini file (e.g. the SAMPLE.INI file which is part of the archive). Then you have only to make some changes on the pages of the settings notebook. Open let you select an existing ini file for your current project. Changes on the notebook pages will overwrite the selected ini file which will have an effect to other projects using this ini file. Save as makes a copy of the current ini file. The old ini file can be used for another Hypertext project.
  4384.  
  4385. Graphic Files
  4386.  
  4387. When checking "check graphic files" the list above will be activated. In this case when compiling, Hypermake searches the necessary graphic files in the directories you have entered here. If a file is missing, you will get a warning message. See copying graphic files.
  4388.  
  4389. If you don't check this checkbox, you have to copy the graphic files yourself to the directory where the HTML files or where the source file for the second compiler (IPF, RTF file) resides.
  4390.  
  4391. also do start 2nd compiler, start viewer
  4392.  
  4393. After compilation of the source text to the hypertext format is finished successfully, Hypermake can start the second compiler and/or the viewer automatically, if you want. If you enable this checkboxes, make sure that in the program settings (view - program settings), page "2nd Comp" and "View", the filenames of the programs are entered correctly, e.g. the EXE file of the Netscape Browser).
  4394.  
  4395. More about how Hypermake works see compilation.
  4396.  
  4397. Target
  4398.  
  4399. You can select one Hypertext format you want to get created from your source text. You can also select a different target format with project - compile to, which overwrites this setting.
  4400.  
  4401. If-Conditions
  4402.  
  4403. Hypermake lets you define conditions for including and excluding parts of your source text without changing the source text, see if-conditions. 
  4404.  
  4405. .3
  4406. Parameter
  4407.  
  4408. .in program parameter
  4409. In the settings notebook, page "Main", you will find a number of checkboxes in the "Parameter" section. If you use the commandline version of Hypermake, the expressions in parenthesis are the parameter names you have to enter.
  4410.  
  4411. .IF HTMLDOC
  4412. "No Frames": Creating HTML files without frames functionality (NOFRAMES)
  4413.  
  4414. .it no frames
  4415. (only HTML) This parameter 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].
  4416. .fu[]
  4417.  
  4418. "No ID": Ignore ID dot commands (NOID)
  4419.  
  4420. (only HTML) If you use ~.ID~ dot commands, the HTML file gets the name of the ID. Normally Hypermake uses filenames N000.HTML, N001.HTML and so on. If you don't want to change to fixed ID filenames, you can use this parameter.
  4421.  
  4422. "Pre Filename": Several Hypermake documents in only one directory (PRE)
  4423.  
  4424. (only HTML) 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 this parameter.
  4425.  
  4426. If the projekt name is MY, Hypermake creates HTML files ~MY\MY*.HTML~. So you can copy the files of all your different projects into one single directory without name conflicts.
  4427.  
  4428. Using DOS drives, "pre filename" or the name of the HMP file must not exceed 3 chars!
  4429.  
  4430. "Alt Graphic File": Different languages in only one directory (_) underscore
  4431.  
  4432. (only HTML) 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.
  4433.  
  4434. This commandline parameter 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.
  4435. .END
  4436.  
  4437. "Big Font": Choosing a globally bigger font (BIGFONT)
  4438. "Small Font": Choosing a globally smalle font (SMALLFONT)
  4439.  
  4440. With these parameters which have effect to all target fomats you can influence the size of the fonts which have got a size value in the ini file. I have seen that with the same INI file, e.g. Winhelp generates bigger fonts and IPF smaller ones. To avoid using two ini files, you can use these parameters.
  4441.  
  4442. .IF IPFDOC
  4443. "New IPFC": Generating same output with two IPFC compiler versions (NEWIPFC)
  4444.  
  4445. The newer IPFC version 3 generates different beginnings of the pages (indention and new line) in comparison to the versions 1 and 2. With the parameter ~/newipfc~ you will get the same look of the hypertext files when compiling with IPFC 3 like when compiling with IPFC 2 without the ~/newipfc~ setting.
  4446. .END
  4447.  
  4448. .IF not DOS
  4449. Forcing DOS filenames (FAT)
  4450.  
  4451. With this parameter, Hypermake writes filenames in DOS 8.3 syntax. You have to control possible conflicts by yourself: if the name of a chapter is "mainchapter1.HTML" and of another one "mainchapter2.HTML", both chapters would get the same name "MAINCHAP.HTM".
  4452. .END
  4453.  
  4454. .2
  4455. General settings
  4456.  
  4457.  
  4458. .ID P_proj_general
  4459. Language of Hymake User Interface
  4460.  
  4461. .sfB
  4462. //possible settings: ENGLISH, GERMAN, C, PASCAL
  4463. Language = ENGLISH C
  4464. .sf
  4465.  
  4466. Actually, English and German is supported. This document is also available in German language. This switch won't have any effect to the output files. It only sets the language of the user interface and the (error) messages running Hypermake. Some dot commands are different in the german documentation, but they are both interpreted.
  4467.  
  4468. When choosing a native language, you also have to set the language specific settings endings of words and extended letters.
  4469.  
  4470. Your Programming Language (IPF, Winhelp, HTMLHELP)
  4471.  
  4472. If you want to create Panel ID and Helptable files, Hypermake has to know your programming language C or µPascal.
  4473.  
  4474. Registration Key
  4475.  
  4476. .in Registration key
  4477. .sfB
  4478. Registration code = 0
  4479. .sf
  4480.  
  4481. Here you have to enter your registration key, if you want to compiler bigger sources than 20 kB.
  4482.  
  4483. see registration
  4484.  
  4485. Beep after successful compilation
  4486.  
  4487. .sfB
  4488. //beep when finishing compiling - possible settings: YES, NO
  4489. beep = YES
  4490. .sf
  4491.  
  4492. If Hypermake has created the IPF/RTF file or the HTML files successfully, you will hear a beep. Here you can turn the beep off. OS/2, DOS and Windows NT/2000 activates the PC internal speaker, Win95/98 the sound card.
  4493.  
  4494.  
  4495. .2
  4496. Format settings
  4497.  
  4498. .ID P_proj_format
  4499. Source File Format
  4500.  
  4501. .sfB
  4502. //possible Settings: ASCIIHARDRET, ASCIISOFTRET, WORDSTAR4
  4503. Source format = ASCIISOFTRET
  4504. .sf
  4505.  
  4506. see handling of Returns
  4507.  
  4508.  
  4509. Source Codepage
  4510.  
  4511. .sfB
  4512. //possible Settings: ISO, IBM
  4513. source codepage = IBM
  4514. .sf
  4515.  
  4516. 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.
  4517.  
  4518. This setting is also used by the Hymake editor. The codepage setting of the last Hypermake project is used.
  4519.  
  4520.  
  4521. Target (interpreted, but not written in Hymake 4.0, now in HMP file)
  4522.  
  4523. .in target format
  4524. .sfB
  4525. //possible settings: IPF, HTML, WINHELP3, WINHELP4, HTMLHELP
  4526. Target = HTML
  4527. .sf
  4528.  
  4529. Note that you can temporary overwrite this settings by using the expressions as program parameters in the HMP file or the commandline.
  4530.  
  4531. Choosing the parameters WINHELP3 and WINHELP4 depends on using HC.EXE/HCP.EXE or HCW.EXE. The differences are not very big.
  4532.  
  4533. .2
  4534. specific characters
  4535.  
  4536. .ID P_proj_spec
  4537. Check conflicts
  4538.  
  4539. is a functionality only inside the settings notebook. It will warn you if you have defined a character for two purposes.
  4540.  
  4541. List chars
  4542.  
  4543. .sfB
  4544. //only ASCII source
  4545. List chars = =-
  4546. .sf
  4547.  
  4548. List chars are necessary to create unordered lists.
  4549.  
  4550.  
  4551. Index char
  4552.  
  4553. .sfB
  4554. Index char = #
  4555. .sf
  4556.  
  4557. see linking and indexing. The dot command ~.ICX~ overwrites this default setting with the char X.
  4558.  
  4559.  
  4560. Index Filter
  4561. .in index filter
  4562. .sfB
  4563. //characters not shown in index and duplicated heading
  4564. index filter = ().
  4565. .sf
  4566.  
  4567. You can omit specific characters in the index and when duplicating heading text.
  4568.  
  4569.  
  4570. toggle chars
  4571.  
  4572. .sfB
  4573. //highlighted char toggles
  4574. //all formats:    1 alternate  2 italic 3 bold 4 underlined
  4575. //IPF:            5 red 6 cyan 7 blue
  4576. //HTML:           8 strike 9 big 10 small
  4577. //HTML, Winhelp:  11 sub 12 sup
  4578. //        123456789012
  4579. toggles = ************
  4580. .sf
  4581.  
  4582. You always have to enter all twelve toggle chars, even you don't use IPF or HTML.
  4583.  
  4584. You can enter these characters in the integrated editor by using popup menu - toggle.
  4585.  
  4586. If you use IBM Codepage, you are allowed to use the characters below ASCII 26. To enter characters in the settings notebook which are not part of your keyboard, hold the ALT down and type the ASCII number with the number keys on the right side of your keyboard.
  4587.  
  4588. Extended Letters
  4589.  
  4590. .in extended letters
  4591. .sfB
  4592. //language specific letters besides A...Z, a...z, 0...9
  4593. //english '- 
  4594. //german äöüßÄÖÜ 
  4595. extended letters = '- 
  4596. .sf
  4597.  
  4598. 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
  4599.  
  4600. .sfB
  4601. This is a sample with a marked german word #Kindergärten.
  4602. .sf
  4603.  
  4604. (That's plural of Kindergarten.) If you haven't defined "ä" as an extended letter, the index entry and link target is only "Kinderg".
  4605.  
  4606. 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.
  4607.  
  4608.  
  4609. .2
  4610. Font characters
  4611.  
  4612. .ID P_proj_font
  4613. .sfB
  4614. //Font chars from A to Z and from a to z (case-sensitive!)
  4615. //both HTML and IPF: size Linestandard OmitLinks PRE center
  4616. //only IPF: Fontname codepage foregroundcolor BACKGROUNDCOLOR
  4617. //only HTML: PHRASEELEMENT Color
  4618. Font A = 15 fmodern:Courier Courier CODE
  4619. Font b = fmodern:Courier Courier 12 CODE black 437 Linestandard OmitLinks
  4620. Font B = 30 Arial,Helvetica,Univers fswiss:Helvetica Helv neutral
  4621. Font Z = GREEN 30 Arial,Helvetica,Univers fswiss:Helvetica Helv yellow 
  4622. Font G = 15 Arial,Helvetica,Univers fswiss:Helvetica Helv black
  4623. Font T = 18 froman:Roman Tms_Rmn
  4624. Font C = black
  4625. Font o = OmitLinks
  4626. .sf
  4627.  
  4628. 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.
  4629.  
  4630. In the settings notebook, you can activate the font dialog by double clicking a line in the list box or by pressing the "change" button. In the font dialog, you can change the font, you can edit the edit field which will chause changes in the dialog item states or you can use the dialog items which will modify the edit field. The "sample" field cannot cannot show a perfect preview of the font style, because the different hypertext formats are too different.
  4631.  
  4632. The characteristics of the strings in the edit field / behind the = sign are:
  4633.  
  4634. ■ size: all numbers smaller than 200
  4635. ■ codepage: (only IPF) all numbers equal and bigger than 200
  4636. ■ foregroundcolor: (See color samples)
  4637.   - IPF: all colors in lower case letters:
  4638.     default, blue, cyan, green, neutral, red, yellow, black.
  4639.   - HTML, Winhelp: lower case letters, but first char capital letter:
  4640.     Black, Silver, Gray, White, Maroon, Red, Purple, Fuchsia, Green, Lime, Olive, Yellow, Navy, Blue, Teal, Aqua.
  4641. ■ backgroundcolor: (only IPF) all colors in capital letters: DEFAULT, BLUE, CYAN, GREEN, NEUTRAL, RED, YELLOW, BLACK.
  4642. ■ Phrase element: (only HTML) ADDRESS PRE EM STRONG DFN CODE SAMP KBD VAR CITE. 
  4643. ■ IPF Font-Type: all strings which are not a color.
  4644. ■ HTML Font-Type: at least two fontnames separated by comma, without spaces
  4645. ■ Winhelp Font-Type: fontfamily:fontname seperated by a colon. Font families are fmodern, froman, fswiss.
  4646.  
  4647. Note that fonts with two words have to be connected with "_".
  4648.  
  4649. You only have to enter the settings which are different from default.
  4650.  
  4651. .IF IPFDOC
  4652. The default IPF codepage is defined by the settings in your operating system or by a parameter of IPFC.
  4653. .END
  4654.  
  4655. Note that you can mix HTML, IPF and Winhelp instructions, so one font character defines different outfit dependent on the target format.
  4656.  
  4657. 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.
  4658.  
  4659. 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.
  4660.  
  4661. For further information, please refer to the font chapter.
  4662.  
  4663. .2
  4664. link specific settings
  4665.  
  4666. .ID P_proj_link
  4667. endings of words
  4668.  
  4669. .in endings of words
  4670. .sfB
  4671. //endings in german words: n en s es
  4672. ending of words = s es ies 's ion ions ing ings
  4673. .sf
  4674.  
  4675. See Linking, Handling of endings
  4676.  
  4677.  
  4678. Text for link to
  4679.  
  4680. .sfB
  4681. Text for link to subchapters = @subchapters:@
  4682. Text for link to next chapter = @next chapter:@
  4683. .sf
  4684.  
  4685. 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.
  4686.  
  4687. You can turn off this function by leaving the entryfield blank or entering NO in capital letters:
  4688.  
  4689. .sfB
  4690. Text for link to subchapters = NO
  4691. Text for link to next chapter = NO
  4692.  
  4693. Text for link to main chapter = to main chapter (Font Z)
  4694. .sf
  4695.  
  4696. When using the frames dot command ~.WA~ window arrangement, 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 in HTML like "contents" are not created in the second window, the "link to main chapter" is the only connection to the remaining document. It can be disabled by typing ~NO~, but I cannot recommend turning it off.
  4697.  
  4698. .IF IPFDOC
  4699. When creating IPF, ~text for link to main chapter~ is not used.
  4700. .END
  4701.  
  4702. no more links in
  4703.  
  4704. .in no more links in
  4705. .sfB
  4706. //possible Settings: PARAGRAPH, WINDOW, ALWAYS
  4707. no more links in = PARAGRAPH
  4708. .sf
  4709.  
  4710. see Linking, Omitting links
  4711.  
  4712. Marking external links
  4713.  
  4714. .sfB
  4715. //graphics file for marking external URL links or NO for no graphics file
  4716. URL graphics file = World
  4717. .sf
  4718.  
  4719. Besides Winhelp3, all target formats support links to the WWW. It's useful to know whether a links is an external link or not because external links are only running if the computer is online. Hypermake can place a graphics file in front of every external link.
  4720.  
  4721. .IF HTMLDOC
  4722. .2
  4723. HTML-0: preselect HTML designs
  4724.  
  4725. .ID P_proj_html_0
  4726. Hypermake offers a lot of user settings for the HTML target format. If you don't want to study all the settings, you can preselect a well-tested design which is a set of specific settings of the pages HTML-1 and HTML-2. The designs are sorted in an order from simple and nearly without using Javascript to a high-featured design which has got a lot of Javascript and is internally more complicated. If you use Hypermake for a longer time: the number behind "Hypermake" shows the Hypermake version number where the design was the default design.
  4727.  
  4728. Language has got an effect to all language-specific settings when pressing a HTML design button. If your language is not listed in the radiobox, please send me your ini file.
  4729.  
  4730. The Hypermake 4.0 design uses different frame names (default frame, content frame) for the content and normal text. The start page / homepage is no more N000.HTML or INDEX.HTML, it's INDXF.HTML. This is a frame page which shows the content in the left frame and the normal text in the right frame. The user can reach this frame page by clicking to the "Home" button in the first/last line of the normal text pages. The design is close to Microsoft HTML-HELP, so do not use this design when creating HTMLHELP - in this case two content trees would be visible simultaneously. 
  4731.  
  4732. If you have selected an interesting design, please send me your ini file. If you need some additional functionality to get your favourite design, please let me know.
  4733.   
  4734. The checkboxes below refers to some basic functionality: if you create a short and simple Homepage, it can be useful to turn off create contents page and create index page, Normally  you will turn this functionality on, because that's the main purpose of Hypermake.
  4735.  
  4736. By default, Hypermake writes the heading text of a chapter in proper HTML syntax, so it's the job of the browser to show the headings in an expedient way: the heading of chapter level 1 in a big font, level 2 in a smaller font and so on. When creating Winhelp, the user has to define a heading font for each heading level, because Winhelp does not know a "heading font" command. Turning the Use heading fonts on Winhelp page for HTML checkbox on will use these font definitions also for HTML headings. You can use this setting e.g. to define different colors for heading text dependent on the heading level. But the recommendend setting is not to use these fonts.
  4737.  
  4738. .2
  4739. HTML-1: HTML specific settings, page 1
  4740.  
  4741. .ID P_proj_html_1
  4742. µ:body tags:
  4743.  
  4744. You can enter several HTML body tags for describing the look of the Browser window. E. g. a background graphics file and a text color for all normal text windows and a background color for the contents window.
  4745.  
  4746. .sfB
  4747. //enter tags or NO
  4748. body tags = background="backgr.gif" TEXT="#00FFFF"
  4749. contents tags = BGCOLOR=#"CCFFCC"
  4750. .sf
  4751.  
  4752. The contents tags setting is optional.
  4753.  
  4754. .IT background color
  4755. .iN background color
  4756. .IT default text color
  4757. 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, there's no risk.
  4758.  
  4759. In the settings notebook, when pressing the button near to the editfield, you will get a dialog window where you can select background color or a background graphics file (which should be placed in one of your graphic path directories, see page Main) and a foreground color (font color) for the default fonts where no color is defined.
  4760.  
  4761. First and last line
  4762.  
  4763. see also chapter Navigation Buttons
  4764.  
  4765. .sfB
  4766. //only HTML: first and last line in file
  4767. function for first line = BACK FORWARD CONTENT INDEX
  4768. text for first line =     back forward content index
  4769. function for last line =  FORWARD CONTENT INDEX
  4770. text for last line =      forward content index
  4771. .sf
  4772.  
  4773. 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, also the order of the functions. But you have to make the changes for function and text similar.
  4774.  
  4775. The design "Hypermake 4.0" (see settings page HTML-0) uses two extended functions HOMEF (Homeframe) and MAX (maximize). Additionaly, the user can set user defined buttons pointing to an arbitrary page of the hypertext. For more information see page Navigation Buttons.
  4776.  
  4777.  
  4778. Buttons
  4779.  
  4780. .sfB
  4781. //you can use buttons BACK.GIF FORWARD.GIF CONTENT.GIF INDEX.GIF
  4782. //instead of simple text or use Javascript buttons
  4783. //possible settings: TEXT GIF JAVASCRIPT (Font X)
  4784. buttons = GIF
  4785. .sf
  4786.  
  4787. You can choose between textual links, buttons with graphic files and Javascript buttons in the first/last line. The graphics file names are fixed: function name with extension ".GIF".
  4788.  
  4789. Besides GIF, you can select a font. For Javascript buttons, a smaller font (property "-1") is recommended.
  4790.  
  4791. 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!
  4792.  
  4793. You will find a Library of Buttons in the directory BUTTONS.
  4794.  
  4795. The setting ~JAVASCRIPT~ creates buttons based on the Javascript programming language. The program generating the Java buttons is part of the HTML file and much more smaller and faster than separate GIF files. But besides a font, you can't change the design of the buttons.
  4796.  
  4797.  
  4798. title in every file
  4799.  
  4800. .sfB
  4801. //enter YES (Font X) or NO
  4802. title in every file = NO
  4803. .sf
  4804.  
  4805. It can be desired to have got the title on every HTML page. The title (which you have defined by .TI at the beginning of the source text) is shown at the beginning of the page, above the "first line" with the navigation buttons.
  4806.  
  4807. minimal Entries for Extended Index
  4808.  
  4809. .in entries for extended index
  4810. .sfB
  4811. entries for extended index = 30
  4812. .sf
  4813.  
  4814. Here you can enter the minimal number of index entries where the program has to create the extended index instead of the simple index.
  4815.  
  4816. µ:New File Level:
  4817.  
  4818. .sfB
  4819. //HTML text file is divided in several files.
  4820. //Enter heading level where new file begins (0 means only one HTML text file)
  4821. new file level = 3
  4822. .sf
  4823.  
  4824. 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.
  4825.  
  4826. If Frames (window arrangement) is active in a specific area of the text, Hypermake creates a new HTML file for every chapter. 
  4827.  
  4828.  
  4829. Horizontal Rule Level
  4830.  
  4831. .sfB
  4832. //Enter heading level up to which has to be divided by horizontal rules
  4833. //  (0 means no rules)
  4834. horizontal rule level = 4
  4835. .sf
  4836.  
  4837. 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. 
  4838.  
  4839. shown in Contents (also Winhelp3)
  4840.  
  4841. .in context level
  4842. .sfB
  4843. //Enter heading level up to which has to be shown in the HTML content file
  4844. //  (6 means all levels, 0 means no content)
  4845. content level = 6
  4846. .sf
  4847.  
  4848. 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.
  4849.  
  4850. Contents tree view
  4851.  
  4852. .sfB
  4853. //enter NO for non-Javascript or AlternateLinkText;OpenText;CloseText
  4854. contents tree = Link to normal contents view;open tree;close tree (Font X)
  4855. .sf
  4856.  
  4857. The ~contents tree~ setting lets you define three text inputs for the Javascript Contents Tree: "AlternateLinkText" gets a link to the normal unordered list view. "OpenText" and "CloseText" is shown in newer browsers if the mouse pointer is over the graphics files which represents the function open/close the subchapter tree as bubblehelp. In any case, this text is shown instead of the graphics files if the user has chosen "load no images" in the browser (HTML IMG ALT text). Then you can select a font for the Javascript contents tree. A font with the PRE setting is recommended. This omits word wrap inside the tree which would impair the proper formatting of the tree.
  4858.  
  4859. .2
  4860. HTML-2: HTML specific settings, page 2
  4861.  
  4862. .ID P_proj_html_2
  4863. Filename Appearance
  4864.  
  4865. .sfB
  4866. //possible settings: sample.html SAMPLE.HTML Sample.html sample.htm SAMPLE.HTM Sample.htm
  4867. filename appearance = sample.html
  4868. .sf
  4869.  
  4870. 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.
  4871.  
  4872. Warning if Filename not 8.3
  4873.  
  4874. .sfB
  4875. //choose DOS or LONG - DOS means 8.3 filenames, LONG no limit
  4876. filenames = LONG
  4877. .sf
  4878.  
  4879. Hypermake generates a lot of warnings if in the ~filename appearance~ setting a 3 char extension was chosen and Hypermake locates filenames with more than 8 characters length. With the ini file setting ~LONG~ you can omit these warnings.
  4880.  
  4881. pre filename
  4882.  
  4883. (Only ini file, with settings notebook use "Pre Filename" checkbox on the Main page.)
  4884.  
  4885. .sfB
  4886. //pre filename = XYZ* let all HTML files begin with XYZ
  4887. pre filename = *
  4888. .sf
  4889.  
  4890. (Registration required) 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.)
  4891.  
  4892.  
  4893. Identifier for frame/browser window
  4894.  
  4895. .sfB
  4896. default frame = _top
  4897. contents frame = _top
  4898. .sf
  4899.  
  4900. If you are using the WWW, sometimes a new browser window opens. Here the author has used another identifier than "_top".
  4901.  
  4902. 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. The default setting is ~_top~.
  4903.  
  4904. For larger documents it can be useful that the user can open two browsers: One for the contents and one for the text. You can do that when choosing different names for ~default frame~ and ~contents frame~, e.g. "main" and "cont".
  4905.  
  4906. The predefined "Hypermake 4.0" design (settings notebook page HTML-0) uses two different identifiers here.
  4907.  
  4908. footnote appearance
  4909.  
  4910. .sfB
  4911. //choose between ActiveX popup footnotes (ACTIVEX) frame footnotes (FRAMES) or no frames (NOFRAMES)
  4912. footnotes = FRAMES
  4913. .sf
  4914.  
  4915. When creating HTML, you can choose the appearance of the footnotes. In the ini file, setting ~footnotes~ you can choose between ~frames~, ~noframes~ and ~activex~. The activex setting forces popup footnotes and is useful together with HTML-Help. For the activex setting, the user needs a Microsoft browser, so don't use this setting to publish in the Web!
  4916.  
  4917. Heading of notes text
  4918.  
  4919. .sfB
  4920. notes text = notes
  4921. .sf
  4922.  
  4923. If a source file is compiled with the setting or program 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.
  4924.  
  4925. Text in Browser Titlebar, for Searching Machines and in Browser Statusbar
  4926.  
  4927. .sfB
  4928. //here you can define the text appearing in the browser titlebar
  4929. //enter DOCTITLE, HEADING, FILENAME and fixed text, e.g. a slash
  4930. //NO means no text
  4931. file title = DOCTITLE - HEADING
  4932. meta content = DOCTITLE - HEADING
  4933. statusbar mouseover = to chapter: HEADING (file FILENAME)
  4934. statusbar default = DOCTITLE - visit the Homepage regulary!
  4935. .sf
  4936.  
  4937. 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.
  4938.  
  4939. The statusbar text appears in the bottom text field of every HTML-browser. If the mouse pointer is over a link, the text under ~statusbar mouseover~ will appear, otherwise the text defined in the ~statusbar default~ setting.
  4940.  
  4941. It's not possible to use the characters ' and ".
  4942.  
  4943. .END HTMLDOC
  4944.  
  4945. .IF WINHELPDOC
  4946. .2
  4947. Winhelp specific settings
  4948.  
  4949. The "Winhelp specific settings" page concerns both target formats Winhelp and RTF-text.
  4950.  
  4951. .ID P_proj_winhelp
  4952. Do not scroll Headings
  4953.  
  4954. .sfB
  4955. //heading level 123456
  4956. heading fonts = ddcooo
  4957. //omit scrolling of the heading, YES or NO
  4958. keep heading = YES
  4959. .sf
  4960.  
  4961. Winhelp allows to get the heading text fixed, so scrolling the page does not hide the heading text. You can turn off and on this setting.
  4962.  
  4963. Heading Fonts
  4964.  
  4965. .sfB
  4966. //heading level 123456
  4967. heading fonts = ddcooo
  4968. //omit scrolling of the heading, YES or NO
  4969. keep heading = YES
  4970. .sf
  4971.  
  4972. You can choose the fonts for the headings in every heading level. Every character is a font char which represents a font. Normally you will choose bigger fonts for the higher heading levels (1, 2). Of course these font chars have to be defined in the settings notebook, page Font or in the ini file, setting ~Font =~.
  4973.  
  4974. List indention
  4975.  
  4976. .sfB
  4977. //influences the left margin command and the indention of lists
  4978. list indention = 4
  4979. .sf
  4980.  
  4981. Here you can influence globally the size of the left margin when using the .LM dot command and the size of the indention when writing sorted lists and unsorted lists.
  4982.  
  4983. Default Font Size
  4984.  
  4985. .sfB
  4986. //default value is 10
  4987. default font size = 10
  4988. .sf
  4989.  
  4990. The default Windows font for help windows is a small and thin font (~10~). The font size ~11~ is only a little bigger, but thicker than ~10~. I cannot recommend a bigger font size than ~12~.
  4991.  
  4992. Create HLP-internal contents
  4993. Create External CNT file
  4994.  
  4995. .in contents creation
  4996. .sfB
  4997. //enter CNTFILE, INTERNAL, BOTH or NO
  4998. contents creation = BOTH
  4999. .sf
  5000.  
  5001. This setting is independent from the WINHELP3/WINHELP4 ~target format~ setting (page General). An internal contents is a contents page in the HLP file - here the yet HTML specific "contents level" setting (page HTML-1) is interpreted. So you can create a contents page with only 2 heading levels. 
  5002.  
  5003. The Winhelp4 format has got an external Contents file (CNT file). Please note that you have to ship the CNT file together with the HLP file.
  5004.  
  5005. It can make sense to let create both contents simultaneously together with the WINHELP3 target format. In this case, the help file can be read on all Windows systems. Nevertheless, Windows 95 and NT users can use the CNT tree view contents.
  5006.  
  5007. "CNT" General Text
  5008.  
  5009. .snB
  5010. //heading text for the subchapter containing the text
  5011. //of the main chapter in CNT files
  5012. contents general text = General
  5013. .sf
  5014.  
  5015. The CNT file format has got a very bad design: A main chapter cannot point to a page with explaining text before the sub chapters begin. But that's the normal form of text documents. Hypermake creates a new first sub chapter where this text is placed. Here you can change the heading text of this first sub chapter. 
  5016.  
  5017. Printed List chars
  5018.  
  5019. .sfB
  5020. //character which is the left fat dot in lists, in different list levels
  5021. printed listchars = oooo
  5022. .sf
  5023.  
  5024. You can choose which character is the "left fat dot" in unordered lists, one character for every list level. You are allowed here to use bitmap characters (command .BT bitmap text).
  5025.  
  5026. .2
  5027. Rich text format specific settings
  5028.  
  5029. .ID P_proj_rtftext
  5030. When generating RTF text (rich text format), most settings on the "Winhelp" settings page are interpretated.
  5031.  
  5032. Color correction
  5033.  
  5034. .sfB
  5035. //enter yes or no
  5036. Color correction = YES
  5037. .sf
  5038.  
  5039. When generating a RTF file for importing into a wordprocessing program, a color table is generated at the beginning of the file. This determines the colors for the fonts used in the RTF file. The problem is that Winword interpretates this table different from all other programs. If you want to import the RTF file to Winword, then turn the color correction off, otherwise on. Even Windows Wordpad interpretates the color table different from Winword. If the colors of the font are imported wrong, please change this setting.
  5040.  
  5041. automatic heading enumeration
  5042.  
  5043. .sfB
  5044. //enter yes or no
  5045. automatic heading enumeration = YES
  5046. .sf
  5047.  
  5048. If you turn this switch on, Hypermake generates a RTF code for the heading level instead of the text e.g. "7.2.3". The majority of wordprocesssing software interpretate this code. If this setting is switched off, the enumeration text "7.2.3" is normal text.
  5049.  
  5050. Wordprocessing software programs like Winword have got the ability to create a content with page numbers for each heading automatically. But this functionality is only available if the automatic heading generation is activated.
  5051.  
  5052. .END WINHELPDOC
  5053.  
  5054. .2
  5055. Help file specific settings (not HTML)
  5056.  
  5057. .ID P_proj_help
  5058. Help Start ID Value (only IPF)
  5059.  
  5060. .sfB
  5061. Help Subtable Start ID = 7000
  5062. .sf
  5063.  
  5064. 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.).
  5065.  
  5066. Helptable Filenames (only IPF)
  5067. Panel ID Filename
  5068.  
  5069. .sfB
  5070. //files will be overwritten without warning
  5071. Helptable filename = HLPTABLE.RC
  5072. Panel ID filename  = PANELID.H
  5073. .sf
  5074.  
  5075. 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.
  5076.  
  5077. The Panel ID file defines constants in your program source code whichs represents a chapter of your help text. On the "format" page of the settings notebook, you can select the programming language C or Pascal.
  5078.  
  5079. Note: The helptable file and the Panel ID file will be overwritten without warning.
  5080.  
  5081.  
  5082. .WA verti 25
  5083. .1
  5084. About
  5085.  
  5086. .in Hypermake
  5087. .id P_about
  5088.  
  5089. .2
  5090. Registration
  5091.  
  5092. .in Registration
  5093. .in price
  5094. .afE
  5095. 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.~
  5096.  
  5097. 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. If you write a Freeware program with a documentation which exceeds the 20 kB limit, I will send you the registration key for free.
  5098.  
  5099. 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 ~45 Euro~ for the small registration key and ~90 Dollar~ or ~102 Euro~ for the big one.
  5100.  
  5101. When ordering more than one licenses, you will get a 30% discount for every additional license.
  5102.  
  5103. .URL http://www.bmtmicro.com
  5104. .in BMT Micro
  5105. .LOCAL
  5106. You can register this software by sending a Mail to BMT Micro, see BMTORDER.TXT or via Web Browser and Atlantic Coast Soft Shop http://www.swreg.org, search "Hypermake".
  5107. If you have got a bank account in an Euro country, you can transfer the money to my bank account in Germany Dresdner Bank Ottobrunn, german bank code 700 800 00, account Nr. 075 64 62 400.
  5108.  
  5109. The registration key has to be placed in your Hypermake ini files or in the project settings notebook, page "General". The key fits for all platforms and all future versions.
  5110.  
  5111. .2
  5112. Disclaimer
  5113.  
  5114. 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.
  5115.  
  5116. .2
  5117. Author
  5118.  
  5119. .in Author
  5120. Martin Vieregg, 36. I've studied economics. My main job is working in my own consulting company. Our special subject is public transport, especially railways and airports. The title of my doctoral (PhD) thesis was "increasing efficiency of railway long-distance passenger traffic".
  5121.  
  5122. .in Contacting the author
  5123. .in E-Mail
  5124. E-Mail address: Martin@vr-transport.de
  5125.  
  5126. Homepage of my Freeware- and Shareware programs:
  5127.  
  5128. http://www.hypermake.com
  5129.  
  5130.  
  5131. Postal Address:
  5132.  
  5133. Dr. Martin Vieregg
  5134. Emdenstr. 11
  5135. D-81735 Munich
  5136. (Germany)
  5137.  
  5138. .2
  5139. Versions
  5140.  
  5141. .in program versions
  5142. .sfE
  5143. Ideas for future versions
  5144. .sf
  5145.  
  5146. If you have bug reports and ideas for new functionality, please E-Mail me!
  5147.  
  5148. I want to publish a Linux version in the future.
  5149.  
  5150. I am not planning to implement µPDF target format (µ:Adobe portable document format:), because there are a lot of good converters from RTF-Text to PDF. But if you miss specific RTF-text functionality to get a better source for generating PDF, please tell me your ideas.
  5151.  
  5152. .sfE
  5153. Hypermake 4.0
  5154. .sf
  5155.  
  5156. The development of the graphical version of Hypermake was a lot of work. In this time (from 3.66 to 4.0), I set the focus to the development of the graphical environment and not to the functionality. Nevertheless, I made some work for improving functionality:
  5157.  
  5158. ■ A fifth target format is now implemented: RTF text (rich text format) for importing Hypermake documents into word processing software; you can use this format to get a paper print of your document. Because this format is very similar to RTF Winhelp files, you can use the Winhelp settings.
  5159.  
  5160. ■ (HTML) Improvement of Javascript navigation buttons and of frames, font selection for contents text and for the navigation lines (first line, last line). These improvements culminates in a new combination of project settings (page HTML-0, "Hypermake 4.0 design").
  5161.  
  5162. ■ a file comparison functionality enables locating the changed HTML files of a HTML project
  5163.  
  5164. ■ Some new program parameters for the user interface of the commandline version HMAKE.EXE, returncodes
  5165.  
  5166. ■ Some minor, not remarkable bugfixes.
  5167.  
  5168. .sfE
  5169. new functions in Hypermake 3.65
  5170. .sf
  5171.  
  5172. ■ improved table functionality, new dot command .TW table word wrap
  5173. ■ user-defined internal numbering of headings and files (HTML)
  5174. ■ ignore uppercase letters when creating links
  5175. ■ Bitmap Directory for HTML graphics
  5176.  
  5177. .sfE
  5178. new functions in Hypermake 3.60
  5179. .sf
  5180.  
  5181. ■ content tree view for HTML by using Javascript (can be viewed by all default browsers)
  5182. ■ statusbar text for internal links
  5183. ■ extended functionality in HTML tables
  5184.  
  5185. .in new version
  5186. .sfE
  5187. new functions in Hypermake 3.5:
  5188. .sf
  5189.  
  5190. ■ support of the Winhelp format
  5191. ■ reverse converting mode RTF to Hypermake
  5192. ■ support of the new Microsoft context-sensitive HTML format
  5193. ■ HMP files as a mouse substitute for the commandline
  5194. ■ Hypermake also available in a DOS version
  5195. ■ Javascript navigation buttons and ActiveX footnotes
  5196. ■ copying graphic files automatically 
  5197. ■ manual external links and automatic external links to the WWW for all source formats besides Winhelp3; marking external links
  5198. ■ HTML info file
  5199. ■ improved embedding of HTML commands
  5200.  
  5201. .sfE
  5202. new functions in Hypermake 3.0:
  5203. .sf
  5204.  
  5205. ■ tables both for IPF and HTML
  5206. ■ user-defined navigation buttons in addition to back, forward, content, index, pointing to specific chapters or URLs
  5207. ■ user head tags (meta entries) copying into every HTML file
  5208. ■ settings for the appearance of filenames (small/capital letters, 8.3 convention)
  5209. ■ settings for the titlebar text in the HTML browser
  5210. ■ commands for bugfixing
  5211. ■ settings for appearance of links to subchapters
  5212. ■ more flexible usage of toggle chars
  5213. ■ HTML fonts
  5214. ■ Library of Buttons.
  5215.  
  5216. .sfE
  5217. new functions in Hypermake 2.9:
  5218. .sf
  5219.  
  5220. ■ target file format HTML in addition to IPF
  5221. ■ reverse converting mode from IPF to Hypermake
  5222. ■ index filter
  5223. ■ many source files (see commandline parameters)
  5224. ■ (2.91) first version also available as a Win32 program
  5225. ■ (2.91) footnotes also for HTML.
  5226.  
  5227. .sfE
  5228. bugfixes in (new name) Hypermake 2.9:
  5229. .sf
  5230.  
  5231. ■ "link to subchapters = NO" created a malfunction
  5232. ■ Together with IPFC Version 2.1 (1993) and the  "ASCIIHARDRET" setting, in larger paragraphs a space was missing after 200 chars.
  5233. ■ With the "ASCIIHARDRET" setting, malfunctions with unsorted lists occured.
  5234.  
  5235. .sfE
  5236. new functions in µMakeIPF 2.0:
  5237. .sf
  5238.  
  5239. ■ external links to separate HLP- and INF-files
  5240. ■ launching programs by hyperlinks
  5241. ■ automatic duplication of heading text in the text window, heading text gets link target and is placed in the index
  5242.  
  5243. ■ more detailed error messages, so running IPFC will create fewer error messages
  5244. ■ tabs are converted into a number of spaces like an editor does (use only with non-proportional fonts)
  5245. ■ improved window arrangement
  5246. ■ registration via Compuserve
  5247.  
  5248. .2
  5249. Bug report
  5250.  
  5251. .in bug report
  5252.  
  5253. ■ All Hypermake versions before 3.94 crash immediately with Windows NT 4 Servicepack 4 or later, also in Windows 2000.
  5254.  
  5255. There were some minor bugs in Hypermake 3.66 which are not documented. The bugs in the graphical beta version 3.9X were not documented, too, because the number of bugs is too large. For 4.0 and later, I will report again all occuring bugs.
  5256.  
  5257. The following Hypermake 3.65 bugs are fixed in 3.66:
  5258.  
  5259. ■ 3.65.01 (only Win95/NT version), double clicking to the HMP file won't activate the second compiler
  5260. ■ 3.65.02 When compiling Winhelp, .SL (sorted lists) numbering don't reset after a higher level list entry
  5261. ■ 3.65.03 When compiling Winhelp, the output centered command (.OC) is corrupted
  5262.  
  5263. The following Hypermake 3.60 bugs are fixed in 3.65:
  5264.  
  5265. ■ 3.60.01: When compiling Winhelp and the source ends with an (ordered/unordered) list, a bug occurs (more { than }).
  5266. ■ 3.60.02: when reverse compiling IPF to Hypermake, in the :h1. command there have to be more than 2 chars between : and .
  5267. ■ 3.60.04: mailto:emailaddress won't get a link.
  5268. ■ 3.60.05: ASCIISOFTRET together with target Winhelp forces missing spaces in running text.
  5269. ■ 3.60.06: (oops, that was not a bug, it's necessary because of a bug in the Winhelp Compiler/viewer) If a CNT file ends with a main chapter without subchapters, a "general" chapter is created nevertheless.
  5270. ■ 3.60.07: Tables: The " sign for enlarging the cell height does not work when it's in the first table column.
  5271.  
  5272. Former bugs are not reported.
  5273.  
  5274. .2
  5275. Download Location
  5276.  
  5277. An easy way for uploading is my Homepage
  5278.  
  5279. http://www.hypermake.com
  5280.  
  5281. In Compuserve, you will find the latest OS/2 version of Hypermake in Compuserve IBMUSER and the Win95/NT version in the HYPERTEXT forum.
  5282.  
  5283. In the internet, the versions for all platforms are available on ftp://ftp.bmtmicro.com/bmtmicro
  5284.  
  5285. Filenames:
  5286. OS/2 version: hmakeos2.zip
  5287. Win95/98/ME/NT/Win2000/XP version: hmakewin.zip
  5288. DOS version: hmakedos.zip
  5289.  
  5290. Archive file names with version number (e.g. hmake400.zip) are usually the Windows version.
  5291.  
  5292. The filesize of the Hypermake archive file is 1,75 MB for the Windows and 1,25 MB for the OS/2 version and only 300 kB for the DOS version because the DOS version includes only the commandline version and has no pre-compiled help.
  5293.  
  5294. .2
  5295. Trademarks
  5296.  
  5297. IBM and OS/2 is a registered trademark of International Business Machines Corp.
  5298. WordStar is a trademark of The Learning Company.
  5299. SpeedPascal is a trademark of SpeedSoft GmbH.
  5300. TurboPascal is a trademark of Borland Corp.
  5301. Windows is a trademark of Microsoft.
  5302.  
  5303. .2
  5304. Platforms
  5305.  
  5306. .it several platforms
  5307. 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 Speedsoft SpeedPascal http://www.speedsoft-online.de . It's a cross compiler generating both OS/2 and Win32 programs. A Linux is also planned, so Hypermake will be available for Linux in the future, too. 
  5308.  
  5309. The DOS version is compiled with TurboPascal and does not use extended memory. The source file length is limited to 1 up to 4 MB, dependent on the number of links. Theoretically, Hypermake for DOS runs on a old XT computer. So Hypermake DOS should run without problems on all operating systems where a simple DOS emulation software is available (e.g. Linux). The Pentium-300 bug of all TurboPascal programs (too much speed) is not fixed. The graphical 4.0 version won't be available for DOS, but the commandline version will be supported in the future.
  5310.  
  5311. .IF NOT OS2
  5312. Do you think the IBM IPF Hypertext format is absolutely not interesting for you? Do you write Windows programs? Then you should think about porting your program to OS/2. Windows programmers often don't know that shipping an OS/2 version can be very attractive. Here some facts and remarks:
  5313.  
  5314. ■ IBM has lost the home user fight against Microsoft, but nevertheless OS/2 is very important in companies. A number of small companies, especially in Europe, are using OS/2 and cannot change to Windows NT because of high migration costs. Some bigger companies have changed to OS/2 in 1997. There are two times more OS/2 installations than Macintosh installations. IBM has committed to OS/2 for the next ten years and the frequency of service packs is higher than Microsoft does for NT.
  5315.  
  5316. ■ About my Shareware Programs, I can report that I get more registrations from OS/2 users than from Windows users. That means the "advantage" of the lack of OS/2 programs is bigger than the disadvantage of the small number of OS/2 installations.
  5317.  
  5318. ■ Porting Windows programs to OS/2 is not very difficult. 700 of the most important Win32 API functions are supported since Warp 4 ("Open32" extension, also part of Warp 3 fixpacks). A lot of C++ libraries are available for OS/2. Delphi programs can be (nearly) recompiled with VirtualPascal or SpeedPascal. Pure 32 bit code without I/O or system operations is nearly full compatible, because OS/2 is also an intel-based operating system, in comparison to Macintosh.
  5319.  
  5320. ■ Last but not least, Hypermake generates OS/2 help files.
  5321. .END
  5322.  
  5323. .2
  5324. Other progs
  5325.  
  5326. Other programs I have written, both Windows 95/98/ME/NT/2000/XP and OS/2 (Linux versions for some programs are planned)
  5327.  
  5328. .in WSedit
  5329. WSedit:
  5330. The Hypermake editor as an own program with additional functionality. Compatible to Wordstar: reading and writing Wordstar (DOS) files, ASCII IBM and ISO codepage. Supports Wordstar Ctrl key commands and CUA commands. Syntax-highlightning, Translation, spell checking, function key macro recorder and a lot of other features. WSedit handles very large ASCII files. Freeware. 
  5331.  
  5332. pmCalc: a "pocket" calculator automatic clipboard functionality, programmers and scientific functions, Regression. There's a separate input and output field, the formula you type rests in the input field. (Shareware)
  5333.  
  5334. TinyAlarm:
  5335. A simple countdown with a slider from 1 to 60, an alarm by entering alarm time and a chime. System shutdown. Freeware. 
  5336.  
  5337. cd-shortcut:
  5338. instead of whole directory names you enter only substrings. Searching through several drives and opening OS/2 WPS folders. Freeware.
  5339.  
  5340. Simple Zipshell:
  5341. Packing and unpacking ZIP files by using the graphical desktop. Freeware. 
  5342.  
  5343. Clear:
  5344. (only OS/2) Uses also Info-Zip and let you backup your data e.g. on floppies. You can enter filenames like *.BAK which are not copied, directories which are skipped. Then you can enter filenames with a specific age which are deleted. Freeware.
  5345.  
  5346. For more information, screenshots and downloads, visit my Homepage
  5347.  
  5348. http://www.hypermake.com
  5349.  
  5350. end of hypertext
  5351. ..
  5352. ..external link to my Homepage and to the Library of Buttons
  5353. .URL http://www.hypermake.com
  5354. .ID HOMEP
  5355. .in my Homepage
  5356. .in Hypermake Homepage
  5357. .IF WINHELP or IPF
  5358. .URL ..\buttons\content.htm
  5359. .ELSE
  5360. .URL ..\..\buttons\content.htm
  5361. .END
  5362. .in Library of Buttons
  5363. .LOCAL
  5364.