Section 2.15

2.15 HELP FILES AND HELP TEXT

Help text describes a proc and the parameters associated with the proc. The Terminal Monitor accesses the help text for a proc when:

tutor mode is entered for the proc
the HELP command is executed

The Terminal Monitor searches for proc help text by looking for the "HELP" parameter on the PROCESS, PROCEDURE, GLOBAL, or PARMSET command in the PDF; if the "HELP" parameter is not specified, TAE looks for a "HLP" type file with the same name as the proc.

The existence of help text for a proc is optional. If the "LEVELl" text (see below) does not exist when tutor mode is entered for a proc, then tutor processing will display "description not available" as the description for each parameter. If no help file exists when help is requested for a proc, TAE responds with "help not available".

The "parameter summary page" produced by parameter help in tutor is automatically generated from the PDF definition of the parameter. The summary page is produced even when there is no programmer-supplied parameter help.

2.15.2 Help Text Structure

The following structure is applicable to help files. A sample of help text is shown in Figure 2-3.

.TITLE Text to be used for the header of the tutor and HELP displays .HELP General help text to be displayed for the HELP command .LEVELl .VAR variable-1 Level 1 help text for variable-1. .VAR variable-2 -subcommand-1 Level 1 help text for variable-2 defined for subcommand-1. . . . .SUBCMD subcommand-1 Level 1 help text for the named subcommand. .LEVEL2 .VAR variable-1 Level 2 help text for variable-1. .VAR variable-2 -subcommand-1 Level 2 help text for variable-2 defined for subcommand-1. . . . .SUBCMD subcommand-1 Level-2 help text for the named subcommand.

.END

The help directives begin with a period because the directives bracket free-field text. The help directives are:

.TITLE - Delimits the title for the help display and the tutor display.
.HELP - Delimits the text to be used for the current proc's help display.
.LEVEL1 - Indicates the start of the "level 1" section. Level 1 text appears in the description column of the tutor display.
.LEVEL2 - Indicates the start of the "level 2" section. The level 2 text is the detailed description displayed in response to the command "HELP parm" in tutor mode and the "HELP-PARM" command in command mode.
.VAR or .VARIABLE - Indicates the start of the level 1 or level 2 help text for a given variable. It has a scope field following the variable name. The scope field has the format of "proc-subcommand" with "proc" defaulting to the associated PDF's file name. If no subcommand is specified, then the help text for the variable may apply to any subcommand. NOTE: the scope field does not work for internal procs.
.SUBCMD - Delimits the description of a subcommand. The text is used in the subcommand display of tutor mode (see the "TAE Command Language (TCL) User's Manual").
.PAGE - Forces a new page on the help or tutor display. .PAGE is permitted in a HELP block or a LEVEL2 block.
.INCLUDE - References text to be included from another file; the library of the referencing file is the default for the INCLUDE file specification. The default file type is "HLP". The referenced file must not contain help directives other than .PAGE. The file name may be a fully qualified name valid in the host operating system.
.END - Terminates the help text.

Figure 2-3

Help File for Proc in Figure 2-2

.TITLE
Demonstration Image Copy Driver
.HELP

    IMGCOPY does an image copy using one of three fixed
    windows depending on the "from" file name:

        FILE NAME                WINDOW
        ---------                ------
        "alaska"                 (0,2048,0,2048)
        "hawaii"                 (0,256,0,156)
        Anything else            (0,512,0,512)

!**** Level 1 help text.
.LEVEL 1
.VAR FROM
Input file name.
.VAR TO
Output file name.
.VAR WINDOW
Image Window
!**** Level 2 help text.
.LEVEL2
.VAR FROM
This is the file name in standard UNIX format. Example:

       /mydir/myimages/nebraska
.VAR TO
This is the file name in standard UNIX format. Example:

       /mydir/myimages/nebraska
.VAR WINDOW
This is the image window in lines by pixels. The first two numbers are
the first and last line numbers of a rectangle, and the second two
numbers are the first and last pixels.
.END

The following rules apply to the use of help directives:

All of the major sections (.TITLE, .HELP, .LEVEL1, and .LEVEL2) are optional.
Except as indicated in the rules below, the help processor does no formatting of the help text. If, for example, a blank line or tab is desired within a parameter description on the help or tutor screen, then the blank line or tab must be inserted in the help file text.
Text for level 1 is displayed on the tutor screen in a 32-character field; lines longer than thirty-two characters are folded to fit in the field.
There is no limit on the number of lines associated with help text in any section.
Tutor runs faster if the level 1 section precedes the level 2 section.
It is recommended that level 1 text be constrained to as few lines as possible so that TAE can pack more parameters per tutor page. Level 2 may be used to supply extensive detail without affecting the tutor parameter display.
If present, the .TITLE directive must be the first directive. The help processor imposes no limit on the number of title lines.

