What is MS Help Generator?

Related Topics

MS Help Generator creates Microsoft Windows Help directly from module design information recorded in the repository. Windows Help is a practical way of providing online assistance for the Windows-based applications you can design and develop using Oracle Designer Generators:

•	Form Generator

•	Visual Basic Generator

The main source for MS Help Generator is Help text, which you define against modules and module components using Oracle Designer Design Editor. How

Generated Help files may be used standalone, or integrated within generated applications.


What is Windows Help ?

Related Topics

A Windows Help system consists of one or more Help files (.HLP) with each Help file containing one or more topics.

Main features of Windows Help

Topics Popup windows	Contents topics Keywords	Browse buttons Glossary button	Entry points into Help Context-sensitive entry
Displaying help information

Topics	Help files are broken down into a hierarchy of topics. Each topic appears in the Help window as an individual page of information, and can contain both text and graphics.

Hyperlinks, also referred to as 'jumps' allow the reader to display Related Topics, rather like cross-references in a book.

Popup windows	Supplementary information, such as definitions of terms and illustrations are often displayed in popup windows which temporarily superimpose the main Help window.

Finding information

Contents topic	Every Help file has a Contents topic. Like the contents of a book, this topic  provides an overview of all the topics and the means to access Help file information. Most Help files have a 'Contents' button on the toolbar of the main Help window. When pressed, this button displays the Contents topic.

Keywords	The keyword search facility acts like a book index and is often the fastest way to access a specific Help topic for information. During a search all the topic titles relevant to the keyword subject are listed for the reader.

Glossary	Explanations of words and phrases that may be unfamiliar to the reader are normally displayed in popup windows. These terms are often compiled into a separate Glossary which the reader may browse through, independently from the main Help window.

Navigation aids

Browse Buttons	Related Topics are grouped together in 'browse sequences'. Browse Forward (>>) and Browse Back (<<) buttons on the Windows Help toolbar allow the reader to move through topics, rather like turning pages in a book.

Opening Windows Help

Help Icon	Help for a Windows application is often displayed as an icon in the Windows desktop. If you double-click on the icon the contents topic  is displayed.

Help Menu	Most Windows applications provide a Help menu item. If you open the help from the Help menu the contents topic  is normally displayed.

Help Button	Windows dialog boxes can provide Help buttons. If you select this button the Help topic relating to the current dialog box is displayed.

Pressing F1	Most Windows applications provide 'context-sensitive' Help systems. This means that if the person using the application presses F1, the Help file opens at the topic directly relating to the application item currently in focus, or the Contents topic.


Features added for MS Help Generator in 6i

Major new features in MS Help Generator 6i

Support for generation from versioned repositories.

New repository features enable you to use the repository as well as the filesystem to store files required during generation, and also to store generated files after generation. Storing files in the repository gives you access to features such as the Dependency Analyzer and version control.

Other new and improved MS Help Generator features in 6i

New colors for those messages displayed in the Message Window that indicate whether MS Help Generator has successfully or unsuccessfully updated repository properties during generation.


Features added to MS Help Generator in previous releases

Features added to MS Help Generator in Oracle Designer Release 6.0

Features added to MS Help Generator in Oracle Designer Release 2.1.2

Features added to MS Help Generator in Designer/2000 Release 2.1.1

Features added to MS Help Generator in Designer/2000 Release 2.1


Features added to MS Help Generator in Oracle Designer Release 6.0

No new features were added to MS Help Generator in Oracle Designer Release 6.0.


Features added to MS Help Generator in Oracle Designer Release 2.1.2

New MS Help Generator preferences in Oracle Designer Release 2.1.2.

NOHTML	Filter out any HTML in the Help text
ITMPPM	Control post caption marker
ITMSPM	Control split caption marker


Features added to MS Help Generator in Designer/2000 Release 2.1.1

No new features were added to MS Help Generator in Designer/2000 Release 2.1.1.


Features added to MS Help Generator in Designer/2000 Release 2.1

Terminology

New/changed terminology

Major new features

Support for latest WinHelp compiler (HCRTF.EXE)

Hide or customize hyperlink titles

Help text on item groups and unbound items

Unique context ID prefix allocated to reusable module components

Other new and improved features

New Repository properties

Repository supports multi-line text

Preferences

New preferences

New/changed terminology

If you have used MS Help Generator in a previous release of Oracle Designer you will notice some terminology changes:

Release 1.x element	Release 2.1 element
Detailed column usage	Item
Detailed table usage	Module component table usage
Release 1.x property	Release 2.1 property
Base Table Usage Alias	Module Component Name
Zone Caption	Title
Block Title	Title
Column Usage Alias	Item Name
Display Prompt	Prompt
Display Caption	Prompt
Display Group Caption	Item Group Prompt
Major new features

Support for latest WinHelp compiler (HCRTF.EXE)

You can compile generated MS Help source files using the latest WinHelp compiler by setting the Help Compiler option prior to generation.

Help text on item groups and unbound items

You can define Help text against item groups and unbound items.

Unique context ID prefix allocated to reusable module components

Reusable module components are designed to be used in more than one module. To ensure that context IDs remain unique, MS Help Generator automatically allocates a context ID prefix to reusable module components.

New Hyperlink title preferences

You can hide or customize static titles for module, module component, item group and item hyperlinks using a set of hyperlink title preferences.

Repository supports multi-line text

The Designer/2000 Repository Release 2.1 onwards supports multi-line text. This means you can now enter help text with embedded carriage returns.

New Repository properties used by MS Help Generator

Repository element	Property	Use in MS Help file

Module Component	Context ID Prefix	Ensures context IDs are unique.
Item Group	User/Help Text	Help text for the item group.


About generated MS Help files

Scope of generated Help systems

Topic structure

Topic text

Keywords

Glossary terms

Context-sensitive entry

MS Help compilation and runtime options

Customization

Graphics

Preferences


About the scope of generated Help systems

Related Topics

The module network for your Windows application governs the overall scope of the Help system. You may either generate a single Help file for the entire module network, or create a Help system made up of several smaller Help files. This diagram illustrates the various options:

The nature, size and complexity of your Windows application will influence how you choose to define the scope of each Help file. You define the scope, by setting the Help File Name property on the 'top-level' module for each Help file you require. How

If the Help system is generated for a Visual Basic application, the entire module network must be included in the same Help file.

Note:	MS Help Generator does not process Library modules.


About topic structure in generated Help files
About topic structure

Related Topics

Topics within any Help file are organized into a hierarchical structure. At the top is a table of contents listing the categories of topics available and each successive step down the hierarchy will reveal more detailed information about the application.

MS Help Generator generates Help files in exactly the same way. The overall topic hierarchy is derived from the module network and the help information generated from any one module in the network, may be further broken down into topics based on the module components.

Example topic structure

A typical application modeled in Oracle Designer might comprise several modules, for example:

The Help topics generated from this sample module design are illustrated below. Hyperlinks (shown in green) are generated so the reader may navigate from the contents topic, to lower level topics containing more detailed information.

Customizing topic structure

The diagram above shows the default set of topics generated from the sample application. If necessary you can customize the topic structure to better suit your application using these preferences:

New topic for each module component (TUPLCT)	Module topics and module component topics can be combined.
New topic for each item group (IGPLCT)	Module component Help text can be split up into smaller topics that describe each item group.


About topic text in generated Help files
About topic text

Related Topics

Design Editor allows you to enter Help text against the following module elements:

•	module definition

•	module components

•	item groups

•	items

During generation, MS Help Generator extracts this text and transforms it into Windows Help topics.

Substitute topic text

If no help is defined against a particular module element MS Help Generator can make use of other text sources. The substitute text used is determined by these preference settings:

Action when no module component help text defined (DTUNHP)

Action when no item help text defined (DCUNHP)


About Contents topics in generated Help files
 About Contents topics

Related Topics

Every Windows Help file has a Contents topic. MS Help Generator creates a Contents topic from the top-level module of the Help file. At the start of the Contents topic there is normally a description of the application, derived from the Help text defined for the top-level module.

The introduction is followed by a series of hyperlinks to topics which describe those modules which are called by the top-level module. There may also be hyperlinks to topics which describe lower level module components, however it is unusual for the top-level module to have module components.

This is an example of a generated Contents topic, where:

•	the Bug Management System is the top of the module hierarchy

•	the next level down in the module network comprises five called modules.

Normally when you open a Help file the Contents topic is displayed first, rather like the first page of a book. The exception to this rule is when you use F1 to open context-sensitive Help, here the Help opens at the topic which describes the application item in focus.

	The Contents button on the Windows Help toolbar allows you to navigate to the Contents topic at any time.
Note:	To find out which repository properties are used to derive this topic, see Contents topic elements.


About keywords in generated Help files
About keywords

Related Topics

MS Help Generator can automatically create a set of keywords that link to module, module component, item group and item descriptions within the Help file. You can also define your own keywords while entering Help text within the module design specification. How

The keyword facility is often the fastest way to find information in a Help file and the search process is most effective when the Help system provides a comprehensive list of keywords. For this reason, you are encouraged to specify as many useful keywords as necessary.

	The Windows Help viewer WINHELP.EXE uses the Search button to activate the keyword search facility.
	The Windows Help viewer WINHLP32.EXE uses an Index button to activate the keyword search facility.
Note:	You can disable automatic keyword generation by setting the Use prompts as keywords (CAPKEY)  preference to NO.


About glossary terms in generated Help files
About glossary term popups

Related Topics

Terms that are specific to a generated Windows application can be defined in the repository as Business Terminology. How

These definitions are similar to Glossary terms you find in a book and they are very useful to new users who are unfamiliar with your application, or the terminology used in the business area it supports.

MS Help Generator generates a single glossary file from these definitions and then scans each of the topic files, for an instance of any term. If a term appears within the Help text, MS Help Generator underlines the term (dotted) to indicate to the reader that additional popup information is available. When the reader clicks on the popup link, a small window containing the description stored in the repository is displayed.

Terms only need to be explained once per topic, therefore MS Help Generator only highlights the first occurrence of a term, in any given topic. Nested glossary terms are not supported i.e. a glossary term is not highlighted if it appears within a glossary description.

Glossary button

If glossary terms are defined, a glossary button is added to the Help toolbar. This button displays an alphabetical listing of all the glossary terms you have defined in a secondary Help window.

Note:	In some languages, the initial character of the glossary term (Name property) may not map to a character in the language character-set. In this case, you must specify which character (in the character-set) the terms should be listed under on the glossary topic, using the Glossary Grouping Character property. How


About browse sequences in generated Help files
About browse sequences

Related Topics

A browse sequence is automatically created between Help topics generated from a single module. The sequence organizes the Help topics from the highest module design level (module definition), to the lowest (item groups), and then from one module component to the next in the order they appear in the generated application.

This illustration shows the browse sequence for a typical module, comprising several module components:

	The Browse forward and backward buttons on the Windows Help toolbar allow you to step through all the topics generated for a module.
When the module definition topic (1) is displayed the browse back button <<  is dimmed, this indicates that the topic is the first in a series. Likewise, the browse forward button >> is dimmed when you display the last topic (9).


About context-sensitive entry in generated Help files
About context-sensitive entry

Related Topics

MS Help Generator creates context-sensitive Help files automatically. This means that when the person using the Windows application presses F1, the Help file opens at the topic which describes the application item currently in focus. This feature provides the required information instantly, and the user avoids having to search through the Help file.

During generation MS Help Generator automatically allocates the context-sensitive IDs which will link application items to their associated Help file descriptions. It also creates mapping files (.HM) to store the mappings between these context IDs and topic context strings.

