ODE97: Tips for Creating and Compiling Your Windows Help File

• Microsoft Office 97 Developer Edition

SUMMARY

Moderate: Requires basic macro, coding, and interoperability skills.

This article contains helpful hints on how to create and compile your Windows Help files using the Windows 4.0 Help Compiler that is included in the Windows Help Workshop. It explains the necessary steps, the tools that you will need, and some of the problems you may encounter.

MORE INFORMATION

Windows Help files consist of topic files and project files. You can create your topic files using a word processor, such as Microsoft Word. You can create your project files using Microsoft Help Workshop. The following steps are involved in creating your Windows Help file:

1. Creating Your Topic file in a Word processor.

2. Creating Your Project file.

3. Compiling and Viewing Your Windows Help file.

4. Troubleshooting Problems You Encounter Creating Your Windows Help File.

Creating Your Topic file in a Word Processor

A topic file contains the words and pictures that make up your Help file. It is usually divided into logical sections, or topics, that users can search through by clicking hot spots, using keyword searches, or browsing through the topics.

NOTE: Microsoft Word 97 produces a Rich Text file that is incompatible with Microsoft Help Compiler 4.0. For more information about this problem, please see the following article in the Microsoft Knowledge Base:

   ARTICLE-ID: Q164012
   TITLE     : Error Compiling Word 97 RTF in Help Compiler, Help Workshop.

 ~ HCWSETUP.EXE (size: 1596080 bytes) 

For more information about downloading files from the Microsoft Software Library, please see the following article in the Microsoft Knowledge Base:

   ARTICLE-ID: Q119591
   TITLE     : How to Obtain Microsoft Support Files from Online Services

• Before you start, take time to plan what you want to accomplish with your Windows Help file. Determine the topics you want to include and the best place to include them in your application.
• For the sake of simplicity, keep all of the component files for your Windows Help file in the same folder on your hard disk. This will help eliminate problems you may encounter referencing the files when you try to compile or open your Windows Help file.
• Remember to save your topic file in the .rtf format.
• If you are adding pop-up text or jump text in your topic file that will be followed by punctuation, be sure to format the punctuation in the same way that you format the pop-up or jump.
• If you need to save space, add graphics to a topic file by including a bitmap statement.

For information about creating context-sensitive help for your application, please see the following articles in the Microsoft Knowledge Base:

   ARTICLE-ID: Q141621
   TITLE     : ACC: How to Create Pop-up Context Sensitive Help (95/97)

   ARTICLE-ID: Q90808
   TITLE     : HelpContextID Property Accepts Valid Negative Values

   ARTICLE-ID: Q103179
   TITLE     : ADT/ODE: Help Topic Does Not Exist Err Invoking Custom
               Help File

Creating Your Project File

After you have successfully created your topic file, you will need to create a project file. Project files contain information about the location of your topic and graphic files. They also contain settings that customize the way your Help file looks and functions. You can use the Help Workshop to compile your project file.

For information about using the Help Workshop for compiling your project file, please see the topic "Creating a Project File" in the Help Workshop Help Index.

NOTE: If you use the Training cards on the Help Menu for assistance in creating a project in the Help Workshop, when you get to the last card, the Close button will not dismiss the Final Training card. You must manually close the card by click the Close button in the upper-right corner of the window or by pressing ALT+F4 on the keyboard.

Compiling and Viewing Your Windows Help File

Once you have created your project file, you can compile and view your Help file in Help Workshop. To compile your Help file, follow these steps:

1. On the File menu, click Compile.

2. In the "Compile a Help File" dialog box, select your project file in the Project File list box. If your project file does not appear in this list box, click the Browse button to search for it.

3. When your project file is displayed in the Project File list box, click Compile.

4. If Help Workshop reports any errors while compiling the topic file, you will need to check your topic file and project file for errors. Help Workshop stores error messages in the MyHelp.err file. When your Windows Help file compiles without errors, it is ready to be distributed with your application.

Troubleshooting Problems You Encounter Creating Your Windows Help File

The following section describes problems you may encounter while creating and compiling your Windows Help file and offers suggestions on how to solve them.

• Your Help file does not reflect the change you made in a topic file.

  You did not save your topic file before compiling. Save your topic file and compile again.

• There are other Help files on your computer with the same name.

  Check for duplicate versions of your Help file in different folders or directories on your computer. Delete or rename all duplicates.

• Bulleted and numbered lists do not look right on screen.

  If you are using Microsoft Word to create your topic file, use the Bullets or Numbering buttons on the Formatting toolbar. If you are using another word processing program, you should check that application's documentation for instructions about creating bulleted or numbered lists.

  If you want to create lists with hanging indents, but do not want to use your word processing program's commands for automatically creating them, you must set a tab stop on the first line, even with the hanging indent. Otherwise the first line will not tab correctly between the bullet or number and the text.

