PreviousOn-line Help Viewer (HyHelp) On-line Help Source File FormatNext

Chapter 10: On-line Help System

This chapter describes how to use Ohbld and Hyhelp.

If you are creating your own on-line help files, you must perform the following procedures:

  1. Create your on-line help source files.

  2. Build your source files into an on-line help file using the On-line Help Builder (Ohbld).

  3. Display your on-line help files using the On-line Help Viewer.

  4. Add a call to the On-line Help Viewer from your program.

  5. Configure the On-line Help Viewer.

  6. Ship the On-line Help Viewer with your applications.

These steps are described in the following sections.

10.1 Creating Source Files

Using an editor, create text files that contain the information you wish to be displayed. The maximum line length allowed is 255 characters. The files should be formatted according to the structure described in the chapter On-line Help Source File Format. This structure has been designed to take account of future changes and additions to HyHelp and some features might not be visible in your current environment. However, all files should be created using the full range of features.

The following information describes how you should organize your source files and the information within them.

10.1.1 Source File Structure

Any number of source files can be used to create a single on-line help file. There is no need to have more than one source file except to aid you in file management, or possibly to share source files with other systems. The first source file should start with the title to be given to the file and the .define tags to connect all the local topic-names to context numbers. These are followed by topics. Each topic starts with a .context tag or an IPF heading. You should follow this with a .topic tag to give the topic a title, and any :i1 index entries relating to the whole topic.

The topics in the file should be ordered in a logical sequence. For example, if the file were published as a book, the sequence of the topics should reflect that book. This ensures that the contents list, produced automatically, is correctly ordered.

The first topic in the file is the home topic. This topic is displayed if the file is accessed with no topic-name or context number specified. It is also available at any time using the Home function. The home topic should describe the file contents in brief and supply cross-references to the main sections of the file.

10.1.2 Writing Topic Text

A topic should be well structured so that the information it holds can be accessed easily. There should be enough information available at the start of the topic, and visible when the topic is first displayed, so the reader can determine what information the topic contains.

You should always create your topics with formatting tags. The topic consists of paragraphs, fixed-lines blocks and lists. An entry within a list starts with a paragraph but can be followed by further paragraphs, fixed-lines blocks or lists.

To make the source text readable, you should place the first line of paragraph text on the same line as the paragraph or list-item tag. This, and the remaining text in the paragraph, should be indented to reflect the structure of the topic. Ohbld removes all the leading spaces, and HyHelp reformats according to the size of the topic window. However, by providing a visual structure to your source, later updates are made easier. It is also much easier to spot missing tags when the source is structured.

By default, hotspots are highlighted automatically. Other highlighting can be used for identifying other items such as section headings and special terms. However, you should be careful not to use highlighting excessively as this can detract from the information.

Topics should be kept reasonably short to avoid the need for excessive scrolling.

10.1.3 Defining Topic-Names and Context Numbers

In the source files, every topic is identified by a local topic-name, and all cross-references (hypertext links) are to these names. Each topic is given a context number using .define tags. These numbers are used by the application when asking for a specific help topic to be displayed (using the on-line-qry-by-context action). Since you specify the numbers, any change to the source files does not affect the numbers allocated to specific topics (provided the .define statements are not changed).

It is important that the topics within a file should retain the same number when the file is updated. External information, such as bookmarks, is stored using the filename and context number. If the context numbers were to change between updates, a set of bookmarks relating to the file would all become meaningless.

When allocating numbers, you should use sequential numbers with as few gaps as possible. The on-line help file holds a look-up table allocating three bytes for every integer from one through the largest context number defined. So if you have 500 topics but define one as having context number 1000, you are losing at least 1500 bytes in the file.

Context numbers do not define the structure of the created file. They can be allocated entirely arbitrarily. It is preferable to use all numbers sequentially, allocated arbitrarily, than to leave large gaps which results in wasted space in the file.

Cross-references within the source are made using local topic-names. These are converted to context numbers, saving space in the file and saving time when the user activates a cross-reference.

If you use context numbers rather than external topic-names, the on-line help file is smaller, and access to the topics considerably faster. You can do this for most applications, since the information is held in a single on-line help file and it is normally only accessed directly from the application or by cross-reference within the file itself. In this typical situation, the topics can be identified and accessed by context number rather than by external name.

You should use external names only on topics that a user will want to enquire about from outside the application. It is probably useful to provide a single external name for an application on-line help file, applied to the home topic. The application help file can then be easily accessed by using the search function on the application name.

10.1.4 Using Character On-line Help Tags

An on-line help source file comprises the following types of information:

