Copyright: Copyright 1993, 1994 G.Plowman


About Dialog

Purpose

The About Dialog displays version and copyright information about this version of the HelpBuilder application.

Available from

Help/About HelpBuilder menu option


Bitmap Dialog

Purpose

The Bitmap Dialog is used for inserting bitmap pictures into topic files.

Available from

Ninth toolbar button

Edit/Bitmap menu option

Comments

Like a topic file, a bitmap file must be added to your project using the Edit Project dialog

The Bitmap dialog has the following fields:

Bitmap File Name

This is the file name of the bitmap which you wish to appear. The list box contains all of the bitmaps currently added to the help project file, but you can type another name

Bitmap Allignment

This specifies how the bitmap is to be positioned by Windows Help.

Left allignment positions the bitmap against the left margin and further text will appear wrapped on the right of the bitmap

Right allignment positions the bitmap against the right margin and further text will appear wrapped on the left of the bitmap

Current line allignment places the bitmap on the current line and any further text appears below it

Example 1

The following example places a bitmap on the left of the Windows Help window and places text wrapped in the space to the right of the bitmap:

\{bml ARCHES.BMP\}This is some test text which will wrap on the right of the bitmap

Result:

This is some test text which will wrap on the right of the bitmap

Example 2

The following example places a bitmap on the right of the Windows Help window and places text wrapped in the space to the left of the bitmap:

\{bmr ARCHES.BMP\}This is some test text which will wrap on the left of the bitmap

Result:

This is some test text which will wrap on the left of the bitmap

In both examples, the text must be on the same line as the bml/bmr statement otherwise the text will appear underneath the bitmap on the screen.


Bold Text
How to make bold text

Bold text is obtained by typing some text and then highlighting it with the mouse and then clicking on the 'B' toolbar icon.

This will place an open curly brace and a backslash b before your text and a close curly brace after your text.

To turn the bold off, either delete these characters or highligh the text including the RTF bold characters and click the 'B' toolbar icon again.

Alternatively, bold text can be inserted by selecting some text using the mouse and then selecting the Text/Font menu option to obtain the Font Dialog.


Browse Dialog

Purpose

The Browse Dialog enables the user to select a file use by HelpBuilder.

Available from

Browse button on the Default Project Files Dialog

Browse button on the Topic/Popup Link Dialog

Comments

Type the name of the required file in the File Name field and then press the Enter key.

Alternatively, use the mouse to click on the required project and click the Ok button to select it.

To exit out from the dialog, press the Esc key or click on the Cancel button or the system menu icon.


Cannot Create Project Error

An error has occured while attempting to create a new project file.

Possible causes:

An attempt to create a new project on a write-protected diskette

An attempt to create a new project in the same location and with the same name as the currently open project

An attempt overwrite an existing project file which is write-protected

An attempt to overwrite an existing project file which is currently open by another instance of the HelpBuilder application or another use in a networked environment

An attempt to create a new project on a diskette which has not been formatted or has serious read/write failures - either reformat the diskette or discard it


Cannot Delete Main Window Error

This error occurs when the user has attempted to delete the 'main' window definition in the Project Windows Dialog.

The 'main' window definition cannot be deleted because it is required by Windows Help for the main window of a help file. You can however change the Sizing to Default in which case the definition will not be used. Any other Sizing setting will cause the 'main' window definition to be used and therefore activated.


Cannot Open Project Error

This error occurs when HelpBuilder has failed to successfully open a project file.

Possible causes

An attempt has been made to open a Project which does not exist. If the project appeared in the most recently used project list at the bottom of the Project menu then it is likely that the project file has been deleted

A general failure to read a disk

An attempt has been made to open a project file on a disk which is write-protected or the project is in use by another user on a network. HelpBuilder MUST have read-write access to project files in order to successfully open them


Cannot Open Icon

This error occurs when the HelpBuilder help file Wizard has failed to successfully open the QUESTION.ICO file which is held in the application's directory.

Possible causes

QUESTION.ICO has been deleted from the HelpBuilder application directory or it has been renamed. The file should be re-installed.


Cannot Open Topic File Error

This error occurs when HelpBuilder has failed to successfully open a topic file.

Topic files are opened and kept open in read/write mode. Subsequent accesses to a topic file will only open it in read-only mode

Possible causes

An attempt has been made to open a Topic which does not exist. If the topic appeared in the most recently used file list at the bottom of the File menu then it is likely that the topic file has been deleted

A general failure to read a disk


Changing Colours
How to change text colours

To change the colour of some text within a topic, the text must be enclosed in {} braces with the \cf RTF statement:

{\cf2 Changes to colour 2 in the colour table}

Rather than type RTF commands to change colours, it is better to use the mouse to highlight some text and select the Text/Colour menu option. This displays the Color Dialog from which a colour may be selected. When a colour is selected from the dialog, the appropriate RTF commands are written for you.

See also: Colour Dialog


Changing Fonts
How to change text fonts

To change the font of some text within a topic, the text must be enclosed in {} braces with the \f RTF statement:

{\f0 Changes to font 0 in the font table}

Rather than type RTF commands to change fonts, it is better to use the mouse to highlight some text and select the Text/Font menu option. This displays the Font Dialog from which a font, its style and size may be selected. When a font is selected from the dialog, the appropriate RTF commands are written for you.

See also: Fonts Dialog.


Colour Dialog
Color Dialog

Purpose

The Color Dialog is used to change the colour of the currently selected text.

Available from

11th toolbar button

Text/Colour menu option

Comments

To change the colour of some text, it must be selected either by using the shift key with the cursor keys or by swiping the mouse across it. Then, select the Text/Colour menu option or the toolbar button.

To change the colour of some text which already has its colour set, you should highlight the text and the surrounding RTF statements including the { and } brace characters.

From the color dialog, select the required colour and then press 'Ok'. HelpBuilder will then automatically save the colour to the RTF colour table and then write the appropriate RTF commands in your text.

Press 'Cancel' to exit without selecting a colour.


Commonly Reported Problems/Questions
Commonly Reported Problems and Questions Asked

Following is a list of reported problems and commonly asked questions about HelpBuilder together with the solutions.

'Error 1079 Out of file handles'

This is an error reported by HC31.EXE. HC31.EXE is a DOS program and is therefore subject to the setting of FILES= in your CONFIG.SYS.

It is suggested that you have at least FILES=60 and this should resolve the problem.

'This application uses CTL3DV2.DLL, which has not been correctly installed'

HelpBuilder uses CTL3DV2.DLL to provide a '3d' appearance to all controls in dialogs. CTL3DV2.DLL is a Microsoft product and expects to be installed in the \WINDOWS\SYSTEM directory. If it is not, then the above error results.

The Setup program for HelpBuilder installs CTL3DV2.DLL in \WINDOWS\SYSTEM.

If you receive this error then another copy of the .DLL must have been found, probably in your \WINDOWS directory or a directory in your path.

It is suggested that you only have one copy of CTL3DV2.DLL on your machine to avoid this error.

Note that the application can be run perfectly successfully even if the above message does appear.

'This software has not been installed correctly. Please re-run the installation procedure'

HelpBuilder uses a technique of coded serial numbers in order to determine the expiry date of a review (unregistered) copy of the software.

It is possible that you have installed the application perfectly correctly and you still receive this error when you run the application. In this case, it is due to a bug in version 1.06. You will also receive this error if you tamper with certain entries in the .INI file.

The solution is to delete \WINDOWS\HELPBLDR.INI and reinstall the software the next day. Better still, obtain the latest version of the software since this bug has now been fixed.

C:\WINDOWS\COMPILE.BAT Cannot find file. Check to ensure the path and filename are correct

HelpBuilder uses the Microsoft HC31.EXE Help Compiler program to create help files. To do this, it creates a batch file (COMPILE.BAT) in the WINDOWS directory which contains a call to HC31 and then runs a Windows .PIF file (HECOMP.PIF - also in the WINDOWS directory) to run the batch file.

The above error occurs whenever Windows has not been installed in the C:\WINDOWS directory, for example on a network drive or simply another directory eg C:\WIN31

To correct the problem you must use the Windows PifEdit program to modify HECOMP.PIF. You should modify the 'Program Filename' to point to the directory in which Windows has been installed. A typical example modification might be:

G:\WIN31\COMPILE.BAT

You should then save the changed .PIF file. This should resolve the problem.

I've created a topic, saved it and created a Topic identifier but it does not appear in the Topic Locator window and/or I get compiler 'Unresolved jump of popup errors'

This is a commonly asked question and has a simple answer. It is caused by not including a topic file in a project via the Project/Edit menu option. 'Unresolved jumps/popups' are normally caused by not setting the Topic Link information for a Topic via the File/Topic Links menu option while at the same time correctly refering to that topic via a jump link from another topic.

My Topic Name/Keyword begins with a 'K' and is not shown in the Windows Help Search dialog - the 'K' is missing

This is a bug in the Microsoft help compiler. To work around the problem, start your topic name/keyword with a second 'K':

KKeyword

Error 5059: Not enough memory to Compile Help File/Out of Memory

This error usually occurs when using HC31.EXE with HelpBuilder. HC31.EXE is a DOS program and is extremely limited on the amount of memory it has available to compile help files.

The above error generally occurs when you have a number of bitmaps in a help file and this can be as few as 3-4 large bitmaps.

There are two solutions:

Remove some bitmaps from your project

or

Obtain the DPMI version of HC31.EXE called HCP.EXE. HCP.EXE is supplied with Microsoft Project as part of the 'Cue Card' package and probably several other packages. It is probably also available from the Microsoft forums on Compuserve.

Install HCP.EXE into HelpBuilder using the Project/Settings 'Compiler Installation' section.

HCP.EXE will resolve the problem.


Delete Window Confirmation

This confirmation occurs when the user has selected to delete the currently highlighted window in the window list of the Project Windows Dialog.

Select 'Yes' if you wish to proceed to delete the selected window completely from the project.

Select 'No' to keep the window intact and not make any changes.


Contents Page

Contents for HelpBuilder Help

HelpBuilder is a utility program for creating and maintaining Windows Help files.

To learn how to use Help, press the F1 key.

  Terminology

  HelpBuilder menu options

  Main HelpBuilder Window

  Quick Start/Tutorial to Creating a Help File

  How To...

  Error Messages

  Help Compiler Error Codes/Messages

  Commonly Reported Problems and Questions Asked

  Suggestions for use

  Other products available

  What is Shareware ? - Description and Disclaimer

  Payment for and Registration of Software

  Software Price List

  Contacting the Author

  Application Limitations & Limitations on use

  Other HelpBuilder Users

  Help File Copyright


Project Context Identifiers Dialog

Purpose

The Project Context Identifiers Dialog enables the user to maintain a list of context identifiers for use by topics within a help file.

Available from

Project/Context Identifiers menu option

Context IDs button on Topic Links Dialog

Context IDs button on Topic Link Dialog

Context IDs button on Project Settings Dialog

Comments

The dialog consists of the following fields:

Context Identifiers

This list contains all of the identifiers which have been defined in the main header file of your help project.

The list shows the identifier and its corresponding numeric value.

The contents of this list is used to rewrite the header file.

Identifier

When creating/maintaining a context ID, this field is used to specify the name of the Context ID. Any sequence of characters may be entered.

Value

