Progress
Help Development
Guide


Project File Sections

Table 4–3 summarizes the project file sections, explaining the function of each one. Some of the individual sections are explained in more detail later in this chapter.

Table 4–3: Summary of Project File Sections
Section
Description
[ALIAS]
Assigns one or more topic IDs to the same help topic. This section is optional.
[BAGGAGE]
Lists files (typically multimedia elements) that the Windows Help compiler stores within the help file’s internal file system. This section is optional.
[BITMAPS]
This section is recognized by the help compiler for backward compatibility only. It was formerly used to list graphic files to include in the build. The help compiler now uses the BMROOT option in the [OPTIONS] section to specify a directory where graphic files are located..
[BUILDTAGS]
The [BUILDTAGS] section defines the valid build tags for a help file. The compiler uses the build tags to determine which topics to include or exclude when building the Help file.
[CONFIG]
This section is used to specify author-defined menus and buttons to be used with the help file, and to register DLLs and DLL functions used as macros in the help file that define non-standard menus, buttons, and macros used in the help file. This section is required if the help file uses any of these features.
[CONFIG:name]
This section is used in the same way as the [CONFIG] section, except that the content of the section only applies to the window type indicated by name.
[EXCLUDE]
This section specifies build tags that identify topics that should be excluded from the help file.
[FONTS]
This section specifies the fonts in topic files that are to be replaced with different fonts, point sizes, or character sets.
[FILES]
Specifies the help topic files to include in the build. This section is required.
[INCLUDE]
This section specifies build tags that identify topics that should be included in the help file.
[MACROS]
This section specifies macros to run whenever a user selects one of the keywords (also listed in this section) from the Index tab of the Help Topics dialog box.
[MAP]
Associates topic IDs with context IDs. This section is optional.
[OPTIONS]
Specifies options that control the build process. This section is required, and should appear first in the project file, so the options will apply during the entire compilation.
[WINDOWS]
Defines the size, location, and colors for the main help window and any secondary window types used in a help file. This section is required if the help file uses secondary windows.

The following sections describe the various sections of the help project file and use the project file for the Procedure Editor help file, (editeng.hpj) as an example. (See the “Accessing Files in Procedure Libraries” section in the Preface for information on how to access this project file.)

[ALIAS] Section

The [ALIAS] section of the help project file specifies alternate names for topic IDs. The [ALIAS] section is optional.

Normally, if you combine, remove, or replace any of your help topics, you have to manually update all the affected topic IDs to maintain the intended hypertext functions. By including an [ALIAS] section in the help project file, you can tell the help compiler to substitute a newer topic ID for a topic ID that you no longer want to use.

For instance, if you combined the Cutting_Code, Copying_Code, and Pasting_Code help topics into a single new help topic named Drag_and_Drop, you could automatically update the hypertext references by adding the following statements to the [ALIAS] section in the help project file:

[ALIAS]
Cutting_Code=Drag_and_Drop
Copying_Code=Drag_and_Drop
Pasting_Code=Drag_and_Drop 

If you include this [ALIAS] section in the help project file, the help compiler links all references to any of the three help topics to the new replacement help topic Drag_and_Drop.

The [ALIAS] section can also be used to resolve compiler errors if two or more topic IDs are assigned to the same help topic. For example, if one help author assigns the topic ID Cut_and_Paste to an Edit menu topic and another author uses Drag_and_Drop to reference the same help topic, an error would occur. To fix the problem, simply include the following statement in the [ALIAS] section:

[ALIAS]
Cut_and_Paste=Drag_and_Drop 

[BAGGAGE] Section

The [BAGGAGE] section lists files (typically multimedia elements) that the help compiler stores within the help file’s internal file system. The help engine can access data files stored in the help file more efficiently than it can access files in the normal file system, since it doesn’t have to read the file allocation table:

[BAGGAGE]
meep.wav 

If a file is listed in the [BAGGAGE] section, you refer to that file in the topic file by prefixing the filename with an exclamation point (!). The filename must appear exactly the same in the topic file as it appears in the [BAGGAGE] section. To avoid having to specify a full path, use the ROOT option in the [OPTIONS] section to specify the path. All filenames that you specify in the topic file are relative to the ROOT path.

This example is from the [BAGGAGE] section of the Procedure Editor help project file:

[BAGGAGE]
[Map]
#include <EDITENG.HH> 

[BITMAPS] Section

The [BITMAPS] section of the help project file is no longer used by the help engine. If you are using an old help project file that contains a [BITMAPS] section, the help compiler will ignore it.

By default, the compiler looks for graphics files in the same directory as the help project file, then in the same directory as the .rtf file that specified the graphics, and then in all directories specified by the ROOT option. The BMROOT option is necessary only if graphics files are not in one of these locations. You can specify multiple BMROOT options.

