Power-Programmierung

home *** CD-ROM | disk | FTP | other *** search

/ Power-Programmierung / CD2.mdf / c / library / mslang / mh / mh.txt < prev next >

Wrap

Text File | 1993-09-04 | 17.1 KB | 570 lines

MINIHELP Create Microsoft Windows Help Files in a flash! Requirements: Microsoft Windows The HC31.EXE help compiler or its equivalent An ASCII text editor such as QEDIT or NotePad. Copyright 1993 by Tom Campbell. All Rights Reserved. You may use MiniHelp any way you like, as long as you preserve the copyright notices. This distribution contains: MH.EXE -- The MiniHelp preprocessor MH.TXT -- You're reading it! MC.C -- Source code to MiniHelp TEST?.HPJ -- Sample help project files. TEST?.SRC -- Sample MiniHelp source files. WHAT IT IS If you've ever tried to create topic source files for the Microsoft Windows Help compiler (HC from here on in), you know it's a pain. Commendably enough, Microsoft has made the input to HC a subset of RTF or Rich Text Files. Not all word processor support RTF, though. Even when they do, using RTF isn't exactly intuitive. Finally, you're probably used to your own text editor and not all that excited about changing. MiniHelp works as a go-between, taking its simplified language as input and creating as output Help-compliant RTF topic files. It offers only a few commands, a mere fraction of the rich language that HC understands, but those commands are the ones you'll use by far the most often. You can create the first pass using MiniHelp and add things like buttons and graphics using RTF later, or just stick with MiniHelp. MiniHelp supports easy-to-use versions of these topic file features: - Topic names - Titles - Keywords - Hypertext links - Font sizing - Comments That's pretty much it. I have created complete help systems using nothing but MiniHelp because it's fast and easy. You can of course include standard RTF commands within a MiniHelp script, but once you change the output .RTF file, you can't read the .RTF file back into MiniHelp to recreate the MiniHelp source with the changes you added. It's a one-way process. (Quit complaining. It's free, after all!) EXAMPLES Here's a before-and-after example of MiniHelp in action. This is a minimum help topic file in RTF. It contains a topic name, a title, and a few words of text. {\rtf1\ansi \deff2 {\fonttbl {\f0\froman Times New Roman;} {\f1\fdecor Courier New;} {\f2\fswiss Arial;}} #{\footnote SuperNoteOverview} ${\footnote A SuperNote Overview} Supernote lets you write several different notes at once. \page } Here's the equivalent file written using MiniHelp: .topic SuperNoteOverview .title A SuperNote Overview Supernote lets you write several different notes at once. As you can see, even if you have an RTF-capable editor, MiniHelp source files resemble the organization of Windows help files much more closely. And there's a lot less to keep track of. You must remember to end each topic in the RTF file with a \page command, you must remember to end the RTF file itself with a closing curly brace, you must remember to end font names with a semicolon, etc. MiniHelp lets you forget all that and concentrate on getting the job done. The example above lacked a feature or two, notably keywords and hypertext links. Here's a multitopic help file with table of contents, keywords, titles, and hypertext links. .topic TOFC .title Table of Contents Table of Contents {Find a file anywhere on the disk with FF.EXE:FileFind} {Finding Today's Files with All2Day:All2day} .topic FileFind .title Find Files on Your Disk .keyword FF.EXE;FileFind;files, finding;finding files FileFind, or FF.EXE, lets you find files anywhere on your disk. Use it in conjunction with {ALL2DAY.EXE:all2day}, which lets you find all the files you created today. See also {Table of Contents:TOFC} .topic All2Day .title Finding the Files You Created Today .keyword All2Day;ALL2DAY.EXE;Today Whereas {FileFind (FF.EXE):FileFind} searches for the specfied file anywhere on your hard disk, All2Day searches the default disk for all files created today. See also {Table of Contents:TOFC} This may look a bit complex, and it is. But compare it to the RTF version: {\rtf1\ansi \deff2 {\fonttbl {\f0\froman Times New Roman;} {\f1\fdecor Courier New;} {\f2\fswiss Arial;} } #{\footnote TOFC} ${\footnote Table of Contents } \par {\uldb Find a file anywhere on the disk with FF.EXE}{\v FILEFIND} \par {\uldb Finding Today's Files with All2Day}{\v ALL2DAY} \par \page #{\footnote FileFind} ${\footnote Find Files on Your Disk} K{\footnote FF.EXE} K{\footnote FileFind} K{\footnote files, finding} K{\footnote finding files} FileFind, or FF.EXE, lets you find files anywhere on your disk. Use it in conjunction with {\uldb ALL2DAY.EXE}{\v ALL2DAY} , which lets you find all the files you created today. \par See also {\uldb Table of Contents}{\v TOFC} \par \page #{\footnote All2Day} ${\footnote Finding the Files You Created Today} K{\footnote All2Day} K{\footnote ALL2DAY.EXE} Whereas {\uldb FileFind (FF.EXE)}{\v FILEFIND} searches for the specfied file anywhere on your hard disk, All2Day searches the default disk for all files created today. \par See also {\uldb Table of Contents}{\v TOFC} \page } As you can see, keeping track of all those nested curly braces and backslash commands gets old fast. MiniHelp can save you from all that. CHAPTER 1. OVERVIEW MiniHelp creates help topic files. A topic file contains one or more of the following: 1. A topic 2. A title 3. Keywords (optional, but strongly recommended) 4. The topic text itself You can have multiple topics in a topic file. The only constraint is that topics be given unique names. Titles are not so constrained. The Microsoft Help Compiler (HC) doesn't use the topic file directly, however. You give it the name of a help project file instead. The help project file has a default extension of .HPJ and contains a list of the topic files. There's a lot going on in a help project file, but you can safely ignore all but the [FILES] section. That's the section that names the topic files. Here's an example of a complete help project file named TEST1.HPJ: [FILES] TEST1A.RTF You have to create the project file yourself; MiniHelp can't do it because it doesn't know what files are in the project. The files listed must include full pathnames with extensions. Normally, you'll have only one project per directory and keep all the topic files in that directory. In some cases you might not want it that way; for example, if you have a standard help topic file for the File menu with such unchanging features as Save As, Print Setup, and so on, you might wish to keep them in a common directory to avoid duplicated effort and maintainence problems. HC "automatically" creates a table of contents; it's whatever happens to appear on the first screen of the topic. See TEST2.* for an example. At any rate, include all of the topic files in your help project file. They may include cross-file references; that is, a topic doesn't have to be in file A as long as it appears in file B. The next chapter shows you how to create the topic files using MiniHelp. CHAPTER 2. CREATING A MINIHELP SOURCE FILE MiniHelp source files contain the text of the help, "dot commands", and hypertext links. That's all. They get converted into the .RTF files that HC needs to create binary .HLP files for Microsoft Windows. A dot command starts the line with a period, a.k.a. dot, and contains a single dot command. Each dot command has at at least one operand. The line should contain nothing else. If you're used to old-fashioned programs such as troff, WordStar, or TeX, this will be old hat. Dot commands can be in upper, lower, or mixed case. It doesn't matter. Here's a summary of the dot commands, in rough order of importance: Dot command What it does ----------- ------------ .topic Creates a location for the topic. Does not appear. .title Creates the text used in Search and History dialogs. .keywords Creates alternate text for Search dialogs. .fontsize Lets you specify a font size in points. In addition to the dot commands, there are: Text What it does ---- ------------ Blank lines Appear as carriage returns in output file hypertext link Lets the user jump to a different topic Comments Start line with a ';'. The line is ignored and not sent to output. Everything else (Called the topic text) Appears literally Remember that word wrap isn't as it appears in the file for the topic text. Here are the rules for for word wrap: 1. The first character on lines after the first one must be preceded by a space if you want them to be separated from the preceding words 2. You can force a break using a newline. Here's the reference to Minihelp in alphabetical order. The next chapter shows complete code examples. KEYWORD: .fontsize FORMAT: .fontsize <integer> WHAT IT DOES: Lets you specify a font size in points. EXAMPLES: .fontsize 10 .fontsize 12 ------------------------------------------------------------------- KEYWORD: .keywords FORMAT: .keywords <word or phrase> .keywords <word or phrase>;<word or phrase>;...<word or phrase> WHAT IT DOES: Creates alternate text for Search dialogs. Clicking on these keywords in the Search dialog will jump to the current topic. The keywords may consist of more than one word, and may include or start with numbers. You may specify more than one keyword by separating them with semicolons. You can also use ".keyword", without the "s", if you have just one keyword on the line. But you don't have to. EXAMPLES: .keyword File .keywords File;File menu;Open;Exit;Save As...;Save ------------------------------------------------------------------- KEYWORD: (link) FORMAT: {<text to display>:<topic identifier>} WHAT IT DOES: Hypertext links aren't dot commands, but they're critical to the creation of good help files. Links are embedded in the topic text. The first part of a link is a left curly brace, the '{' character. Then comes one or more words of a phrase that will be displayed underlined and in green on the help screen. This phrase is followed by a colon separator, the ':' character, and a single-token topic identifier. Finally, there's a closing curly brace '}' character. EXAMPLES: See the {File menu:FileMenu} for more details. See also the {Options menu:Options_Menu} and the {View menu:View_1_A0}. ------------------------------------------------------------------- KEYWORD: .title FORMAT: .title <title text> WHAT IT DOES: Creates the text used in Search and History dialogs. <title text> may consist of more than one word. EXAMPLES: .title The File Menu .title Table of Contents .title Printing ------------------------------------------------------------------- KEYWORD: .topic FORMAT: .topic <identifier> WHAT IT DOES: Creates a location for the topic. Does not appear. <identifier> follows the same rules as variables in programming languages. It must start with a letter, and may consist only of letters, underscores, and numbers. It may not include any spaces, tabs, or punctuation marks. EXAMPLES: .topic FileMenu .topic Options_Menu .topic View_1_A0 ------------------------------------------------------------------- CHAPTER 3. Examples Here are two brief, step-by-step examples listing all the steps required to create and run a help file. Example 1. The bare minimum --------------------------- This example creates a file so simple, it has no keywords and a single screen that serves as both the table of contents and a topic. 1. Create a file called TEST1.SRC with these contents: .topic SuperNoteOverview .title A SuperNote Overview Supernote lets you write several different notes at once. 2. Create a file called TEST1.HPJ with these contents: [FILES] TEST1.RTF 3. Run MiniHelp on TEST1.SRC: rem Remember that .SRC is the default extension rem used by MH. mh test1 This creates the output file TEST1.RTF. 4. Run HC on the .HPJ file: rem Remember that .HPJ is the default extension rem used by HC. hc31 test1 HC plucks the file named TEST1.RTF, which was automatically generated from TEST1.SRC by MiniHelp, out of the [FILES] list of TEST1.HPJ and compiles it. 5. Run WinHelp on the resultant .HLP file. For example, if you're working in the C:\MH directory, choose Run... from the Program Manager's File dialog and enter this: winhelp c:\mh\test1 Example 2. Soup to Nuts ----------------------- This example creates a short file showing off most of MiniHelp's features. This is much closer to what you'll normally do when you create help for a real-life project. 1. Create a file called TEST2.SRC with these contents: .topic TOFC .title Table of Contents Table of Contents {Find a file anywhere on the disk with FF.EXE:FileFind} {Finding Today's Files with All2Day:All2day} .topic FileFind .title Find Files on Your Disk .keyword FF.EXE;FileFind;files, finding;finding files FileFind, or FF.EXE, lets you find files anywhere on your disk. Use it in conjunction with {ALL2DAY.EXE:all2day}, which lets you find all the files you created today. See also {Table of Contents:TOFC} .topic All2Day .title Finding the Files You Created Today .keyword All2Day;ALL2DAY.EXE;Today Whereas {FileFind (FF.EXE):FileFind} searches for the specfied file anywhere on your hard disk, All2Day searches the default disk for all files created today. See also {Table of Contents:TOFC} 2. Create a file called TEST2.HPJ with these contents: [FILES] TEST2.RTF 3. Run MiniHelp on TEST2.SRC: rem Remember that .SRC is the default extension rem used by MH. mh test2 This creates the output file TEST2.RTF. 4. Run HC on the .HPJ file: rem Remember that .HPJ is the default extension rem used by HC. hc31 test2 HC plucks the file named TEST2.RTF, which was automatically generated from TEST2.SRC by MiniHelp, out of the [FILES] list of TEST2.HPJ and compiles it. 5. Run WinHelp on the resultant .HLP file. For example, if you're working in the C:\MH directory, choose Run... from the Program Manager's File dialog and enter this: winhelp c:\mh\test2 6. Try jumping from topic to topic and using keyword searches. You'll find that this is beginning to look like a help file someone could actually use. CHAPTER 4. THE SOURCE CODE You can use this source code in your own projects. It's quite modular, and uses some general-purpose routines with wide ranging applications: void AddExtension(char *str, char *ext); ------------------------------------------------------------- Adds an extension to a filename if it doesn't have one. int Parse(char *Input, char *Separators, WORD StartAt, BOOL ForceUpper, WORD MaxLen, char *Buffer); ------------------------------------------------------------- A reentrant routine that parses lines of text. Somewhat like strtok(), but a little more unwieldy, nondestructive, and a lot more flexible. void ReplaceExtension(char *Filename, char *Ext); ------------------------------------------------------------- Replaces the file extension, or adds one if none is present. int StripExtension(char *input); ------------------------------------------------------------- Removes a file extension. int UpStr(char *Str); ------------------------------------------------------------- Forces a string to uppercase Copyright 1993, by Tom Campbell. All Rights Reserved. Use this code any way you wish, as long as you preserve the copyright notice.