Overview

HTML Help is a new standard in Help files introduced by Microsoft and endorsed by many leading industry help vendors. HTML Help offers the possibility of easier assembly of Help files, using the familiar HTML document standards. HTML Help can integrate programmed routines written in JavaScript or VBScript, as well as links to technical support Web sites. In this session, we'll examine the basics of HTML Help, how it can be generated from Visual FoxPro 6.0, and how to link an HTML Help file into your application

Why HTML Help?

Using HTML (Hypertext Markup Language) as the basis for Help, and other multimedia, presentations has been discussed at various help and authoring conferences for several years. A number of vendors including Microsoft, Sun and Netscape have each proposed designs for systems. With the release of HTML Help 1.0 and 1.1 last year, and the expected and much anticipated release of versions 1.2 and 2.0, Microsoft has taken a strong lead in delivering the next generation of online help software. Rumors abound that Microsoft has devoted considerable resources to this project, combining the WinHelp and MediaView groups. Microsoft's Internet Explorer 4.0 shipped with HTML Help, and it is expected that most if not all products shipped from Microsoft will include HTML Help. Visual Studio 6.0 is no exception.

Conventional Windows 3.1 Help, no doubt soon to be deemed "classical" help and within a few more Internet minutes "legacy" help files, were challenging to write, limited in extensibility and viewable only through proprietary viewers. The Rich Text Format (RTF) files used to generate the core material were difficult to produce and tended to be slightly different in each product used to make them. The internal macro language was very difficult to work with. Add-ons to the help product typically needed to be developed as DLLs, requiring sophisticated knowledge of relatively low-level languages and intimate understanding of the Windows API. HTML Help, on the other hand, offers the standards of HTML, the extensibility of the Internet Explorer object model, and the power and sophistication of cascading style sheets, DHTML, JavaScript, VBScript and more.

How does HTML Help Work?

HTML Help files are usually distributed as Compressed HTML files, with a CHM extension. The file is compiled and compressed using Microsoft's HTML Help compiler, HHC.EXE, which is distributed as part of the free Microsoft HTML Help Workshop, downloadable from Microsoft at http://www.microsoft.com/workshop/author/htmlhelp and installed as part of Visual Studio 6.0. Rather than compiling all of our help from the command line, Microsoft's Help Workshop ships with a GUI interface that allows completely graphical development of the project file, table of contents and index. It does not, however, provide a WYSIWYG interface for editing of HTML - in this regard, the Workshop is no better than Notepad. However, Microsoft and many third parties offer HTML Editing tools tuned for this purpose.

Neither HTML Workshop nor other third-party tools need to be used to create the help files. The only requirement is that a Help Project File is passed to the compiler and that tables of contents and indexes (if included) are in the Sitemap format. It is conceivable that a development organization might use the Workshop (or other third party product) to generate the basic shell of the files needed, and then create an automated process to update these files as software development continued, invoking the compiler as needed to generate test help files. Let's look at the construction of these files a little more closely.

The Help Project file is a plain ASCII text file, similar in format to Windows INI files. Major sections set the overall options for the project, identify the files to be included, and point to the associated Alias and Include files. A sample is shown below:

[OPTIONS]

Compatibility=1.1

Compiled file=hhtest.chm

Contents file=hhtest.hhc

Default topic=button.htm

Display compile progress=No

Index file=hhtest.hhk

Language=0x409 English (United States)

[FILES]

button.htm

form.htm

[ALIAS]

#include hhtest.ali

[MAP]

#include hhtest.h

Listing 1: The contents of the HHP Project File

The Index and Table of Content files are HTML files. They consist of a standard HTML header, and the main body. The body contains the individual line items which appear on the Index of Table of Content pages. Each item is a separate object tag. The heirarchy of the objects is maintained with the Unordered List (<UL> and </UL>) tags used in a nested fashion. Each object is set off by a List Item (<LI>) tag. A sample follows:

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">

<HTML>

<HEAD>

<meta name="GENERATOR" content="Microsoft® HTML Help Workshop 4.1">

</HEAD><BODY>

<OBJECT type="text/site properties">

<param name="ImageType" value="Folder">

</OBJECT>

<UL>

<LI> <OBJECT type="text/sitemap">