This field contains the numeric value assigned to the named Context ID. The number must be a positive integer.

New MFC Identifiers

Under the Microsoft Foundation classes (MFC), different help contexts have been assigned groups of valid values. Unless the Microsoft standard is adhered to, help contexts will not work when a help file is integrated with an MFC application.

The buttons in this section are used to automatically populate the Value field with the next available value for the appropriate MFC group.

Generally, the Dialog and MessageBox options are the most frequently used.

Please see the section How to integrate a help file with a C/C++ application for further information.

Notes

To create a new identifier, press the New ID button and then type some text in the Identifier field. Press the Add button to store the new identifier to the list.

To edit an identifier, double click on it in the Context Identifiers list so that it appears in the Identifier and Value fields. Modify it as required and then press the Update button to save it back to the list.

To delete an identifier, single click on it in the Context Identifiers list and then press the Delete button. Answer the delete confirmation as required.

Press the Ok button to exit the dialog and save all the changes or the Cancel button to exit the dialog without saving any changes to the header file.

HelpBuilder automatically remembers the next identifier value to be used for each of the different context/MFC groups therefore, if you add/delete IDs and create IDs using the New buttons you should not have any duplicates.

You must not manually edit a header file in a HelpBuilder window otherwise this dialog will not be able to open it.

If you are not creating a help file for integration with an MFC application, you should generally use the New button for all new context identifiers.

You may use the MFC offsets, but it is not compulsory.


Help File Copyright
This Windows Help file was written by Graham Plowman

using Help Builder Version 1.07 and refers to:

Help Builder Version 1.07 / 06/10/95

Copyright 1993, 1994, 1995 G.Plowman


Creating a new Project
How to create a new help project

A HelpBuilder project must be created for each Windows Help file you wish to build. The project identifies all those files to be included in the Windows Help file, together with various other settings and options.

There are two ways in which HelpBuilder may be used to create a new project:

Using the Project/New menu option

Using the Project/Wizard menu option

Project/New

This method simply creates a new HelpBuilder project file to which you may add extra files as required.

Various project defaults are set for you which you can change as required.

On selecting Project/New, the New Project Dialog appears, asking for the filename of the new project. Enter the required file name and press 'Ok'.

Having created the new project file, the Edit Project Dialog appears, requesting the user to select files for inclusion in the project. Select the required files and press 'Ok' or 'Cancel' as appropriate.

Project/Wizard

The project Wizard performs the same actions as the standard Project/New menu option, but it also sets a lot of defaults for you and creates the basic files necessary for all help projects: a contents page topic file, a header file, a copyright topic file and an icon file. All of these files are pre-created and already linked together such that all you need to do is continue to build on them.

The Project Wizard may also be used to import Norton Guides help projects into HelpBuilder.

The files created by the Project Wizard form the basis of all HelpBuilder/Windows Help projects files and form a ready made help project which can be compiled and run immediately.

It is quicker to use the Wizard to create a new project.

On selecting Project/Wizard, the New Project Dialog appears, asking for the filename of the new project. Enter the required file name and press 'Ok'.

A dialog will then appear asking whether you require a Norton Guides Project to be imported. Answering 'No' will cause HelpBuilder to proceed to create the component files for a standard new project. Answering 'Yes' will cause the Import Norton Guides Project Dialog to appear to ask for the name of the Norton Guides project to import. HelpBuilder will then proceed to import the project.

When the new project has been created/imported, HelpBuilder automatically opens the header file and contents page file ready for editing.

The user may then select the Project/Edit menu option for  the Edit Project Dialog to select files for inclusion in the project.


Create Dependencies Warning

This warning occurs when HelpBuilder identifies that the project file (.PRJ) which is currently being opened has been moved to another directory which is different from that in which the project was originally created.

HelpBuilder assumes that if a project file has been moved, then it is likely that the component files (topic files, header files, icons and bitmaps) have also been moved. Since the names of these files are held in the project file, they must be amended to reflect the new project directory.

If the user selects the Yes button, the dependencies will be rebuilt.

If the user selects the No button, dependencies will not be rebuilt but the project file will be amended to register the fact that it has been moved. The topic files will not be affected.

Normally, if you copy all the component files of a project from one directory to another then you should answer 'Yes' to rebuilding dependencies.


Delete Context Identifier Confirmation

This confirmation occurs when the user has selected to delete the currently highlighted Context Identifier definition in the Context Identifiers listbox.

Select 'Yes' if you wish to proceed to delete the selected Context Identifier definition completely from the main project header file.

Select 'No' to keep the definition intact and not make any changes.


Edit Project Dialog

Purpose

The Edit Project Dialog is used to select all of the component files to be included into a help project. The dialog is used to select topic files (.TXT), bitmap and segmented hypergraphic picture files (.BMP, .SHG), icon files (.ICO) and header files (.H, .HPP).

Available from

Project/Edit menu option

Comments

The top left list in the dialog shows all of the topic files and bitmap files in the current directory, while the combination box below it is used to select which type of files to display in the list.

The top right list shows the subdirectories and disk drives available from the current directory.

The bottom list shows all of the topic, bitmap, icon and header files which have been selected for inclusion in the project.

To add a file to the project, click on the required file in the top left list and it will appear in the bottom list. Note that you cannot add a file twice and you cannot add unrecognised file types, so you may need to rename your file(s) for it to be included.

To remove a file from the project, click on the file to be removed in the bottom list.

Press the 'Add All' button to add all files in the current directory to the project. Note that if a file is already in the project it will not be added again.

Press the 'Remove All' button to remove all topic files from the project.

Press the Ok button to save the project list or cancel to exit without saving it.

Notes

If an unregistered shareware version of HelpBuilder is being used, the number of files allowed in a project will be limited to 25. This includes topics, graphics and header files.

Registered versions will allow up to 2048 files.


Error Messages

Cannot Delete Main Window Error

Cannot open topic file

Create Dependencies Warning

Delete Context Identifier Confirmation

File too big too load into memory

Invalid Context ID Error

Invalid Context Number Error

Invalid File

Invalid File Name

Invalid Number Error

Invalid Topic Title Error

Invalid Window Name Error

Invalid Window Title Error

Maximum number of topics for a help project reached

Memory Allocation failure

Mutiple Icons

No Main Header File Error

Open Header File Failure

Prompt to save changed file

Save As Fail

Too Many Colours Error

Too Many Fonts Error

Too Many Windows Defined Error

Too Many Windows Error

Unable to create project file

Unable to open the selected project

Unrecognised project (.PRJ) file

Unrecognised project (.PRJ) file version

Unrecognised topic (.TNF) information file

Unrecognised topic (.TNF) file version

Update Context Identifier Confirmation


Prompt to save changed file

This prompt appears when an attempt is made to close a topic window which contains a topic file which has been changed since it was last saved.

Select 'Yes' if you wish to save the changed file and continue to close the window.

Select 'No' if you do not wish to save the changed file but you do wish to close the window.

Select 'Cancel' if you do not wish to save the changed file and you do not wish to close the window.


Topic Links Dialog

Purpose

The Topic Links Dialog is used to provide a topic page with a context ID and optionally, any search or keyword strings.

Available from

File/Links menu option

Comments

The dialog contains the following fields:

Context ID

This is the context ID of the topic. It may be a string or a number. It is best to use a string which has been #define'd to a value within a header file. The header file must be included in the Project Settings dialog.

It is adviseable to use #define'd values for context IDs since the same header file may be included in your C or C++ application(s) and this reduces error and eases integration of a help file to an application.

Example:	IDH_CONTENTS

Topic Title

This is the name of the topic which will appear in the lower 'goto' box of the Search dialog within Windows help.

Example:	Contents Page

Search Keywords

You can enable users to find and view topics by assigning keywords to the topics. You assign a keyword by placing a keyword/string in this field. Windows Help collects all keywords in a help file and displays them in its Search dialog box. Using this dialog box, a user can select a keyword and view the help topics associated with it.

You may have multiple keywords by placing each new keyword on a new line within this field. Press Ctrl+Enter to start a new line.

A keyword can be assigned to any number of topics. When the user selects the keyword in the Search dialog box, Windows Help displays all topics associated with the keyword. The user then selects the one to view.

Example:	Contents Page

Index

Menu

Browse Sequence

You can enable users to browse through a sequence of help topics by creating a browse sequence.

Note that HelpBuilder automatically detects the presence of browse sequences and will automatically insert the browse buttons into Windows Help for you.

Example:	shorttopics

A browse sequence typically consists of two or more related topics which are intended to be read in sequence.

Windows Help adds topics with sequence identifiers to the browse sequence and determines the order of the topics in the sequence by sorting the identifiers alphabetically. If two topics have the same identifier, Windows Help assumes that the topic which appears in the Project file list first is to be displayed first.

You can create more than one browse sequence in a help file by using sequence numbers with sequence identifiers. The sequence number consists of a colon (:) followed by an integer number. Windows Help combines all topics having the same sequence identifier (but with different sequence numbers) into a single browse sequence and determines the order of the topics by sorting them alphabetically. To ensure that numerics are sorted correctly, they should have the same number of digits. For example, the numbers 1 to 10 should be 01, 02, 03 .. 10.

Example:	alpha:3


Open Dialog

Purpose

The Open Dialog enables a previously created help topic file or ordinary text file to be opened for editing.

Available from

Second toolbar button

File/Open menu option

Comments

Type the name of the required file in the File Name field and then press the Enter key.

Alternatively, use the mouse to click on the required file and click the Ok button to open it.

A topic file may only be open in read-write mode by one user at a time. If another user attempts to open the same file in a networked environment they will receive it in read-only mode and this will be shown on the window caption once the file is opened.

You cannot change a read-only file - you must save it under another name first.

To exit out from the Open dialog, press the Esc key or click on the Cancel button or the system menu icon.


Save Topic As Dialog
Save As Dialog

Purpose

The Save As Dialog enables the currently open help topic file or ordinary text file to be saved under a different file name.

Available from

Second toolbar button

File/Save As menu option

Comments

Type the new name of the file in the File Name field and then press the Enter key to save the file.

Alternatively, use the mouse to click on the required file and click the Ok button to select it as the new name.

Note: If the new file name is the same as a file already present on the disk, you will be requested to confirm overwriting of that file.

To exit out from the Save As dialog, press the Esc key or click on the Cancel button or the system menu icon


Font Dialog

Purpose

The Font Dialog is used to change the font of the currently selected text.

Available from

10th toolbar button

Text/Font menu option

Comments

To change the font of some text, it must be selected either by using the shift key with the cursor keys or by swiping the mouse across it. Then, select the Text/Font menu option or the toolbar button.

To change the font of some text which already has its font set, you should highlight the text and the surrounding RTF statements including the { and } brace characters.

From the font dialog, select the required font, style and size and then press 'Ok'. HelpBuilder will then automatically save the font to the internal RTF font table and then write the appropriate RTF commands in your text.

Press 'Cancel' to exit without selecting a font.


1xxx Error Codes
Help Compiler Error Codes/Messages - 1xxx

File Errors

1019	Project file extension cannot be .HLP or .PH

1030	Filename exceeds 259 characters

1079	Out of file handles

1100	Cannot open file - permission denied

1150	Cannot overwrite file (ie read only)

1170	File name is a directory name

1190	Cannot use DOS filename (ie COMn, LPTn or PRN)

