#Help Files 

What is HelpFile ?

Who needs HelpFiles ?

Advantages

Compilers

Standardization

How to build a HelpFile

#What is Help File 

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

#Who Needs Help Files ? 

Help Files can be very UN User 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
{bml DRIVER~1.BMP} 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
{bml DRIVER~1.BMP}Click Here To get Help on This Button
{\bml DRIVER~1.BMP}ThisDoesClick Here To get Help on This Button

#{bml DRIVER.BMP}

#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