[BUILDTAGS] Section

The [BUILDTAGS] section specifies all valid build tags for a particular build.

This section is used in conjunction with the build tag footnote (*) in help topic files, and the BUILD option in the [OPTIONS] section of the help project file. The build tag footnote associates a particular build tag with a given topic.

The help compiler processes those help topics assigned a build tag plus any help topics that contain no build tag. The compiler ignores only help topics containing build tags that are not defined in the project file’s [BUILDTAGS] section.

If you do not include a [BUILDTAGS] section in your project file, the help compiler processes all the help topics in all the topic files listed in the [FILES] section. The [BUILDTAGS] section is optional.

Note that Help Workshop does not provide a way to modify the [BUILDTAGS] section in your project file. To create or modify a [BUILDTAGS] section, load the project file into a text editor, and then add or edit the section.

Also note that Help Workshop does not provide a way to specify the BUILD option in your project file. Instead, it provides a Build Tags tab in the Options dialog box that enables you to specify what build tags to include and exclude. These build tags are placed in the [INCLUDE] and [EXCLUDE] sections respectively. If there is an [INCLUDE] or [EXCLUDE] section in your project file when you compile a file, Help Workshop ignores any BUILD option you may have specified.

To use a BUILD option instead of an [INCLUDE] or [EXCLUDE] section, you must load the project file into a text editor and add the option to the [OPTIONS] section. You must also add a [BUILDTAGS] section specifying all the build tags that you will be using:

[BUILDTAGS]
WINDOWS 

[CONFIG] Section

The [CONFIG] section of the help project file specifies which help macros are executed when the help engine first loads the help file.

This section can contain macros that carry out actions, such as creating buttons or menus, and macros that register routines in external DLLs as WinHelp macros. These routines can then be used the same as WinHelp macros.

The [CONFIG] section is optional.

A help macro is a predefined routine that executes a specific action, such as adding, modifying, or removing buttons and/or menu options displayed in the help viewer. In the following example, browse buttons are enabled in the help viewer:

[CONFIG]
BrowseButtons() 

For detailed information about the function, parameters, and correct syntax for each macro, see the Help Author’s Guide , hcw.hlp, the help file for Help Workshop.

[FILES] Section

The [FILES] section of the help project file specifies all the help topic files (.rtf) you want the help compiler to process when creating the help file. A help project file must have a [FILES] section.

If a file is not on the defined path and cannot be found, the help compiler generates an error message.

[MAP] Section

The [MAP] section of the help project file supports context-sensitive help. The [MAP] section is optional. See the "Mapping Context-sensitive Help Topics" section for more information on this process.

[OPTIONS] Section

The [OPTIONS] section includes options that control how a help file is compiled and what feedback the compilation process displays. This section, along with the [FILES] section, is required in all project (.hpj) files. The [OPTIONS] section should be placed first in the project file so that the specified options apply during the entire compilation process.

Options are specified using the following syntax:

SYNTAX
option name = status of option 

The following example shows the [OPTIONS] section of the Procedure Editor help project file:

[OPTIONS]
BUILD=WINDOWS
CNT=editeng.cnt
TITLE=Procedure Editor Help
COPYRIGHT=Copyright c 1999 Progress Software Corp.
OLDKEYPHRASE=NO
REPORT=NO
OPTCDROM=0
DBCS=0
NOTES=1
COMPRESS=12
BMROOT=..\gfx
ERRORLOG=M:\checkin\EDITENG\EDITENG.err 

For a complete of [OPTIONS] section options, see Appendix B, "Options in the [Options] Section of the Project File."

[WINDOWS] Section

The [WINDOWS] section defines the size, location, and colors for the main help window and any secondary window types used in a help file. You can define up to 255 secondary window types (although the help engine can display no more than nine secondary window types at one time).

You can use window definitions established in the [WINDOWS] section with the SYSTEM-HELP statement or as a part of the hypertext link definition to display help information in a customized secondary help window. For more information about the SYSTEM-HELP statement, see the "The SYSTEM-HELP Statement" section in Providing Help for Progress Applications." For information about window redirection in a hypertext link definition, see the "Creating Secondary Window Links" section in Creating Help Topic Files."

You can also associate a window type with a topic in the help topic file by specifying the window type in a footnote coded with the greater-than sign (>). This footnote type specifies the window type a topic will appear in when the topic is opened from the Index or Find tab, or from an ALink or KLink macro.

Help Workshop provides a useful graphical interface for creating or editing the [WINDOWS] section. It is much easier to use Help Workshop to define window types, rather than using a text editor.

For detailed reference information on defining window types, see the Help Author’s Guide , hcw.hlp, the help file for Help Workshop.


Copyright © 2004 Progress Software Corporation
www.progress.com
Voice: (781) 280-4000
Fax: (781) 280-4095