Help Files

What is a HelpFile ?

Who needs HelpFiles ?

Advantages

Compilers

Standardization

How to build a HelpFile


What is a Help File

Help File is a HyperText Document
Help File is more like HTML
Help File Contains:
Simple text
Images
Links
Popups


Who Needs Help Files ?

Help Files can be very User Un Friendly.

It is difficulty to find  specific information
Links can get you inside a  maze
a lack of information

Some users prefer to open the manual book read it
and learn all they need about the software,
        When they want to find  a certain topic they open
        the book with the index.

Very Hard To build
build HelpFiles, with the old version of help                 compilers ,you need to be expert in the syntax


Advantages

Online Help -
Just press F1 and get a simple tutorial
Case Sensitive Help


Compilers

In this tutorial, I will present just the PC 80x86 support.
Windows 3.1 HC.EXE
Windows 95  HC31.EXE
are the Help compilers provided by Microsoft

Windows 3.1 and Win95 help compilers (HCx) require a Rich Text Format (RTF) file format,
locking you into using a word processor or text editor that supports the RTF specification, e.g MS Word.


Standardization

The standard that will be presented is the Microsoft standard for building and displaying a help file.
The tools that are required at each machine are:
RTF Editor
Microsoft Help Compiler
WinHelp.EXE


How To Build HelpFile

How To Build a Topic

How To Build RTF File

How To Build  a project File

How To Generate a HelpFile


How To Build a Topic

1. First give a name to the topic
        #Main
that will be encoded as rtf format to
#{footnote Main\}.
where Main is usually  the name of the topic of the
first page that will be presented.

2. Write the text you want to present at
this topic.
leaving spaces for links and Popups.


How To Build RTF File

At some time or another, every Windows-application developer has to generate help files. However,
the standard method of generating Windows help files is tedious and complicated, requiring
nonintuitive commands that give little indication of the actual function they represent. For example,
$\footnote creates a topic title.

Furthermore, the Windows 3.1 and Win95 help compilers (HCx) require a Rich Text Format (RTF) file format,
locking you into using a word processor or text editor that supports the RTF specification.

This process is further complicated by the fact that the resulting RTF file can only be understood by an
expert in Windows HelpFile generation. Many of the Windows HelpFile specification's commands are
buried in footnotes that are difficult to associate to the text they are generated from.

In this short tutorial I will present some features of RTF very generally just to help us get the concept of
Rich Text Format that is a code to produce a HyperText Document .

Remember the spaces we have left for links and Popups?
now let's fill them:
The special structure of a help file contains links to other topics those links are HOTSPOTs
because when one clicks the mouse on such a hotspot (that looks like simple text).
The viewer presents the topic that is linked to that hot spot.
This action can be encoded in RTF - by telling the viewer that a certain text item
is a hot spot and the topic to jump to. ( this topic can even be in a different file).

Who needs HelpFiles ?
* Whoneeds>Main

        Remember this topic at the main page? Well if you try to view the RTF file in a RTF viewer
you will see that this link jump to the topic Whoneeds.
       Its RTF code is:

_pard\plain{\b\cf2\f4\fs20\li100\ql\ri100\sa20\sb20
{\uldb Who needs FelpFiles ? \line }
{\v * Whoneeds>Main}} \par

Another  kind of HOTSPOTS are Popups - the origin help page stays in its place and another help page appears on top of it but doesn't concealing it.
The main propose of Popups is to give Tips or small explanation.
this action can be encoded in RTF - by telling the viewer that a certain text
is a hot spot and which topic to popup . ( this topic can even be in a different file).

What is HelpFile ?
* Whatis

        remember this topic at the main page? Well if you try to view the RTF file in a RTF viewer
you will see that this popup shows the topic Whatis.
        Its RTF code is:

pard\plain{\b\cf5\f4\fs20\li100\ql\ri100\sa20\sb20
{\ ul What is HelpFile ?\line}
{\v * Whatis}}\par

