&HELPICONENT; &HELPLANGENT; &HELPCHARENT; <metainfo> CDE Help System Demo Volume <copyright> <term nogloss|Common Desktop Environment (CDE)| Copyright © 1993, 1994 Hewlett-Packard Company Copyright © 1993, 1994 International Business Machines Corp. Copyright © 1993, 1994 Novell, Inc. Copyright © 1993, 1994 Sun Microsystems, Inc. <\image> <abstract> Demonstration help volume for the CDE Help System. <\abstract> Widget Class A type of widget. A widget's !!class!! determines what methods will be called for it and what instance variables it has. <procedure>See Also <list bullet tight> * <xref SUBCLASSESDEF> * <xref WIDGETDEF> <\list> Widget Subclass A more specific class, used to create related widget objects. A widget !!subclass!! has its own features plus many of the features of its superclasses. <procedure>See Also <list bullet tight> * <xref CLASSESDEF> * <xref WIDGETDEF> <\list> Widget An individual component used within a graphical user interface. Widgets are like "building blocks" -- push buttons, scroll bars, data fields -- used to build application interfaces. <procedure>See Also <list bullet tight> * <xref CLASSESDEF> * <xref SUBCLASSESDEF> <\list> He's dead, Jim!
<\figure> Nope, nothing in here.
<\figure> Online!
<\figure> Learning products cost too much?
<\figure> What's up?
<\figure> <\metainfo> <hometopic>The CDE Help System

