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
add
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.