Chapter 12: Directives for the On-line Help Builder

This chapter describes the directives that can be specified to control the behavior of the On-line Help Builder, Ohbld. Each entry describes the effect of the directive when set. Unless otherwise specified, the opposite effect can be assumed if the directive is negated. The default setting that applies if you do not explicitly set any of these directives is also given.

See the section Running the On-line Help Builder in the chapter On-line Help System for details of where you specify the directives.

/AUTOHOTSPOT

Default:

/AUTOHOTSPOT

Specifies whether the default attribute for hotspot text is to be used. This default attribute can be changed by specifying COLOR-HOTSPOT in the configuration file. The On-line Help Builder ignores any attributes for hotspot text specified in your source file and output an error message under the default setting of this directive.

Setting this directive to /NOAUTOHOTSPOT enables you to specify in your source file the hotspot text attribute to be displayed.

/CASE

Default:

/NOCASE

Specifies that topic-names within the on-line help file produced are to be regarded as case sensitive. Note that the default is that topic-names are not case sensitive.

/COMPRESS[:compress-type]

/C

Default:

/COMPRESS:1

Specifies whether or not the topics are compressed.

Parameters:

compress-type can take the values:

0 - no compression
1 - compression

/CONTENTS

Default:

/NOCONTENTS

Creates a topic containing a list of all the topic titles defined in the on-line help file. The ID of this topic is saved in the file header and used by the Contents function in the On-line Help Viewer.

You can use heading tags to create a multi-level list of contents. See the section Control Tags in the chapter On-line Help Source File Format for details on heading tags.

/CONTENTSTITLE:"contents-title"

Default:

/CONTENTSTITLE:"Contents for hnf-filename"

Specifies the text displayed in the title bar of the help file's contents list. You must specify /CONTENTS or /CONTENTSTOPIC for this directive to have any effect.

/CONTENTSTOPIC

Default:

/NOCONTENTSTOPIC

Causes the contents to be displayed as a topic rather than as a list box.

You should use /CONTENTSTOPIC instead of /CONTENTS if your contents contains 1,000 or more entries.

/CPY:filename

Default:

/NOCPY

Parameters:

filename The name to give to the copyfile.

Produces a COBOL copyfile which contains a level-78 entry for each local topic in the on-line help source file. You can use this .cpy file to access topics directly from a COBOL program rather than by searching for a topic-name.

If /CPY is specified without a filename, the copyfile has the same name as the .hnf file being created, with a .cpy extension.

Example:

File fred.txt contains:

.context @one 
.topic Topic one 
:p.This is topic one

.context @two 
.topic Topic two 
:p.This is topic two

.context @three 
.topic Topic three 
:p.This is topic three

Specifying the following On-line Help Builder command line:

run ohbld fred /cpy:fred.cpy

produces the file fred.cpy, which contains:

78  78-ctxt-one       value 1.
78  78-ctxt-two       value 2.
78  78-ctxt-three     value 3.

Note: Any context names longer than 30 characters will be truncated in the .cpy file.

/DEFINE:filename

Default:

/NODEFINE

Produces a .def file which contains a .define entry for each local topic-name in the on-line help source file. You can use this .def file as input to the next build of the same source in order to preserve existing context numbers.

This directive could be useful if, for example, an old bookmark file depends on old context numbers, or if a COBOL program accesses topics directly by their context number.

If /DEFINE is specified without a filename, the .def file has the same name as the .hnf file being created, with a .def extension.

Example:

File fred.txt contains:

.context @one 
.topic Topic one 
:p.This is topic one

.context @two 
.topic Topic two 
:p.This is topic two

.context @three 
.topic Topic three 
:p.This is topic three

Specifying the following On-line Help Builder command line:

run ohbld fred /define:fred.def

produces the file fred.def, which contains:

.define @one 1
.define @two 2
.define @three 3

/ERRQ

Default:

/ERRQ

By default, the On-line Help Builder pauses each time it finds an error in the on-line help source and asks whether you want to continue, stop, or zoom to the end. If /NOERRQ is specified, the On-line Help Builder does not stop at errors.

/EXTERNAL

Default:

/NOEXTERNAL

Produces a list of all cross-references which reference topics not defined in the on-line help file being built. The list of references is written to file or displayed, depending on the setting of /LIST.

/IGNORE:boolean-variable {,boolean-variable}

Default:

/NOIGNORE

Specifies a list of Boolean variable names, all of whose values are false. This directive is used for conditional building. These variables can be used in the text with the $if tag to conditionally exclude a marked block of text from the build.

Parameters:

boolean-variable Any name or identifier that can have the value of true or false. /IGNORE sets this parameter to false.

Example:

File fred.txt contains:

.context @topic1
.topic Topic One
:p. $if cond-1. Include this text if cond-1 is true
$else.
:p. Include this text if cond-1 is false.
$end.

Specifying the following On-line Help Builder command line:

run ohbld fred /ignore:cond-1

causes the text between the $if and $else tags to be excluded from the build, while including the text between the $else and $end tags.

Omitting the /IGNORE directive does not affect the result of the build, but the On-line Help Builder assumes undeclared variables to be false and so issues a warning.

/INCLUDE:boolean-variable{,boolean-variable}

Default:

/NOINCLUDE

Specifies a list of Boolean variable names, all of whose values are true. This directive is used for conditional building. These variables can be used in the text with the $if tag to conditionally include a marked block of text from the build.

