Contents | Start | End | Previous: Chapter 4: Using HTML Templates | Next: Chapter 6: Using Custom Checking
This chapter describes how to use Jutoh Plus to create HTML help. This is useful for application developers and technical authors who want to create integrated application help from Jutoh projects, as well as documentation in the other formats supported by Jutoh.
Jutoh Plus can create HTML Help files used by Windows and wxWidgets applications. Windows HTML Help files have the extension CHM, and wxWidgets HTML Help files have the extension HTB. HTB files contain simplified HTML with no CSS, but the two formats otherwise have similar project, contents and keywords files. CHM files are mainly used on Windows, but there are CHM viewers for other platforms. HTB files are, like wxWidgets, multiplatform.
In a wxWidgets application, you can use a help controller class to show help topics at appropriate points, either using HTB/wxHTML Help for all platforms, or using CHM for Windows and wxHTML Help for other platforms. The built-in wxHTML Help viewer can be used within an integrated window in the application, or in a separate window. Jutoh uses both of these modes depending on whether a modal dialog is active or not.
Since the wxWidgets HTML renderer is quite simplistic, you can only put very basic HTML into an HTB file. You can’t use CSS, and paragraph spacing is not adjustable, but you can use image and tables. The lack of CSS is mitigated by the fact that Jutoh will generate appropriate inline formatting within the restrictions of HTB. A full list of supported tags can be found in the wxWidgets documentation under the topic wxHTML Overview.
A more advanced version of wxHTML Help is currently being written that uses the wxWebView control and can therefore handle full HTML and CSS. So in future you will be able to set the HTML version option in your HTB configuration to 4 or 5 and Jutoh will generate modern HTML instead of the simplified HTML that the current system requires.
A CHM help file uses Microsoft Internet Explorer (up to version 7) to render content on Windows, so richer formatting is possible with CHM.
An HTB file is simply a zip file containing the content, whereas a CHM file must be created by a help compiler from an HHP project file and other files. The official compiler is included in Microsoft HTML Help Workshop, which is a free download, and is called hhc.exe.
These are the constituents of an HTML help file:
A set of HTML files;
a project file with extension HHP with options and a list of HTML and other files;
a contents file with extension HHC describing a hierarchy of topic titles, topic identifiers and HTML files;
an optional index file with extension HHK listing keywords with one or more links to HTML files, adding an Index tab to the help viewer;
an alias file consisting of lines of the form IDENTIFIER=FILE, relating topic identifiers to the relevant HTML file;
a map file consisting of lines of the form #define IDENTIFIER INTEGER which you can include in your application source files so that you can refer to topics by symbol.
For HTB only, HHC files are generated with an extra parameter for each topic object with the integer identifier, for example:
<param name="ID" value=101>
In CHM mode, this doesn’t compile so is not included.
You can create a new project based on an existing wxHTML Help or CHM project. A CHM project will first need to be decompiled to a folder using a suitable application, which you can find on the web. In the New Project Wizard, specify an HHP project file. Import will be performed after you finish the wizard.
If there is an HHK file in the HTML help project, it will be imported and you can edit it in Project Properties/HTML Help/Keywords.
Be aware that converting HTML to a Jutoh project is a somewhat imprecise process. It’s likely that you’ll need to do some editing to correct import issues. But it’s still a lot faster than reworking your project from scratch.
You have several choices when generating an HTB or CHM file and creating an HHK file:
use the keywords as edited via Project Properties/HTML Help/Keywords;
use document titles (one link per document, or if using an advanced table of contents, all the found headings);
use Jutoh index entries.
In fact you can use all three methods if you wish, or a combination, or none. You can choose which to use via Project Properties/HTML Help/Options.
If you specify a symbol in the “Id” property under Document Properties/Advanced Properties, this will be added to the map and alias files, along with an automatically generated integer that the topic identifier is associated with.
If you check the relevant option in Project Properties/HTML Help/Options, the map and alias files will be copied to the Jutoh project folder with the suffixes _alias.h and _map.h. In fact the alias file is not a valid C++ header file but you may wish to parse it to retrieve the association between topic identifiers and HTML files; normally this is not necessary since you can use the preprocessor symbols in the _map.h file instead and the help system will know what HTML file to load for a given topic identifier.
Here’s an example of loading and showing help. We assume that a section in the Jutoh project has its “Id” defined as ID_HELP_OVERVIEW.
#include "myproject_ids.h"
...
m_helpController->Initialize(helpFile);
...
m_helpController->DisplaySection(ID_HELP_OVERVIEW);
In the example, ID_HELP_OVERVIEW is defined as an integer in myproject_ids.h, and the help system looks up the topic integer in the HHC file to find the HTML file to show. Currently, you can’t use identifiers within a document other than the top-level “Id” value since Jutoh doesn’t gather identifiers from the content itself, only document properties.
Please refer to the wxWidgets documentation for further information on how to use the wxHtmlHelpController and wxCHMHelpController classes.
Generated HTB and CHM files use slightly different encoding schemes for their constituent parts.
The HHC and HHK file encoding is UTF-8 in HTB, and for CHM files is determined by the CHM contents file encoding selection in Project Properties/HTML Help. In HTB, the HHC and HHK files do not specify their encoding since it is specified in the HHP file using the Charset option and adding an encoding specification to the individual files can confuse wxWidgets HTML Help.
HTML files are always in UTF-8 in both formats.
Encodings for imported HHP projects can be more varied and Jutoh performs various checks to determine individual file encoding.
In this chapter we learned how Jutoh can be used for importing and generating application help.
Next, we look at a tool that can dramatically reduce the number of typos in your books: custom checking.
Contents | Start | End | Previous: Chapter 4: Using HTML Templates | Next: Chapter 6: Using Custom Checking