| On-line Help Viewer (HyHelp) | On-line Help Source File Format | |
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:
These steps are described in the following sections.
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.
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.
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.
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.
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.
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).
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.
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:
Unless overridden by directives, the first filename
supplied determines the name of the .hnf, .lst and .msg
files produced.
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
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.
You can invoke HyHelp from a Net Express command prompt or from a program.
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 |
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.
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.
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.
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. |
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
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.
Specifies the action to be performed by HyHelp.
Pre-loads and initializes HyHelp. If you do not use this, the first call to HyHelp causes it to load and initialize.
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.
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.
Causes the system to be terminated - all resources are freed, all tables are cleared. This should be followed by a CANCEL "HYHELP" statement.
Causes the index of the specified file to be displayed on entry. The
filename must be in on-line-topic with no
trailing "!".
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 "!".
Causes the specified file to be added to the list of files available to HyHelp.
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. |
Specifies the handling of resources after a query call, according to the following bit settings (where bit 0 is the least significant bit):
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. |
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:
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.
Specifies the window size, in characters. These fields are ignored if
bit 2 of on-line-win-flags is set.
This data item is not used by HyHelp.
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.
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.
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.
| On-line Help Viewer (HyHelp) | On-line Help Source File Format | |