In some cases a programmer wants to give a specific explanation on a certain icon that appears in a form,
or to allow the user that reads the help file to see how the form reacts when an icon is pressed.
RTF allows you to link an icon to a topic

 Click this icon in order to see the Driver's Form

{\bml DRIVER~1.BMP}Form>Main Click this icon in order to see the Driver's Form

Click Here To get Help on This Button

{\bml DRIVER~1.BMP}ThisDoesClick Here To get Help on This Button


This Button loads the driver's form


How To Build  a project File

Now You have reach the stage of building a project file that wraps up the topics, rtf documents, bmp files.
The major contents of a project file are:

1. Options - How to compile the project

2. Files      - In which files the topics are placed

3. Bitmaps - The path to the bitmaps files

4. Map       - The serial number each topic gets

click here to see what our project file looks like


Options

[OPTIONS] section

[OPTIONS]
option

The [OPTIONS] section includes options that control how a Help file is compiled and what feedback the compilation process displays. This section, along with the [FILES] section, is required in all project (.hpj) files. This section should be placed first in the project file so that the options apply during the entire compilation process.

Parameter	Description

option	Specifies one or more of the following project-file options.

Option	Description

BMROOT	Specifies the folder that contains the bitmap files named in {bmc}, {bml}, and {bmr} references in the topic                             (.rtf) files.
                        BMROOT

                        BMROOT=pathname

                        You specify the BMROOT option in the [OPTIONS] section of the project (.hpj) file. BMROOT provides                        Help Workshop with information about where to find the graphics files specified in the source files.
                       By default, Help Workshop searches for graphics files in the same folder as the project file, then in the                        same folder as the .rtf file that specified the graphics, and then in all folders specified by the ROOT option.                        The BMROOT option is necessary only if graphics files are not in one of these locations.

                        You can specify any number of BMROOT options.

BUILD	Determines which topics to include in the build.

COMPRESS	Specifies how the Help file should be compressed.

CONTENTS	Specifies the default topic ID.

CONTENTS=topic-id
You specify the CONTENTS option in the [OPTIONS] section of the project (.hpj) file. CONTENTS identifies the topic 	ID of the default topic.WinHelp displays this topic by default if it encounters a broken jump or the associated contents 	file is missing.
Note

·	If the [OPTIONS] section does not specify a default topic, Help Workshop uses the first topic in the first topic (.rtf) file 	that is listed in the [FILES] section of the project file.

COPYRIGHT	Adds a unique copyright message for the Help file to WinHelp's Version dialog box.

HLP	Specifies the name of the Help (.hlp) file to create.
HLP=help-file
You specify the HLP option in the [OPTIONS] section of the project (.hpj) file. HLP identifies the name of the Help 	(.hlp) file to compile.
Comments
If the [OPTIONS] section does not include an HLP option, Help Workshop creates an .hlp file that has the same 	filename as the current project file.

LCID	Specifies the language of the Help file.

MAPFONTSIZE	Maps a font size in the topic file to a different font size in the compiled Help file

NOTES	Specifies whether Help Workshop should display notes.
NOTES=[0 | 1 | yes | no]
You specify the NOTES option in the [OPTIONS] section of the project (.hpj) file. NOTES specifies whether Help 	Workshop should display notes while compiling the Help file. Notes are messages Help Workshop displays when it 	encounters problems that may or may not adversely affect your Help file.

Most of these options can appear in any order within the [OPTIONS] section. If used, the REPLACE option must come before the ROOT or BMROOT options.


MapFontSize

MAPFONTSIZE=m[-n]:p

You specify the MAPFONTSIZE option in the [OPTIONS] section of the project (.hpj) file. MAPFONTSIZE maps the font sizes specified in topic (.rtf) files to different sizes when they are displayed in the Help window. You can use one font size in your topic files and have Help Workshop change the font so that it is a different size when the Help topic is displayed.
This option is especially useful if there is a significant size difference between the authoring display and the intended user display.

Parameter	Description