These define the text to be displayed and any highlighting required. All tags are preceded by a colon (:), a period (.) or a dollar sign ($). The tags preceded by ":" or "$" can start anywhere on a line. The tags preceded by "." must start in column one of a line. Most tags can be followed by parameters. Tags preceded by ":" are terminated by a period, the parameters normally appearing before the period.

The source file must start with a .define, .title, .comment or .context tag. Blank lines are ignored unless they are within a fixed-lines block or topic.

See the chapter On-line Help Source File Format for a detailed list of the tags available.

10.2 Building Character On-line Help Files

When you have created the source files, you are ready to build them into character on-line help (.hnf) files. To do this you use the On-line Help Builder (Ohbld).

10.2.1 Specifying On-line Help Builder Directives

When you build your on-line help source files into on-line help files , the On-line Help Builder uses a default set of values to control its behavior. For example, unless you specify otherwise, the name of the on-line help file is the name of the first on-line help source file (with the extension .hnf), and an index and table of contents are not produced.

You can, however, change many aspects of the On-line Help Builder's behavior by specifying directives in much the same way as you could specify directives to the Compiler when compiling a COBOL program.

10.2.2 Running the On-line Help Builder

When you run the On-line Help Builder, it takes your on-line help source files and creates an on-line help file from them. You can modify the behavior of the On-line Help Builder by specifying the appropriate directives at the Net Express command prompt or in a command file.

Ohbld converts specially formatted text files into .hnf format help files which can then be accessed and displayed by HyHelp. The format of the text files is described in the chapter On-line Help Source File Format.

Ohbld processes the source files in the order you specify them, producing messages when appropriate. For each topic, a block of text is created containing embedded reformatting tags and hotspot information. When the text for each topic has been processed, the block is compressed, if required, and stored. When all the source files have been processed, contents and index topics are created, if requested. Finally, the look-up information relating external topic-names to context numbers, and context numbers to the location of the relevant topic are added in the file.

The command line for running the On-line Help Builder is:

run ohbld {filename     } ...
          {directive    }
          {@command-file}

where the parameters are:

filename The name of a information text source file. If no extension is supplied, the extension .txt is used. More than one filename can be supplied, and filename can contain the wild-card characters * and ?. Full pathnames can be supplied.
directive One or more of the directives listed in the chapter Directives for the On-line Help Builder. All directives begin with "/" and can be negated by inserting "NO" between the slash and the directive text. For example, /NOERRQ means "don't stop at errors"; that is, the opposite of /ERRQ.
command-file A line sequential file containing a list of further filenames and/or directives. Command files cannot be nested. The "at" character (@) is mandatory. See the section Ohbld Command Files later in this chapter for more information.

Unless overridden by directives, the first filename supplied determines the name of the .hnf, .lst and .msg files produced.

10.2.3 Ohbld Command Files

If you have a number of filenames and directives which you want to specify to the On-line Help Builder, you will probably find it inconvenient to have to type them every time at the Net Express command prompt. It is also possible for the string to be too long to fit within the command line character limit.

Therefore, the On-line Help Builder can accept filenames and directives from a command file. A command file is a line sequential file containing a list of filenames and/or directives. You tell Ohbld to use the command file by including the command file on the Ohbld command line, prefixed by the "at" character (@). For example:

run ohbld @myproject.txt

where myproject.txt contains the following lines:

  File1.txt
  File2.txt
  File3.txt
  /output:myproject.hnf
  /contents
  /index
  /noerrq

The above example is the same as specifying the following command line:

run ohbld file1.txt file2.txt file3.txt
    /output:myproject.hnf /contents /index /noerrq

See the chapter Directives for the On-line Help Builder for descriptions of the Ohbld directives specified in this example.

You can use filenames and directives on the command line in addition to a reference to a command file. Files and directives are acted upon in the order given. This has the following effects:

For example, using the command file above, you could add an extra file (preface.txt), turn error messages back on (/ERRQ) and write error messages to a file (/MSG) by entering the following command line:

run ohbld preface.txt @myproject.txt /errq /msg

10.3 Using the On-line Help Viewer to Display Your On-line Help Files

HyHelp runs as a stand-alone program or can be called from another program. When started, an initial topic is displayed, and the user is given control. You can configure HyHelp to specify the colors to use, and information about the help files to use at start up.

10.3.1 Invoking the On-line Help Viewer

You can invoke HyHelp from a Net Express command prompt or from a program.

The Command Line

To invoke HyHelp from the Net Express command prompt, enter:

run hyhelp [filename!][topic-name]

or:

hyhelp [filename!][topic-name]

where the parameters are:

filename The name of the on-line help file to display. If filename is not specified, the first file in the directory containing on-line help files specified by the COBHNF environment variable is used. By default, in the Development Environment, Hyhelp's own help file, hyhelp.hnf is displayed.
topic-name The name of the topic in the on-line help file that you want to be displayed.

If filename is specified without topic-name, the home topic of the selected on-line help file is displayed.
If topic-name is specified without filename, all on-line help files are searched.


Note: You need to specify run if you are using a configuration file to change HyHelp's behavior. Omitting run causes HyHelp to run using its default configuration.


10.4 Calling the On-line Help Viewer From Your Programs

Although you can run HyHelp from the Net Express command prompt, you are more likely to want to incorporate it in your application. HyHelp includes a call interface and a copyfile that enable you to integrate your on-line help with the rest of your applications.

If you want to make use of the On-line Help System in your own applications, you can add a simple call to HyHelp.

10.4.1 Coding Your Application to Call the On-line Help Viewer

You can code your application in such a way that, when information is requested by your users on any particular item, the application calls HyHelp, specifying the context number of the topic to be displayed and the filename of the on-line help file containing that topic. In some cases you might also wish to set the location within the topic that should always appear on the top line.

It is a good idea to set up a copyfile for your application which uses level-78 items to relate the names to the numbers. The same names and numbers used in the define statements should be used in this file (except for omitting the leading @ characters). This means that the same names can be used throughout the application to refer to the same topics.

10.4.2 Call Definition

You can call HyHelp from any COBOL program using a standard COBOL call as follows:

call "hyhelp" using on-line-pb                    
                    on-line-topic

where the parameters are:

on-line-pb A parameter block in the copyfile onl-link.cpy, holding fixed-length information about the display environment as described below. You must include onl-link.cpy in any program that calls HyHelp.
on-line-topic The topic-name for an on-line-qry-by-name action, and on-line help filename (or any other information needed) in a variable-length string terminated by a space.

The topic-name can be preceded by a filename terminated by a "!". If no filename is passed, the on-line help files that are active are searched.

For an on-line-qry-by-context, on-line-index or on-line-contents action, on-line-topic contains just a filename, space terminated with no trailing "!".

If the filename has no path specified, the current directory is searched first, followed by the path specified by the COBHNF environment variable, depending on the extension. If the filename has no extension, .hnf is assumed.

10.4.3 Example of Calling the On-line Help Viewer

 78 appl-menu              value 3.
   . . .
 copy "onl-link.cpy"
   . . .
   . . .
     move on-line-qry-by-context to on-line-action
     move "myapp.hnf" to on-line-topic
     move appl-menu to on-line-context
     perform call-on-line 
   . . .
 call-on-line section.
     call "hyhelp" using on-line-pb 
                         on-line-topic
     if on-line-return not = 0
         display "on-line error:- " on-line-return
     end-if

10.4.3.1 onl-link.cpy

The following parameter description is held in the file onl-link.cpy:

 01 on-line-pb.
       78 on-line-initialize                        value 0.
       78 on-line-qry-by-name                       value 1.
       78 on-line-qry-by-context                    value 2.
       78 on-line-close-down                        value 4.
       78 on-line-index                             value 5.
       78 on-line-contents                          value 6.
       78 on-line-add-file                          value 7.
     03 on-line-action              pic 9(2) comp-x value on-line-qry-by-name.
     03 on-line-return              pic 9(2) comp-x value 0.
       78 on-line-bad-action                        value 1.
       78 on-line-topic-not-found                   value 2.
       78 on-line-file-not-found                    value 3.
     03 on-line-flags               pic 9(2) comp-x value 0.
       78 on-line-default-window                    value 0.
       78 on-line-window-specified                  value 7.
     03 on-line-win-flags           pic 9(2) comp-x value on-line-default-window.
     03 on-line-context-no          pic 9(4) comp-5.
     03 on-line-ptr                 pic 9(4) comp-5.
     03 filler.
         05 on-line-window-x        pic 9(4) comp-5.
         05 on-line-window-y        pic 9(4) comp-5.
         05 on-line-win-width       pic 9(4) comp-5.
         05 on-line-win-height      pic 9(4) comp-5.
     03 on-line-ui-id               pic 9(9) comp-5.
on-line-action

Specifies the action to be performed by HyHelp.

on-line-initialize

Pre-loads and initializes HyHelp. If you do not use this, the first call to HyHelp causes it to load and initialize.

on-line-qry-by-name

Displays the topic selected by the topic-name supplied in on-line-topic, optionally preceded by a filename. The full functionality of HyHelp is then made available to the user.