<emph>Welcome to a self-paced demonstration of the CDE Help System!<\emph> <newline>What better way to learn about a hypermedia system, than by using the system itself. This demo lets you explore information and capabilities about CDE Help according to your interests. <idx|getting started| To get started, choose one of the hyperlinks below (they're underlined): <list bullet tight> * <xref overview> * <xref features> * <xref design> <\list> <note> This help volume serves as a self-paced demonstration of the CDE Help System, as well as supports the various help entry points used within the ``dthelpdemo'' sample program. ``dthelpdemo'' is sample OSF/Motif client intented to show how the CDE Help System can be used. The source code for both the ``dthelpdemo'' client as well as this help volume are present on your system. <\note> A Self-Guided Tour <idx|touring CDE Help| This tour demonstrate the major features of the CDE Help System. You may explore them in any order. While exploring, to return to a previous topic, choose the Backtrack command button. To return to the top-level topic, choose Contents. The indented list at the top of the help window tells you where you are in the topic hierarchy and lists the sutopics for the current topic. You can go directly to any topic in the path by selecting its title. <list bullet tight> * <xref HYPERTEXT> * <xref DEFINITIONS> * <xref GRAPHICS> * <xref AUDIO> * <xref COMMANDS> * <xref COMMUNICATION> <\list> General Overview CDE Help is an online help system, primarily intended for OSF/Motif applications. The following sections provide a summary of major CDE Help features. (For more details, refer to "<xref DESIGN>.") <otherhead>Hyperlinks Hyperlinks are the key feature in a hypermedia system. CDE Help supports four types of hyperlinks: <list bullet> * <emph>Standard hypertext jumps<\emph> immediately move the reader to a different location within the online information. By default, these types of jumps replace the contents of the existing window. However, the author may specify jumps that should be displayed in a "new view." (For more detail, refer to "<xref HYPERTEXT>.") * <emph>Definition links<\emph> temporarily show the definition of a key word or phrase. Although intended for keyword-to-glossary lookup, definition links have many other useful applications. (For an example, refer to "Introducing the CDE Desktop.<\link>.") * <emph>Command links<\emph> execute an author-defined command to invoke an action beyond the domain of the help system. Any shell command can be executed, so this feature is really the "open door" to the outside world for CDE Help authors. (To try examples, refer to "<xref COMMANDS>.") * <emph>Application-defined links<\emph> (To try some examples, refer to "<xref COMMUNICATION>.") <\list> <otherhead>Embedded Graphics CDE Help supports the following graphics formats. To view samples of a few of these formats, refer to "<xref GRAPHICS>." <list bullet> * !!X Window Dump!! (xwd) color graphics. This format is created using the standard <computer>xwd<\computer> utility program. Many popular graphics tools for the X Window System also support this format. * !!X Pixmap!! (xpm) color graphics. This is an emerging standard format for multicolor icons. * <emph>X Bitmap<\emph> (bitmap) two-tone graphics. The foreground and background of these images tracks the foreground and background used to display text in the display area. This format can be created and edited using the standard <computer> bitmap<\computer> utility program. * <emph>TIFF<\emph> (tagged image file format) black and white and greyscale graphics. This is perhaps the most common format in the personal computer graphics industry. <\list> <otherhead>Interactive Keyword Index CDE Help's keyword index functions much like the index in a book, listing words the author marked as important. Unlike the index in a book, this online index accelerates the reader's ability to jump to references because each word or phrase is a link to the location (or list of locations) where it is used. <otherhead>Help Registration When an application is installed, it may install its help files in any location. Optionally, applications can participate in a "registration" process that enables two important features for online help: <list bullet> * <emph>Cross-application links<\emph> that allow hyperlinks to jump from one application's help to another's. * <emph>System-wide access to help<\emph> provided by the CDE Help Manager<\link>. <\list> <note> See the dtappintegrate Man Page<\link> for specific information on registration of application help volumes. <\note> Hyperlinks for Navigation The "hyper" in hypermedia is what separates hypermedia systems from online documentation systems. Unlike books that have a linear organization, hyperlinks let authors create many different, nonlinear organizations, including "webs," "trees," "circles," and "chains." In CDE Help, the basis for all organizations is a hierarchy. However, authors can augment the structure by creating links between related topics that are in different branches of the hierarchy. <otherhead>Simple Jumps (Same Window) Most hyperlinks are simple jumps within the same application help. These simple jumps reuse the same window, overwriting the previous topic with each jump. <otherhead>Jumping to a New Window When an author creates a new link, she can specify that the link should open a new help window. The application is responsible for creating and managing the new window.

For example, this camera icon is a hyperlink to this topic on hypertext. However this link specifies that a new window is desired. Effectively, this link takes a "snapshot" of this window. You may use this snapshot link to create as many demo windows as you want. The demo will continue to run until you close the last one. <otherhead>Knowing Where You Are Near the top of the general help window is an indented list of topic titles. This list represents your current position (highlighted entry) with respect to its related topics. You can go directly to any of the related topics in the list by selecting its title. <otherhead>Knowing Where You've Been CDE Help keeps track of each topic you've viewed in each help window. To go back to previous topics, you can: <list bullet> * Choose Backtrack from the Navigate menu or from the pop-up menu in the dipslay area to immediately go back to the previous topic. * Choose History from the Search menu to display a list of all the topics you've viewed. To return to a topic, select its title in the list. <\list> Pop-Up Definition Links A special class of hyperlink is provided for temporarily displaying "elaborative" information. Most frequently, this feature is used to display the glossary definition for a key word or phrase. For example, the following paragraph has three definition links.

OSF/Motif graphical user interfaces are constructed using widgets<\link>. Widgets are organized by form and function into classes<\link> and subclasses<\link>. The use of definition links is not limited to defining key words and phrases. For instance, you could use this feature to provide a visual overview<\link> of the application. A Graphics Sampler The following images demonstrated the diverse capabilities of CDE Help's graphics support. Some of these images are oversized -- you may want to resize the window to get a better view. <idx|Graphics Sampler|

<\figure> <otherhead>We Do Bitmaps!
<\figure>
<\figure> <otherhead>We Do Grayscale!
<\figure> An Audio Sampler <idx|Audio Sampler|
<\figure>
<\figure> <otherhead>Pop-Up Windows With Graphical Audio Links <list bullet> * Whats up?<\link> * Our customer, after getting too many manuals ...<\link> * I found it ...<\link> <\list> <otherhead>Some Text-Based Audio Links <list plain loose> * Monkey <\link> * Pleasant Chord <\link> * Hal 9000 <\link> * Prepare to attack! <\link> * I'll be back! <\link> <\list> Executing Commands <idx|Command execution| Each of the following icons is a hyperlink assigned to a particular system command. If the program in the command is installed on your system, clicking the icon will invoke it.

This icon starts the ``xclock'' program if it is installed on your system, and in your PATH.

This icon starts the ``xload'' program if it is installed on your system, and in your PATH. Command links do not have to be graphics. For example, this link executes the CDE Calculator<\link> program (if it is installed on your system). <note> The above Execute examples take advantage of Execution Aliases in the hyperlinks. When execution alises are defined in the help volume, and supported in the hosting client, they execute directly when selected by the user. To learn more general information about supporting execution hyperlinks and aliases, refer to the <book|CDE Author's and Programmer's Guide|. <\note> Two-Way Communication <idx|Two way communication| A help system that is tightly coupled with an application has more potential for presenting relevant, context-sensitive information. The architecture of the ... <otherhead>Help System Controlling the Application Since CDE Help is intended for use in OSF/Motif-based applications, it takes advantage of the !!callback!! mechanism used by all other user interface components. Help callbacks notify the application when certain events occur within a help window. Perhaps the most powerful use of help callbacks is the use of !!application-defined links!!. These are link types invented by the application developer that can have any meaning. For example, a developer may want to create a special type of link to play video clips. Each time the user selects one of these links, the application is notified so it can do whatever is necessary to play the appropriate video. <xref controlTestId> <otherhead>Application Controlling the Help System As a toolkit, all CDE Help facilites are under control of the application. All help windows are transient windows of the application. The application can control the number of help windows, the color schemes used within them and other options provided by the CDE Help libraries. Sample Application Defined Links The following collection of hypertext links demonstrate how the CDE Help System can control the hosting application. These links are authored as <emph>AppDefined<\emph> links, and require special support in the hosting client <note> These example !!application-defined!! links are supported by the ``dthelpdemo'' program. (If you view this help volume with another application, such as dthelpview, the links are ignored.) <\note> <otherhead>Controlling <emph>YOUR<\emph> client: <list bullet> * Move dthelpdemo's window<\link> * Resize dthelpdemo's window<\link> <\list> The CDE Help System Design <list bullet tight> * <xref MODEL> * <xref TOOLKIT> * <xref API> * <xref HELPTAG> <\list> The CDE Help System Use Model <idx|use model| <idx|prime directive| The overriding principle for providing online help is:

!!Get the user back on task as quickly and successfully as possible.!! To fulfill this "prime directive," online help must be easily accessible within whatever applications the user has chosen to accomplish the task. The CDE Help System is cast in a supporting roll. That is, the help system's job is to function as part of the application with the purpose of making the user successful with the rest of the application.

<\figure> The idea of keeping the help system tightly coupled with the application improves the user's <emph>perceived proximity<\emph>. User are more likely to be successful and productive if they feel like devations to get help don't take them far from the application. CDE Help supports two types of <emph> entry points<\emph> into online help: <list bullet> * Quick help<\link> presents a focussed node of information for a given context. * General help<\link> presents navigable information that the user can explore. <\list> Quick Help Quick help information is optimized -- by writing style and organization -- to get the user back on task with minimal interruption.
<\figure> Quick help has a high level of context sensitivity and contains very specific information. By design, the content and presentation of quick help information should <emph>not<\emph> encourage the user to "explore." So, what if a quick help entry point doesn't fill the user's need? <emph>Progressive disclosure<\emph> sequences are designed to maintain a sense of proximity, while exploring an author-constrained path of nodes that incrementally provide more information for the given context. (This concept is sometimes called "progressive revelation" or "progressively-more-help.") Typical uses of quick help include: <list bullet> * Messages (errors, status, etc.). * Context-sensitive help (invoked with F1 key or Help command button). * Each step in a constrained progressive disclosure sequence. * Item help. * Application copyright and version. * Simple help on help. <\list> General Help General help information is anything that isn't quick help. Usually, general help is intended to be explored (such as this demo).
<\figure> Typical uses of general help include: <list bullet> * Application overview. * A follow-up to quick help -- that is, when quick help isn't enough. * Application tutorials. * Application training modules. * Complete help on help (when quick help on help isn't enough). <\list> The Toolkit Architecture Application developers add help components to their software just as they add any other window. The CDE Help programmer's toolkit defines new widget classes for the various help windows. There are many advantages to this toolkit architecture: <list bullet> * There's no dependency on a separate help server process -- the "help system" is part of the application. * Response time is dramatically faster. * Memory usage is significantly less (which increases overall system performance). * User's perceive help to be part of the application, making it seem like less of a deviation to ask for help. * There's no need for an inter-process communication (IPC) mechanism. The application interacts with CDE Help components just as it does with all other user interface components. * There's no new programming paradigm -- all CDE Help components are accessed using the same object-oriented interface used for OSF/Motif (via the Xt Intrinsics and convenience functions). <\list> Since the CDE Help toolkit is based exclusively on standards (ANSI C, Xlib, Xt Intrinsics, and OSF/Motif), it is as portable as any OSF/Motif application can be. CDE Help API Summary <idx|API summary| The CDE Help System's Application Programmers Interface (API) includes the following functions: <list bullet> * Functions for creating and working with help dialogs: <list plain tight> * DtHelpDialog()<\link> * DtHelpQuickDialog()<\link> * DtCreateHelpDialog()<\link> * DtCreateHelpQuickDialog()<\link> * DtHelpQuickDialogGetChild()<\link> <\list> * Function for implementing item help mode: <list plain tight> * DtHelpReturnSelectedWidgetId()<\link> <\list> * Function for specifying the message catalog for the Xvh library: <list plain tight> * DtHelpSetCatalogName()<\link> <\list> <\list> Authoring with HelpTag Authoring for CDE Help is based on the HelpTag markup language and accompanying software. HelpTag is based on the SMGL standard (ISO 8879). <otherhead>The HelpTag Markup Language Online help is written in ordinary text files. You use special codes, or tags to markup elements within the information. The tags form a markup language called CDE HelpTag. The CDE HelpTag markup language defines a hierarchy of elements that define high-level elements such as chapters, sections, and subsections, and low-level elements such as paragraphs, lists, and emphasized words. To learn more general information about authoring with CDE HelpTag, refer to the <book|CDE Author's and Programmer's Guide|. <otherhead>The HelpTag Software The HelpTag software is responsible for converting the author's files into the run-time help files that are shipped with the application. The software is invoked with a command like this: <ex>dthelptag %%basename%%.htg<\ex> A run-time help file is generated. If the application that the help is intended for is ready to use, the help volume can be tested immediately. If the application is not ready, or the help is not associated with a particular application, it can be viewed using the