wxWidgets Logo
 
 

Docs

 
  Tutorials
FAQ
Licence
 
 
Writing Online Help

Try using HelpBlocks 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.

End of article
(c) 1998 Julian Smart, Anthemion Software
 
 

Quick Links

 
  Documentation
Hello, world!
Stable manual
Latest manual
Change log

Community

Mailing Lists
wxBlog
wxCode (Add-ons)
wxForum
wxWiki

Development

Sources
wxTrac
New ticket
Roadmap
 
 
 
 

wxSolutions

 
   
 
 
 

wxBook

 
 

Buy it From:
Amazon.com
Amazon.co.uk

 
 

Site design and update scripts by Kevin Ollivier, with special thanks to Brad Anderson for his improvements to the sidebar, intro table and navbar designs, Bryan Petty for the new wxWidgets blocks graphics and logo text, and to the wxWidgets community for all their helpful suggestions, comments and testing!