m[-n]	Specifies the size of the source font. This parameter is either a single point size or a range of point sizes, as indicated by the optional parameter n, which specifies a font range to be mapped. A range of point sizes consists of the low and high point sizes separated by a hyphen (-). If a range is specified, all fonts in the range are changed to the size specified by the p parameter.
p	Specifies the size of the desired font for the Help file.

Comment

Although you can specify as many as five font ranges in the [OPTIONS] section of the project file, you can map only one font size or range with each MAPFONTSIZE statement. If you include more than one MAPFONTSIZE statement, the source font size or range that is specified in subsequent statements cannot overlap previous mappings.

Examples

The following example illustrates a correct use of the MAPFONTSIZE option, using two statements, in a project file:

[OPTIONS]
MAPFONTSIZE=8:12            ; display all 8 pt. fonts as 12 pt.
MAPFONTSIZE=12-24:16     ; display fonts from 12 to 24 pts. as 16 pt.

The following two statements show an incorrect use of the MAPFONTSIZE option because the second statement contains a point size already mapped in the preceding statement (14 falls in the 12-24 range):

[OPTIONS]
MAPFONTSIZE=12-24:16
MAPFONTSIZE=14:20


Files

[FILES] section

[FILES]
filename

The [FILES] section lists all topic (.rtf) files used to create the Help file. A Help project (.hpj) file must have a [FILES] section.

Comments

You can create an ASCII text file that contains a list of the topic files you want to include in a build, and then use the #include statement in the [FILES] section to specify the ASCII file.
The #include statement has the following syntax:

#include filename

The filename must reside in the Help project folder, or must specify a complete path. Help Workshop does not use the INCLUDE environment variable to search for files.
Help Workshop searches for files in the project folder, in the path (if any) specified for the file, and in all folders specified by ROOT options in the [OPTIONS] section of the project file.


Bitmaps

[BITMAPS] section

[BITMAPS]
filename.bmp

This section is obsolete and is maintained for backwards compatibility only. New projects should use the Bitmaps button in Help Workshop which defines one or more BMROOT statements.


Map

[MAP] section

[MAP]
topic-id          numeric value

The [MAP] section associates topic IDs (or aliases) with context numbers for context-sensitive Help. The context number corresponds to a value the parent program passes to WinHelp to display a particular topic.

Parameter	Description

topic-id	Specifies the topic ID of a topic in the Help file. The ID can be any combination of characters, except spaces, and must also be specified in a topic ID footnote (#) in some topic in the Help file.
numeric value	Specifies the context number to associate with the topic ID. The number can be in either decimal or standard C hexadecimal format.


Our Project File

[Options]
Compress=No
Contents=Main
OldKeyPhrase=No
Title=Help Files Tutorial
Warning=1
BMROOT = .
[Files]
d:\help\seminar\main.rtf

[BuildTags]

[Config]

[Bitmaps]
D:\HELP\SEMINAR\DRIVER~1.BMP
D:\HELP\SEMINAR\DRIVER.BMP

[Map]
Main 1
Whatis 2
Whoneeds 3
Advantages 4
Compilers 5
Standardization 6
Howto 7
HowToBuildaTopic 8
HowToBuildRTFFile 9
Form 10
ThisDoes 11
HowToBuildaprojectFile 12
Options 13
MapFontSize 14
Files 15
Bitmaps 16
Map 17

[Alias]

[Windows]
ZZZZZZZZ="",(0,0,350,623),0,(255,255,255),(192,192,192), 0

[Baggage]


How To Generate a Help File

You have reached the final stage of building a help file now you already have a rtf document and a project all you need to do is to compile them and to generate a windows help file.

The compilation is very simple just write to the prompt, the command :

Hc31.EXE  Main.hpj

If nothing is wrong with your project you will get a windows help file that you can display with the command:
Winhelp32.EXE Main.Hlp


Click This Icon To Exit The Editor


Click This To Go To Write Mode


Click Here To Go To Delete Mode


Click Here To Go To Mail Sender


Click Here To Save Text


Click Here To Open a File


Click Here To Print Document


Click Here To Undo Changes


Click Here To Redo Changes


Click Here To Get Help