by John P Scott

Creating a Windows Help System

A basic requirement of any Windows application is a Windows Help file for the application integrated with the application through the use of a Help menu. The help file consists of pages of information (called topics) linked in various ways. The help file should bypass the need for a manual in most, if not all, cases (e.g. Borland Quattro Pro for Windows has the complete manual on-line as a Help file). Windows Help is a basic feature of Windows itself, and there are sound reasons for making use of the facility, two of which are its ease of use and its good range of facilities. Many Multimedia systems base their application structure on the Windows Help model.

A standard Windows .HLP file is in effect a hypertext/graphics system. The Windows help program (WINHELP.EXE) reads the .HLP file and presents the information contained in it.

Windows help provides the following facilities.

Context sensitive jumps
An application can be designed to access the Help system directly at the appropriate topic, by the use of a context identifier. The Help system designer and the application programmer/application designer agree a set of context identifiers which will be used to jump directly to the appropriate topic when the application program executes WINHELP.EXE

Cross referencing
Information within the Help system can be cross reference allowing the user to jump directly to an appropriate topic, or to display a temporary piece of information (a pop-up item), by selecting a hotspot identified by a key phrase or graphic in the current topic.

Keyword searches
A search button brings up a dialog box which allows the user to type in a keyword into a combo box. The list automatically scrolls to the nearest matching keyword. A Show Topics button will bring up a list of all topics relevant to the keyword. The user can choose to go to any of the topics. This facility acts much like an index in a book.

Browsing
Groups of related topics can be browsed (stepped through) using << and >> buttons.

History file
The help systems tracks the users use of Help and maintains a history list. The history list can be brought up at any time and used to jump directly to a previous topic. A ‘Back’ button allows access directly to the previous topic without having to use the history list.

Annotation and Bookmarks
The user can place a named bookmark anywhere in the help file, thus allowing access to the topic at a later time without having to search for the information. Annotations can also be added to topics so the user can place extra information for use at a later date.

Hypergraphics
Graphic images can be placed within a topic to assist the user, but these graphics can be modified to contain active areas, or hotspots, which allow context sensitive jumps to other topics.

Customised menus and buttons with macros
A comprehensive set of macros, which can be executed at start-up or by the user selecting hotspots in the help system allow a help system to be produced with a customised user interface, and with extra facilities (see the next two items)

Execution of other programs directly from Help
A macro can cause other programs to be executed. The help system can therefore allow demonstrations to be run, or spoken assistance to be given (using the Media Player). Many other possibilities exist.

Multiple Windows
Secondary windows can be displayed allowing multiple pages of information to be viewed.

The above list is not comprehensive, but gives a brief overview of the main features of the Windows Help system.

Create the source text in a suitable form
The Microsoft help systems requires the text to be save as a Rich Text Format (.RTF) file. The basic text is supplemented by the addition of footnotes which identify all the added structure required in the help system (e.g. cross references, keywords and browse sequences) The help source can be in several files and contain many images. A Help Project file (.HPJ) contains details of the required files and any options required. This file can be created using any text editor.

Compile the source text using the Microsoft Help Compiler
Windows Help differs between Windows 3.0 and Windows 3.1. Two help compilers are available (HC30.EXE and HC31.EXE) allowing compilation of a help system for any target Windows version. Most development software allows you to distribute the Windows 3.1 version of WINHELP.EXE with the application and so it may not be necessary to use the Windows 3.0 help compiler. Windows 3.1 help provides a much better set of facilities.

1.

Input the text into Word for Windows, inserting a hard page break after each help screen and each pop-up definition. Save a copy using the file type 'Rich Text Format' option in the File Save As dialog. Use .RTF rich text format at all times for working with help source files. This simplifies editing and compiling. You will also need to use hidden text for creating the file so choose Tools|Options|View|HiddenText so that you will be able to see the hidden text on screen. The file PLAINHLP.RTF contains the basic text for the demonstration help system.

2.

Makle sure Word for Windows is in View|Normal mode and select the View|Footnotes option. Add Titles for each of the main help topics by placing footnotes using the special footnote symbol '$' and typing the title in the footnote. Titles are listed in the search dialog box as a result of performing a keyword search. It is important that you use meaningful footnotes for the titles (often they will be the same as the topic heading). The file TITLEHLP.RTF contains the text with titles added for the demonstration help system.

3.

Add context labels to each help screen and each pop up definition by placing footnotes using the special footnote symbol '#'. All cross referencing is done by jumping to the place with a particular context label. Place a unique identifier for each screen and definition in the footnote. The file XREFHLP.RTF contains the basic cross referenced text for the demonstration help system.

4.

Add cross references into the document. Cross references are solid underlined green phrases on the help screen which cause a jump to another screen when clicked on. Place a double underline under any word or phrase you wish to use to cause a jump to another screen. Immediately after this word or phrase type the unique context label of the screen you want to jump to. Format the text for this label as 'hidden' text. It will appear with a dotted underline if you have hidden text set to be visible.