<param name="Name" value="Top Heading">

</OBJECT>

<UL>

<LI> <OBJECT type="text/sitemap">

<param name="Name" value="Form Help">

<param name="Local" value="form.htm">

</OBJECT>

<LI> <OBJECT type="text/sitemap">

<param name="Name" value="Button Help">

<param name="Local" value="button.htm">

</OBJECT>

</UL>

</BODY></HTML>

Listing 2: A typical Table of Contents file

Display Options

HTML Help can be used in a variety of ways. For example, you may use some of the HTML files as part of your web site to show portions of the help file or to provide support for commonly asked questions. These same HTML files can be incorporated into the CHM (compressed HTML) file that makes up the common point of access. This CHM file can be viewed with HTML Help's native viewer, HH.EXE. Alternatively, an enterprising develop could create their own viewer, as was done with the magnificent HTML Reference Library - a completely customized viewer that reads the CHM format.

Creating a Web site using HTML Help

You can also use HTML Help's source documents as well as the table of contents and index data to generate a web site matching the HTML Help file. This can be useful as a demonstration of the documentation provided with your product, or as a means to update users as new information is available. A typical HTML Help web site is shown in Figure 1.

Figure 1: HTML Help files can also provide information via the web.

The typical HTML Help Web site is composed of several frames. To closely imitate the HTML Help viewer, the left frame contains the HTML Help ActiveX control, HHCtrl.OCX and the right pane contains the topic HTML files. In order to get the topics to display in the right pane, a single attribute, cleverly called "Frame:" of the table of contents and index must be changed to the name of the right pane.

The Main.HTML file sets the scene by defining the two frames and their contents:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">

<HTML>

<HEAD><TITLE>Introduction to HTML Help</TITLE></HEAD>

<FRAMESET COLS="220,100%">

<FRAME SRC="HH_TOC.html" name="left" scrolling="no">

<FRAME SRC="sld001.htm" name="Right" scrolling="yes">

</FRAMESET></HTML>

Listing 3: MAIN.HTML defines the two frames where the action takes place.

The HH_TOC.HTML file embeds the HTML Help OCX in the frame and adds buttons to switch from the Table of Contents to the nearly identical Index page:

<HTML>

<BODY>

<TABLE>

<TR>

<TD><FORM ACTION=POST>

<INPUT TYPE=BUTTON VALUE="Contents"

ONCLICK="location = 'hh_toc.html';" NAME="Help Topics"></FORM></TD>

<TD><FORM ACTION=POST>

<INPUT TYPE=BUTTON VALUE="Index"

ONCLICK="location = 'hh_index.html';" NAME="Index"></FORM></TD>

</TR>

</TABLE>

<OBJECT

id = hhctrl

type = "application/x-oleobject"

classid="clsid:adb880a6-d8ff-11cf-9377-00aa003b7a11"

codebase = "hhctrl.ocx"

width=100%

height=80%

<PARAM name = "Command" value = "Contents">

<PARAM name = "Item1" value = "TOC.hhc">

</OBJECT>

</BODY>

</HTML>

Listing 4: HH_TOC.HTML hosts the HTML Help ActiveX control and displays the Table of Contents

A few notes on the table of contents page are in order. Note the CODEBASE attribute of the OCX object. This tells the client browser what file to request if the OCX is not available on the client's machine. Depending on the security settings of the client, they may or may not be able to install the OCX. Consider providing some alternative means of accessing the information if you anticipate clients with these issues.

Viewing HTML Help as a separate window within your application

Like "classic" WinHelp, HTML Help can be access via the F1 key and appear in a separate window on the desktop. This is supported natively in Visual FoxPro 6.0 by simply issue SET HELP TO {yourhelpfile}.CHM. Pressing F1 will pass the HelpContextID of the currently active control to the help engine and displaying the appropriate help topic. As with the older HLP and DBF forms of help, you may want to use an ON KEY LABEL F1 command to control how help is invoked.

This version of help uses HH.EXE, an included stand-alone viewer.

Viewing HTML Help within your forms