Parameters:

boolean-variable Any name or identifier that can have the value of true or false. /INCLUDE sets this parameter to true.

Example:

File fred.txt contains:

.context @topic1 
.topic Topic One 
:p. $if cond-1. Include this text if cond-1 is true
$else.
:p. Include this text if cond-1 is false.
$end.

Specifying the following On-line Help Builder command line:

run ohbld fred /include:cond-1

causes the text between the $if and $else tags to be included in the build, while excluding the text between the $else and $end tags.

The /INCLUDE directive can be used in conjunction with the /IGNORE directive to achieve a more precise conditional build. The following command line:

run ohbld fred /include:cond-1 /ignore:cond-2

causes the first marked block of text to be included and the second to be excluded.

/INDEX

Default:

/NOINDEX

Creates an index topic containing all the index items defined in the help file. The index topic's context number is saved in the file header and is used by the Index function in the On-line Help Viewer. Selecting the Index function causes the index to be displayed in a list box. Selecting an entry from the index causes that topic to be displayed.

/INDEXTITLE:"index-title"

Default:

/INDEXTITLE:"Index for hnf-filename"

Specifies the text displayed in the title bar of the help file's index list. You must specify /INDEX or /INDEXTOPIC for this directive to have any effect.

/INDEXTOPIC

Default:

/NOINDEXTOPIC

Causes the index to be displayed as a topic rather than as a list box.

You should use /INDEXTOPIC instead of /INDEX if your index contains 1,000 or more entries.

/LIST

Default:

/NOLIST

By default, all output from the On-line Help Builder is displayed on the screen. Specifying /LIST produces a summary listing file with the same name as the on-line help file being created, but with an extension of .lst, and places it in the current directory.

/LISTTEXT

Default:

/NOLISTTEXT

Causes source text to be written to the screen as it is built. If /LIST is specified, this information is also written to the specified .lst file.

/LOCAL

/L

Default:

/NOLOCAL

Produces a list of all local topic-names. The list is written to file or displayed, depending on the setting of /LIST.

/MAXNAME:context-length

Default:

/MAXNAME:32

Specifies the maximum length of context names. context-length must be between 1 and 32 inclusive. The On-line Help Builder displays a warning if it encounters a context name longer than the value you specify.

You need to specify a value of 22 or less if you use the /CPY directive to create a copyfile that you later syntax check. This is because the On-line Help Builder prefixes each context name with eight characters (78-ctxt-) before writing it to the copyfile, and the maximum length of a COBOL data name is 30 characters.

/MSG

/M

Default:

/NOMSG

Produces a message file with the same name as the first on-line help source file read, but with an extension of .msg, and places it in the current directory. This file can be used to locate errors in the on-line help source text.

/OUTPUT:filename

Default:

None present. Uses the name of the first on-line help source file, appending the extension .hnf.

Specifies the name to be used for the on-line help file being built. This should have an extension of .hnf.

/PASS2

Default:

/NOPASS2

By default, the On-line Help Builder takes one pass to build an on-line help file. /PASS2 causes the On-line Help Builder to read the on-line help files in two passes.

You need /PASS2 to correctly resolve forward references to sub-headings, and for the RES parameter in :h1, :h2 and :h3 tags.

/SOUND

Default:

/SOUND

By default, the On-line Help Builder sounds the system bell whenever it encounters an error when building an on-line help file. If your on-line help source file contains a large number of errors, you might want to silence the system bell by specifying /NOSOUND.

/TOPIC

/T

Default:

/NOTOPIC

Produces a list of topic-names defined in the on-line help file being built. The list is written to file or displayed, depending on the setting of the /LIST directive.

/VERSION:number

Default:

/VERSION:6

Parameters:

number The version to use.

Specifies the version of the on-line help file produced. /VERSION:n causes the On-line Help Builder to build .hnf file of version n. The only valid parameters for this directive are 5 and 6.

You should use this directive if your version of the On-line Help Viewer is older than your version of the On-line Help Builder.

/WARNING

Default:

/WARNING

Displays warning messages encountered when building, with the prefix OHBnnnW, where nnn is the message number. Specifying /NOWARNING suppresses these warning messages.

See the chapter Ohbld Error Messages for a list of these errors.

Chapter 12: Directives for the On-line Help Builder

/AUTOHOTSPOT

Default:

/CASE

Default:

/COMPRESS[:compress-type]

/C

Default:

Parameters:

/CONTENTS

Default:

/CONTENTSTITLE:"contents-title"

Default:

/CONTENTSTOPIC

Default:

/CPY:filename

Default:

Parameters:

Example:

/DEFINE:filename

Default:

Example:

/ERRQ

Default:

/EXTERNAL

Default:

/IGNORE:boolean-variable {,boolean-variable}

Default:

Parameters:

Example:

See also:

/INCLUDE:boolean-variable{,boolean-variable}

Default:

Parameters:

Example:

See also:

/INDEX

Default:

/INDEXTITLE:"index-title"

Default:

/INDEXTOPIC

Default:

/LIST

Default:

/LISTTEXT

Default:

/LOCAL

/L

Default:

/MAXNAME:context-length

Default:

/MSG

/M

Default:

/OUTPUT:filename

Default:

/PASS2

Default:

/SOUND

Default:

/TOPIC

/T

Default:

/VERSION:number

Default:

Parameters:

/WARNING

Default: