Help System

[Jonathan Gapen]

     In hopes of clearing up some confusion, here's the information I
could dig up on help systems:

NSHelpPanel:
     The OpenStep standard describes NSHelpPanel, a panel which provides a
help interface with a table of contents, an index, and individual help
text, based on RTF or RTFD.  The Help menu item brings up the panel.
     With the help panel, you can associate help text with certain objects
using -attachHelpFile:markerName:to: so that when the user holds the help
button and clicks an object, the panel appears with the associated help
text.

NSHelpManager:
     In OPENSTEP 4.2, NeXT marked NSHelpPanel as deprecated in favor of
this class.  It's meant to be more platform-independent.  With this class,
the Help menu item simply sends a request to NSWorkspace to open the app's
help text, whatever format that may be.  (RTF on Mach, .hlp files on
Windows, etc.)
     With this class, you can -setContextHelpForObject:locationHint: so
that when the user holds the help button and clicks an object, a small
panel (or huge tooltip, if you like) appears with a short description of
the selected object.  I put up a small image of it at:
     http://www.hoofers.org/images/screengrab.png
     (Grab.app didn't catch the shadow, and got a white area instead.)

OPENSTEP 4.2:
     Obviously, there's a conflict between NSHelpPanel and NSHelpManager
over the proper use of the help key.  It seems that this release was in
transition; existing apps bring up the panel, but PB and IB only support
the new way.  I didn't test what happens when you associate help with an
object using both NSHelpManager and NSHelpPanel.
     The Help menu item still brings up the help panel.

MacOS X:
     I don't have access to this OS, but the documentation says that it
uses NSHelpManager for context help.  Otherwise, the help system is Apple
Help, a Carbon and HTML 3.2-based help system.

GNUstep:
     It has NSHelpManager, but no support for a help key and no
NSHelpPanel implemented yet.  You can add help support to your application
by adding an RTF file to the app's resources, and giving its name under
the GSHelpContentsFile in the appnameInfo.plist.  Point your Help menu
item at the first responder (or NSApp) with the showHelp: selector and
you're good to go.  (Assuming the user has an app capable of loading RTF
installed.)  HelpViewer could be supported easily with a slight change to
look for .xlp resources.

     GNUstep clearly needs to support both classes for OpenStep and MacOS
X compliance, with NSHelpManager as the preferred interface to the help
system for cross-platform compatibility.  The merits of using an external
app (flexibility) versus the built-in help panel (consistency) to
implement the help system in native GNUstep environments is up for debate.