If a filename is specified, this file is searched first, followed by the files available to HyHelp.

on-line-qry-by-context

Displays the topic selected by the context number supplied in on-line-context-no and the file supplied in on-line-topic. The full functionality of HyHelp is then made available to the user.

on-line-close-down

Causes the system to be terminated - all resources are freed, all tables are cleared. This should be followed by a CANCEL "HYHELP" statement.

on-line-index

Causes the index of the specified file to be displayed on entry. The filename must be in on-line-topic with no trailing "!".

on-line-contents

This causes the contents of the specified file to be displayed on entry. It only operates for .hnf files, and for Microsoft Advisor format files that contain a topic with name h.conTENTS. filename must be specified in on-line-topic with no trailing "!".

on-line-add-file

Causes the specified file to be added to the list of files available to HyHelp.

on-line-return

If nonzero, indicates that some form of error has occurred. The possible values for on-line return are:

Value
Meaning
on-line-bad-action The action code is not one of the defined codes.
on-line-topic-not-found The topic given cannot be found.
on-line-file-not-found The file given cannot be found.

on-line-flags

Specifies the handling of resources after a query call, according to the following bit settings (where bit 0 is the least significant bit):

Bit
Description
7 When set, starts HyHelp with menus invisible.
6 Not used.
5 When set, HyHelp screen is left displayed on exit.
4 When set, HyHelp does not return control to the application if the topic requested by the call is not found.
3 When set, no files are opened automatically on initialization.
2 When set, the user screen is saved, and restored on exit.
1 When set, closes all help files on exit.
0 When set, all dynamically allocated memory is deallocated on exit. We recommend that this bit is set for normal use.

on-line-win-flags

Specifies the behavior of the windowing environment, depending on the following bit settings (where bit 0 is the least significant bit.)

Bit
Description
2 Set if the parameters given for size of the topic window are to be used. If this bit is not set, HyHelp displays the topic full-screen.
1 Set if the parameters given for location of the topic window are to be used.
0 Not used.

Note that if HyHelp is called with a window that is smaller than the screen, the window has a maximize icon in the top right-hand corner. Clicking on this icon enlarges the window to cover the whole screen and gain a restore icon in the top right-hand corner. Clicking on the restore icon returns the window to its original size. The window cannot be resized using any other method.

on-line-context-no/on-line-ptr

If the action is on-line-qry-by-context, this is the context number to be used to look up the topic. The topic associated with this number in the on-line help file named in on-line-topic (no trailing exclamation point) is located directly.

In addition, the start position within the topic can be specified in on-line-ptr. This is a number indicating the offset within the text buffer of the character that must always be on the top line of the window. At present this must be calculated by trial and error.

As a rough guide, add:

on-line-window-x/y

Specifies the start position of the window (in characters), used if on-line-win-flags bit 1 is set. These are relative to the top-left corner of the screen starting from zero.

on-line-win-width/height

Specifies the window size, in characters. These fields are ignored if bit 2 of on-line-win-flags is set.

on-line-ui-id

This data item is not used by HyHelp.

on-line-topic

on-line-topic contains the topic-name for an on-line-qry-by-name action. The topic-name can be preceded by a filename terminated by a "!".If no filename is passed, the on-line help files that are active are searched.

For an on-line-qry-by-context, on-line-index or on-line-contents action, on-line-topic contains just a filename, space terminated with no trailing "!".

If the filename has no path specified, the current directory is searched first, followed by the path specified by either the COBHNF or QH environment variable, depending on the extension. If the filename has no extension, .hnf is assumed.

10.5 Configuring the On-line Help Viewer

If you do not want to use the default settings provided by HyHelp, you can configure them by specifying parameters in a configuration file. You use the standard configuration file, HyHelp configuration file (hyhelp.cfg).

hyhelp.cfg is not provided with Net Express; if you need to vary from the default settings you must create this file. hyhelp.cfx is provided in the \bin directory as an example of the format of the configuration file. You can use this .cfx file in any of the following three ways:

You must run HyHelp using run for any configuration file changes to take effect.

The configuration options must follow the tag [HYHELP] regardless of which of the above methods you use.

For a list of all available configuration options, see the chapter Configuration Option Tags.

For a description of the ASCII text format of on-line help source files, see the chapter On-line Help Source File Format.

10.6 Shipping the On-line Help Viewer

HyHelp uses the following files, so you must include them with any application you ship that makes use of HyHelp:


If access to Microsoft .hlp files is required, HyHelp requires the following additional files:


Copyright © 2000 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.

PreviousOn-line Help Viewer (HyHelp) On-line Help Source File FormatNext