• Characters in Help appear different than in your topic file.

  You may be using a font in your topic file that is not available on the computer you are using to view the Windows Help file. WinhHelp will substitute the font with a Windows 95 font if your font is not on the computer. To ensure that the characters match on screen and in the topic file, follow these steps:

      a. Use only fonts supplied with Windows 95.
  

         Windows 95 automatically installs the following TrueType fonts:
  

          - Arial
          - Times New Roman
          - Courier
          - Symbol
          - Wingdings
  
         Windows 95 automatically installs the following Raster fonts:
  
          - MS Serif
          - System
          - MS Sans Serif
          - Terminal
          - Courier
  
      b. Create a bitmap representation of characters that are not
         supported by the Windows 95 font character sets, and insert the
         bitmap(s) in your topic.
  
      c. Install the necessary fonts with your Windows Help file.
  
         WARNING: Fonts are legally protected by trademarks, patents, and
         copyrights. You must obtain the necessary legal rights from the
         font developer before distributing fonts.
  
  

• The punctuation mark immediately follows a hot spot.

  Make the punctuation part of the hot spot. Place the punctuation mark after the hot-spot text and before the instructions.

• The punctuation mark is in a line of text.

  Rewrite the line to lengthen or shorten the sentence or phrase when this occurs. If this occurs frequently in your Windows Help file, you should increase the width of the window in Help Workshop. However, be aware that this might not eliminate all of the breaks, and in some cases, it might introduce new ones at different places in the Windows Help file.

• A paragraph in your Help file will not wrap.

  This will happen if you have text in a table in your topic file. Text in a table is designed not to wrap when the window is narrower than the width of the table. If you want to leave the text in a table, try one of the following methods:

      - Adjust the window size in the project file by using Help Workshop.
  

      - Adjust the width of the table in the topic file, so that it fits
        within the window.
  

  This behavior will also occur if you have the Keep Lines Together feature set in Microsoft Word.

  If you are using this feature in Microsoft Word you should turn it off by doing as follows:

      1. Place the insertion point in the paragraph.
  

      2. On the Format menu, click Paragraph.
  

      3. On the Lines and Page Breaks tab, clear the Keep Lines Together
         check box.
  

• Text appears over the graphic instead of below or beside it.

  The text and graphics are in a line of text. If your graphic is taller than the line spacing for the line of text it is in, then the text might wrap around to the next line over the graphic. To work around this behavior, in your topic file, increase the line spacing for the paragraph containing the graphic until the entire graphic is showing, or decrease the height of the graphic.

• Both text and graphics are in the same table.

  This can be caused by having a background bitmap in your topic file. Background bitmaps are graphics you place in a topic file to appear behind the text. If the graphics take up more space than they should they will spill over into the space reserved for the text. To fix this problem you can increase the width of the table column that contains the graphic.

• Graphics in the text interfere with line spacing.

  This can be caused by graphics that are much taller than the line spacing of the text they are in. To ensure that your graphics do not interfere with line spacing, do one of the following:

      - Use a graphics program to decrease the height of the graphic to the
        same height as the line spacing.
  

      - Place the graphic on the first line of text in a paragraph if there
        is more space between the paragraphs than between the sentences.
  

      - Remove the graphic from the line of text and place it in its own
        paragraph.
  

• The top of the graphic is cut off.

  This can be caused by your graphic being taller than your line spacing and the height of the line spacing being locked by your topic file. This can be corrected in your word processor by increasing the line spacing for the paragraph containing the graphic until the entire graphic is showing.

• Colors in a graphic do not look like the original.

  This can be caused by the screen resolution on the computer you are installing your Help file on not matching the screen resolution of the computer on which the Help file was created. To accommodate different color depths on different computers, create a separate version of each bitmap for each color depth, and then specify each version in a bitmap statement. For more information about doing this, see Microsoft Windows 95 Help Authoring Kit, Chapter 6, "Working with Text, Graphics, and Video."

• A bitmap statement appears in your Windows Help file instead of a graphic.

  This will happen in any of the following situations:

      - The bitmap does not exist.
  

      - The bitmap is not in the folder specified by the project file.
  

      - The bitmap name is misspelled.
  

  To correct this problem, do the following:

      1. Open the project file, and then click Bitmaps.
  

      2. Make sure the correct folders for the bitmap locations are
         specified in the project file.
  

      3. Check the bitmap locations in Windows Explorer or My Computer.
  

      4. Check the spelling for the bitmap file name.
  

      5. Check the syntax for the bitmap statement. One or both of the braces
         ({}) might be missing, or parentheses (()) or square brackets ([])
         were used instead of curly braces.
  

For more information about error messages that you receive in Help Workshop, search the Help Index for "error numbers, Winhelp."

For more information about using the Windows Help compiler, please see the following articles in the Microsoft Knowledge Base:

   ARTICLE-ID: Q74937
   TITLE     : Authoring Windows Help Files for Performance

   ARTICLE-ID: Q77841
   TITLE     : PRB: Vertical Scroll Bars Missing from Windows Help

   ARTICLE-ID: Q83020
   TITLE     : Semicolons Cannot Separate Macros in .HPJ File

   ARTICLE-ID: Q85490
   TITLE     : PRB: Number Causes Help Compiler Invalid Context ID Error

   ARTICLE-ID: Q110540
   TITLE     : PRB: Quotation Marks Missing from Compiled Help File

   ARTICLE-ID: Q93395
   TITLE     : Using the FORCEFONT .HPJ Option

   ARTICLE-ID: Q90291
   TITLE     : Using Graphics Within a Help File

Keywords          : Softlib kbusage
Version           : 97
Platform          : WINDOWS
Hardware          : x86
Issue type        : kbfile