TkHelpBrowser 1.3

TkHelpBrowser is a Tk widget based on the htmllib package and sample browser client developed by Stephen Uhler and maintained by Clif Flynt (the Flynt version is available at http://noucorp.com). TkHelpBrowser is designed to function as a drop-in widget, callable from a Tcl/Tk application with no modification required. In addition to displaying help pages formatted in HTML, TkHelpBrowser also provides navigation and search capabilities for user documentation. It is designed to be a simple but complete user documentation system.

Using TkHelpBrowser in Your Application

TkHelpBrowser is deployed as a Tcl package and can be invoked with package require tkhelpbrowser (for the standard Tk version) or package require tkhelpbrowser_tile (for the Tile version).

TkHelpBrowser defines two commands:

tkhelpbrowser_setHome {file}: This command defines the home page for your user documentation.using the Home variable, and takes a file path as an argument. Example: tkhelpbrowser_setHome [file join [file dirname [info script]] html index.html] This command also specifies the directory that is parsed for the tree display of help pages.
tkhelpbrowser_showDoc {file}: This command loads a specific page, typically your user documenation's home page, and takes a file path as an argument. Example: tkhelpbrowser_showDoc $Home

TkHelpBrowser has dependencies on the following Tcl/Tk packages: BWidget, fileutil, Tablelist, and (optionally) Tile. These packages can be downloaded from standard sites.

Structuring Your Documentation to Be Displayed in TkHelpBrowser

TkHelpBrowser requires a few adjustments to your documentation to display it effectively:

HTML file names should be saved with a numeric prefix, i.e. 01-file.html, 02-file.html, etc. TkHelpBrowser parses the HTML directory and sorts the list of names for display in the navigation tree.
HTML pages should be saved in a single directory. The navigation tree cannot recursively scan directories and correctly display the results.
All pages should have a title using the title tag. TkHelpBrowser uses this tag to display page names in both the tree view and the search results.

Comparison of TkHelpBrowser to Other Help Display Systems

Many systems for displaying user help in Tcl/Tk applications have been developed; see this page at the Tcl wiki for examples. TkHelpBrowser differs from many other help systems based on tkhtml in that it is a pure Tcl/Tk widget rather than a compiled extension, and thus highly portable. TkHelpBrowser also displays plain HTML with minimal adjustment, rather than prescribing a complex documentation format; finally, TkHelpBrowser is licensed under the standard Tcl/Tk license and can be used in commercial and open-source applications.

TkHelpBrowser Improvements

TkHelpBrowser updates the htmllib package in the following ways:

The core htmllib code is modified to display hyperlinks as underlined texts, like standard browsers, rather than using raised/lowered relief.
The client widget, which actually displays the HTML, adds buttons, icons and tooltips to make navigation through help pages easier.
The client widget is now read-only after a selected HTML file is loaded, to avoid the end user inadvertantly changing the text.
Handlers to support the calling of external applications for http://, ftp://, and mailto:// links have been added. These handlers support the Windows, Mac OS X, and X11 environments.
TkHelpBrowser adds a navigation tree using the BWidget tree view; search functionality using the ::fileutil::grep module; and display of search results with the Tablelist widget.

TkHelpBrowser is not a compiled extension; it is based on the Tk text widget. As such, it should function on any platform that Tcl/Tk supports. In addition to a standard Tcl/Tk version, a version that incorporates the Tile widget set is also available.

Known Issues

TkHelpBrowser does not support advanced HTML features such as frames or CSS.
TkHelpBrowser includes native support for gif images, like Tk itself. Other image formats supported by extensions such as Img should work as well, but this has not been tested.
TkHelpBrowser sets the selection in the display tree according to the page that is loaded in the HTML viewer; it does not handle hyperlink anchors gracefully.
TkHelpBrowser's parser does not correctly handle colons in page titles; colons should be avoided.

Changes from Version 1.2

Restored tooltips.
Added code to better support Mac OS X interface conventions such as "disclosure triangles" for tree widget.

Changes from Version 1.1

Added tree display and search capabilities.
Restored menu to configure text display.

Changes from Version 1.0

Simplified GUI design to use standard Tk elements (buttons rather than custom labels), switched to clearer icons, and removed tooltips.
To simplify the project's development, table support has been removed from the htmllib package.
Now available as a standard Tcl package.

tkHelpBrowser is available under a BSD-style license.