After help file generation the allocated context IDs are saved back to the repository, so they may be incorporated within the Windows application when it is next generated.

MS Help Generator allocates a context ID to each:

•	module definition

•	module component

•	item

In this way, the user can obtain context-sensitive information from within the Windows application, at various levels of detail. If you press F1 on an element which has no Help text defined, its parent topic (in the Help topic hierarchy) is displayed instead.

To ensure that all context IDs within a Help file are unique, a unique Context ID Prefix must be defined against each module and reusable module component described in the Help file.

Note:	MS Help Generator will automatically allocate a Context ID Prefix if one is not defined. However, note the following:

•	The allocated context ID is not guaranteed to still be unique if you migrate or share modules (or module components) between containers (i.e. folders or application systems). In such cases, it is advisable to enter your own, unique value.

•	You must generate the Windows application again using the appropriate Oracle Designer Generator to incorporate the new context IDs that MS Help Generator has allocated.


About Help compilation and runtime options for generated Help files
About MS Help compilation and runtime options

Related Topics

MS Help Generator generates all the files needed to compile a Windows Help file (HLP) for your application.  After generation you can compile and run the generated Help file from Design Editor providing the appropriate MS Help Generator options have been set. How

•	WinHelp compiler

•	WinHelp viewer

Note:	WinHelp compilers are available from Microsoft.

Windows platform for generated application	WinHelp viewer (.EXE)	Valid Help compilers          (.EXE)
Windows 3.x	WINHELP	HC31   HC    HCP
Windows NT	WINHELP	HC31   HC    HCP
Windows NT 3.51 or later	WINHELP WINHLP32	HC31   HC    HCP HC31   HC    HCP    HCW/HCRTF
Windows 95	WINHELP WINHLP32	HC31   HC    HCP HC31   HC    HCP    HCW/HCRTF
WinHelp viewer executables

Windows Help is provided with Microsoft Windows  (WINHELP.EXE or WINHLP32.EXE). From Design Editor you can define which of these WinHelp viewers will be used to run the generated Help file. You should choose the same viewer executable that will be called from your generated application.

WinHelp compilers

WinHelp compilers are available from Microsoft. When you obtain a Help compiler, ensure it creates Help files that are compatible with the Windows Help viewer available from your generated application (see table above).

HC31.EXE, HC.EXE and HCP.EXE

All these compilers run under DOS. Use one of these compilers if the generated application is designed to operate under Windows 3.x or Windows NT prior to 3.51. WINHELP.EXE is the standard viewer for Help files built with these Help compilers.

Ensure that the corresponding WinHelp error message file (HCP.ERR, HC31.ERR, HC.ERR) is located in the same directory as these Help compilers.

HCW.EXE and HCRTF.EXE

The HCRTF.EXE compiler can be run directly or it can be run from the Window Help Workshop (HCW.EXE). Use the HCRTF.EXE compiler or HCW.EXE (Windows Help Workshop) if the generated application is designed to operate under Windows 95 or Windows NT 3.51 or later.

WINHLP32.EXE  is the standard viewer for Help files built with this version of the Help compiler. WINHELP.EXE can not be used to view these help files.

Note:	If you are familiar with Windows Help development you can run the Help compiler independently from Design Editor.


About graphics in generated Help files
About graphics

Related Topics

MS Help Generator allows you to display a graphic at the beginning of each module topic. All you have to do is specify the name of the graphic file and where it is stored, so it can be located when the Help file is compiled. How

Including graphics in a Help file is optional. Typically, they will be used to illustrate, or clarify the purpose of the module. For example:

  Open New Customer File

  Close Customer File

You could also define a graphic on the contents topic (top-level module) to simply display a company, or product logo:

  Company ABC

You can incorporate three different types of graphics in your Help system; Bitmaps (.BMP), Windows Metafiles (.WMF) or Multi-resolution Bitmaps (.MRB).


Generate Help System dialog
Generate Help System dialog box

Related Topics

You generate help systems using the MS Help Generator to create MS Help source files from module design specifications held in the repository. How

You can use the generated MS Help source files to provide context-sensitive help for Oracle Forms applications and Visual Basic applications that you create using Form Generator and Visual Basic Generator respectively.

Use this dialog box to generate a new MS Help file from the selected module (or module network), or update an existing MS Help file.

Note:	This dialog box also allows you to update Form Generator Help Tables.

Module

Displays the Short Name of the module selected for generation.

Generate Options

To select the type of help and the range of files to be generated, click one of the Generate Options.

Generate all the MS Help source files

To generate all the source files required to create a standalone Help file (Help project file (.HPJ), topic files (.RTF), mapping files (.HM) and glossary file (.RTF), click Generate all the MS Help source files.

Include the module network in this help system

To generate a Help source files for the whole module network starting from the chosen module, select the Include the module network checkbox. If the Help File Name property is not defined against the chosen module, the Help project will be generated with a temporary name (t_implementation name.hpj).

Do not select this checkbox if you want to create a standalone (temporary) Help project for a single module, for testing and debugging purposes.

Note: Temporary Help files cannot be used in conjunction with the generated application.

Only generate the topic (.RTF) and mapping (.HM) files

To update topic (RTF) and mapping (HM) files for a single module, click Only generate the topic (.RTF) and mapping (.HM) files.

This option avoids having to regenerate a complete new set of Help source files when modifications are restricted to a specific module.

Update the Form Generator Help Tables

To update help tables for a Form module, click Update the Form Generator Help Tables. Help tables are specific to Form Generator and they may be used as an alternative to MS Help. About

Generate help for the module

To update help tables for a Form module, click Generate help for the module.

Generate help for the associated tables

To update help tables for the tables within a Form module, click Generate help for the associated tables.

Post Generation

Use the Post Generation options to specify what happens when generation is complete.

Post Generation - Commit

Select this option to update repository objects when generation is complete.

Note that there are some circumstances when MS Help Generator will not update properties of repository objects. For more information, refer to When are repository objects not updated during generation and design capture.

Post Generation - Revert

Select this option if you do not want to update repository objects with the property settings used during generation.

Post Generation - Browse/Edit mode

Select this option to activate Post Processing Mode, which enables you to choose how to process proposed repository changes.

For more information about Post Processing Mode, refer to About the Design Editor Post Processing Mode.


Help System Generator Options dialog
Help System Generator Options dialog box

Related Topics

Sets generation, compilation and runtime options for MS Help Generator.

Source

These options enable you to specify the location of files required during generation.

File System

Select this option if you want those files that are required during generation to be retrieved from the filesystem and not from the repository.

Repository

Select this option if you want those files that are required during generation to be retrieved from the repository and synchronized with files in the filesystem before being used.

For more information about storing source files in the repository, refer to About storing files in the repository for use during generation.

Repository Folders

Specify the repository folder containing the files required during generation. To specify multiple folders, separate the folder names with commas. Multiple folders are searched in the order in which you specify them.

For more information about storing source files in the repository, refer to About storing files in the repository for use during generation.

Destination of generated files

To save generated files in a specific directory, enter the drive and directory you require. Alternatively, click Browse to select the location.

If no location is specified, generated files are saved to the working directory of the program item or shortcut used to start Oracle Designer. The default location is <ORACLE_HOME>\BIN\.

Upload generated files to repository

To save generated files in the repository folder mapped to the directory specified in the Destination of generated files field, check this checkbox. If a repository folder is not mapped to the specified directory, files are not saved in the repository.

For more information about saving generated files in the repository, refer to About storing generated files in the repository after generation.

Help Compiler

To compile a generated MS Help file using a particular Help compiler immediately after successful generation, enter the name and location of the compiler you want to use. Alternatively, click Browse to select the name of the executable file.

Note:	If you want to use the compiler that runs from Help Workshop, enter the name and location of the Help Workshop executable (HCW.EXE) rather than the compiler itself (HCRTF.EXE). You should also enter the  /C switch command. For example, d:\winhelp\hcw.exe /c

If no location is specified ensure the executable is in your system path. If no compiler is specified HCP.EXE is used by default.

Help Executable

To run a generated MS Help file using a particular version of Windows Help immediately after successful compilation, enter the name and location of the Help executable you want to use. Alternatively, click Browse to select the name of the executable file.

If no location is specified ensure the executable is in your system path. If no executable is specified WINHLP32.EXE is used by default.


MS Help Generator preferences
About MS Help Generator preferences

Related Topics

You can customize the generation of MS Help files by changing the initial settings of the MS Help Generator preferences.

To find out more about MS Help Generator preferences, refer to:

•	MS Help Generator Preferences - organized alphabetically

•	MS Help Generator Preferences - organized by category


MS Help Generator preferences - organized alphabetically

Related Topics

CAPKEY	Use prompts as keywords
DCUCAP	Display prompts for items with no Help text
DCUJPS	Add hyperlinks to item Help text
DCULTL	Title for item hyperlinks
DCUNHP	Action when no item Help text defined
DTULTL	Title for module component hyperlinks
DTUNHP	Action when no module component Help text defined
GRHLOC	Graphic locations
GRPLTL	Title for item group hyperlinks
IGPLCT	New topic for each item group
ITMPPM	Control post caption marker
ITMSPM	Control split caption marker
MODLTL	Title for module hyperlinks
NOHTML	Filter out HTML in the Help text
TUPLCT	New topic for each module component


MS Help Generator preferences organized by category
MS Help Generator preferences - organized by category

Related Topics	Where am I?

Preference Category	Use preferences in this category to:
General	specify the location of graphic files and whether to include prompts as keywords
Hyperlink titles	specify titles for modules, module components, item groups and items
Topic structure	specify whether to create new topics for item groups and module components
Topic text	specify the behavior of MS Help Generator when no help text exists, and whether to add links within topics


General preferences for generated help files
General preferences

Related Topics	Where am I?

Name	Description
CAPKEY	Use prompts as keywords
GRHLOC	Graphic locations
ITMPPM	Control post caption marker
ITMSPM	Control split caption marker


Use prompts as keywords preference (CAPKEY)
Use prompts as keywords (CAPKEY)

Related Topics	Where am I?

Default:	Yes
Values:	Yes, No
Levels:	Container, module
Category	General

Use this preference to specify whether keywords are automatically created, based on prompts defined for the module definitions, module components, items and item groups.

To ensure that generated keywords uniquely identify a module element in the application, MS Help Generator appends each prompt with the module title.

For example:	salary (Enter New Employee Details)
salary (Change Employee Details)

Keywords are automatically assigned to the topic where the module element is described. This preference creates an effective search facility for generated Help files, with minimum effort. Remember that you can also add extra keywords of your choice.

These values are:

Yes	Keywords are automatically generated from module definition, module component, item and item group prompts.
No	Keywords are generated only for the words and phrases you specify explicitly, alongside Help text.
The table below shows which repository property MS Help Generator uses to generate keywords.

Repository element Module definition Module component Item group Item	Generated keyword Top Title Title Prompt Prompt


Graphic locations preference (GRHLOC)
Graphic locations (GRHLOC)

Related Topics	Where am I?

Default:	None
Values:	Any valid path name. To enter multiple locations separate each location with a comma.
Levels:	Container
Category	General

Use this preference to specify the location (or a series of locations) of any graphic files you intend to use to illustrate module topics. The graphic location information defined here is added to the [BMROOT] section of the Help project file (.HPJ). This ensures that the graphics can be located when the Help file is compiled. For example,

d:\bitmaps,d:\metafile,d:\logo

To define multiple directory locations, separate each location with a comma only.

Note:	In a team environment, this location should be on a networked drive that all the team members access through a consistent drive letter.

See Tips on graphics for some advice on the types of pictures you should include in a Help file.


Control post caption marker (ITMPPM)

Related Topics	Where am I?

Default:	|
Values:	<any character>
Levels:	Container
Category	General

Use this preference to specify the character in a repository item's Prompt property that indicates the position in the generated prompt at which to insert the generated item.

MS Help Generator removes the first occurrence of this character in an item's prompt and encloses all subsequent text in parentheses.

For example, if ITMPPM is set to | and the repository item prompt is "Time | hours", the heading for the item in the help topic will be Time (hours).


Control split caption marker (ITMSPM)
Control split caption marker (IMPSPM)

Related Topics	Where am I?

Default:	*
Values:	<any character>
Levels:	Container
Category	General

Use this preference to specify the character in a repository item's Prompt property that indicates the position in the generated prompt at which to to split the prompt across multiple lines.

MS Help Generator replaces every occurrence of this character in an item's prompt with a space.

For example, if ITMSPM is set to * and the repository item prompt is "Time*in hours", the heading for the item in the help topic will be Time in hours.


Hyperlink title preferences for generated help files
Hyperlink title preferences

Related Topics	Where am I?

Name	Description
DCULTL	Title for item hyperlinks
DTULTL	Title for module component hyperlinks
GRPLTL	Title for item group hyperlinks
MODLTL	Title for module hyperlinks


Hyperlink title preferences

Related Topics	Where am I?

Use these preferences to customize or hide static titles for module, module component, item group and item hyperlinks.

Title for module hyperlinks (MODLTL)

Default:	DEFAULT  (Associated forms/reports within this application:)
Values:	Up to 250 characters.
Levels:	Container, module
Category	Hyperlink titles

Use this preference to override the default title text for module hyperlinks.

Title for module component hyperlinks (DTULTL)

Default:	DEFAULT (This form consists of the following components:)
Values:	Up to 250 characters.
Levels:	Container, module
Category	Hyperlink titles

Use this preference to override the default title text for module component hyperlinks.

Title for item group hyperlinks (GRPLTL)

Default:	DEFAULT (This form consists of the following groups:)
Values:	Up to 250 characters.
Levels:	Container, module, module component
Category	Hyperlink titles

Use this preference to override the default title text for item group hyperlinks.

Title for item hyperlinks (DCULTL)

Default:	DEFAULT (This component consists of the following fields:)
Values:	Up to 250 characters.
Levels:	Container, module, module component
Category	Hyperlink titles

Use this preference to override the default title text for item hyperlinks.


Topic structure preferences for generated help files
Topic structure preferences

Related Topics	Where am I?

Name	Description
IGPLCT	New topic for each item group
TUPLCT	New topic for each module component


New topic for each item group preference (IGPLCT)
New topic for each item group (IGPLCT)

Related Topics	Where am I?

Default:	Never
Values:	Always, Stacked, Never
Levels:	Container, module
Category	Topic structure

Use this preference to define whether a new topic is created for each item group, or whether they appear in the Help topic created for the module component. This preference allows you to control the amount of information that appears in each topic in a similar way to the New topic for each module component (TUPLCT) preference.

Help for item groups are normally displayed in the same topic as their module component. However, complex module components may contain many items and/or item groups and there may be too much Help text to display in one topic. To split the Help text into a set of smaller topics choose 'Always'. This will create a new topic for every item group (in addition to the topic created for those items not in any item group).

Tip:	The optimal length of a Windows Help topic is one screen, and at most, two screens long. Try to avoid creating topics which are very long and unreadable.

These values are:

Always	Place all Item Groups on New Topics A new topic is created for each item group.
Stacked	Place Stacked Groups on New Topics Creates a separate topic for each stacked item group. Non stacked groups remain in the same topic as their module component.
Never	Place all Item Groups on Same Topic as Module Component  Every item group is described in the topic created for its module component.


New topic for each module component preference (TUPLCT)
New topic for each module component (TUPLCT)

Related Topics	Where am I?

Default:	More than One
Values:	More than One, Always, Never
Levels:	Container, module
Category	Topic structure

Use this preference to define whether a new topic is created for each module component, or whether all module components are combined into a single Help topic. This preference allows you to customize the Help topic structure to suit the Windows application and allows you to manage the amount of text each topic displays.

Simple modules may not require much explanation and have only a small amount of Help text to display. In this case, use the 'Never' option to combine all the Help text into a single Help topic, rather than creating several topics which may contain only a few sentences.

Conversely, complex modules comprising many module components may require very detailed descriptions, have many items and a considerable amount of information to display. In this case, use 'Always' to break the Help text into smaller topics.

Tip:	The optimal length of a Windows Help topic is one screen, and at most, two screens long. Try to avoid generating topics that are very long and unreadable.

These values are:

Always	Place Module Components on New Topics Creates a new topic for every module component in a module.
More than One	Place Module Components on New Topics if More Than One If a module comprises more than one module component, each module component is described in a separate Help topic. If a module has only one  module component, it is described in the same topic as the module.
Never	Place All Module Components on Same Topic as Module A single topic is created for the module and all its module components.


Topic text preferences for generated Help files
Topic Text preferences

Related Topics	Where am I?

Name	Description
DCUCAP	Display prompts for items with no Help text
DCUJPS	Add hyperlinks to item Help text
DCUNHP	Action when no item Help text defined
DTUNHP	Action when no module component Help text defined
NOHTML	Filter out any HTML in the Help text


Display prompts for items with no Help text preference (DCUCAP)
Display prompts for items with no Help text (DCUCAP)

Related Topics	Where am I?

Default:	Yes
Values:	Yes, No
Levels:	Container, module
Category	Topic text

Use this preference to hide the topic headings for items with no description.  By default, headings are created for items even when no Help text is available. The empty headings will help you identify where Help text has been omitted accidentally.

If for any reason you purposely do not enter Help text for one or more items, you may also want to hide its associated heading within a topic.

Note:	No context strings, context IDs or jumps are generated to empty headings. If the user presses F1 on an item with no Help text, the start of its module component topic is displayed instead.

These values are:

Yes	Display item prompts even when Help text is not available.
No	Hide item prompts when Help text is not available.


Add hyperlinks to item Help text preference (DCUJPS)
Add hyperlinks to item Help text (DCUJPS)

Related Topics	Where am I?

Default:	0
Values:	0 to 500
Levels:	Container, module
Category	Topic text

Use this preference to specify whether jumps (hyperlinks) are created to item descriptions within a Help topic. Jumps like this are useful for module components which contain many items and/or item groups and where the list of descriptions within a topic becomes very long.

If jumps are displayed at the beginning of the topic, the reader doesn't have to scroll through the topic searching for specific information. Instead, they can click on the jump of interest and the Help window will move down to the required description immediately.

Jump lists are not necessary within very short topics. This preference allows you selectively to create jumps, depending on the number of items and item groups described in any one topic.

Specify the minimum number of item descriptions required to trigger the generation of jumps. The default value is zero, which means that jumps are never created.

Note:	If the New topic for each item group (IGPLCT) preference is set to 'Always' or 'Stacked', some item descriptions will appear in separate topics. Jumps to separate item group topics are always displayed at the beginning of a module component topic.


Action when no item Help text defined preference (DCUNHP)
Action when no item Help text defined (DCUNHP)

Related Topics	Where am I?

Default:	Use Hint Text
Values:	Use Hint Text, Use Help Text from Column Definition, No Action
Levels:	Container, module
Category	Topic text

Use this preference to specify what happens when there is no Help text defined against an item. This preference enables the Help system to display some Help text for the item rather than nothing at all.

These values are:

No Action	No text is substituted if Help text is omitted. Topic headings are still created for the items.
Use the Hint Text	If any Hint text is defined against the item, the Hint text is displayed in the Help topic.
Use Help Text from Column Definition	If Help text is defined against the underlying column of the item, this information is displayed in the Help topic.
No context strings, context IDs or jumps are generated for items which have no Help text (or substitute Help text) to display. If the user presses F1 on such items, its module component topic is displayed instead.

Note:	To hide headings for items with no descriptions, use the Display prompts for items with no Help text (DCUCAP) preference.


Action when no module component Help text defined preference (DTUNHP)
Action when no module component Help text defined (DTUNHP)

Related Topics	Where am I?

Default:	Use Table Definition
Values:	Use Help Text from Table Definition, No Action
Levels:	Container, module
Category	Topic text

Use this preference to specify what happens when there is no Help text defined against a module component. This preference enables the Help system to display some Help text for the module component rather than nothing at all.

These values are:

No Action	No text is substituted if Help text is omitted. Topic titles or headings are still created for the module component.
Use Help Text from Table Definition	If Help text is defined against the underlying base table of this module component, this information is displayed in the Help topic.


Filter out any HTML in the Help text (NOHTML)

Related Topics	Where am I?

Default:	No
Values:	Yes, No
Levels:	Container, module
Category	Topic text

Use this preference to specify whether MS Help Generator filters out HTML character sequences within Help text (e.g. <b>, </HTML>) during generation.

If this preference is set to Yes, MS Help Generator filters out HTML character sequences. However, note that MS Help Generator might also filter out other characters that you do want to appear in the generated help file. For example, if the Help text contains the less than symbol  (i.e. the < character), MS Help Generator will filter out not only that character but also all other characters that follow until reaching a greater than symbol (i.e. the > character).

If this preference is set to No, MS Help Generator generates all the Help text as topic text and does not filter out HTML character sequences.


 Generating MS Help for Windows applications step-by-step

Related Topics

The overall process for generating Help systems using MS Help Generator is outlined in the flowchart below. To jump to a task, click on the appropriate box:

	Generate and test Windows application
	Set MS Help Generator options
	Plan the Help system
	Name the Help files
	Record basic content for each MS Help file Define Help against the module definition Define Help against module components Define Help against item groups Define Help against items
	Extend Help design and customize layout Define popup glossary terms Add extra keywords Illustrate module topics Define context ID prefixes Customize MS Help design using preferences
	Generate MS Help source files
	Compile MS Help source files
	Run and check generated Help file
	Test Help with generated application


Generating and testing the Windows application

Related Topics	Where Am I?

Use Design Editor to design and generate your Windows application before using MS Help Generator to create its associated Help file. Only when the modules are complete will you have a clear idea of the scope and contents of any Help files. About

Although MS Help Generator is not used initially, Help text should still be defined against module elements during the design stage.

Check that you have completed the following preliminary tasks:

1.	Designed modules for your client application. How

2.	Generated modules for your application, using:

•	Form Generator How

•	Visual Basic Generator How

Important Note:
When the content of your generated Help file is complete, you will have to re-generate the Windows application again in order to incorporate Help context IDs into the application design. About

Next step

Once the generated Windows application is complete set MS Help Generator options using Design Editor. How

Then, plan the Help system. How


Setting MS Help Generator options

Related Topics	Where am I?

For MS Help Generator to compile and run generated Help files you must define the name and location of the WinHelp compiler and WinHelp executable you want to use. The versions you choose must be compatible with the version of Windows running the generated application. About

You can also define where MS Help Generator saves generated files.

To set MS Help Generator options:

1.	In the Design Editor, choose Options→Generator Options→Help System

2.	Use the Source options to specify where to locate required files (on the filesystem or in the repository) during generation.

3.	(Optional) Use the Destination of generated files field to specify the directory where generated MS Help files are stored.

By default, files generated by MS Help Generator are saved to the working directory of Oracle Designer.

4.	If you want to store generated files in the repository after generation, check the Upload generated files to repository checkbox.

5.	Enter the name and location of the Help Compiler you want to use.

Valid Help compilers (available from Microsoft) are HC31.EXE, HC.EXE, HCP.EXE and HCRTF.EXE.

Note:	HCRTF.EXE can be run directly, in which case you must also enter the /X switch command. For example, d:\winhelp\hcrtf.exe /x.

Alternatively, you can run it from the Help Workshop. Enter the name and location of the Help Workshop executable (HCW.EXE) and the /C switch command. For example, d:\winhelp\hcw.exe /c. In this case the Help Workshop is opened, the project is compiled using HCRTF.EXE and a report file is produced.

6.	Enter the name and location of the Help Executable you want to use.

Valid Help viewer executables are WINHELP.EXE (for HC31.EXE, HC.EXE, HCP.EXE) and WINHLP32.EXE (for HCW.EXE or HCRTF.EXE).

7.	Click OK.

Next step

Plan the Help system for the generated application. How


Planning a Windows Help system for generated applications

Related Topics	Where am I?

Use the module network to determine the scope and contents of each Help file you require. About

To plan a Windows Help system for generated applications:

1.	Decide on the structure of the Help system, the options available are:

•	describe the entire module network in a single Help file

•	create separate Help files for module sub systems

•	describe each module in a separate Help file

2.	Identify the top-level module for each Help file you require.

You need to specify a Help file name against the top-level module only, not on each module to be included in the Help file.

Next step

Define the name of the Help file against each top-level module. How


Naming MS Help files

Related Topics	Where am I?

Name the Help files for your generated application by setting the Help File Name property against the top-level module for each Help file. About

To follow the steps below ensure:

•	the top-level module for the Help file has been identified. How

•	the Design Editor is set to display Property Palettes (Options→Use Property Palette).

To name a Help file (.HLP) and generated project file (.HPJ):

1.	On the Navigator, double-click the top level module for the Help file.

2.	Enter the Help File Name.

The file extension is not required here.

Note:	The Help File Name should not exceed 8 characters if it is to be used in conjunction with a 16 bit Windows application.

3.	Click [image] to save.

Next step

Record the content of each Help file. How


Recording the content of MS Help files

Related Topics	Where am I?

Once you have determined the scope and named the Help files required, you can record the contents of each Help file. This involves specifying Help properties and entering the Help text you wish to display.

The overall process for each Help file is outlined in the flowchart below (note that some of the tasks are optional). To jump to a task, click on the appropriate box:

	Define Help against the module definition
	Define Help against module components
	Define Help against item groups
	Define Help against items
	Extend Help design and customize layout Define popup glossary terms Add extra keywords Illustrate module topics Define context ID prefixes Customize MS Help design using preferences
	Generate MS Help source files


Defining Help against module definitions

Related Topics	Where am I?

If a module is to be included in an MS Help file, you must enter Help text and keywords against the module definition. About

To define Help against a module definition:

1.	Open the module diagram in Design Editor. How

2.	Choose Options→Use Property Palette.

3.	On the module diagram, double-click the module element.

4.	Double-click the User/Help Text property to open the TextPad.

Alternatively, click [image] to open your preferred ASCII Editor.

5.	Enter Help text for the selected module.

If this is a top-level module, this text appears on the Contents page.

6.	After the Help text, enter keywords for the module. Tip

Place each word or phrase on a new line, prefixed with the keyword identifier
@@.

7.	Click

8.	(Optional)  Enter the Graphic File Name of the picture you wish to display on the module topic.

The file extension must be specified here i.e. .BMP, .WMF and .MRB. See Tips on graphics.

9.	Click [image] to save.

Next step

Enter Help text and keywords for each module component. How


Defining Help against module components

Related Topics	Where am I?

To generate a comprehensive Help system, you should enter Help text and keywords against every module component in a module. About

To define Help against a module component:

1.	Open the module diagram in Design Editor. How

2.	Choose Options→Use Property Palette.

3.	On the module diagram, double-click the module component element.

4.	Double-click the User/Help Text property to open the TextPad.

Alternatively, click [image] to open your preferred ASCII Editor.

5.	Enter Help text for the module component.

6.	After the Help text, enter keywords for the module component. Tip

Place each word or phrase on a new line, prefixed with the keyword identifier
@@.

7.	Click [image] to save.

Next step

Enter Help text and keywords for each:

•	item group  How

•	item  How


Defining Help against item groups

Related Topics	Where am I?

For larger module components that are broken down into item groups you may want to enter Help text and keywords against each of the item groups. About

To define Help against an item group:

1.	Open the module diagram in Design Editor. How

2.	Choose Options→Use Property Palette.

3.	Choose View→Display View. About

4.	Double-click the item group element.

5.	Double-click the User/Help Text property to open the TextPad.

Alternatively, click [image] to open your preferred ASCII Editor.

6.	Enter Help text for the item group.

7.	After the Help text, enter keywords for the item group. Tip

Place each word or phrase on a new line, prefixed with the keyword identifier
@@.

8.	Click [image] to save.

Next step

Enter Help text and keywords for each item. How

If the module component contains many item groups you may also want to set the New topic for each item group (IGPLCT) preference so that each group is placed on a new topic.


Defining Help against items

Related Topics	Where am I?

To generate a comprehensive Help system, you should enter Help text and keywords against every item within a module. About

Note: 	Use the Display prompts for items with no Help text (DCUCAP)  preference to hide topic headings for items with no description.

To define Help against an item:

1.	Open the module diagram in Design Editor. How

2.	Choose Options→Use Property Palette.

3.	On the module diagram, double-click the item.

4.	Double-click the User/Help Text property to open the TextPad.

Alternatively, click [image] to open your preferred ASCII Editor.

5.	Enter Help text for the item.

6.	After the Help text, enter keywords for the item. Tip

Place each word or phrase on a new line, prefixed with the keyword identifier
@@.

7.	Click [image] to save.

Next step

Once you have entered Help text and keywords for every module, module component and item in the Help file, generate the MS Help source files. How

You may want to define glossary terms or set Help design preferences before you generate, but these tasks are optional.


Generating all the MS Help source files for an entire Help file

Related Topics	Where am I?

When you have recorded Help text and keywords for every module in a Help file, you are ready to generate the MS Help source files for the entire Help file.

Note:	Ensure that MS Help Generator options are set correctly. How

To generate all the MS Help source files for an entire Help file:

1.	On the Navigator, select the top level module for the Help file.

2.	Choose Generate→Generate Module As

3.	Click Help System and then OK.

4.	Choose Generate all the MS Help source files.

This option generates all the source files required to create a standalone Help file (Help project file (.HPJ), topic files (.RTF), mapping files (.HM) and glossary file (.RTF).

5.	Select Include the module network in this help system.

This generates Help source files for the whole module network starting from the chosen module.

Note: 	You can create a standalone (temporary) Help project for a single module, for testing and debugging purposes.

6.	Use the Post Generation options to specify whether to save changes to the repository during generation:

•	Commit - update repository objects

•	Revert - do not update repository objects

•	Browse/Edit - show proposed repository changes, enabling you to choose how to process them

Note that there are some circumstances when MS Help Generator will not update properties of repository objects. For more information, refer to When are repository objects not updated during generation and design capture.

7.	Click Start.

Next step

After successful generation, compile the MS Help file. How


Generating temporary Help files for testing

Related Topics	Where am I?

You can generate and compile temporary Help files for testing purposes.

Note:	Ensure that MS Help Generator options are set correctly How

To generate a temporary Help file for testing:

1.	On the Navigator, select the module you require.

Do not specify a Help File Name against the module, MS Help Generator creates a temporary project file named t_<implementation name>.hpj.

2.	Choose Generate→Generate Module As.

3.	Click Help System and then OK.

4.	Choose Generate all the MS Help source files.

This option generates all the source files required to compile the temporary Help file.

5.	To generate a temporary help file for a

•	single module, deselect Include the module network...

•	module sub network, select Include the module network...

6.	Use the Post Generation options to specify whether to save changes to the repository during generation:

•	Commit - update repository objects

•	Revert - do not update repository objects

•	Browse/Edit - show proposed repository changes, enabling you to choose how to process them

Note that there are some circumstances when MS Help Generator will not update properties of repository objects. For more information, refer to When are repository objects not updated during generation and design capture.

7.	Click Start.

Next step

After successful generation, compile the MS Help file. How


 Updating MS Help source files for individual modules

Related Topics	Where am I?

You can update the topic (RTF) and mapping (HM) file for a single module. This option avoids having to regenerate a complete new set of Help source files when modifications are restricted to a specific module.

Note:	Ensure that MS Help Generator options are set correctly How

To update MS Help source files for an individual module:

1.	On the Navigator, select the module that has been modified.

2.	Choose Generate→Generate Module As

3.	Click Help System and then OK.

4.	Click Only generate the topic (.RTF) file and the mapping (.HM) files.

5.	Use the Post Generation options to specify whether to save changes to the repository during generation:

•	Commit - update repository objects

•	Revert - do not update repository objects

•	Browse/Edit - show proposed repository changes, enabling you to choose how to process them

Note that there are some circumstances when MS Help Generator will not update properties of repository objects. For more information, refer to When are repository objects not updated during generation and design capture.

6.	Click Start.

Next step

After successful generation, compile the MS Help file. How


 Compiling MS Help source files after generation

Related Topics	Where am I?

The MS Help generation process creates all the source files needed to compile the Help file (.HLP). Immediately after generation, you can compile the Help source files from Design Editor. About

To compile generated MS Help source files after generation from Design Editor:

During generation the Message Window displays progress information and details of errors that occur. If necessary, use the automated message action facility to fix any errors that occur and then generate the Help again. After successful generation follow the steps below:

1.	Choose Messages→Build Actions, or click [image] on the Message Window.

Note: Actions are only displayed after generation.

2.	Double-click Compile Help File from the list of possible actions.

If compilation is not initiated check the name and location of the Help compiler How

3.	Check for any errors which may have occurred during compilation. Tip

If a compilation error means you must make changes to one or more modules, remember to generate the appropriate source files again, before attempting to recompile.

4.	In the Design Editor Build Action dialog, double-click 'Run Help File' to view the compiled Help file.

Next step

Run the compiled Help file to check for errors and omissions. How

Once complete, you can either:

•	test the Help file in conjunction with the generated Windows application How

•	or, extend the Help design and customize layout How


Compiling MS Help source files independently from Design Editor

Related Topics	Where am I?

The generation process creates all the source files needed to compile a Windows Help file (.HLP). About

If necessary you may compile a generated Help file independently from Design Editor. The steps required depend on which Help compiler you have chosen to use:

To compile MS Help source files from MS-DOS using HC31, HC or HCP:

1.	Switch to MS-DOS.

2.	Change to the DOS directory containing the generated Help source files.

3.	Enter the appropriate command at the DOS prompt:

hc31 <Help project file name>
hc <Help project file name>
hcp <Help project file name>

If the error log file contains error numbers instead of error messages, ensure that the appropriate WinHelp error message file (HCP.ERR, HC.ERR, HC31.ERR) is located in the same directory as the Windows Help Compiler.

To compile MS Help source files from Help Workshop (HCW):

1.	Choose File→Compile

2.	In the Project File box, type the name and location of the project (.hpj) file you want to compile, and then click Compile.

Next step

Run the compiled Help file to check for errors and omissions. How

Once complete, test the Help file in conjunction with the generated Windows application. How


 Running and checking Help files after generation

Related Topics	Where am I?

After compiling a Help file from generated source files, you may wish to run the Help file as a standalone application to first check, and then refine, the contents. About

To follow the steps below ensure that MS Help source files have been:

•	generated successfully  How

•	compiled successfully  How

To run the generated Help file after generation from Design Editor:

1.	Choose Messages→List Actions, or click [image] on the Message Window.

Note: Actions are only displayed after generation.

2.	Double-click Run Help File from the list of possible actions.

If the Help file is not displayed check the name and location of the Window Help executable How

3.	Review the Help file.

For more information, see troubleshooting tips.

4.	Make changes to the Help file content, as required. How

5.	Generate the Help source files again:

•	if you made changes to several modules, included new modules, changed container-level preferences, or modified glossary terms, generate all the MS Help source files again How

•	if your changes are limited to one or two specific modules, update the MS Help source files for the affected modules How

6.	Compile the Help source files again How

Next step

Once complete, test the Help file in conjunction with the target Windows application. How


Testing Help with a generated application

Related Topics	Where am I?

Once the contents of a Help file has been checked and refined, you may test it in conjunction with the target Windows application. Essentially, this involves verifying correct entry into the Help file.

Note:	Only test with the final, entire Help file. Standalone, temporary Help files generated for testing purposes will not run with the generated application.

To regenerate Windows applications and test Help file integration:

1.	To incorporate Help context IDs into the application design, generate the Windows application again using the appropriate Oracle Designer Generator.

Note:	For Form Builder applications ensure that the Type of help system used (HLPTYP) preference is set to MSHELP.

2.	Check that the Help file, or files, reside in the directory expected by the generated application:

Form Builder	HELPFILE_PATH parameter

Visual Basic	HelpFilePath parameter

3.	Run the generated application.

4.	Select any Help menu items to check that the Help file opens correctly.

5.	Select F1 to check context-sensitive entry points on different items in the generated application.

If the Help file opens at the wrong topic, it is either because the application element has no context ID allocated, or it is incorrect. This may occur if you forget to generate all or part of the target application again, after changes have been made to the Help file structure.


Troubleshooting tips (MS Help)
Troubleshooting tips

Related Topics

Use this checklist while testing and refining the contents of a generated Help file. The list is categorized into the following sections:

•	module information

•	module component information

•	item information

•	keywords

•	glossary popups

Module information

Missing modules ?

If whole modules are missing, or should not be included, the most likely problem is that you selected the incorrect module for generation. Remember to select the top-level module of the Help file, and if you want to include all the other modules which are directly/indirectly called from this one, also remember to select the 'Include the module network' checkbox.

Individual modules may be missing if you entered a different Help File Name against the missing module by mistake, i.e. different from the expected top-level module's Help File Name. The same error may also cause module sub networks to be missing.

Missing module help text?

If you forget to enter a module description, use Design Editor to add the module help text.

Missing/wrong graphics on module topics ?

If the wrong graphic is displayed, check the module's Graphic File Name property. Ensure the name and file extension are correct.

If the graphic is missing, check the Graphic File Location preference for the module, or container (i.e. folder or application system). Ensure the correct path to the graphic has been specified. Also check the directory itself to ensure the file is stored in the correct place.

Module topics too long, or too short ?

You can control the length of module topics using the New topic for each module component (TUPLCT) preference. Choose 'Always' to split up a long topic into a series of smaller topics. Choose 'Never' to combine a small amount of module information into one topic. This preference is normally set at the module level, rather than the container level.

Module component information

Missing module component help text ?

If you forget to enter a module component description, use Design Editor to add the module component Help text.

Module component topics too long, or too short?

You can control the length of module component topics using the New topic for each item group (IGPLCT) preference. Choose 'Always' to split up a long topic into a series of smaller topics. Choose 'Never' to combine a small amount of module component information into one topic. This preference is normally set at the module level, rather than the container level.

List of item descriptions too long?

If there is a long list of item descriptions it is helpful to provide jumps to each description at the beginning of the topic. These jumps provide an easier way to access the information. Set the Add hyperlinks to item Help text (DCUJPS) preference to include jumps.

Item information

Missing item help text ?

If you forget to enter an item description, use Design Editor to add the item Help text.

Headings with no descriptions ?

If you intentionally do not enter an item description, you may also want to hide the associated heading. Set the Display prompts for items with no Help text (DCUCAP) preference to 'No'.

Keywords

Select the Search button on the main Help window and review the current set of keywords:

•	adequate for searching ?

•	additional keywords required ?

•	incorrect or ambiguous ?

Modify or add new keywords as required. If some auto-generated keywords do not appear in the keyword list as expected, ensure that the Use prompts as keywords (CAPKEY) preference is set to 'Yes' at both the container and module level.

Glossary Popups

Review the glossary terms which appear in the Help file:

•	any missing?

•	additional terms required?

•	descriptions satisfactory?

A new or updated glossary file is generated only when you select 'Generate all the Help source files' So any terms you add after generating from this option will be missing from the compiled Help file.

Therefore whenever you add glossary terms or modify their descriptions, remember to generate again, using the 'Generate all the Help source files' option.


About extending the Help design and customizing layout
Extending the Help design and customizing layout

Related Topics	Where am I?

Recording Help text and keywords against every module in a Help file creates a basic Help file for your generated application. In addition to you can:

•	add extra keywords  How

•	define popup glossary terms  How

•	illustrate module topics  How

•	define context ID prefixes  How

•	modify the topic structure using preferences How

New topic for each module component (TUPLCT)
New topic for each item group (IGPLCT)
Add jumps to item Help text (DCUJPS)

•	choose what is displayed when no Help text is available using preferences How

Action when no module component Help text defined (DTUNHP)
Action when no item Help text defined (DCUNHP)
Display prompts for items with no Help text (DCUCAP)

Generating MS Help source files after customization

When you modify a Help related property or preference you will have to generate all or some of the MS Help source files again. MS Help Generator provides several generation options to support the various stages of help development. For example, you can:

•	generate a temporary help file for a single module or module sub network for testing purposes  How

•	update files for individual modules How


Defining glossary terms

Related Topics	Where am I?

Glossary terms specific to a generated Windows application can be defined in the repository as Business Terminology, using Repository Object Navigator. About

To define popup glossary terms for a container (i.e. folder or application system):

1.	Open Repository Object Navigator.

Tip: If Design Editor is open, choose Tools→Repository Object Navigator.

2.	Choose Tools→Property Palette

3.	On the Navigator, select the Ref Data tab.

4.	Select the container.

5.	Choose Edit→Create Child and select Business Terminology.

6.	In the properties window, enter the Name of the glossary term.

MS Help Generator searches each topic file for the word or phrase you specify here. It also creates an alphabetical listing of all the glossary terms you have defined ,which is accessible via the Glossary button.

Note:	In some languages, the initial character of the glossary term (Name property) may not map to a character in the language character-set. In these cases, use the Glossary Grouping Character property to specify which character (in the character-set) this term should be listed under on the glossary topic i.e. the topic displayed when the Glossary button is selected.

7.	Double-click the Comment property.

8.	Enter a short description which defines the glossary term.

The description may be up to 240 characters in length. When the reader clicks on the glossary term in the Help file, the information specified here is displayed in a popup window.

9.	Click [image] to save.

Next step

After adding or modifying Business Terminology, remember to Generate all the MS Help source files again. How

This will update the glossary file and ensure that any new or modified popup terms appear in the Help file, the next time it is compiled.


Customizing the Help design using preferences
Customizing MS Help using preferences

Related Topics	Where am I?

MS Help Generator provides a set of Help design preferences that can customize the structure, appearance and functionality of a generated Help file to suit the nature of your Windows application. Typically you set these preferences while refining the Help file. However you can set these preferences before generating for the first time, if from prior experience you know what the appropriate settings should be.

To customize Help design using preferences:

1.	In Design Editor, display the Generator Preference Palette for the container (i.e. folder or application system), module or module component. How

2.	From the Product dropdown list, select Help Generator.

3.	From the preference list, select the preference you want to change.

The preferences displayed depends on the type of element selected (on the Navigator).

4.	Set the new preference value.

5.	Click [image] to save.

Next step

To view the effect of a new preference setting you must run MS Help Generator and recompile the updated Help source files. If you change any preference at the:

Container level	Generate all the MS Help source files for the module network again. How
Module level	Update the topic and mapping files for the module that has changed. How


Defining context ID prefixes

Related Topics	Where am I?

If you intend to migrate or share modules (or module components) between containers (i.e. folders and application systems) it is advisable to enter your own unique context ID prefixes against modules and reusable module components included in the Help file. This will ensure that the overall context ID remains unique. About

To define context ID prefixes:

1.	In Design Editor, choose Options→Use Property Palette.

2.	On the Navigator, double-click the module or reusable module component.

3.	Enter a unique 3 digit Help Context ID Prefix.

•	each module must have a unique value

•	each reusable module component must have a unique value

4.	Click [image] to save.

Next step

Note the following:

•	Whenever you specify, or modify a Context ID Prefix you must generate the mapping file (.HM) for the affected modules and compile the Help file again. How

•	MS Help Generator will automatically allocate a Context ID Prefix if one is not defined

In both cases, you must also generate the Windows application again using the appropriate Oracle Designer Generator to incorporate new or modified context IDs.


Adding extra keywords
Adding keywords

Related Topics	Where am I?

Keywords can be defined at the same time you enter Help text for module definitions, module components, item groups and items. About

To add keywords:

1.	Open the module diagram in Design Editor. How

2.	Choose Options→Use Property Palette.

3.	On the module diagram, double-click the module element that requires keywords.

This may be the module itself, a module component, an item group or an item.

4.	Double-click the User/Help Text property to open the TextPad.

5.	After the Help text, enter the keywords you require. Tip

Place each word or phrase on a new line, prefixed with the keyword identifier
@@  Example

6.	Click [image] to save.

Note that you can enable or disable automatic keyword generation using the Use prompts as keywords (CAPKEY)  preference.

Next step

When you specify or modify a keyword you must generate the module's topic file (.RTF) again. How

The new keywords will appear in the Help file the next time it is compiled.


Illustrating module topics

Related Topics	Where am I?

You can illustrate each module topic with a graphic. All you need to do is specify the name of the graphic file you wish to use and its location, so the picture is included during compilation. About

To illustrate a module topic:

1.	Choose Options→Use Property Dialogs.

2.	On the Navigator, double-click the module.

3.	Enter the Help Graphic File Name.

The name and file extension must be specified here. Valid file formats are BMP, WMF and MRB.

Note:	Do not enter the path here.

4.	Click [image] to save.

5.	Use the Graphic Locations (GRHLOC) preference to define where the graphic file is stored. How

Next step

When you specify or modify a Graphic File Name you must generate the module's topic file (.RTF) again. How


Defining the location of graphic files

Related Topics	Where am I?

You can illustrate each module topic with a graphic by specifying:

•	the name of the graphic file to use  How

•	the location of the graphic file

During generation, MS Help Generator includes:

•	a reference to the graphic file in the generated .rtf file

•	the specified location in the generated .hpj file as the BMROOT option

During compilation, the Help compiler

•	identifies the graphic files referenced in generated .rtf files

•	searches for the graphic files in the locations specified by the BMROOT option in the generated .hpj file

Note that you can store graphic files in the repository as well as in the filesystem. MS Help Generator synchronizes files in the repository with files in the filesystem during generation to ensure the Help compiler uses the correct versions of files during compilation. Use the Source options on the Help System Generator Options dialog box to specify whether graphics files are stored in the repository (and therefore require synchronizing) or on the filesystem (no synchronization required). In either case, MS Help Generator includes the location specified by GRHLOC in the generated .hpj file for use by the Help compiler.

To define the location of graphic files:

1.	From the Navigator, select the node for the container (i.e. folder or application system) i.e. the top-level node.

2.	Choose Edit→Generator Preferences.

3.	Set the Product to Help Generator.

4.	Expand the General category and use the Graphic Locations (GRHLOC) preference to define the directory, or directories, where graphic files are stored.

5.	Click [image] to save.

Next step

When you add or modify a graphic location you need to Generate all the Help source files for the module network again. How

This updates the Help project file with the new settings and the graphics appear in the Help file the next time it is compiled.


Setting the location of generated Help files

Related Topics	Where am I?

By default, all files generated by MS Help Generator are saved to the working directory of Oracle Designer. If the working directory is not suitable, change the directory where generated MS Help files are stored.

To define a new location for generated files:

1.	In Design Editor, choose Options→Generator Options→Help System

2.	Use the Destination of generated files field to specify the directory where generated MS Help files are stored.

3.	Click OK.


Defining the Help compiler

Related Topics	Where am I?

Before running MS Help Generator, define the name and location of the Help compiler that must be used to compile the generated MS Help source files. About

To select a Help compiler:

1.	In Design Editor, choose Options→Generator Options→Help System

2.	Enter the name and location of the Help compiler you wish to use.

Valid Help compilers are HC31.EXE, HC.EXE, HCP.EXE and HCW.EXE (HCRTF.EXE). Select a compiler that creates Help files compatible with the version of Windows running your generated application.

Note:	If you want to use the compiler that runs from Help Workshop, enter the name and location of the Help Workshop executable (HCW.EXE) rather than the compiler itself (HCRTF.EXE). You should also enter the  /C switch command. For example, d:\winhelp\hcw.exe /c

3.	Click OK.


Defining the Help viewer executable

Related Topics	Where am I?

Before running MS Help Generator, define the name and location of the Windows Help executable that must be used to run the compiled Help file. About

To select a Help viewer executable:

1.	In Design Editor, choose Options→Generator Options→Help System

2.	Enter the name and location of the Help Executable you wish to use.

Valid viewer executables are WINHELP.EXE and WINHLP32.EXE. Select the Help viewer that is compatible with the version of Windows running your generated application.

3.	Click OK.


Checking for compilation errors

If compilation takes place under MS DOS, use Notepad or a similar text editor to open the error log file hcp_errs.txt. This file is saved to the same directory as other generated MS Help source files. If the error log file contains error numbers instead of error messages, ensure that the appropriate WinHelp error message file (HCP.ERR or HC31.ERR) is located in the same directory as the Help compiler.

If compilation takes place under Help Workshop, any errors are displayed after compilation.


Help text tips

Text can be cut, copied and pasted to and from all Help text boxes using the hot-keys Ctrl+X, Ctrl+C and Ctrl+V.


Important:

If your Help file is to be launched from a 16-bit program, the generated MS source files must be compiled using either HC31.EXE, HC.EXE or HCP.EXE. These compilers support only eight character filenames.

MS Help Generator uses the Implementation Name of the module definition to name generated Help source files. To ensure the names of all the generated MS source files do not exceed the eight character limitation, the Implementation Name must be 6 characters or less.  In the absence of an Implementation Name the module Short Name is used instead, so if the Short Name is being used, check it does not exceed 6 characters.


Generating MS Help for Windows applications

	Generate and test Windows application
	Set MS Help Generator options
	Plan the Help system
	Name the Help files
	Record basic content for each Help file Define Help against the module definition Define Help against module components Define Help against item groups Define Help against items
	Extend Help design and customize layout Define popup glossary terms Add extra keywords Illustrate module topics Implement context sensitive Help Customize MS Help using preferences
	Generate MS Help source files
	Compile MS Help source files
	Run and check generated Help file
	Test Help with generated application


Generating MS Help for Windows applications

	Generate and test Windows application
	Set MS Help Generator options
	Plan the Help system
	Name the Help files
	Record the basic content of each Help file
	Extend Help design and customize layout
	Generate MS Help source files
	Compile MS Help source files
	Run and check generated Help file
	Test Help with generated application


Generating MS Help for Windows applications

	Generate and test Windows application
	Set MS Help Generator options
	Plan the Help system
	Name the Help files
	Record the basic content of each Help file
	Extend Help design and customize layout
	Generate MS Help source files
	Compile MS Help source files
	Run and check generated Help file
	Test Help with generated application


Generating MS Help for Windows applications

	Generate and test Windows application
	Set MS Help Generator options
	Plan the Help system
	Name the Help files
	Record the basic content of each Help file
	Extend Help design and customize layout
	Generate MS Help source files
	Compile MS Help source files
	Run and check generated Help file
	Test Help with generated application


Generating MS Help for Windows applications

	Generate and test Windows application
	Set MS Help Generator options
	Plan the Help system
	Name the Help files
	Record the basic content of each Help file
	Extend Help design and customize layout
	Generate MS Help source files
	Compile MS Help source files
	Run and check generated Help file
	Test Help with generated application


Generating MS Help for Windows applications

	Generate and test Windows application
	Set MS Help Generator options
	Plan the Help system
	Name the Help files
	Record the basic content of each Help file
	Extend Help design and customize layout
	Generate MS Help source files
	Compile MS Help source files
	Run and check generated Help file
	Test Help with generated application


Generating MS Help for Windows applications step-by-step

	Generate and test Windows application
	Set MS Help Generator options
	Plan the Help system
	Name the Help files
	Record the content of each Help file Define Help against the module definition Define Help against module components Define Help against item groups Define Help against items
	Extend Help design and customize layout
	Generate MS Help source files
	Compile MS Help source files
	Run and check generated Help file
	Generate the Windows application again
	Test Help with generated application


Generating MS Help for Windows applications step-by-step

	Generate and test Windows application
	Set MS Help Generator options
	Plan the Help system
	Name the Help files
	Record the content of each Help file Define Help against the module definition Define Help against module components Define Help against item groups Define Help against items
	Extend Help design and customize layout
	Generate MS Help source files
	Compile MS Help source files
	Run and check generated Help file
	Generate the Windows application again
	Test Help with generated application


Generating MS Help for Windows applications step-by-step

	Generate and test Windows application
	Set MS Help Generator options
	Plan the Help system
	Name the Help files
	Record the content of each Help file Define Help against the module definition Define Help against module components Define Help against item groups Define Help against items
	Extend Help design and customize layout
	Generate MS Help source files
	Compile MS Help source files
	Run and check generated Help file
	Generate the Windows application again
	Test Help with generated application


Generating MS Help for Windows applications step-by-step

	Generate and test Windows application
	Set MS Help Generator options
	Plan the Help system
	Name the Help files
	Record the content of each Help file Define Help against the module definition Define Help against module components Define Help against item groups Define Help against items
	Extend Help design and customize layout
	Generate MS Help source files
	Compile MS Help source files
	Run and check generated Help file
	Generate the Windows application again
	Test Help with generated application


Generating MS Help for Windows applications step-by-step

	Generate and test Windows application
	Set MS Help Generator options
	Plan the Help system
	Name the Help files
	Record the content of each Help file Define Help against the module definition Define Help against module components Define Help against item groups Define Help against items
	Extend Help design and customize layout
	Generate MS Help source files
	Compile MS Help source files
	Run and check generated Help file
	Generate the Windows application again
	Test Help with generated application


Generating MS Help for Windows applications step-by-step

	Generate and test Windows application
	Set MS Help Generator options
	Plan the Help system
	Name the Help files
	Record the basic content of each Help file
	Extend Help design and customize layout Define popup glossary terms Add extra keywords Illustrate module topics Implement context sensitive Help Customize MS Help using preferences
	Generate MS Help source files
	Compile MS Help source files
	Run and check generated Help file
	Generate the Windows application again
	Test Help with generated application


Generating MS Help for Windows applications step-by-step

	Generate and test Windows application
	Set MS Help Generator options
	Plan the Help system
	Name the Help files
	Record the basic content of each Help file
	Extend Help design and customize layout Define popup glossary terms Add extra keywords Illustrate module topics Implement context sensitive Help Customize MS Help using preferences
	Generate MS Help source files
	Compile MS Help source files
	Run and check generated Help file
	Generate the Windows application again
	Test Help with generated application


Generating MS Help for Windows applications step-by-step

	Generate and test Windows application
	Set MS Help Generator options
	Plan the Help system
	Name the Help files
	Record the basic content of each Help file
	Extend Help design and customize layout Define popup glossary terms Add extra keywords Illustrate module topics Implement context sensitive Help Customize MS Help using preferences
	Generate MS Help source files
	Compile MS Help source files
	Run and check generated Help file
	Generate the Windows application again
	Test Help with generated application


Generating MS Help for Windows applications step-by-step

	Generate and test Windows application
	Set MS Help Generator options
	Plan the Help system
	Name the Help files
	Record the basic content of each Help file
	Extend Help design and customize layout Define popup glossary terms Add extra keywords Illustrate module topics Implement context sensitive Help Customize MS Help using preferences
	Generate MS Help source files
	Compile MS Help source files
	Run and check generated Help file
	Generate the Windows application again
	Test Help with generated application


Generating MS Help for Windows applications step-by-step

	Generate and test Windows application
	Set MS Help Generator options
	Plan the Help system
	Name the Help files
	Record the basic content of each Help file
	Extend Help design and customize layout Define popup glossary terms Add extra keywords Illustrate module topics Implement context sensitive Help Customize MS Help using preferences
	Generate MS Help source files
	Compile MS Help source files
	Run and check generated Help file
	Generate the Windows application again
	Test Help with generated application


Generating MS Help for Windows applications step-by-step

	Generate and test Windows application
	Set MS Help Generator options
	Plan the Help system
	Name the Help files
	Record the basic content of each Help file
	Extend Help design and customize layout Define popup glossary terms Add extra keywords Illustrate module topics Implement context sensitive Help Customize MS Help using preferences
	Generate MS Help source files
	Compile MS Help source files
	Run and check generated Help file
	Generate the Windows application again
	Test Help with generated application


Generating MS Help for Windows applications step-by-step

	Generate and test Windows application
	Set MS Help Generator options
	Plan the Help system
	Name the Help files
	Record the basic content of each Help file
	Extend Help design and customize layout
	Generate MS Help source files
	Compile MS Help source files
	Run and check generated Help file
	Test Help with generated application


Generating MS Help for Windows applications step-by-step

	Generate and test Windows application
	Set MS Help Generator options
	Plan the Help system
	Name the Help files
	Record the basic content of each Help file
	Extend Help design and customize layout
	Generate MS Help source files
	Compile MS Help source files
	Run and check generated Help file
	Test Help with generated application


Generating MS Help for Windows applications step-by-step

	Generate and test Windows application
	Set MS Help Generator options
	Plan the Help system
	Name the Help files
	Record the basic content of each Help file
	Extend Help design and customize layout
	Generate MS Help source files
	Compile MS Help source files
	Run and check generated Help file
	Test Help with generated application


Generating MS Help for Windows applications step-by-step

	Generate and test Windows application
	Set MS Help Generator options
	Plan the Help system
	Name the Help files
	Record the basic content of each Help file
	Extend Help design and customize layout
	Generate MS Help source files
	Compile MS Help source files
	Run and check generated Help file
	Test Help with generated application


Aspects of Help generation

Aspects of generated Help

Files created by MS Help Generator

Help File Name property

Topic titles and headings

Contents topic elements

Generated context strings and context IDs

Hints and tips

Tips on graphics

Troubleshooting tips


About the Help File Name property

Related Topics

You can define the Help File Name property against a module definition. How

MS Help Generator uses this property to name the Help file generated from the module, plus any descendant modules where the Help File Name property is undefined.

Creating a single Help file for a module network

If you specify a Help File Name on a particular module, it implies that the given module is the top-level module for a Help file. MS Help Generator will then create a Help file describing the module network which exists below this top-level module, and uses the property to name the compiled Help file.

Note:	Descendent modules are included in the Help file only if they have the same Help File Name, or if the property is undefined.

In the example below, one Help file (helpme.hlp) will be created for the entire module network, because the Help File Name properties of all the modules below the top-level module are undefined.

Creating multiple Help files for a module network

If the Help File Name property is blank, the module's Help text is incorporated into the Help file of the nearest parent module, where the property is defined. If you want to implement a Help system comprising multiple Help files, you must first identify which modules will become the top-level module of each Help file. Then you simply set a new Help File Name property on the top-level module of each Help file you require.

In the example module network below, a different Help File Name property has been set on three of the modules. This scenario generates three Help files:

helpme1.hlp	Contains Help text for modules A, C and G It also has links to B and D
helpme2.hlp	Contains Help text for modules B, E and F
helpme3.hlp	Contains Help text for modules D, H and I


Files created during MS Help generation

Related Topics

During generation, MS Help Generator creates all the files which are required to build a context sensitive Windows Help file (.RTF, .HPJ, .HM, .HLP). It is not necessary for you to know the exact contents of these files but you may wish to understand why they are created, their names and where they will be stored.

If you are unfamiliar with the fundamentals of Windows Help development, read the overview first. This topic explains the various files which make up a typical Help project. The following topic provides detailed information on how MS Help Generator creates and names these files:

•	About MS Help source files (overview)

•	About files created by MS Help Generator


About MS Help source files
About MS Help source files (overview)

Related Topics

This diagram illustrates the various files which make up a typical Windows Help file.

Source File	Type	Description
Topic	.RTF	Topic text and hyperlinks to other topics. Also includes codes to link topics, define popups, include graphics, define keywords and create browse sequences. A single RTF file may contain the source text for many topics. Text is stored in Rich Text Format.
Graphics	.BMP .WMF .MRB	Pictures to illustrate the Help file in several graphic formats; Windows Bitmap, Windows Metafile, Multi-resolution Bitmap.
Project	.HPJ	ASCII file describing how to make the Help file. It names source files, locates pictures, dictates how files are compiled and what the final Help window looks like. Every Windows Help file has an associated project file.
Mapping	.HM	ASCII file listing context strings and their associated context IDs. A context string identifies a unique location within a topic file. Context IDs are mapped to context strings to facilitate context-sensitive entry to the help file from an external application (e.g. Oracle Forms, Oracle Power Objects or Visual Basic).
Help	.HLP	Compiled Help file.


About files created by MS Help Generator

Related Topics

During generation, MS Help Generator transforms module design information into file formats which are recognized by the Windows Help compiler. It is not necessary for you to know the exact contents of these files but you may wish to know why they are created and their file names.

You can define a specific location for generated files using the MS Help Generator Options dialog. How

The MS Help generation process creates:

•	a topic file for each module (RTF)

•	a mapping file for each module (HM)

•	a project file for the Help system (HPJ)

•	a glossary file for the Help system (RTF)

•	the final Help file (HLP)

Caution	Any existing files with the same name(s) as generated files will be overwritten.

Module topic files (.RTF)

A separate topic file is generated for every module to be included in the Help file.

Note:	Separate files are not created for menu modules. Menu information is incorporated within the appropriate module topic file.

Topic filenames are derived from the module's Implementation Name property i.e. <module implementation name>.rtf

Examples:	emp.rtf      ordent.rtf      cust.rtf

The names of all the topic files are added to the [Files] section of the Help project file (HPJ). This ensures they are included when the Help file is compiled.

Mapping file (.HM)

A separate mapping file is generated for every module to be included in the Help file. These files store context mappings for the module, i.e. a list of context strings and their associated context IDs. Like topic files, the names of these files are derived from the module's Implementation Name property i.e. <module implementation name>.hm

Examples:	emp.hm     ordent.hm      cust.hm

The names of all the mapping files are added to the [Map] section of the Help project file (HPJ). This ensures the Help file is context-sensitive when used in conjunction with the generated application.

Project file (.HPJ)

During generation MS Help Generator makes use of a template project file (template.hpj). The contents of this file are modified to include:

File section
[FILES]	Lists the topic files (.RTF)
[MAP]	Lists the mapping files (.HM)
[BMROOT]	Path names to graphics files
[OPTIONS]	Title of the Help system
[OPTIONS]	Context string for the Contents topic
[CONFIG]	Glossary button for the Help toolbar
The name of the project file is derived from the Help File Name property of the top-level module i.e. <help file name>.hpj

However, if you decide to create a temporary Help file (for testing and debugging purposes), the Help File Name property may not be defined on the module chosen for generation. In this instance MS Help Generator creates a temporary project file named t_<implementation name>.hpj.

Note:	A project file is not generated when you select the 'Only generate the topic (RTF) and mapping (HM) file' option. In this case it is assumed that one has been generated previously.

Glossary file (.RTF)

A separate .RTF file is created for any glossary terms defined as Business Terminology in the repository. MS Help Generator creates only one glossary file per container (i.e. folder or application system) and therefore the name of this file is derived from the container's Name property i.e. g_<container name>.rtf

Example:	g_obs.rtf

MS Help Generator adds the name of this file to the [Files] section of the Help project file (HPJ). This ensures that popup descriptions for glossary terms are included when the Help is compiled. If a glossary file exists a Glossary button appears in the toolbar.

A glossary file is not generated:

•	if you select the 'Only generate the topic (RTF) and mapping (HM) file' option. In this case it is assumed that one already exists

•	when no terms are defined for the container.

Help file (.HLP)

All the generated Help source files are used to compile the final Windows Help file. The name of the Help file is derived from the Help File Name property of the top-level i.e. <help file name>.hlp.

If you create a temporary Help file (for testing and debugging purposes), the Help File Name property may not be defined. In this instance the temporary Help file will be named t_<implementation name>.hlp.

Note:	Only test with the final, entire Help file. Standalone, temporary Help files generated for testing purposes will not run with a generated application.

Following generation, Help files may be compiled from Design Editor.


template.hpj

[OPTIONS]

title=[TOP-LEVEL MODULE TOP TITLE] Help

compress=0

warning=3

report=1

errorlog=hcp_errs.txt

bmroot=[GRAPHIC LOCATIONS]

[FILES]

[MODULE IMPLEMENTATION NAME].rtf

g_[CONTAINER NAME].rtf

[CONFIG]

BrowseButtons()

CreateButton("btn_glossary", "&Glossary", "JumpId(`[HELP FILE NAME].hlp >glossary', `gls_contents')")

[MAP]

#include [MODULE IMPLEMENTATION NAME].hm

[WINDOWS]

main=, , 0, , (255,255,255)

glossary=" Glossary",(0,0,400,500),0, , (255,255,255), 1


About topic titles and headings in generated Help files
About topic titles and headings

Related Topics

Topic titles and headings within generated Help files are derived from module design information held in the repository. This topic details where title text comes from, which may be useful if you want to quickly find out how to make changes to a particular Help title or heading:

•	Help file title

•	topic titles

•	headings

Help file title

The title of the Help file is displayed on the title bar at the top of the Help window. It is also displayed beneath the Help icon on the Windows desktop. MS Help Generator derives the Help file title from the 'Top Title' property of the top-level module for the Help system for example, <Top Title> Help

If the Top Title property is not defined, the module 'Short Name' is used instead.

Topic titles

Topic titles appear in the non-scrolling region of a Help window. They are also displayed as the result of keyword searches to indicate which topics contain keyword-related information. The table below show the repository properties used to derive topic titles. They also detail what substitute text is used if the first property is omitted.

Repository element	Repository property	If omitted
Module definition	Top Title	Short Name
Module component	Title	Name
Item group	Prompt	Name
Topic titles are also used within hyperlinks.

Headings

Headings appear within topics and they are normally generated for the titles of item descriptions which do not require a topic of their own. The table below shows the repository property normally used to derive headings. It also details what substitute text is used if the first property is omitted and there is Help text to display.

Repository element Item	Repository property Prompt	If omitted Name
Headings are not only generated for item descriptions. Headings may be created for module component and item group descriptions if you have chosen to combine topics using these preferences:

•	New topic for each module component (TUPLCT)

•	New topic for each item group (IGPLCT)

Handling special characters in headings

If the title text contains special marker characters they will be removed. For example, you may have used the '&' character in the module top title to specify a mnemonic character for the item in the generated application i.e.

Product &Codes -> Product Codes

In this instance MS Help Generator removes the '&' character such that 'Product Codes' is displayed in the Help file.

Note:	If you want '&'  to be generated, it must be prefixed with the same character i.e. '&Names &&Addresses' is displayed in the Help file as 'Names & Addresses'.


About Contents topic elements

Related Topics

This table shows the repository properties used to generate elements of the Contents page:

Contents topic element	Repository property
Graphic	Graphic file defined for the top-level module.
Contents topic title	Top Title property of the top-level module.
Help file introduction	Module Help text for the top-level module.
Jumps to module topics	Top Title property of each called module.
Jumps to module component topics	Title property of any top-level module components. Typically, the top-level module is created to link called modules, so normally it does not have module components.
Help file title⇒ Graphic and topic title⇒ Help file  introduction ⇒ Jumps to called module topics ⇒


About generated context strings and context IDs

Related Topics

The derivation of context strings and context IDs are detailed here for reference purposes only.

Context IDs

MS Help Generator allocates a unique context ID to all module elements that provide context-sensitive entry to the Help file i.e. modules, module components and items. A map file (.HM) is then created to store the mappings between context strings and context IDs that are generated for each module.

The context ID is made up of three parts to ensure they are unique within a Help file:

<module prefix><reusable module component prefix><item suffix>
<     XXX            ><                          YYY                                ><      ZZZZ       >

module prefix	A unique 3 digit integer that can be defined by the user against modules included in the Help file. How
reusable module component prefix	A unique 3 digit integer that can be defined by the user against reusable module components included in the Help file. How
item suffix	A 4 digit integer automatically generated by MS Help Generator to be unique within the module.
For example,

Module	XXX 000 0000
Specific module component	XXX 000 ZZZZ
Reusable module component	XXX YYY 0000
Item (specific module component)	XXX 000 ZZZZ
Item (reusable module component)	XXX YYY ZZZZ
After Help generation, context IDs are saved back to the repository. This is so that other Oracle Designer Generators can use the context IDs to add context sensitive Help to the generated application.

Context id values are also used as the context string.

Context strings

Context strings are unique values within a Help file that are used to define jumps to the start of a topic, or somewhere specific within a topic. Context strings can also be mapped against a context ID to provide context-sensitive entry to the specific Help file location.

MS Help Generator creates context strings for module design elements using the convention shown below:

Modules	<Context ID for the module>
Module components	<Context ID for the module component>
Items and item groups	< Context ID for the item or item group>
Glossary terms	term_<unique ID>


Tips on graphics in generated Help files
Tips on using graphics in MS Help files

Related Topics

Graphic File Formats

Graphics must be created independently from the MS Help generation process and saved in one of the following recognized formats:

•	Windows Bitmap (.BMP)

•	Windows Metafile (.WMF)

•	Multi-resolution Bitmaps (.MRB)

File Size

Windows Help limits the size of a paragraph (text and graphics) to 64K. Try not to create large, complex graphics which will exceed this restriction, otherwise you will have problems compiling your Help file. Note that metafile files are typically much smaller than bitmaps.

Physical Size

Graphics which accompany a topic title appear in the non scrolling region at the top of the Help window. Try to use small graphics because this avoids big non scrolling regions, which reduce the area where normal Help text is displayed.

Colors and Resolution

For the best results on most screens:

•	use the Windows 16-color palette.

•	design BMPs for VGA screen resolution.

•	if the screen resolutions may vary, use MRBs wherever possible.

File storage

As well as storing graphic files in the filesystem for use during generation, you can also store graphic files in the repository. For more information, refer to About storing files in the repository for use during generation.


Keyword tips for Help file generation
Keyword tips

Related Topics

Some issues you should consider when entering keywords:

•	normally lowercase

•	any ANSI character

•	a single word or phrase

•	any punctuation, except semicolon


Sample help text and keywords
Product Query Dialog - sample Help text and keywords

This dialog allows you to query which products you are allowed to modify or enter change requests for. Simply click the QUERY button to query the database for the available products. A combo box details the products and their version.

Select the product you require from the list. The change request zone is then prepared to allow the insertion of a new change request.

@@product query

@@query available products

@@change requests, modifying or entering new

@@QUERY button

@@modify change request

@@enter new change request


Repository module properties used by MS Help Generator

Use Design Editor to set these properties How

Module property	Use by MS Help Generator	Notes and Related Topics
Owning Folder	Not used by MS Help Generator.
Short Name	Used to generate a topic title if the module Top Title is not defined.	About topic titles and headings
	Used to name generated files if the Implementation Name is not defined. In this context the name is limited by any filename length restriction.	About files created by MS Help Generator
Name	Not used by MS Help Generator.
Language	Not used by MS Help Generator.
Purpose	Not used by MS Help Generator.
Implementation Name	Used to name the Help topic (.RTF) and mapping (.HM) files generated from this module.  If the Implementation Name is omitted the Short Name is used instead.	About files created by MS Help Generator
	If you have set a length restriction for generated files, ensure this value does not exceed the maximum length allowed; otherwise, generation will be unsuccessful.
Module Type	Defines the type of the module. MS Help Generator only processes modules if the type is DEFAULT or MENU i.e. LIBRARY modules are ignored.
Display
Top Title	Used as the title of the module topic, and as a module identifier within generated keywords.	About topic titles and headings   About keywords
	For the top-level module of the Help system, this is the main title of the generated Help file. This title is displayed on the title bar at the top of the Help window and also beneath the Help icon on the Windows desktop.
Bottom Title	Not used by MS Help Generator.
Short Title	Defines the caption that is displayed on generated buttons.
Layout Format	Not used by MS Help Generator.
Planning
Status	Not used by MS Help Generator.
Candidate?	Not used by MS Help Generator.
Prevent Generation?	Not used by MS Help Generator.
Size	Not used by MS Help Generator.
Complexity	Not used by MS Help Generator.
Project	Not used by MS Help Generator.
Activity	Not used by MS Help Generator.
Task	Not used by MS Help Generator.
Time Estimate	Not used by MS Help Generator.
Estimate Units	Not used by MS Help Generator.
Invocation
Top Level?	Not used by MS Help Generator.
Command Line	Not used by MS Help Generator.
Return Type	Not used by MS Help Generator.
Runtime Path	Not used by MS Help Generator.
Source
Source Path	Not used by MS Help Generator.
Help
User/Help Text	Specifies topic text and keywords for the module topic. If this is a top-level module, this text appears on the contents topic.	About topic text
Help File Name	Defines the name of the compiled Help file (.HLP) created for this module and its associated module network. Only specify this property against the top-level module of a Help file.	About the Help File Name property  About files created by MS Help Generator
Help Graphic File Name	Defines the name and file extension of the graphic file used to illustrate the module topic.  Acceptable file formats are Bitmap (.BMP), Windows Metafiles (.WMF) and Multi-resolution Bitmaps (.MRB).	About graphics
Help Context ID Prefix	Used to generate unique context IDs for the help file. This value must be unique for each module included in a Help file. Optional, but recommended for MS Help generation, a 3 digit integer.	About context-sensitive entry
Documentation
Release Notes	Not used by MS Help Generator.
Description	Not used by MS Help Generator.
Notes	Not used by MS Help Generator.


Repository module component properties used by MS Help Generator

Use Design Editor to set these properties How

Module component property	Use by MS Help Generator	Notes and Related Topics
Owning Folder	Not used by MS Help Generator.
Module	Not used by MS Help Generator.
Name	Not used by MS Help Generator.
Short Description	Not used by MS Help Generator.
Template/Library Object	Not used by MS Help Generator.
Language	Not used by MS Help Generator.
Module Level?	Not used by MS Help Generator.
Sub-component	Not used by MS Help Generator.
Usage Sequence	Not used by MS Help Generator.
Placement
Window	Not used by MS Help Generator.
Placement	Not used by MS Help Generator.
Right of Component	Not used by MS Help Generator.
Placement Template/Library Obj	Not used by MS Help Generator.
X Position	Not used by MS Help Generator.
Y Position	Not used by MS Help Generator.
Relative Tab Stops
Tab Stop Scope	Not used by MS Help Generator.
Data
Datasource Type	Not used by MS Help Generator.
Datatarget Type	Not used by MS Help Generator.
Operations
Insert	Not used by MS Help Generator.
Delete	Not used by MS Help Generator.
Update	Not used by MS Help Generator.
Query
Query?	Not used by MS Help Generator.
Autoquery?	Not used by MS Help Generator.
Display
Title	Used to create a topic title or heading for module component Help text. It is also used to generate a keyword.	About topic titles and headings   About keywords
Layout Style	Not used by MS Help Generator.
Rows Displayed	Not used by MS Help Generator.
Overflow	Not used by MS Help Generator.
Size
Width	Not used by MS Help Generator.
Height	Not used by MS Help Generator.
View Width	Not used by MS Help Generator.
View Height	Not used by MS Help Generator.
Help
User/Help Text	Specifies topic text and keywords for the module component.	About topic text
Help Context ID Prefix	This property applies only to reusable module components and it is used to generate unique context IDs for the help file. This value must be unique for each reusable module component included in the Help file. Optional, but recommended for MS Help generation, a 3 digit integer.	About context-sensitive entry
Documentation
Description	Not used by MS Help Generator.
Notes	Not used by MS Help Generator.


Repository item group properties used by MS Help Generator

Use Design Editor to set these properties How

Item property	Use by MS Help Generator	Notes and Related Topics
Owning Folder	Not used by MS Help Generator.
Module Component	Not used by MS Help Generator.
Name	Not used by MS Help Generator.
Parent Item Group	Not used by MS Help Generator.
Template/Library Object	Not used by MS Help Generator.
Display
Prompt	Used to create a topic title or heading for the item group description.  It is also used to generate a keyword for the item group.	About topic titles and headings   About keywords
Layout Format	Not used by MS Help Generator.
Orientation	Not used by MS Help Generator.
Stacked?	If item groups are to be stacked in the generated application (e.g. implemented as a series of tabs), a separate Help topic can be created for each stacked item group.	New topic for each item group (IGPLCT) preference
Relative Tab Stops
Tab Stop Scope	Not used by MS Help Generator.
Start Tab Stop	Not used by MS Help Generator.
End Tab Stop	Not used by MS Help Generator.
Reports Break Group
Break Group?	Not used by MS Help Generator.
Break Group Direction	Not used by MS Help Generator.
Help
User/Help Text	Specifies topic text and keywords for the item group.	About topic text
Documentation
Description	Not used by MS Help Generator.
Notes	Not used by MS Help Generator.


Repository item properties used by MS Help Generator

Use Design Editor to set these properties How

Item property	Use by MS Help Generator	Notes and Related Topics
Owning Folder	Not used by MS Help Generator.
Module Unit	Not used by MS Help Generator.
Table Usage (bound items only)	Not used by MS Help Generator.
Column (bound items only)	Not used by MS Help Generator.
Name	Not used by MS Help Generator.
Unbound Type (unbound items only)	Not used by MS Help Generator.
Maximum Length (unbound items only)	Not used by MS Help Generator.
Usage Sequence	Not used by MS Help Generator.
Template/Library Object	Not used by MS Help Generator.
Operations
Insert?	Not used by MS Help Generator.
Update?	Not used by MS Help Generator.
Query
Query?	Not used by MS Help Generator.
Range Search	Not used by MS Help Generator.
ConText Option? (bound items only)	Not used by MS Help Generator.
Display
Display?	Not used by MS Help Generator.
Prompt	Used to create a topic heading for the item description.  A preference allows you to hide topic headings for items with no description. The prompt property is also used to generate a keyword.	About topic titles and headings   Display prompts for items with no Help text (DCUCAP) preference   About keywords
Display Type	Not used by MS Help Generator.
Show Meaning	Not used by MS Help Generator.
Width	Not used by MS Help Generator.
Height	Not used by MS Help Generator.
Alignment	Not used by MS Help Generator.
Format Mask	Not used by MS Help Generator.
Formatting	Not used by MS Help Generator.
Wrap Style	Not used by MS Help Generator.
Item Group	The name of the item group that this item belongs to.
Context?	Not used by MS Help Generator.
User Text Areas (unbound items only)	Not used by MS Help Generator.
Relative Tab Stops
Start Tab Stop	Not used by MS Help Generator.
End Tab Stop	Not used by MS Help Generator.
Align Prompt?	Not used by MS Help Generator.
Definition
Domain (unbound items only)	Not used by MS Help Generator.
Datatype	Not used by MS Help Generator.
Default Value	Not used by MS Help Generator.
Default Value Type	Not used by MS Help Generator.
Optional?	Not used by MS Help Generator.
Ordering
Order By Sequence	Not used by MS Help Generator.
Sort Order	Not used by MS Help Generator.
Computed
Reset Level (unbound items only)	Not used by MS Help Generator.
Reset Group (unbound items only)	Not used by MS Help Generator.
SQL
Derivation Text (unbound items only)	Not used by MS Help Generator.
PL/SQL Block	Not used by MS Help Generator.
Validation
Dynamic List? (unbound items only)	Not used by MS Help Generator.
Help
Hint	If Help text is omitted for an item, this property can be used as substitute Help text.	Action when no item Help text defined (DCUNHP) preference
User/Help Text	Specifies topic text and keywords for the item.	About topic text
Documentation
Comment	Not used by MS Help Generator.
Description	Not used by MS Help Generator.
Notes	Not used by MS Help Generator.


Repository business terminology properties used by MS Help Generator

Use Repository Object Navigator to set these properties How

Business Terminology property	Use by MS Help Generator	Notes and Related Topics
Name	Specifies the glossary term. MS Help Generator searches each topic file for the word or phrase you specify here. It also creates an alphabetical listing of all the glossary terms you have defined, which is accessible via the Glossary button.	About glossary terms
Comment	A short description which defines the glossary term. The description may be up to 240 characters in length. When the reader clicks on the glossary term in the Help file, the information specified here is displayed in a popup window.
Documentation
Description	Not used by MS Help Generator.
Notes	Not used by MS Help Generator.
Multi-Byte Help Generation
Glossary Grouping Character	Use this property if you are using MS Help Generator to create Windows Help and the first character of the term you have defined does not form part of the current language 'character-set'.  Enter the character under which this term should be placed on the glossary topic.