HTML Help offers this intriguing new capability unavailable in classic WinHelp. Since HTML Help can be viewed with a browser, and the browser is an ActiveX control that can be embedded within a VFP form, it is possible to use the browser control to display your help file within the form itself. See Figure 2 for an example of how this might work. This is a really powerful means of delivering, not only text, but richly formatted text, graphics and even applets within your forms. The rich object model really puts the feeble Rich Text control to shame, and should be considered anytime sophisticated graphics, text or scriptability is needed.

Figure 2: Unlike WinHelp, HTML Help can integrate directly into the application.

How to build an HTML Help File

Create your topics, using your choice of HTML authoring tool. Organize the topics as appropriate for your application, generating a table of contents (TOC) and an index file. The TOC and Index need to be in Microsoft's Sitemap format, the variant of HTML that supports a hierarchical list of links as described above. Again, these steps can be accomplished using Microsoft's Help Workshop, available for free download, or they can be created manually with a text editor or with a programming language like Visual FoxPro capable of text manipulation.

Compile these together using the HTML Help compiler supplied by Microsoft. The HHC.EXE can be called from a command line, as in

hhc "d:\Microsoft Visual Studio\MSDN98\98VS\1033\

samples\vfp98\solution\help\solution.hhp

but that solution gets old fast. The Microsoft HTML Help Workshop does a better job of allowing you to specify options for the compile interactively, rather than needing to specify all changes in the HHP file. In addition, the Workshop captures output into a log file, so that it can be viewed directly within the Workshop.

At one point, changes that were made to an Index or Table of Contents needed to be saved manually before compiling the project, or the older version on disk was used. I've been working with HTML Help on and off for 220 days, and I am not sure that I have ever compiled the help file twice with exactly the same combinations of DLL and EXE builds on my machine, so you will want to check out these sorts of issues for yourself.

Linking your application to your Help file

There are a number of different ways to link the materials in the Help file in to your applications. The simplest solution just runs the Help file, allowing it to display its default topic. The most complex solution gives you precise control over the display, though it takes more work. In most cases, developers can settle for a little less control with less overhead in the development process by selecting the second method below.

In some very small applications I have written, it is acceptable on the few screens of the application to have a help button that brings up the main, or perhaps the only help topic. Help of this nature can be invoked by calling the standalone viewer and passing the name of the file to be displayed, as in the example below.

RUN /N HH.EXE FoxHelp.CHM

The HH.EXE is normally installed directly into the Windows subdirectory as an integral part of the operating system, so there should be no pathing difficulties in locating and executing it.

The second technique for accessing the help files assumes that you need slightly better control. If you need context-specific help based upon the control with the focus, use this method. The mapping of controls to help topics involves two files, one storing "aliases" for the actual help topic files, and the second "include file" mapping the HelpContextIDs to these aliases. While this technique may seem awkward if you are a solo developer putting together an application and its help file, it really is a better technique for scaling up to multiple developers and dedicated help authoring professionals. Developers and help authors need to agree on the names of the aliases only. The authors can then change the names of the actual topics at will, as long as the alias mappings are updated. Similarly, the programmers change HelpContextIDs as needed, and update their include file to reflect these changes. This is an area where Visual FoxPro's Wizard and Builder technologies could play an important part - it is easy to envision Wizards and Builders supporting and automating this process.

HHTEST_FORM=form.htm

HHTEST_BUTTON=button.htm

Listing 5: An alias file matches constants, on the right, with matching topic names

#DEFINE HHTEST_FORM 123

#DEFINE HHTEST_BUTTON 456

Listing 6: The include file defines the HelpContextID values and matches them to constant names

Create an Include file that defines the match between alias and HelpContextID number for each of the controls in your system (see Listing 5). In addition, create the alias file, that matches each alias with its associated topic file name. These are each imported into the Help Project file as shown in Listing 1, or matched to the project using the Workshop interface and the HTMLHelp API Information dialog.

Finally, there will be some situations when nothing but complete control will do. In this case, using the HTML Help API is the way to go.

Hand-craft or use a Third-party tool?

While there may be advantages to rolling your own solution to HTML Help generation, that may not be the optimal solution for developers on a tight time as well as monetary budget. Fortunately, most of the major help vendors have developed add-ons or enhanced versions of their products to support the new HTML Help features.

Vendors include:

Blue Sky Software, makers of RoboHelp Office and RoboHTML

Eon Solutions Ltd, makes of EasyHelp/Web

