7.4.2 Customized Form Helpfile Layout

When using a customized helpfile, form calls showtext with the categories and subjects in the order listed in Table 7-2. For each entry, the corresponding help text is displayed if the help section is found and the criterion for that help section are met.

Table 7-2: Category and Sections called with customized helpfile

Category Subject Comments

error error string Skipped if form is not displaying an error message.

formname mode Display help relative to the current mode of form. The section name consists of both the current form name and form mode. The valid modes are nomode, query, find, update and


formname field_name Skipped if the cursor is not in a field. The formfile's form name and current field name are passed to showtext to display the help section for the field.

formname The help section for the formfile's form name is displayed.

For example, the help sections in the mag formfile in the C/Base demonstration are:

1 mag nomode

1 mag query

1 mag find

1 mag update

1 mag add

1 mag

2 magazine

2 title

2 year_rate

2 subscribers

A customized helpfile is organized efficiently if each of the data entry field names for the form follow the form name's help section with higher section level numbers. This displays the field description help sections after displaying the data entry form help section.

The help sections in the form helpfile should be in a particular order to best use the help facility. All the help sections for the first form should be first, followed by the help sections for the second form, and so forth.

For each of the forms, the help sections should be ordered:

Table 7-3: Form Help Section Ordering

Section Level Number

Section Name Composition

1 form section for each data entry mode

1 form section with no data entry mode

2 data entry field sections

The help sections for a form's data entry modes are defined as a level 1 help sections so that only the help text for the current data entry mode is displayed. For example, if in add mode, it would not make sense to display the help text for the form when in update mode.

For example, in the C/Base demonstration application, the ordering of the help section names for the subscription data entry form that contains two different forms are as follows:

1 subscriber nomode

1 subscriber query

1 subscriber find

1 subscriber update

1 subscriber add

1 subscriber

2 subscriber

2 name

2 address[1]

2 address[2]

2 city

2 state

2 zip

1 subscription nomode

1 subscription query

1 subscription find

1 subscription update

1 subscription add

1 subscription

2 magazine

2 started

2 issues

Each section title is followed by one or more lines of help text and separated from each other by at least one blank line.

Note that the help sections for form fields are all level 2 and follow the help section for the data entry form. When the section for the data entry form is displayed, all the field description sections are displayed since they have a higher section number than the form's help section.