1230	File not found

1292	File is not a valid bitmap file

1319	Disk full

1513	Bitmap file duplicated in project

1536	Not enough memory available to compress bitmap


2xxx Error Codes
Help Compiler Error Codes/Messages - 2xxx

Project File Errors

2010	Cannot nest #include more than 5 times

2030	Comment unclosed at end of file

2050	Invalid #include syntax

2091	Bracket missing from section heading

2111	Section heading missing (ie heading not complete)

2131	Invalid OPTIONS syntax: 'option=value' expected

2141	Invalid ALIAS syntax: 'context=context' expected

2151	Incomplete line in section

2171	Unrecognised text

2191	Section heading unrecognised

2214	Line in .HPJ file exceeds length limit of 2047 characters

2273	[OPTIONS] should preceed [FILES] and [BITMAPS] for all

options to take effect

2291	Section already defined

2305	No valid files in [FILES] section

2322	Context string cannot be used as alias string

2331	Context number already used in [MAP] section

2341	Invalid or missing context string

2351	Invalid context identification number

2362	Context string already assigned an alias

2372	Alias string already assigned

2391	Limit of 6 window definitions exceeded

2401	Window maximisation state must be 0 or 1

2411	Invalid syntax in window colour

2421	Invalid window position

2431	Missing quote in window caption

2441	Window name is too long

2451	Window position out of range 0..1023

2461	Window name missing

2471	Invalid syntax in [WINDOWS] section

2481	Secondary-window position required

2491	Duplicate window name

2501	Window caption exceeds limit of 50 characters

2511	Unrecognised option in [OPTIONS] section

2532	Option previously defined

2550	Invalid path name in option (ie ROOT or BMROOT)

2570	Path name in option too long

2591	Invalid MAPFONTSIZE

2612	Maximum of 5 font ranges exceeded

2632	Current font range overlaps previously defined range

2651	File name exceeds 20 characters

2672	Unrecognised font name in FORCEFONT option

2691	Invalid MULTIKEY syntax

2711	Maximum of 5 keyword tables exceeded

2732	Character already used

2752	Characters 'K' and 'k' cannot be used - reserved for keyword table

2771	REPORT option must be ON or OFF

2811	OLDPHRASE option must be ON or OFF

2832	COMPRESS option must be OFF, MEDIUM or HIGH

2842	OPTCDROM option must be TRUE or FALSE

2852	Invalid TITLE option

2872	Invalid LANGUAGE option

2893	Warning option must be 1, 2 or 3

2932	Copyright string exceeds 50 characters

3011	Maximum of 32 build tags exceeded

3031	Build tag length exceeds 32 characters

3041	Build tag contains invalid characters

3076	[BUILDTAGS] section missing

3096	Build expression too complex

3116	Invalid build expression

3133	Duplicate build tag in [BUILDTAGS] section

3152	Build tag not defined in [BUILDTAGS] section

3178	Build expression missing from project file


3xxx Error Codes
Help Compiler Error Codes/Messages - 3xxx

Macro Errors

3511	Macro exceeds limit of 254 characters

3532	Undefined function in macro

3552	Undefined variable in macro

3571	Wrong number of parameters to function in macro

3591	Syntax error in macro

3611	Function parameter type mismatch in macro

3631	Bad macro prototype

3652	Empty macro string (ie !footnote or hidden text doesn't contain a

macro)

3672	Macro nested too deeply


4xxx Error Codes
Help Compiler Error Codes/Messages - 4xxx

Context String Errors

4011	Context string already used

4031	Invalid context string (ie non-alphanumeric characters)

4056	Unresolved context string specified in CONTENTS option

4072	Context string exceeds limit of 255 characters

4098	Context string(s) in [MAP] section not defined in any topic