The title line(s) are displayed exactly as specified in the text following .TITLE; no formatting (e.g., centering) is done.
Lines with help directives may contain internal comments using the "!"convention. Lines that begin with "!" are considered comments and not help text.
A .PAGE directive may be used within a text section to force the remaining text to the top of the next screen display. .PAGE is not allowed in the .LEVEL1 section.
.VAR directives may appear in any order, however, tutor mode will execute more efficiently if the level 1 .VAR directives appear in the same order as the PARM declarations appear in the PDF.
The .VAR and .SUBCMD directives may be interspersed; there is no ordering requirement.
A help screen can display run-time dependent information. Help (HLP) files may use the TCL substitution operator "&" with global variables in the help text. The current value of the global variable will then be substituted into the displayed text at run time. See Section 2.15.3 of this manual for more details.

2.15.3 MDF/HLP Text String Substitution

Menu and help displays may be made sensitive to the current run-time session. The contents of TAE global variables may be substituted into MDF and HLP files as the files are being interpreted by TAE. The ampersand (&) character introduces the variable name using the same rules as the substitution feature in the TAE command language. (See Section 3.3.2.8.) When TAE encounters an ampersand in an MDF or HLP file or in the help extension in a PDF, the next syntactic element is taken as the name of a global variable, and TAE substitutes the value of the variable.

As an example, consider the following MDF segment:

.TITLE
                   This is the root menu.

       &SUSERLIB is your current default directory.

When the menu is displayed, the string "&$USERLIB" is replaced by the contents of the TAE global variable $USERLIB.

Some considerations with respect to this substitution feature are:

Substitution may be used anywhere in an MDF or HLP file, including lines with directives.
Only global variables may be used for substitution. The global variables may have qualifiers. For example:
```
    &GEMPAK.DEVICE is the current device type you
    are using.
```
Substitution may be performed in the middle of other strings by quoting the variable name. For example, consider a global variable FTYPE with string value "sub" and the HLP text line:
```
    The &"FTYPE"command that you want is ...
```
On the screen, this line would appear:
```
    The subcommand that you want is ...
```
The global variable name must immediately follow the ampersand. The variable name must not be terminated by a period. In order to perform substitution at the end of a sentence, use quotes. Example:
```
    The current default directory is &"$USERLIB".
```
Numeric variables are converted to a displayable form. Example:
```
    The current value of EPSILON is &"EPSILON".
```
Use two adjacent ampersands to generate an ampersand, i.e., the ampersand character "escapes" the ampersand character.
The substitution is not recursive, i.e., if a substituted string value contains an ampersand, no additional substitution is attempted.
The variable name may not include an index specification.

The following examples show some applications of the substitution feature:

Context reports. Consider the following MDF segment:

.TITLE
                     Widget Selection


This menu is used for selecting the next widget to be
waddled.  &OCC.WIDGETS  widgets have been waddled in
your current session and there have been &OCC.ERRORS
errors. If the errors are excessive, please give the
officer of the  day, &OCC.ODNAME, a call at
&"OCC.ODFONE". (He has received &OCC.ODCALLS calls so
far today and his current disposition is
&"OCC.ODDISP".)

Highlighting. Various parts of an MDF or HLP screen could be conditionally highlighted depending upon the value of certain globals.
```
.MENU SATKILL

&OCC.SATKILL.ON Abort all spacecraft operations.
&OCC. SATKILL.OFF
```
In this example, the string variables OCC.SATKILL.ON and OCC.SATKILL.OFF would contain null strings for normal display or escape sequences for highlighting.
Context-sensitive help. The name of an included help file could vary depending upon the contents of a global variable. Example:
```
INCLUDE &OCC.PREPASS
```

MDF generation. An entire MDF could be generated by a program setting global variables. For example,consider the following MDF:

.TITLE

&OCC.TITLE

&OCC.MC1   ! command for entry 1
&OCC.ME1   ! description of entry 1

&OCC.MC2   ! command for entry 2
&OCC.ME2   ! description of entry 2

&OCC.MC3   ! command for entry 3
&OCC.ME3   ! description of entry 3

2.15 HELP FILES AND HELP TEXT

2.15.1 Help Text Processing

2.15.2 Help Text Structure

2.15.3 MDF/HLP Text String Substitution