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.
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:
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:
[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:
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:
[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:
[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:
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:
The following example shows the [OPTIONS] section of the Procedure Editor help project file:
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 |