Home‎ > ‎KeyHH 1.1‎ > ‎

KeyHH 1.1 Readme

This is a copy of the documentation that ships with the KeyHH 1.1 release.
Unfortunately the contact details and links are no longer valid. Contact me if you need to contact the Keyworks developers.  - Rob Chandler

Welcome to KeyHH!

License to Use KeyHH

First, let's get the legal stuff out of the way. :-)

BECAUSE THIS PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THIS PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

Whew! Now that we've taken care of that, let's talk about KeyHH.

About KeyHH

KeyHH is a program that augments HTML Help, the help development environment that Microsoft has created for its HTML-based online help systems and electronic books. (You can find out more about HTML Help at http://www.microsoft.com/workwshop/author/htmlhelp/.) KeyHH can be used in addition to or as a complete replacement for HH.EXE. KeyHH provides all of the functionality of HH.EXE, offers solutions for some known bugs in HTML Help, and provides additional functionality as well.

Why Should I Use KeyHH?

KeyHH helps you to resolve these problems with HH.EXE:

6  Open a standalone HTML Help window

You can use KeyHH to create a standalone HTML Help window. This window remains open until the user closes it. Once this window is created, you can open new topics in the window without creating a new window, just as you can with WinHelp. You can use this functionality from an HTML Help window, a program, or a WinHelp file.

6  Open an HTML Help topic from a WinHelp topic

Although you can easily link from an HTML Help (.chm) file to a WinHelp (.hlp) topic, the opposite is more difficult. KeyHH is designed to help you to open a .chm file from a WinHelp topic. This feature is especially useful if you're creating hybrid (mixed WinHelp and HTML Help) documentation sets. For example, suppose you decided that you want to use WinHelp topics for What's This? help, since WinHelp popup topics are more feature-rich than HTML Help popups. However, you also want to link from the What's This? help topics to a more complete explanation in a .chm file. KeyHH allows you to do this without creating multiple HTML Help windows.

6  Open an HTML Help window based on a keyword search

A common way of linking topics in a help system is through keyword and associative links--KLinks and ALinks, in WinHelp terminology. Both HTML Help and KeyHH support this linking capability. However, KeyHH also allows you to open the new topics in a window that is already open. In addition, KeyHH allows you to use ALinks and KLinks in ways that HH.EXE doesn't support. For example, you can:

  • Run KLinks and ALinks that are in a WinHelp topic that is linked to your .chm file.
  • Create a standalone window from an ALink or KLink, rather than just from a specific URL (although you can do that, too)
  • From a program, open a particular topic through ALinks or KLinks, even if your program doesn't handle structures or the HtmlHelp API)

6  Open an HTML Help 1.1 window using a mapped id

HTML Help 1.1 requires you to open a mapped topic in the default window set up in the project. (Mapped topics allow programmers to open a topic in an HTML Help window without having to know the URL. Instead, all they need to know is the id you have mapped to the topic.) HTML Help 1.1 ignores a window type associated with a mapped topic and attempts to open the topic in the default window in your project. If you don't specify a default window, HTML Help attempts to create a default window but doesn't always do a good job. Using KeyHH, you can open a mapped HTML Help topic in any window that you have set up in your project. This doesn't have to be the default window.

If you're using HTML Help 1.2, you don't need to worry about this problem.

How Do I Use KeyHH?

To create a unique KeyHH window

You create a unique KeyHH window by specifying a dash (-) followed by an identifying name and the name of the CHM file. KeyHH will then check to see if an HTML Help window is already open that uses this identifying name. If so, the HTML Help window will simply be updated with the new CHM file or topic. If it is not open, KeyHH will create a new HTML Help window.

You can use any identifier that you want, as long as the first character does not begin with the pound (#) character.

For example, to open a topic called tagref.htm in the htmlhelp.chm file, you would use this command:

KeyHH -MyID htmlhelp.chm::/tagref.htm

Suppose you then wanted to link from tagref.html to a topic called api.htm. You would then use this command:

KeyHH -MyID htmlhlp.chm::/api.htm

If you were using HH.EXE in the above example, HTML Help would open a second window when the user clicked the api.htm link. If you're using KeyHH, api.htm simply replaces tagref.htm in the same window because the identifying name (-MyID) is the same in both cases.

Note: Don't use filenames with hyphens (e.g., new-topic.htm) when working with KeyHH.

To create another HTML Help window that won't close when the original window is closed

You may want to open a topic you have linked in an HTML Help window in a second. Often, help authors use the Related Topics command or an Associative Link command in this case. However, if you close the original window, all HTML Help windows are automatically closed. To keep the second window open, use the HTML Help ShortCut command to run KeyHH. If you are using HTML Help Workshop to edit your HTML file, follow these steps:

  1. Open the HTML file in which you want to create a ShortCut.
  2. Click inside the BODY of the file.
  3. From the Tags menu, choose HTML Help Control.
  4. From the listbox, choose ShortCut as the command you want to add.
  5. If you have already used the HTML Help ActiveX control in this HTML file, type an ID name for this instance of the control in the textbox at the bottom of the wizard. If you haven't used the control, you'll get the default (hhctrl.ocx).
  6. Click Next, and follow the instructions on your screen.
  7. When the page opens that asks for the program, parameters, and window class, enter the following: 
    Program: KeyHH.exe
    Parameter: -MyID htmlhlp.chm::/api.htm
  8. Complete the wizard.

Because of the way HTML Help 1.2 handles unnamed window types, you may still get multiple windows when HTML Help 1.2 is installed, particularly when working with multiple help systems (e.g., merged CHM files). To resolve this problem, declare a window type whose name begins with the prefix "$global_" in each CHM file. For example:

file1.chm::/file1topic1.htm>$global_task 
file2.chm::/file2topic1.htm>$global_task

The $global_" prefix tells HTM LHelp that the window type can be used by any CHM file once the initial window type has been opened.

To link from a WinHelp topic to a CHM file

To link from an WinHelp file to an HTML Help file, you must use the ExecFile WinHelp macro. Here is an example:

ExecFile(KeyHH, "-MyHelp myfile.chm::/mytopic.htm>mywindow", SW_SHOW)

Additional Commands

You can also use KeyHH to find the topic to display based on one or more keywords, one or more ALink names, or a mapped numeric id. Note that when you use one of these commands without specifying a KeyHH identifier, then KeyHH will automatically create an identifier called KL.

To find topics with keywords in common (KLink)

You can have KeyHH find and list topics that share keywords by specifying a -#klink followed by one or more keywords separated by semi-colons. If any of your keywords contain spaces, then all of the keywords must be surrounded in single or double quotes. For example, to look up the topic associated with the keyword "ActiveX Control Wizard" in the HTML Help documentation, you would specify:

KeyHH -MyHelp -#klink "ActiveX Control Wizard" htmlhelp.chm

If more then one topic is found for the keyword or keywords you request, the user will be presented with a dialog listing the titles of the HTML files that were found. The user can choose one of the topics from that list.

To use associative linking (ALink)

You can have KeyHH look up an ALink name in the same way you lookup a keyword, only you specify -#alink instead of -#klink. The rest of the syntax is identical.

To link to a context-sensitive topic

If the project file used to create your .chm file contains a [MAP] and [ALIAS] section, then you can also jump to a specific topic that has a mapped numeric id aliased to it. If you know the number that is mapped to the topic you want to display, use a -#mapid followed by the number. For example, if you wanted to display the topic associated with the mapped id 112 you would specify:

KeyHH -MyHelp -#mapid 112 myfile.chm

Special note for programmers

If you use the HH_HELP_CONTEXT command of the HtmlHelp API with HTML Help version 1.1, the only window type in which you can display your topicis the default window type set up in the HTML Help project. However, KeyHH is able to display the topic in a specified window type even when HTML Help 1.1 is being used. You can use KeyHH as an alternative to the HH_HELP_CONTEXT command to get the correct window type.

Registering KeyHH

KeyHH includes two special commands: -#register and -#unregister. When you call KeyHH with -#register, it becomes associated with all files that have the extension .CHM. Once you do this, KeyHH runs instead of HH.EXE whenever you double-click a CHM file.

After you register KeyHH, the icons for all .CHM files will change to reflect the association with KeyHH instead of HH.EXE.

You can unregister KeyHH by running the -#unregister command. This command removes the association with .chm files, and registers HH.EXE instead.

It is not necessary to register KeyHH. The ability to register KeyHH is provided purely as a convenience (and for those who prefer the KeyHH icons for .chm files). If you do register KeyHH, it is not necessary to ship HH.EXE.

What Do I Need to Do to Ship KeyHH with My Project?

Along with the files for your help projects (e.g., .hlp, .cnt, .chm), you need to distribute KeyHH.exe. This program must installed in the same directory as HH.EXE (the same directory where Windows is installed).

About the Developers

KeyHH is one of the products developed through the parnership of Ralph Walden and Cheri Lockett Zubak. You can find more of Ralph's and Cheri's products at http://www.keyworks.net.

Ralph Walden is best known as Microsoft's lead architect for WinHelp and HTML Help. He began working on online help systems for Microsoft in 1987 with the creation of QuickHelp. In 1992, he took over the development of WinHelp, producing WinHelp 4.0 and Help Workshop. In 1996, he began creating the largest team Microsoft has ever put on a help project, and was the system architect for HTML Help. He has since left Microsoft, and now is principal of KeyWorks Software (http://www.keyworks.net).

Cheryl Lockett Zubak is President of Work Write, Inc., a consulting firm that specializes in the design and development of user assistance and performance support for the Windows and Web platforms. An accomplished and popular speaker on hypermedia design and development, Cheryl is coauthor of Designing Windows 95 Help and a forthcoming book about HTML-based help design. Cheryl is a certified trainer for RoboHELP Office products (Blue Sky Software) and ForeHelp (ForeFront, Inc.), and is a charter member of the HTML Help MVP program. To learn more about Work Write, Inc. services, visit the Work Write, Inc. website at http://www.workwrite.com.

Questions about KeyHH

If you have questions about using KeyHH, please send an email to kthelp@workwrite.com.

Comments