(ie some #define(s) in header file is/are not being used)

4113	Unresolved jump or popup

4131	Hash conflict between contexts - change one context name

4151	Invalid secondary window name

4171	Cannot use secondary window with popup

4196	Jumps and lookups not verified due to low memory

4211	Footnote text exceeds limit of 1023 characters

4231	Footnote text missing

4251	Browse sequence not in first paragraph

4272	Empty browse sequence string

4292	Missing browse sequence number

4312	Browse sequence already defined

4331	Title not in first paragraph

4352	Empty title string

4372	Title defined more than once

4393	Title exceeds limit of 128 characters

4412	Keyword string exceeds limit of 255 characters

4433	Empty keyword string

4452	Keyword(s) defined without title (ie topic has no title)

4471	Build tag footnote not at begining of topic

4492	Build tag exceeds limit of 32 characters

4551	Entry macro not in first paragraph

Topic File Errors

4616	File is not a valid RTF topic file

4639	Unrecognised RTF statement at byte offset

4649	File contains more than 32767 topics

4652	Table formatting too complex

4662	Side by side paragraph formatting not supported

4671	Table contains more than 32 columns

4680	Font in file not in RTF font table

4692	Unrecognsed graphic format

4733	Hidden page break (break is part of hidden text)

4753	Hidden paragraph

4763	Hidden carriage return

4774	Paragraph exceeds limit of 64K

4792	Non-scrolling region defined after scrolling region (\)

4813	Non-scrolling region crosses page boundary (ie \page missing)


5xxx Error Codes
Help Compiler Error Codes/Messages - 5xxx

Miscellaneous Errors

5035	File not created (ie no topics to compile / file empty)

5059	Not enough memory to build help file

5075	Help Compiler corrupted. Reinstall it.

5098	Using old key-phrase table (ie delete .PH file before compile)

5115	Write failed (ie disk operation failed)

5139	Aborted by user (ie Ctrl+C)


Compiler Error Codes/Messages
Help Compiler Error Codes/Messages

Below are all the error messages and codes reported by the Microsoft Help Compiler which HelpBuilder uses to compile help files.

Note that many of the errors should not occur under HelpBuilder since it builds the project (.HPJ) file and the topic (.RTF) file for you.

File Error codes 1xxx

Project File Error codes 2xxx

Macro Error codes 3xxx

Context String/Topic File Error codes 4xxx

Miscellaneous Error codes 5xxx


Using Header Files
How to use header files

To use a header file select the Project/Edit menu option to obtain the Edit Project Dialog.

Select the appropriate file type in the 'List Files of Type' field, then select the required file by double clicking on it to make it appear in the bottom list. You may then use any of the #defined values in that header file as context IDs for your topics.

Note that the Topic LINK Dialog, the Topic Links Dialog and the Project Settings Dialog will display any IDs defined in your header file.

The following file types are treated as header files by HelpBuilder:

.H

.HPP


How to import Norton Guides Projects

Help Builder provides a facility for importing Norton Guides and Expert Help project files. The latter must be in the Norton Guides Format.

Help Builder accepts the name of the main control file of the Norton Guides project. This is the file which contains a description of the menu structure of the Norton Guides project.

Help Builder cannot import a .NG file, the compiled Norton Guides file. Instead, it requires the source files which were used to make the .NG file. There are products available which will recreate the source files from a .NG file, so technically, using one of these products to create the source it would then be possible to import the project into Help Builder.

To import a Norton Guides project, select the Project/Wizard menu option or the Wizard toolbar button.

The New Project dialog will then appear so that the user can specify the HelpBuilder project to create and import the Norton Guides project into. On pressing 'Ok' the Default Project Files dialog will appear, requesting the file names for the default project component files. The defaults provided in the fields should be sufficient. If not, change them as required. Place a check in the Import Norton Guides Project field at the bottom of the dialog. Press 'Ok.

The Import Norton Guides Project dialog will then appear. This dialog should be used to enter the name of the Norton Guides or Expert Help main control file name.

Press 'Ok' and Help Builder will then convert the project.

The import process creates context identifiers from the topics in the Norton Guides project and recreates the menu structure in the new project. 'See Also' references are also handled.

The imported project should be readily compileable under HelpBuilder, however, sometimes the Norton Guides files have errors such as starting bold text and never finishing it. HelpBuilder will report this as a mismatch in curly braces.

The imported project uses a fixed pitch font. This may be changed in the Project Settings Dialog if required, however you might find that all text allignment is destroyed if a proportional font is selected.

Similarly, the colours used are the defaults used by Windows Help. You can change these by using the Project Windows dialog to change the 'main' window colours and the Project Settings Dialog. It would then be possible to recreate the cyan/yellow on blue of Norton Guides! You would need to modify every topic and swap bold settings for a yellow colour setting to make the Windows Help file really look like the original Norton Guides file!


How To...

Create a new help project

Change text fonts

Change text colours

Import Norton Guides Projects

Import Text Files from other Editors

Insert links to other topics and/or create popups

Insert picture links to other topics

Insert special characters

Integrate a help file with a C/C++ application

Integrate a help file with a VB application

Lock the top of the topic page and change its colour

Make bold text

Make italic text

Select Text

Use header files


Import Norton Guides Project Dialog
Project Wizard - Import Norton Guides Project

Purpose

The Import Norton Guides Dialog enables a Norton Guides or Expert Help project to be selected for import into HelpBuilder.

Available from

'Ok' button of Default Project Files dialog

if Import Norton Guides Project was checked

Comments

Type the name of the required import project file in the File Name field and then press the Enter key.

Alternatively, use the mouse to click on the required file and click the Ok button to open it.

The file specified should be the project 'Control' file. Under Norton Guides, this file normally has a .CTL extension whereas the Expert Help version normally has a .LNK extension.

The project control file contains a listing of the main Norton Guides menu structure and specifies the names of all the component project files.

To exit out from the dialog, press the Esc key or click on the Cancel button or the system menu icon.


Importing Text Files
How to Import Text Files from other Editors

To import text from other editors, there are two ways in which this can be done.

Cut/Paste via the Clipboard

This is probably the quickest and simplest way

Importing a Text File

To import a file as a text file, open it as a Topic using the File/Open menu option. Note that HelpBuilder Topic files are limited to 32K in length so you will not be able to import files larger than this.

Having successfully opened your text file, you must save it again using the File/Save As menu option. When you save the topic, it MUST be given a .TXT extension. If you do not, HelpBuilder will not recognise the file as a topic file.

It is a good idea to store all topics for a project in the same directory.

Once the topic has been saved, it must be included in a project. To do this, select the Project/Edit menu option to obtain the Edit Project dialog and add the new file to the project. Press 'Ok' to save the modified project.

Since every topic must have a Context Identifier, you should select the File/Topic Links menu option to obtain the Topic Links dialog. Press the 'Context IDs' button to obtain the Context Identifiers dialog and add a new identifier for the new topic.

Press 'Ok' to return to the Topic Links dialog and enter the new identifier in the 'Context ID' field. Enter any other information required in the dialog and press 'Ok' to save it.

You can now build your project and your new imported text file topic will be included within it.


Inserting Topic Links
How to insert links to other topics and popups

Insert picture links to other topics

Inserting links to other topics is very straightforward. Firstly, decide whether you require a jump or a 'popup' topic. Then, position the caret where you require the jump to be in your text and press the left LINK toolbar icon for a jump or the right LINK toolbar icon for a 'popup' topic.

A dialog will appear asking you to type the text which will appear in your topic and a dropdown list box of valid topic context IDs to jump to.

It is also possible to use a picture as the 'hot spot' instead of the green underlined text normally displayed for a link by Windows Help.

To do this, the dialog contains fields to specify that a picture is to be displayed, a field to specify the bitmap to display and if you want text as well as the bitmap, a control of whether to display the text to the left or right of the bitmap.

Press 'Ok' and the link will be inserted.

You can either manually edit the link command or highlight it (including the { and } braces) and click the LINK icon to modify it.


Install Compiler Dialog

Purpose

The Install Compiler Dialog enables the user to select a compiler program to be installed for use by HelpBuiler.

Available from

Install button on Project Settings Dialog

Comments

Type the name of the required compiler program in the File Name field and then press the Enter key.

Alternatively, use the mouse to click on the required file and click the Ok button to select it.

To exit out from the dialog, press the Esc key or click on the Cancel button or the system menu icon.


Integrating help with C/C++ Applications
How to integrate a help file with a C/C++ application

For an ordinary C/SDK application this is relatively straightforward and a description of how to do this is well documented in the SDK 3.1 Help. There are also good examples programs supplied with Microsoft C.

A C++ Foundation Classes (MFC) application is a completely different story since the Microsoft documentation is somewhat simplistic and doesn't tell you the full story.

Under MFC Microsoft have integrated help as part of the CWinApp class. Every MFC application will use this class and the Application Wizard may be used to build a default application with help support.

The important features of help in an MFC application are to set the F1 key in the accelerator table:

VK_F1,	ID_CONTEXT_HELP,	VIRTKEY,SHIFT

VK_F1,	ID_HELP,	VIRTKEY

and to place entries in the message map of the class you have derived from CWinApp:

BEGIN_MESSAGE_MAP(CTheApp, CWinApp)

    //AFX_MSG_MAP(CTheApp)

    // Global help commands

    ON_COMMAND(ID_HELP_INDEX,    CWinApp::OnHelpIndex)

    ON_COMMAND(ID_HELP_USING,    CWinApp::OnHelpUsing)

    // F1 in main window & dialogs, F1 in dialogs, Context Shift F1 Help maps

    ON_COMMAND(ID_HELP,          CWinApp::OnHelp)

    ON_COMMAND(ID_DEFAULT_HELP,  CWinApp::OnHelpIndex)

    ON_COMMAND(ID_CONTEXT_HELP,  CWinApp::OnContextHelp)

    //AFX_MSG_MAP

END_MESSAGE_MAP()

Each dialog should call its SetHelpID() method in its OnInitDialog() method to set the help id for the dialog. This will give context help for the dialog and this is where the Microsoft documentation stops!

Microsoft give the impression that all you have to do is set help IDs.

What they don't tell you is that if you do this your help won't work! Even if you look at their Appwizard code all looks in order.

The problem is that all of the IDs in the Appwizard code are hard-coded and represent LONG integer values. None of the programmers' help related functions in MFC accept a LONG as a help parameter - they require UINTs.

Looking at the MFC header files you will also find that the MFC help IDs are all larger than a UINT can hold and cannot therefore be passed as parameters.

If you look at the MFC source code you will find that all of the help related functions add an offset to the value you pass which is why if you use a header file for your application and your help file and use the same ID your help doesn't work. This is because MFC passes your value plus an offset to Windows Help which cannot be found!

The solution is as follows.

If you take the offset which MFC help functions add off of your call to the help function and pass this value, your help will work. It is important that your help ID less the offset can be held in a UINT.

The MFC offsets are as follows and are defined in AFXPRIV.H:

// Help ID bases

#define HID_BASE_COMMAND    0x00010000UL        // ID and IDM

#define HID_BASE_RESOURCE   0x00020000UL        // IDR and IDD

#define HID_BASE_PROMPT     0x00030000UL        // IDP

#define HID_BASE_NCAREAS    0x00040000UL

#define HID_BASE_CONTROL    0x00050000UL        // IDC

HID_BASE_COMMAND refers to menu options.

HID_BASE_RESOURCE refers to common dialogs and user defined dialogs in your .RC file.

HID_BASE_PROMPT refers to AfxMessageBox() calls.

Example: A dialog

BOOL CMyDialog::OnInitDialog() {

    // Set the help page

    this->SetHelpID((UINT)(IDH_MYDIALOGHELP - HID_BASE_RESOURCE));

    return (TRUE);

}

Example: An AfxMessageBox() call

AfxMessageBox("My message", MB_OK,

              (UINT)(IDH_MYMSGBOXHELP - HID_BASE_PROMPT));

In your help file for the above, identify your help topics with the context IDs IDH_MYDIALOGHELP and IDH_MYMSGBOXHELP respectively.

Note that IDH_MYDIALOGHELP would be defined with a value equal to or greater than HID_BASE_RESOURCE but it must not be more than 65535 greater than HID_BASE_RESOURCE since this will overflow the limit of a UINT.

Similarly, IDH_MYMSGBOXHELP must be greater than HID_BASE_PROMPT.

If you are using a header file for these IDs note that the Windows Help compiler will not accept #define CCC AAA + 1   type computed values. If AAA was the value 1 you must use #define CCC 2

Why the MFC code accepts UINTs is unexplainable. Perhaps future versions of MFC will change to LONGs - how it should be now!

Once the above problems have been overcome, it is in fact easier to add context help to an MFC application than to a standard C/SDK application.

See also: Terminology


Integrating help with VB Applications
How to integrate a help file with a VB application

Integration of a help file with Visual Basic is a very straightforward process.

Most controls in Visual Basic allow you to set the help context ID in the HelpContextID property.

Within this property your should place the numeric value of the context ID you require.

Unfortunately, Visual Basic does not use header files like C/C++ so it is not possible to share a header file between your help project and your application. However, rather than typing the numbers entered in your Visual Basic application into the Topic Links Dialog for each topic, it is still a good idea to use a header file for your help project because it will make maintenence much easier - when setting numbers in Visual Basic, you need only look in one file of your help project to find the appropriate help context values rather than trying to find it among all your topic files.

To ensure that your Visual Basic application can use your help file you must specify the name of the help file in the Project Options dialog obtainable from the Options/Project menu option within Visual Basic.

Visual Basic automatically performs all other processing necessary to use a help file.

See also: Terminology


Invalid File Error

This error occurs when an attempt is made to add a file to a project file (.PRJ) which is not a recognised file type.

HelpBuilder recognises the following file types:

.TXT	Topic files

.BMP	Bitmap files

.SHG	Segmented hypergraphic files

.ICO	Icon files

.H	Header files

.HPP	Header files

An attempt to add a file which does not have one of the above extensions will result in this error.

If you wish to add a file to a project which does not conform to the above list, then you should rename it.


Invalid Number Error

This error occurs when invalid data has been entered into a field where a number is expected.

Possible causes

Characters instead of digits entered

Out of range number entered


Invalid Context ID Error

This error occurs when invalid data has been entered into a field where a Context Identifier is expected.

A Context Identifier is any sequence of alphanumeric characters and '_' but must start with an alphabetic character.

Possible causes

No characters entered

A non-alphanumeric or '_' has been entered


Invalid Context Number Error

This error occurs when invalid data has been entered into a field where a context number is expected.

A context number is a positive integer number.

Possible causes

Characters instead of digits entered

No number entered


Invalid File Name Error

This error occurs when HelpBuilder is expecting a file name to be entered and the name specified is invalid.

A file name must contain alphanumeric characters. You should enter a valid filename to be allowed to continue.


Invalid Topic Title Error

This error occurs when a Topic Title is entered which contains invalid characters.

A valid Topic Title should contain alpanumeric characters.


Invalid Window Name Error

This error occurs when an attempt is made to save a window in the Project Windows Dialog which has an invalid window name.

A valid window name must be entered consisting of alphabetic characters only.


Invalid Window Title

This error occurs when an attempt is made to save a window in the Project Windows Dialog which has an invalid window title.

A valid window title must be entered consisting of alphabetic characters only.


Italic Text
How to make bold text

Italic text is obtained by typing some text and then highlighting it with the mouse and then clicking on the 'I' toolbar icon.

This will place an open curly brace and a backslash i before your text and a close curly brace after your text.

To turn the italic off, either delete these characters or highligh the text including the RTF bold characters and click the 'I' toolbar icon again.

Alternatively, italic text can be inserted by selecting some text using the mouse and then selecting the Text/Font menu option to obtain the Font Dialog.


Application Limitations

HelpBuilder currently has the following limitations, many of which will be modified in future releases:

25 topics/files on unregistered versions, 2048 on registered versions

A maximum of 32 'windows' may be defined

A maximum of 32 fonts may be selected per project.

This is independent of the number of times font sizes, bold and italic

are selected

A maximum of 32 colours may be selected per project

Limitations on Use

Unregistered users of Help Builder must not distribute the help files produced by HelpBuilder, however registered users may do so freely.

There is no fee payable for distributing large numbers of copies of help files, however, the author does request that if you use HelpBuilder for creating help files for your software for which you have a monetary gain that you mention HelpBuilder and the author'scontact details in your supporting documentation or help files.


Topic/Popup Link Dialog

Purpose

The Topic/Popup Link Dialog is used to insert links/jumps to other topics within a help file or another help file. Links may also be inserted to activate macros..

Available from

7th and 8th toolbar buttons

File/Links menu option

Comments

A link usually appears in a help file as green text underlined by a solid line for a jump or a dotted line for a popup link. Using this dialog, various options can be selected to confgure/maintain a topic link.

The dialog has the following fields:

Link Type

This list shows all the possible link actions which can be set up. The supported link actions are:

Standard Text

Other Help File

Macro

A 'Standard Text' link is the common 'green underlined text' type of link.

'Other Help File' enables a link to be set up to a topic in another help file. To implement this type of link, you must enter a known context identifier from the 'other' help file in the Link Name field discussed below.

A macro link enables a non-standard activity to be performed, usually taking advantages of the in-built features of WinHelp, for example, printing or activating the search dialog.

Link Appearance

This field is used to specify how the link will appear on the screen and may be:

Text

Picture/text

Text is the standard appearance for a link. Picture/Text enables a picture link with optional text.

Text

This is the text which will appear in green and underlined in Windows Help. It provides the user with an indication of the topic to which the link will connect.

The text may be any sequence of alpha-numeric characters you wish.

If a picture is to be displayed, this field may be left blank. If entered, it will be alligned either side of the bitmap depending on the setting of the allignment field.

Underline

Text links are normally displayed as green underlined text. This check box enables this to be turned off such that the link appears in the normal text colour. Moving the mouse over the link in Windows Help will still cause the link to be recognised as a 'hot spot' and change the mouse icon to a hand.

Link Name

This is the context ID of the topic which the link is to connect to when the user clicks on the green text.

Press the down arrow on the combination box to see a list of all the recognised topic context IDs within the project.

You may select one of the listed IDs or type in your own ID.

Note that this list will be empty if no project is open.

Window

When a jump is set to another topic it is possible to specify a window name to be used to display that topic. In this way it is possible to change the colours of the client and non-client locked areas of topics on a topic-by-topic basis. Windows must be configured in the Project/Windows Dialog.

Bitmap File Name

This field contains the name of the bitmap file to be displayed if Link Appearance is set to Picture/Text.

Text Allignment

This field only applies when Link Appearance is set to Picture/Text and both a bitmap and text have been entered.

If the text above is specified it may be placed to the left or the right of the bitmap. This field specifies which side of the bitmap the

text is to appear. If the text field is left blank then this field has no effect.

Help File Name

When a jump is set to another help file, this field specifies the file name of the other help file. Press the browse button to navigate your disks for a suitable file name if required. Generally, this field should contain a file name with no drive or path specified.

Macro

When a jump is set to activate a macro, this field contains the macro(s) to be activated. The drop down list contains the most common macros you are likely to require, however, you can type any macro. You can place multiple macros in the field and use the semi colon ; character to separate them.

Press the 'Ok' button to insert a link in the current topic, otherwise press 'Cancel' to exit the dialog without inserting a link.


Topic Locator List full Warning

The HelpBuilder Topic Locator List has a limit of approximately 600 files, depending on the length of the topic names, identifiers and file names.

This warning appears when the Topic Locator List has become full and it cannot display any more topics. The list will effectively be 'cut short'. Topics not displayed should be opened in the normal way via the File/Open menu option.


Locking/colours of top of page
How to lock the top of the topic page and change its colour

This help page is a good example of this technique whereby the yellow area does not scroll when the user scrolls the rest of this page.

To lock the top of the page, use the mouse to highlight the text at the top of the page which you require to be in the non-scrollable area. Then select the Text/Lock top of page menu option or click on the 14th toolbar button (the lock). The appropriate RTF statements will then be inserted around your text, for example:

\keepn{\b Text in locked/yellow area}

\pard

This is the rest of the page.

You may place multiple lines of text between the first and third lines in the example - the \pard RTF command marks the end of the non-scrollable area.

Note that a non-scrollable area must always start at the top of a topic page.

To remove the non-scrollable area, either delete the RTF commands or highlight the text again including the RTF commands and select the menu option or toolbar button again.

To change the colour of the non-scrollable area, select the Project/Windows menu option to obtain the Project Windows dialog. Within this dialog you can select the appropriate colour. If you have not defined any windows, then the 'main' window colours will apply.


Project Macros Dialog

Purpose

The Project Macros Dialog is used to define macros and various Windows Help features upon startup of a Help File.

Available from

Project/Macros menu option

Comments

Macros are placed in the [CONFIG] section of a project (.HPJ) file.

The BrowseButtons() macro will automatically be added to the project file for you by HelpBuilder if you have defined any topics in your project as belonging to a browse sequence. You therefore do not need to insert this macro in the Project Macros dialog.

Since Windows Help executes the macros when it first opens the help file, macros that create menus, menu items, and buttons are typically placed in this section. If there is more than one macro listed in the [CONFIG] section, Windows Help executes them in the order in which they are listed.

You can create new menu items and buttons for Windows Help by using macros such as CreateButton and InsertMenu. These macros define other Help macros and associate them with the menu items and buttons.

Windows Help executes these macros when the user chooses a

corresponding menu item or button. Macros that create Help buttons, menus, or menu items remain in effect until the user quits Windows Help or opens a new help file.

You can extend the capabilities of Windows Help by developing your own dynamic-link libraries (DLLs) and defining Help macros that call functions in the libraries. To define Help macros that call DLL functions, you must register each function and its corresponding library by using the RegisterRoutine macro in the [CONFIG] section of the project file.

The following is an example of macros which can be inserted. For more detailed information on macros, please refer to the Microsoft Windows 3.1 SDK Help section 'Creating Help Project Files' and 'Help Macros'.

; Button macros and Using Help file

CreateButton("btn_up", "&Up", "JumpContents(`HOME.HLP')")

BrowseButtons()

SetHelpOnFile("APPHELP.HLP")


Main HelpBuilder Window

The main HelpBuilder window appears when the application is first started up and remains on the screen until the application is either minimised or closed.

The main window is a windows 'Multiple Document Interface' which means that it may contain several 'sub' windows within it. These are known as MDI child windows. The HelpBuilder main window may contain three different types of MDI child window:

Topic Window

A Topic Window contains the text for a specific page within a help file. It also has associated 'Topic Links' which are obtained from the File/Topic Links menu option.

A Topic Window is created every time the File/New or File/Open menu options are selected.

You may cut and paste text to/from the clipboard and use all of the various text formatting abilities of HelpBuilder within a Topic Window.

You can have as many Topic Windows as you like, subject to memory limitations.

A Topic Window may have [Read Only] in its title bar. This means that the topic file is either write protected or it is open in another HelpBuiler Topic Window and cannot therefore be modified. Only one copy of a file may be changeable at a time - this will be the one which is opened first. You will not be able to edit Read Only topics, however, you can save them under a new name and they will then become editable.

A Topic Window may be closed by double clicking on the window's system icon.

Topic Locator Window

The Topic Locator Window is obtained from the File/Topic Locator menu option. It contains a list of all the topics which have been defined in a project, giving each Context Identifier and topic title. There is only ever one Topic Locator Window.

You can change the sort order by selecting the appropriate option on the View menu.

The Locator provides a fast method of accessing topic files: you simply double click with the mouse on the required topic and the appropriate file will be opened in a new Topic Window.

The contents of the Topic Locator Window are automatically updated after every project build or Project/Edit.

The Topic Locator window may be closed by double clicking on the window's system icon.

Results Window

The Results Window displays the results of building a help file or the results of a Norton Guides import when using the Project Wizard. There is only ever one Results Window.

You can scroll up/down/left/right to view its contents, but you cannot change it.

The window may be closed when required, however it is automatically recreated/activated every time a build/import is performed.

At the top of the HelpBuilder main window is the menu and a toolbar. Toolbar options may be selected by simply pressing the appropriate button with the mouse. All of the toolbar options are duplicated on pulldown menu options.

At the bottom of the HelpBuilder main window is the status bar. It displays messages about HelpBuilder's current activity. It also displays a brief description of menu options when they are highlighted on a pulldown menu.

Both the toolbar and status bars may be removed/activated by selecting the appropriate option from the View menu.

To close the HelpBuilder main window and therefore exit the application, either press Ctrl+F4 or use the mouse to double click on the system menu icon or select the File/Exit menu option.


Memory Allocation Failure Error

HelpBuilder has failed to allocate some memory for its internal use.

This usually occurs when memory is limited due to many topics being currently open or many other applications running at the same time - try closing some down.

If this still does not solve the problem close down Windows and restart it again.


Menu Options
HelpBuilder menu options

HelpBuilder has 7 pulldown menus as follows:

File

New

Creates a new topic window

Open

Opens an existing topic file from the disk

Save

Saves a topic file to disk

Save As

Saves a topic file in memory under a different name

Close

Closes a topic file in memory. Note that the user will be asked whether to save the topic first

Topic Links

Sets the context ID, title, search strings and browse sequence for a topic

Topic Locator

Activates the Topic Locator window

Print

Prints a topic on the printer

Exit

Exits the HelpBuilder application. Note that the user will be asked whether to save any changed topics in memory first

Edit

Cut

Cuts some text out from a topic and places it on the clipboard

Copy

Copies some text from a topic and places it on the clipboard

Paste

Copies some text on the clipboard into the current topic

Topic Link

Sets a topic jump link to another topic

Popup Link

Sets a topic popup link to another topic

Bitmap

Inserts a bitmap picture in a topic

View

Toolbar

Toggles on/off displaying of the toolbar of icons at the top of the HelpBuilder window

Status Bar

Toggles on/off displaying of the status message bar at the bottom of the HelpBuilder window

Sort by Topic Context ID

Sorts the Topic Locator window by topic context Id

Sort By Title

Sorts the Topic Locator window by topic title

Text

Font

Enables the user to select a font and font size for the highlighted text

Colour

Enables the user to select a colour for the highlighted text

Bold

Toggles the bold setting of the highlighted text

Italic

Toggles the italic setting of the highlighted text

Lock top of page

Enables the top of the page to be 'locked' such that Windows Help displays it as a non-scollable part of the page

Project

New

Creates a new help project file

Project Wizard

Actives the project Wizard to provide a quick method of creating the basic template files for a new help file project.

Also allows the importing of Norton Guides help file projects.

Open

Opens an existing help project file on the disk

Save As

Saves the currently open help project file under a new name

Close

Closes the currently open help project file

Edit

Enables the user to select the topic files to be included in the help project

Settings

Enables the user to set the main project settings

Windows

Enables the user to configure 'windows' to be used by Windows Help to display topics. Also enables the main Windows Help window to be configured  when the help file is first opened

Context Identifiers

Enables the user to automatically maintain the main header file used in a help project

Macros

Enables the user to insert help file startup macros into the project

Print

Prints the project settings and list of help topics in the project on the printer

Print All

Prints the whole help project on the printer including the project settings, the list of topics and all of the topics in the help project

Build Help File

Executes the Windows Help compiler to build the currently open help project

Test Help File

Runs Windows Help to test the currently open help project file

Window

Cascade

Arrange all of the currently open topic windows in an overlaid stack

Tile

Arrange all of the currently open topic windows such that they all fit together on the screen in a tiled formation

Arrange Icons

Arrange all of the currently open iconised topic files in straight lines

Close All

Close all currently open topic files. Note that this will ask the user whether to save any changed topic files

Help

Index

Obtains the main HelpBuilder help file index

Search for Help On

Enables the user to search for help on a specific aspect of HelpBuilder

Using Help

Displays help on how to use Windows Help

About HelpBuilder

Displays version information about this version of HelpBuilder


Multiple Icons Warning

This warning occurs when an attempt is made to add more than one icon (.ICO) file to a HelpBuilder project (.PRJ).

Only one icon file is allowed per help project. This icon is used when Windows Help is minimised when 'running' the help file.


No Main Header File Error

In order to automatically maintain a header file of context identifiers, the name of the header file must be specified.

This error occurs when the main project header file has not been set in the Project Settings Dialog.


Open Header File Failure

This error occurs when an attempt is made to use the Project Context Identifiers Dialog and the main header file specified in the Project Settings Dialog cannot be opened.

This usually occurs if the header file cannot be found, possibly because it has been deleted, or it is currently open in a HelpBuilder window.

If you wish to use HelpBuilder to automatically maintain your main header file, you should not open it in an editing window.


Users of this Application
Other Users of HelpBuilder

HelpBuilder is also used by the following organisations:

Compaq Computers Uk Ltd

Los Alamos National Lab, New Mexico

Cinema Magnetique Communication SA, Paris

St. Mary Regional H.S., New Jersey

Lanier Photocopiers, Georgia

Transport Canada, Winnipeg

Fujitsu Australia, Melbourne, Victoria


Payment/Registration of Software
Payment for and Registration of Software

If you wish to continue to make use of the HelpBuilder software you are expected to pay a registration fee.

The registration fee for the Help Builder software may be found in the Software Price List section of this help file.

Compuserve also has a facility for payment for shareware software which is ideal for overseas users. Essentially, a shareware author registers their software in a database and then the facility transfers payment from one user's account to another.

You can pay for HelpBuilder via this facility via (GO) SWREG at any time. Select the 'Register Shareware' option. The registration number of this software is 4152.

Your registration fee entitles you to use this software on a single computer for an unlimited period and to make as many copies as you wish for backup purposes.

Upon receipt of your registration fee you will receive a disk (mail orders only) containing the latest version of the software and advice on how to remove the 'shareware warning' dialog, stop the one month disabling feature and release the various shareware restrictions in the software. You will also receive notice of updates to the software.

Free technical support is available to registered users.

See Also:Contacting the Author, What is Shareware ? - Description and Disclaimer,   Software Price List


Print Dialog

The Print Dialog appears prior to printing and enables the user to make selections on how much of the print will appear.

HelpBuilder does not support printing parts of topics or projects and therefore does not provide this ability.

You may however select the number of copies required, the print orientation and whether collation is required. Collation is only available when Project/Print All is selected.

Press Ok to commence printing or Cancel to exit without printing.


Project Save As Dialog
Save Project As Dialog

Purpose

The Save Project As Dialog enables the currently open help project to be saved under a different file name.

Available from

Project/Save As menu option

Comments

Type the new name of the project in the File Name field and then press the Enter key to save the project.

Alternatively, use the mouse to click on the required file and click the Ok button to select it as the new name.

Note: If the new file name is the same as a file already present on the disk, you will be requested to confirm overwriting of that file.

To exit out from the Save Project As dialog, press the Esc key or click on the Cancel button or the system menu icon.


New Project Dialog

Purpose

The New Project Dialog enables a new help project file to be created.

Available from

Project/New menu option

Project/Project Wizard menu option

Comments

Type the name of the new project in the File Name field and then press the Enter key to create the project.

Alternatively, use the mouse to click on the required project and click the Ok button to select it as the new name.

To exit out from the New Project dialog, press the Esc key or click on the Cancel button or the system menu icon.

Notes:

If the new project name is the same as a file already present on the disk, you will be requested to confirm overwriting of that file.

If there are any currently open topic files which have been changed, you will be requested to save them before the new project is created.


Open Project Dialog

Purpose

The Open Project Dialog enables a previously created help project file to be opened for use.

Available from

Project/Open menu option

Comments

Type the name of the required project in the File Name field and then press the Enter key.

Alternatively, use the mouse to click on the required project and click the Ok button to open it.

To exit out from the Open Project dialog, press the Esc key or click on the Cancel button or the system menu icon.

Note: If there are any currently open topic files which have been changed, you will be requested to save them before the newly chosen project is opened. Only one user may have a project file open at a time.


Project Windows Dialog

Purpose

The Project Windows Dialog enables the user to specify initial settings for Windows Help when it first opens a help file.

Available from

Project/Windows menu option

Comments

The dialog consists of the following fields:

Window

This is a list of all the windows currently defined in a project. To maintain a definition, select it and then press Edit or double click on it. It will move to the fields on the right of the dialog.

To delete a definition, select it and then press Delete.

When a definition has been changed, press Save to store it back in the list. When Ok is pressed, all of the definitions in the list will be saved to the currently open project.

Window Size/Position

This is the coordinates of a window. The 'main' window definition is always required by Windows Help because it is used when the help file is first opened.

Windows Help always regards the screen as being 1024 x 1024 (help units) regardless of its physical resolution.

The coordinates are therefore specified as values from 0 to 1023 as required.

For example, if the x-coordinate is 512, the left edge of the Help window is in the middle of the screen.

The Sizing list is used to specify the type of sizing required:

Default specifies that Windows Help should use

its own default window size

Preset specifies that the coordinates specified in the

fields should be used to set the window size

Maximised specifies that Windows Help should be maximised

Client Window Colour

Specifies the RGB colour value of the main client area space of Windows Help for the help file.

The Red, Green and Blue value must be entered as numeric values from 0 to 255 in the required combination. The scroll bars may also be used to change the colour. The square box next to the edit fields will change colour according to the current colour selection.

Non-Scrollable Area Colour

Specifies the colour of the non-scrollable area of a topic page. The yellow at the top of this page is an example of this.

The Red, Green and Blue value must be entered as numeric values from 0 to 255 in the required combination. The scroll bars may also be used to change the colour. The square box next to the edit fields will change colour according to the current colour selection.

Notes

Due a limitation of the Windows Help compiler it is not actually possible to set the Windows Help colours above without setting the size and position of the main window at the same time.

Therefore, the Default sizing option does not set the Windows Help colours, while Preset and Maximised do.

Similarly, for the colours of other windows to be used, the definitions must also be Preset or Maximised. Preset however does not affect the size of the main window once the 'main' definition has been used.


Quick Start Tutorial

This page provides a quick start tutorial to creating a typical Windows Help file using HelpBuilder.

Creating a Project

The first thing to be done before any help text can be written is to create a HelpBuilder project for your new help file.

A project is simply a file which lists all of the component files to your help file and all of the settings/options you have selected which relate to how the help file will be built.

To create a HelpBuilder project, it is suggested that you use the Project Wizard facility which creates all of the basic files and options necessary to form the basis of a help file. Select the Project/Project Wizard menu option to obtain the New Project dialog. Within this dialog, select the required directory for your project and enter the name of the project to be created. Typically, the name will be the name of an application, for example.

When the  Default Project Files dialog appears, press the Default button to get the default component file names (in future you might actually want to specify your own file names here), then press Ok.

HelpBuilder will then create a basic project containing a Contents Page, a Copyright message page, a main header file and an icon for the help file.

You are now ready to start creating your help...

Creating a Topic

In Windows Help terminology, a Topic is a complete page of text, usually related to one subject. In Windows Help you can scroll the main window up and down to view a current topic. This Quick Start Tutorial page is a Topic.

In HelpBuilder each topic is held in a separate text file. This enables help projects to share common topic files.

To create a new topic, select the File/New menu option. This will create a new 'topic window'. Within this window you can type all the text you require to appear on your topic page.

In order that Windows Help can maintain cross-references between topics in a help file, every topic must be identified by a unique numeric identifier known as a Context ID or Context Identifier.

To assign a Context ID to your new topic, select the File/Topic Links menu option to obtain the Topic Links dialog.

The first field is where the identifier is placed. You can just enter a unique number, but for maintainability of your help file it is strongly recommended that you use the header file facility.

A header file is a text file which contains a list of text strings each followed by a number. At compile time a 'find and replace' is done by the compiler to replace all occurences of the text with the corresponding number. Users of the C and C++ programming languages will be familiar with this concept, indeed HelpBuilder header files can be #included in C/C++ programs.

By using the HelpBuilder header file facility, it becomes possible to refer to help topics using meaningful textual strings instead of ambiguous numbers. However, the meaningful textual strings (#defines) must be set up in your project main header file before they can be used.

To place values in the main header file of your help project, press the Context IDs button to obtain the Context Identifiers dialog. In the Identifier field, enter the textual string which will be used to identify your topic. This must consist of alphanumeric characters and must not contain spaces. In the Value field, enter the number which this string will represent. Press the Add button to save the new identifier in the list and press Ok to save the list back to your header file.

Back at the Topic Links dialog... press the down button for the Context ID field. Select the identifier you have just set up.

Enter a title for the topic. When the 'Search' dialog is used in Windows Help, the title is displayed in the lower list when a subject is selected in the topic list.

Enter the alternative search keywords. These effectively provide a 'thesaurus' of alternatives to finding the topic. Each search string must be placed on a separate line, using Ctrl+Enter to create new lines. A search string may contain multiple words and must consist of alphanumeric characters. Search strings are all displayed in the top list of the Windows Help Search dialog.

Press Ok to save the entries.

You have now created your new topic, but it will not be 'seen' by HelpBuilder until you include it in your project. You must first save the topic by selecting the File/Save menu option...

Adding Files/Topics to a Project

When building a help file, HelpBuilder will only ever 'see' the files which have been included in your project. To add a topic to your project, select the Project/Edit menu option to obtain the Edit Project dialog. Double click on your topic file in the top list to move it into the bottom list. All the files shown in the bottom list are those which have been selected for inclusion in the project.

Having added the appropriate file(s), press the Ok button to save the list/project.

Please note that most of the technical support calls received about HelpBuilder are usually the result of a user not including a file in a project.

At this stage, you can now compile your help project using the Project/Build menu option. You can then view the created help file using the Project/Test menu option.

However, at this stage, you will only be able to reach your new topic via the Windows Help Search facility. You will want to create the 'green text' links...

Creating Jump Links to Topics

In order to make a help file 'useful' it is a good idea to place references to other topics and create 'hot spots' which cause jumps to those other topics. Typically, the main contents page is effectively a 'menu' to a number of other topics and contains such links.

To create a link to another topic, place the cursor at the position in your topic text where you wish the 'hot spot' to appear.

HelpBuilder supports two types of topic links (in future versions it will also provide support for macro links, program call links and jumps to other help files. All of which can be done now and are demonstrated in the sample project supplied): Jump links and Popup links. The first type is the most common and the second causes a 'popup' window to appear - this is how the copyright page produced by the Project Wizard appears.

Depending on the type of link required, select the Edit/Topic Link or Edit/Popup Link menu options. Both have their respective toolbar buttons. The Topic Link dialog will appear.

Enter the required text - this is the text which appears in green and underlined in Windows Help.

Press the down button on the Link Name field and select the context identifier of the topic to which you require the jump to occur. Note that this list only contains the values defined in your header files and those defined in each of the topics currently included in your project. Every identifier must have a unique numeric equivalent defined in the Context Identifiers dialog. If context identifiers are not defined, unresolved jump link errors will occur at compile time.

Press the Ok button to create the link in your topic. HelpBuilder automatically writes the appropriate RTF commands for you. To change a link, you can manually edit the RTF commands or highlight them including the leading and trailing curly braces and select the appropriate Edit menu option. The Topic Link dialog will appear with its fields already populated, ready for changing.

Having now created your link, you can compile the help project using the Project/Build menu option. You can then view the created help file using the Project/Test menu option.

The above process should be repeated for every topic and link you require to appear in your help file.

The Topic Locator Window

With large help files it is often helpful to have a list of all your topics to enable quick and easy access to them. The Topic Locator Window provides this facility. It also displays the Context IDs which have been assigned to all the topics.

Note that the Topic Locator Window only shows the topic files which are currently included in your project, therefore if an expected topic is not shown, it has not been included in the project and should be via the Edit Project dialog.

To open a specific topic for editing, simply double click on it.

The above should provide a good understanding of how to build a help file using HelpBuilder. If you have any further queries, it is suggested that you refer to the sample help project supplied with HelpBuilder since it demonstrates most of the features you are likely to want to build into a help file.


Save As Fail Error

This error occurs when an attempt is made to save a file using the name of a file which exists and is read-only or is already open by another application.

Solution: Specify another file name to use instead.


Selecting Text
How to select text

Many of the features provided by HelpBuilder require text to be highlighted within a topic file before a menu option or toolbar button is selected.

There are two ways of selecting text:

Using the mouse to 'swipe' the text

by holding the mouse button down

at the same time

Using the shift and cursor keys

Examples of features requiring text selection:

Text font

Text colour

Text bold

Text italic

Inserting topic links

Bitmaps

Cut

Copy

With the exception of the latter two features, all of the others above will write RTF statements in the topic text for you.

Example:

Insert a new topic jump link, then re-edit it to change it.

Firstly, position the caret in your topic text where you wish the link to appear.

Press the 'LINK' toolbar button.

Enter the text and link name required and press 'Ok' - the RTF text will now be written.

To change the link, you can manually edit it, but to change it automatically, highlight link just entered - by default it normally remains highlighted. You must highlight both sets of { } braces in order for the link dialog to pre-populate its fields correctly.

Press the 'LINK' toolbar button.

Make the required changes and press 'Ok' - the RTF text will now be changed.

The above procedure applies to all features which write RTF commands. You must select the whole RTF block from the start { brace to and including the end } brace.


Project Settings Dialog

Purpose

The Project Settings Dialog is used to set configuration information for the Help Project.

Available from

Project/Settings menu option

Comments

The Project Settings Dialog is divided into four sections. Each section may be obtained by selecting the appropriate item from the list on the left of the dialog. The sections are:

Caption/Copyright/Conts

Default Font/Colour

Compiler Options

Compiler Installation

Caption/Copyright/Conts

This section enables the user to change the Windows Help Caption, its Copyright message and the Context identifier of the contents page.

Project Caption

This is the text string which will appear in the caption of Windows Help when the Help file is in use.

Copyright

This is the text string which will appear in the Windows Help About box. You should place the team/developers name for copyright purposes here.

Contents Page Context String

Every topic within a help file is identified by a context ID. This may be a character string or more likely a constant defined in a header file.

The Contents Page Context String field should contain the context ID of the topic which will form the contents page for the help file when the help file first starts up. This topic effectively provides a menu of all the topics available within the help file.

Use the drop-down list box to select the required context ID.

Default Font/Colour

This section enables the user to change the global font and foreground colour used in a help file.

Default Text Font

This specifies the default font to be used throughout a help file if no other font is specified.

Press the 'Change Font' button to obtain the Font Dialog to change the font.

Default Text Colour

This specifies the default text foreground colour to be used throughout a help file if no other colour is specified.

Compiler Options

The help compiler program enables a number of settings and switches. This section enables these to be selected.

Optimise

Specifies whether the help file should be optimised for use on a CD ROM.

Report

Specifies whether a report should be generated by the Windows Help Compiler during the compilation process.

It is recommended that this is selected.

Compress

Specifies whether the help file should be compressed. This increases compile time, but reduces the .HLP file size.

Warning Error Level

This field determines the level of error reporting required when the Windows Help compiler is compiling the file. Level 1 is the minimum and level 3 is the maximum level and is also the default supplied by HelpBuilder when a project is created.

It is recommended that level 3 is used.

Compiler Installation

This section enables the user to install help compiler programs for use by HelpBuilder and to select the compiler to use.

Active Compiler

This displays the currently active compiler which will be used to compile the currently open project and any new projects which you might create.

Each HelpBuilder project file has the compiler required to compile it encoded within it. This eases portability of projects between different machines.

If you attempt to compile a project which specifies a compiler which you do not have installed, a compile error will occur.

Installed Compilers

This list displays all compilers which are currently installed on this machine.

To add more compilers, press the Install button and select the required file from the Install Compiler Dialog.

To delete a compiler from the list, highlight it in the list and press the Delete key or the Delete button.

To activate a compiler for the current project and subsequent new projects, either double click on it in the list or highlight it in the list and press the Activate button.


Inserting Special Characters
How to insert special characters

The Windows help complier recognises certain characters as being special compilation control characters.

If you wish to place these characters in your text to appear for normal usage, you must insert them using an their appropriate HEX Code Sequence:

Char	Sequence	Character

{	\'7B	Left curly brace

}	\'7D	Right curly brace

\	\\	Back slash


Suggestions for Use

The HelpBuilder application may be used to create Windows Help files for a variety of different purposes.

Here are some suggested uses for the HelpBuilder product:

Application Help files

Function library documentation

Conversion of Norton Guides files to Windows

Information distribution

General documentation

Advertising


Terminology
Terminology used throught this help file

Browse Sequence

This is a sequence of topics which have been grouped together, usually because they relate to the same subject, for example all topics relating to Opening/Saving/Creating files may be placed in a browse sequence.

To view the sequence the user presses the Browse buttons at the top of the Windows Help main window.

See Topic Links Dialog for more information.

Topic

A topic is a single page of information displayed by the Windows Help system, for example a contents page. Normally it will display information about one subject.

Within HelpBuilder each topic is held in a separate file which may be opened/saved from the File menu.

HelpBuilder maintains each topic file separately in order that you can share standard topic pages between different help projects.

Topic Title

Every topic has a title. This is the text string which appears in the Windows Help Search dialog when the topic is selected.

See Topic Links Dialog for more information.

Context String or Context ID

This is a unique string of characters which identifies a topic and is used by Windows Help to link topics together.

It may be a number or a character string. It is normal to use a #defined value in a .H header file. This can then be used by both an application and the help project.

See Topic Links Dialog for more information.

Colour Table

A colour table is an array of values informing the Windows Help compiler about all of the colours you wish to use in your project.

The colour table appears at the begining of all RTF files.

HelpBuilder maintains the colour table for you automatically whenever you select the Text/Colour menu option to choose a colour. If you manually type RTF commands to set colours, the colour table will not be maintained for you - this is why you should use the menu option to select colours.

However, the following default colours are provided by HelpBuilder:

Colour	RTF selection command

Black	\cf1

Blue	\cf2

Red	\cf3

Magenta	\cf4

Green	\cf5

Cyan	\cf6

Yellow	\cf7

White	\cf8

The default colour provided by HelpBuilder for help projects is black.

Font Table

A font table is an array of values informing the Windows Help compiler about all of the fonts you wish to use in your project.

The font table appears at the begining of all RTF files.

HelpBuilder maintains the font table for you automatically whenever you select the Text/Font menu option to choose a font. If you manually type RTF commands to set fonts, the font table will not be maintained for you - this is why you should use the menu option to select fonts.

The default font provided by HelpBuilder for help projects is MS Sans Serif. It is also the font Microsoft recommend to be used.


File Too Big to Load into Memory Error

This error occurs when the user has attempted to open a Topic file which is larger than the HelpBuilder limit for a Topic file - 32K.


Too Many Files Error

HelpBuilder has a limit of 25 files per project for unregistered shareware versions and 2048 files per project for registered versions.

This error occurs when the user has attempted to exceed this limit by adding more files.


Too Many Colours Error

HelpBuilder has a limit of 32 colours per project.

This error occurs when the user has attempted to exceed this limit by selecting colours from the Color Dialog.


Too Many Fonts Error

HelpBuilder has a limit of 32 fonts per project.

This error occurs when the user has attempted to exceed this limit by selecting fonts from the Font Dialog.


Too Many Windows Error

The number of topic windows which can be open at any one time is governed by the amount of memory available.

This error occurs when the user has attempted to create more topic windows than memory can contain.


Too Many Windows Defined Error

The number of windows which can be defined is limited to 32.

This error occurs when the user has attempted to save another window definition in the Project Windows Dialog when 32 windows have already been defined. This error message signifies that an attempt is being made to exceed the limit.


Topic Text Macros

HelpBuilder recognises a limited set of macros placed in topic text and replaces them accordingly:

$APPCOPYRIGHT$

This macro will be replaced by the copyright string of the HelpBuilder application, for example:

Copyright 1993, 1994 Graham Plowman

$APPNAME$

This macro is replaced with the application name:

HelpBuilder

$COPYRIGHT$

This macro is replaced with the Copyright string defined in the Project Settings Dialog

$DATE$

This macro is replaced with the current date, for example:

23/11/94

This macro can be used to show when a help file was built.

The date is in the UK or US format depending on your Windows configuration.

$TIME$

This macro is replaced with the current time, for example:

09:20p

This macro can be used to show when a help file was built.

$TOPICDATE$

This macro is replaced with the date of the topic file within which the macro exists, for example:

23/11/94

This macro can be used within a topic file to show when that topic was last changed.

The date is in the UK or US format depending on your Windows configuration.

$TOPICTIME$

This macro is replaced with the time of the topic file within which the macro exists, for example:

09:20a

This macro can be used within a topic file to show when that topic was last changed.

$TITLE$

This macro is replaced with the Windows Help Caption string defined in the Project Settings Dialog

$VERNO$

This macro is replaced with the version number of HelpBuilder, for example:

1.07

Note that text macros have nothing to do with the project macros defined in the Project Macros Dialog.


Unrecognised Project ID Error

HelpBuilder project files have a file identifier encoded in them.

An attempt has been made to open a project file which has an unrecognised file identifier. This means that HelpBuilder does not recognise the selected file as a HelpBuilder project file.

You should select another file or if the file really was a project file, it has probably become corrupted, in which case you should recreate the project using HelpBuilder.


Unrecognised Project Version Error

HelpBuilder project files have a file version number encoded in them in order that future versions of HelpBuilder can recognise files for upgrade/conversion purposes.

An attempt has been made to open a project file which has an unrecognised version number. HelpBuilder should only give this error when an attempt is made to open a file which is not a project file, but just happens to have the correct file identifier - a rare situation.

HelpBuilder recognises all previous file versions (although not forward versions) and automatically converts them to the latest format for the program release when they are saved. This will make files non-backward compatible.


Unrecognised Topic ID Error

HelpBuilder topic information files (.TNF) have a file identifier encoded in them.

Each topic information file refers to a topic text file of the same name, but ending in .TXT. When a topic has its link information changed, the link information is saved in the information file.

An attempt has been made to open a topic file which has an unrecognised file identifier in the information file. This means that HelpBuilder does not recognise the selected file as a HelpBuilder topic information file.

You should select another file or if the file really was a topic file, it has probably become corrupted, in which case you should delete the .TNF file since it will automatically be recreated next time you save the associated topic.


Unrecognised Topic Version Error

HelpBuilder topic information files (.TNF) have a file version number encoded in them in order that future versions of HelpBuilder can recognise files for upgrade/conversion purposes.

An attempt has been made to open a topic file which has an unrecognised version number. HelpBuilder should only give this error when an attempt is made to open a file which is not a topic file, but just happens to have the correct file identifier - a rare situation.

HelpBuilder recognises all previous file versions (although not forward versions) and automatically converts them to the latest format for the program release when they are saved. This will make files non-backward compatible.


Update Context Identifier Confirmation

This confirmation occurs when the user has attempted to add a new Context Identifier definition and the Identifier already exists in the Context Identifier listbox.

Select 'Yes' if you wish to proceed to modify the existing definition to the new definition.

Select 'No' to stop and not add the new identifier.


Project Wizard - File Exists

While using the help file Wizard to create a new help file, the Wizard has identified that some of the component files which it is about to create already exist and may be overwritten.

You may select whether you wish the existing files to be overwritten or not.

Possible causes

An attempt to create a new project in the same directory as another project.


Default Project Files Dialog

Purpose

The Default Project Files Dialog enables the user to specify the file names of the default project component files. This enables more than one project to be created in the same directory using the Project Wizard.

Available from

Ok button of the New Project dialog

Comments

The dialog contains the following fields:

Contents Topic File

This is the name of the topic file which will be used as the contents page for the project

Copyright Topic File

This is the name of the topic file which will be used as the copyright page for the project

Header File

This is the name of the topic file which will be used as the header file for the project

Icon File

This is the name of the topic file which will be used as the icon file for the project

Import Norton Guides Project

This field is used to specify whether a project is to be created by the Wizard from an existing Norton Guides or Expert Help project. Place a check in this field if you wish to import such a project. When you press Ok in this dialog the Import Norton Guides Project dialog will appear to request the name of the main Norton Guides/Expert Help project link file.

Each file specified above will be created in the same directory as that selected for the project.

Press the Browse button to obtain the Browse dialog to navigate your disk(s) for files/names.

Press the Ok button to proceed to create the project using the Wizard, or press Cancel to stop further creation of the new project.


Contacting the Author

Graham Plowman can be contacted by post at the following address:

PO Box 1124, Manly 2095, NSW, Australia

Graham can also be contacted on Compuserve ID: 100105,536


Integrity Check
Integrity Checking

This application has an automatic self-checking feature to advise of corruption to the executeable file.

The main purpose of this is to enable the program to identify whether it has been interfered with, either by a binary file editor or a computer virus.

Note that attempts to change icons and messages etc using products such as App Studio or Resource Workshop will render this application unuseable since they will cause a failure of the check.

If the application executeable is corrupted in any way, the following message will appear:

Integrity Check Violation Error: Integrity has been violated!

If this message does appear, you should re-install this application after checking the reason for it occuring.

Note that all of the author's software is Virus Checked before it is distributed.

Other integrity-related messages are possible. If you need assistance, please contact the author, either directly of via Compuserve ID: 100105,536.


Price List

Price List for Software

Graham Plowman, PO Box 1124, Manly 2095, NSW, AUSTRALIA or

'Fiddlers Rest', Gaveston Hall Drive, Nuthurst, Horsham, West Sussex, RH13 6RG, ENGLAND

Prod                                                            CIS      CIS      CIS     CIS

No      Product                              Price    Price    Price   Shipping  Total   SWREG

                                              AU$      UK£      US$      US$      US$     ID

#00     HelpBuilder                          $70.00   £35.00   $55.00   $10.00   $65.00  #4152

        HelpBuilder Upgrade                  $35.00   £15.00   $24.00    $4.50   $28.50  #5193

        HelpBuilder User Manual              $15.00    £7.00   $10.00    $8.00   $18.00  #5401

#01     Setup Builder                        $70.00   £35.00   $55.00   $10.00   $65.00  #4153

        Setup Builder Upgrade                $35.00   £15.00   $24.00    $4.50   $28.50  #5194

#02     Library Manager Basic Registration  $190.00   £90.00  $140.00   $25.00  $165.00  #4652

        Library Manager Upgrade              $95.00   £45.00   $70.00   $13.00   $83.00  #5195

        Library Manager Extra User License   $84.00   £40.00   $64.00   $12.00   $76.00  #5152

        Postage (orders received by post)

        Per disk                             $10.00    £5.00

        Per manual                           $10.00    £5.00

        Any number of extra user licenses     $5.00    £2.50

All mail orders must be paid by cheque or bankers draft, made out in Australian Dollars and drawn on an Australian bank or in UK Pounds Sterling drawn on a British bank.

Postage is only applicable to mail orders. Payments/orders made by post will receive a disk containing the requested software. Unless you state otherwise, it will be assumed that 3 1/2 inch disks are to be sent. The postage charge is applicable per disk ordered. Where a postal order is only for extra user licenses for already registered software, the extra license postage charge applies for the whole order. For Library Manager please state the number of user licenses you have and how many are required: the license number is based on the total number of users.

Payments may also be made via the Compuserve SWREG (GO SWREG) facility (Register Shareware option).

If payment is made via Compuserve you will receive an acknowledgement via E-Mail, a license number and unlimited time useage permission.

All registrations receive free technical support.

Prices are correct as at 26/09/95. All prices and specifications are subject to change without notice. E.& O.E.


Other Products Available
Products Available from the Same Author

The following products are all available from the same author:

Help Builder

HelpBuilder is a Microsoft Windows 3.1 application for creating and maintaining Windows Help files and is aimed at developers wishing to create Windows Help files to distribute with their products.

This help file was created using Help Builder.

The application is not an 'add-on' to a commercially available word processor, rather, a Multiple Document Interface (MDI) application integrated with the Microsoft HC31.EXE help compiler (or equivalent compatible eg HCP.EXE)(HelpBuilder is configureable). Since it is likely that anyone using this product is likely to be an applications developer using Visual Basic, Microsoft C/C++ or Borland C++ they will already have HC31.EXE as it is supplied with these products.

HelpBuilder does not 'shell' out to DOS to compile files but provides a complete integrated Windows hosted compilation process.

Windows Help and Help Compiler Features Supported

 Topic pages

 Links and 'popup' windows to other topics, including optional 'picture hotspots', macros and 'windows'

 Browse sequence support

 Ability to place bitmaps in help files

 Fonts, colours, bold and italic text

 Header files

 Context identifiers

 Locking of and changing colour of top of Windows Help page

 Start up macros

 Changing of 'locked' and client 'area' colours in Windows Help

 Compiler configuration - warning levels, CD ROM, compression etc

 Configuration of 'windows'

Product Features

 Full keyword support

 Projects to group individual topic files for a specific application

 Topics held in separate files in order that they may be shared between projects

 Toolbar selection of many facilities and status bars

 Error checking on project building

 Self-checking executeable - to detect corruption/tampering eg Virus

 Project Wizard to create a basic project

 Application Installation and De-installation procedure

 Printing of topics and projects

 Fully integrated and context sensitive Windows Help file including 'How to..' section

 Can create Help files for VB, C/C++, PowerBuilder etc - any language supporting Windows Help and passing of context numbers

 Ability to insert RTF commands

 Network locking on project and topic files

 Automatic creation of .HPJ and .RTF files

 Sample demonstration help file project

 Multi-tasking during compilation - no 'DOS' windows!

 Helpfiles 'testable' from within HelpBuilder

 Configurable compiler - via application .INI file

 Topic locator

 Importing of Norton Guides help projects

 In-built text macros

Setup Builder

Setup Builder is a Windows 3.1 application for creating and maintaining Windows Hosted installation procedures and is aimed at developers who wish to provide that 'professional' touch to the installation of their software.

The installation procedure for this piece of software was created using Setup Builder.

The interpreter part of the product can also be used to run Windows Hosted DOS-like batch files using the script language supported.

Forget about distributing Microsoft's 0.5 Mb offering just to install a 100-200K executable! This product uses about 160K of diskette space and is highly tailorable and doesn't require the user to get involved with C/C++ or Visual Basic in order to create install disks.

Setup Builder Application Features

 Setup projects to which files can be added/removed

 Automatic creation of installation disks, requesting extra disks

as required

 Automatic splitting of large files across diskettes (including compressed files)

 Automatic creation of install script code

 Ability for user to place 'user-defined' code in install procedure if required

 Windows hosted with toolbar and status bar

 All files can have attributes set: target location, overwrite checks, in use checks, file compression (requires MS COMPRESS.EXE), create program manager icons etc

 Ability to create program manager groups

 Up to 500 files in an installation

 Optional encription of install scripts (so that users can't change them)

 Context sensitive, comprehensive Windows Help file

 Network locking on project files

 Visual Basic .MAK project import facility

Interpreter Supported Features (this is placed on install disks to 'run' install procedures)

 Script language (similar to DOS batch files) supporting if and goto statements, string and numeric variables

 Windows extensions - predefined dialogs (user definedable text), message boxes, creation of program manager icons/groups and ability to delete them

 User defined dialogs with controls

 Comprehensive Windows Help file

 String and numeric manipulation (left, right, mid, +, -, *, /)

 Copying of files

 Backdrop bitmaps during installation

 Optional fuel gauge during copying

 Date and time functions

 DOS file management - create/delete/renaming of directories, disk space and file presence/overwrite/version checks

 Windows .INI file management

 File management - create/delete/renaming/copying/date & time setting, reading and writing of ASCII files

Library Manager

Library Manager is a Windows 3.1 version control system for management of software source files and configuration management. It provides all the basic functionality expected of a VCS. Ease of use and simplicity were major design criteria.

The source code for this application is managed using Library Manager.

Library Manager is better than many commercially available Version Control Systems!

Library Manager Features

 MDI User interface displaying current status of all files in a project for ease of use

 Security system to which developers access rights can be configured

 Grouping of files into projects

 Unique use of databases which only records changes to files

 Centralised repository - does not 'protect' a directory like other products which can be 'by-passed' in DOS!

 Project templates - allows grouping of files so that specific versions of an application can be recreated. Also enables files to be grouped within an application, for example, all the files belonging to a particular sub-system

 Binary and Ascii files (configureable by file type)

 Back versions - of both ASCII and binary files

 File change comments

 Reports (change comment history, headers, booked files etc) and printing

 File viewing with no need to book/copy out

 Network aware/locking - any number of users (subject to license)

 Multi-tasking - so you can do other things while booking is in progress!

Assistance/Further Information

If you require any assistance or further information on any of my products, I can be contacted at the address in the Contacting the Author section of this help file.

Graham Plowman


What is Shareware ?

Definition of Shareware

Shareware distribution gives users a chance to try software before buying it. If you try a Shareware program and continue using it, you are expected to register. Individual programs differ on details: some request registration while others require it, some specify a maximum trial period. With registration, you get anything from the simple right to continue using the software to an updated program with printed manual.

Copyright laws apply to both Shareware and commercial software, and the copyright holder retains all rights. Shareware authors are accomplished programmers, just like commercial authors, and the programs are of comparable quality. (In both cases, there are good programs and bad ones!) The main difference is in the method of distribution. The author specifically grants the right to copy and distribute the software, either to all and sundry or to a specific group. For example, some authors require written permission before a commercial disk vendor may copy their Shareware.

Shareware is a distribution method, not a type of software. You should find software that suits your needs and pocketbook, whether it's commercial or Shareware. The Shareware system makes fitting your needs easier, because you can try before you buy.

And because the overhead is low, prices are low also. Shareware has the ultimate money-back guarantee: if you don't use the product or it doesn't do what you want it to do or you don't like it, then you don't pay for it.

Disclaimer and Agreement

Users of this software must accept this disclaimer of warranty:

"This software is supplied as is.  The author disclaims all warranties, expressed or implied, including, without limitation, the warranties of merchantability and of fitness for any purpose.

The author assumes no liability for damages, direct or consequential, which may result from the use of this software."

This software is a "shareware program" and is provided at no charge to the user for evaluation.  Feel free to share it with your friends, but please do not give it away altered or as part of another system.  The essence of "user-supported" software is to provide personal computer users with quality software without high prices, and yet to provide incentive for programmers to continue to develop new products.  If you find this program useful and you wish to continue to use it after a reasonable trial period, you must make a registration payment. The registration fee will license one copy for use on any one computer at any one time.  You must treat this software just like a book.  An example is that this software may be used by any number of people and may be freely moved from one computer location to another, so long as there is no possibility of it being used at one location while it's being used at another.

Just as a book cannot be read by two different people at the same time.

Commercial users of this software must register and pay for their copies within 30 days of first use or their license is withdrawn.  Site-License arrangements may be made by contacting the author.

Anyone distributing this software for any kind of remuneration must first contact the author for authorisation.

In this way the distributor can be kept up-to-date with the latest version of this software.

You are encouraged to pass a copy of this software to your friends for evaluation.  Please encourage them to register their copy if they find that they can use it.  All registered users will receive a copy of the latest version of this program, a license number, free technical support and notifications of upgrades.

It is a condition of registration that you accept that you have fully tried and tested this software and found that it meets your requirements to your satisfaction. Please note that once a license number has been given, no refund will be possible.

Graham Plowman