ForeFront Incorporated, makes of ForeHelp and ForeHTML

Hyperact, Inc., makers of eAuthorHelp and eAuthorSite

SolutionSoft, Inc. makes Help Breeze and an HTML Wizard

WexTech, makers of Doc-To-Help and authors of the Microsoft Press book

When to make the switch?

The decision as to when to make the switch from legacy WinHelp to HTML Help format depends on your particular circumstances and needs. HTML Help is still in its infancy and newer revisions can be expected shortly. Like all revisions, there will probably be compromises of backward compatibility in order to support new features. Distribution of HTML Help is still somewhat problematic, as IE 4.0 needs to be installed on each client workstation (although not necessarily set as the default browser) in order to display HTML Help. Nearly all 3rd party Help Authoring Tools (HATs) have updated their product, or added additional utilities, in order to generate HTML Help.

Advanced uses of HTML Help

As mentioned above, Microsoft has thrown considerable resources at the HTML Help development project. Microsoft has put together a product that promises to go far and open up new opportunities for development and authoring.

HTML Help is a poorly chosen name for this technology, for while it does provide context-sensitive help for applications, it is not limited to that niche role. HTML Help could be more properly viewed as "organized web surfing" where related topics and materials can be joined together, cross-referenced and compiled into a portable format. I expect to see a number of uses for "HTML Help" outside the conventional Help usage. For an excellent example of a pioneering application in this field, check out the HTML Reference Library, written by Stephen Le Hunte and available at http://hot.virtual-pc.com/htmlib/. While this program appears to store its information in a CHM file, it has its own proprietary viewer and far different features than the default viewer. Numerous multimedia titles, taking advantage of the web browser capability to present graphics, combined with the powerful scripting capabilities and ability to host ActiveX controls promise to make this an exciting platform for authoring.

Another intriguing use of the HTML Help files is the ability to launch other programs. In the Solutions Sample help entry (available from VFP by typing DO HOME() + "VFP6STRT.APP" and selecting the second option from the screen), the help topic offers "Open" and "Run" options. Select the "View Source" option from the right-mouse menu to see how this is done: the HTML contains VBScript that uses the FPOLE functionality to call the Fox2Hlp program, which in turn actually runs the FoxPro session by KEYBOARD'ing the commands. A relatively simple example, this demonstrates that the HTML Help file is not a static display engine, but a fully programmable application with the ability to interact with other components.

There's still far more information and capabilities available than can be done justice in a set of speaker's notes. Check below for some ideas of where to look from here.

Where to find more information

The authoritative book on the subject is the Official Microsoft HTML Help Authoring Kit from Microsoft Press, ISBN 1-57231-603-9, written by Steve Wexler of WexTech. This 300-page book contains a great deal of background information, as well as examples of using HTML Help in many different situations.

Finally, the best place to learn web technologies is, not surprisingly, the Internet. There is one major newsgroup and a slew of useful sites:

Help University offers training in the various help systems and has an extensive online library of past papers and presentations.

HelpMaster has a tremendous collection of utilities, samples, freeware and demoware for both the HTML Help Windows Help authors.

Cambridge Publications, Inc. are the keepers of the WinHlp-L mailing list archive. There's quite good documentation on the site for how to join and work with the mailing list.

My own HTML Help site is available for conference attendees at http://www.bstone.com/users/troche/htmlhelp/main.html and contains updated material from this document and will continue to grow. The site uses an HTML Help ActiveX control, of course.

About the Author

Ted Roche shipped his first commercial software application in 1978. His first freeware contribution was a double-density Epson printer driver for the GEOS operating system hand-coded in 6502 assembler. He has written for numerous magazines and spoken at user groups and over a dozen professional conferences in four countries. Ted contributed to four books on FoxPro 2.5 and co-authored the critically acclaimed Hacker's Guide to Visual FoxPro 3.0. He's has just completed the Hacker's Guide to Visual FoxPro 6.0, due out soon after VFP 6.0 ships. Ted is a Microsoft Certified Solution Developer, a five-time Microsoft Most Valuable Professional award winner, a Contributing Editor to FoxPro Advisor and a full-time software developer working at Blackstone, Incorporated in Waltham, MA. Contact Ted at mailto:tedroche@compuserve.com.