
Writing online help for wxWidgets applications
Different platforms have different methods of displaying online help. Here's a table
of most of the interesting formats:
Format
|
Platform
|
Viewer
|
Help Controller
|
Description
|
WinHelp (.hlp, .cnt)
|
Windows 3.1 95 98 NT
|
winhelp.exe, winhlp32.exe
|
wxWinHelpController
|
The old Windows Help viewer based
on RTF files is still supported
by Windows and many applications, but
now considered deprecated.
|
MS HTML Help (.chm)
|
Windows 95 98 NT CE
|
hh.exe
|
wxCHMHelpController
|
The new MS help format is
an improvement over WinHelp,
with its contents hierarchy
always present. This is now the favoured help
format for wxWidgets on Windows.
|
HTML (.htm, .html)
|
Any
|
Any browser
|
wxExtHelpController
|
On Unix you can use plain HTML and an external
browser.
|
wxHTML (.htb)
|
Windows, GTK
|
helpview[.exe],
internal wxWin viewer
|
wxHtmlHelpController
|
Thanks to Vaclav Slavik, we now
have a good wxWidgets-based, multiplatform capability
for viewing online help from within an application
or alternatively using an external viewer application.
|
wxHTML (.htm)
|
Windows, GTK
|
internal wxWin viewer
|
wxHelpControllerHtml
|
This old version of wxHTML help
is now obsolete.
|
Deciding on a help format
With so many different help formats available, you may be wondering which is best for you.
The following clarifies some of the pros and cons, and you can also look at the 'help' sample
in the wxWidgets distribution which demonstrates a variety of formats and help controllers.
Unix
If you want all the power of HTML for your help files, then you may consider using plain
HTML files on Unix (invoked by wxExtHelpController). However, the formatting of most help
files doesn't need to be very complex and so a better approach would be to use the
internal wxHTML help system and wxHtmlHelpController. You may have problems using this system
under Motif in 256 colour mode, related to the XPM icons used in the viewer, so you could try the
simpler wxHelpControllerHtml instead which is still powered by wxHTML.
Windows
MS HTML Help is now the favoured format on Windows (invoked by wxCHMHelpController). However,
if your help files need to be read on Windows 3.1, you may wish to use WinHelp instead. Or
you could produce WinHelp files for Windows 3.1 use, but CHM files for WIN32 use.
Accessing help from an application
Sometimes one can rely on wxHelpController being aliased to the standard help system for that platform
(wxHTML help for Unix, WinHelp for Windows). To use a different help controller than
the standard one, you have to include
the file for that controller and create an object using the relevant class name (e.g. 'wxCHMHelpController')
rather than simply using 'wxHelpController'. Please see the wxHelpController documentation in the wxWidgets
manual for details.
To create and initialize a help controller:
helpController = new wxCHMHelpController;
helpController->Initialize("myfile");
To access the contents, use code like the following:
helpController->LoadFile("myapp");
helpController->DisplayContents();
To access a particular section, use code like the following:
helpController->LoadFile("myapp");
helpController->DisplaySection("Diagram cards");
DisplaySection has different meanings for different help controllers, but for most controllers
it does a keyword search. It can also be used to display a particular HTML file within the help file,
for example in MS HTML Help.
To clean up as the application is ending:
helpController->Quit();
delete helpController;
Tools to help write help
There is a variety of freeware, shareware and commercial tools for this purpose, some of
which generate both HTML and WinHelp RTF.
An example of a commercial tool is Julian Smart's HelpBlocks,
available for Windows and Linux and making it easy to write and preview
HTML pages that can be converted to wxWidgets HTML Help and MS HTML Help formats.
You can use Tex2RTF
which
is bundled with the wxWidgets distribution or available separately. With Tex2RTF, you
write your manual in an extended form of Latex, and produce as output a variety of
formats. You can also run your .tex files through a real Latex processor, but this is
optional. With Tex2RTF you can produce manuals in the following formats:
- Linear RTF, for importing into a wide range of word processors.
- Windows Help hypertext RTF, for compilation with HC (Help Compiler).
- HTML (Hypertext Markup Language), as used on the World Wide Web.
Tex2RTF also outputs the project, contents and keyword files required by the HTML Help Workshop
and by wxHTML Help.
Once in MS Word RTF format, other formats can be generated, such as PostScript (by printing
to a PostScript file) and Adobe Acrobat Portable
Document Format (PDF). PDF generation requires MS Word and the full, commercial version of
Acrobat. Alternatively, you can try using GhostScript
to generate PDF, and in the MikTex package there
is a latex2pdf converter.
A short list of tools:
Online help versus printed manuals
Electronic manuals and printed manuals tend to have different characteristics. Printed manuals
are intended to be read mostly in sequence, whereas online help usually consists of little
chunks of information to be called up from the application when necessary, in addition to longer
descriptive sections.
This would seem to rule out the production of printed and online help from the same source,
but in fact a reasonable compromise can be reached, where sections make sense
when read sequentially as well as out of context. Lots of hyperlinks can help to orient
the user. Also, Tex2RTF allows conditional processing of source for different output formats.
Here's a suggested list of chapters for a typical manual/help file.
- Welcome
- Installation
- Read Me (change log, release notes)
- Getting Started
- Using Menu Commands
- Using Toolbar Commands
- The Status Bar
- Working with Window X
- Working with Window Y
- Working with ...
- Dialogs (description of a dialog per section)
- How To (a tip per section)
- Glossary
- Index (non-hypertext version only)
Tips
Tex2RTF can generate a .cnt file which will work on Windows 95, for displaying
a hierarchical contents page. Even if you produce
a Windows 3.1 help file, the .cnt file will still work as expected on Windows 95.
Prepare any bitmaps in both GIF and BMP form (with the same root name)
so HTML and WinHelp generation will work properly. An EPS image file is also required
for use with real Latex and dvips.
Convert images to 16 colours before using with WinHelp files.
If using Tex2RTF with the Windows 95 Help Compiler (as distributed with Windows 95 C++ compilers),
have the generateHPJ ini file setting on for the first time, then switch it off for
subsequent conversions, since the Help Compiler will edit and save the HPJ file.