5.

Add references to pop up definitions. These are dotted underlined green phrases on the help screen, which cause a temporary definition to pop up when selected. Place a single underline under any word or phrase which requires a pop up definition. Immediately after this word or phrase type the unique context label of the pop up definition. Format the text for this label as 'hidden' text. The file FULLXREF.RTF contains the full cross references text with pop-ups for the demonstration help system.

6.

Add the browsing facility. Groups of screens can be arranged into browse sequences which mean the left and right arrow button on the help screen can be used to scan the screens back and forth. Each group of screens needs a unique name and each screen within a group needs a unique number. e.g. the screen for each of the courses in the demonstration have a browse topic name of 'courses', and the browse numbers are 0010, 0020, 0030 and 0040. The numbers all have to be the same length, and it is wise to leave gaps in the numbering sequence to make it easy to add new screen at a later date. Each screen in a browse sequence needs a special brows footnote. Add a footnote using the special footnote symbol '+'. The footnote text is the browse group identifier followed by a colon, ':', and the browse sequence number, e.g. 'courses:0020'. The file BROWSE.RTF contains the basic text for the demonstration help system.

7.

Add keywords searching. Any screen with a title can have key words associated with it. Keywords are listed in alphabetical order in the search list when the search button is pressed. When a keyword is selected a list of help screens is displayed which all have the required key word reference. This provides a quick method of accessing required information. A keyword footnote is required for any screen which should be accessible from a key word search. Add a footnote using the special footnote symbol 'K' and type the list of keywords associated with the screen. Each keyword should be followed by a semicolon (';'). e.g. 'fish;chips;shop;' The file KEYWORDS.RTF contains the basic text for the demonstration help system.

8.

Graphic images can be used in help files. These can be bitmaps (Windows Paint) or metafiles (CorelDraw etc.) or hypergraphics created using the Windows Hotspot Editor. To place a graphic image in your help file use the following syntax:

{bmc filename}   to place a graphic embedded in the text.
{bml filename}   to place a graphic at the left border
					  of the help screen
{bmr filename}   to place a graphic at the right border
                 of the help screen.

The file BITMAPS.RTF contain the basic text for the demonstration help system.

1.

The simplest project file is for a system with no graphics and only one source file. A help system using graphics images will need a project file which lists the names of all the images. The following page gives the project files for each of the example help files. The format is simple and can be adapted for your own needs.

2.

Compile your project. Enter MSDOS using the MSDOS icon in the 'Main' program manager group. Change directory to the one containing your help source files and project file. Call up the help compiler with your help project file name as a parameter. e.g. if the project file is called MYPROJ.HPJ you would type:

			HC MYPROJ

This requires that MSDOS knows where the help compiler is. You may have to set the path to include the help compiler in the MSDOS Path.

3.

The help compiler is very primitive and gives error messages on the screen. Common errors are mis-spelling identifiers, or using the same identifier twice. Also trying to use graphics without it being listed in the project file.

Download the Help Compiler

The HELP directory on the network contains subdirectories for each of the steps in the creation of the final help system, with .RTF, .HPJ and .HLP files.

The stages are:

PLAINHLP.HPJ

Basic text - cannot usefully be compiled

TITLEHLP.HPJ

Titles added - cannot usefully be compiled

XREFHLP.HPJ -> XREFHLP.HLP

Basic cross references added

FULLXREF.HPJ -> FULLXREF.HLP

Complete cross references added

BROWSE.HPJ -> BROWSE.HLP

Browse sequences added

KEYWORDS.HPJ -> KEYWORDS.HLP

Keyword searching added

BITMAPS.HPJ -> BITMAPS.HLP

Graphics added

    [FILES]
    XREFHLP.RTF

    [FILES]
	 FULLXREF.RTF

    [FILES]
    BROWSE.RTF

    [FILES]
    KEYWORDS.RTF

    [FILES]
    BITMAPS.RTF
    [BITMAPS]
    MELON.BMP
    TOMSOUP.BMP
    SANDM.BMP
    FANDC.BMP
    PANDP.BMP
    SPOTDICK.BMP
    TRIFLE.BMP

1.

Experiment with the examples provided in the HELP directory on the network, by adding more definitions, topics and bitmaps.

2.

Create a help system for the Department of Computer Science and Information Technology including source material on the sites where courses run, the laboratories available, modules run and staff within the department. You need not provide comprehensive information within each topic, and you need not include all labs, courses and staff. The important part is to create a Help system which makes it easy for the user to obtain information about any of the required items, and allows the user to jump to other related topics, e.g. while looking at the Graphics Module topic the user can jump to a topic describing the lecturer on the course.

Copyright (C) 1995

JPS Graphics, 30 Adder Hill, Great Boughton,CHESTER, CH3 5RA, UK
All rights reserved

Comments to author: fcg@jpsgraph.demon.co.uk 

URL: HTTP://194.80.193.185/fcg/help/help.htm