Power-Programmierung/CD2.mdf/c/library/mslang/mh/mh.txt

Text File | 1993-09-04 | 18KB | 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.