

<!entity HELPlogo 		FILE "helpShelf.pm">
<!entity SnapshotIcon		FILE "Snapshot.xwd">

<!entity SoundIcon              FILE  "speaker.pm">
<!entity head-down		FILE "head-down.xwd">
<!entity sunset			FILE "sunset.xwd">
<!entity tribe			FILE "tribe.xwd">
<!entity dead-jim		FILE "deadjim.xwd">
<!entity computer-bee		FILE "bee.xwd">

<!entity bugs-bunny		FILE "bugs.bunny.xwd">

<!entity rooster		FILE "rooster.xpm">
<!entity clouds			FILE "clouds.xpm">

<!entity space-shuttle		FILE "shuttle2.xwd">
<!entity integral               FILE "integral.bm">
<!entity snapshot		FILE "Snapshot.bm">

<!entity clock                  FILE "clock.xwd">
<!entity xload			FILE "xload.xwd">
<!entity ApplicationWithHelp	FILE "AppWithHelp.xwd">
<!entity QuickHelpModel         FILE "QuickHelp.xwd">
<!entity GeneralHelpModel	FILE "GeneralHelp.xwd">



<!entity HELPICONENT FILE "helpicon.ent"> 
        &HELPICONENT;
<!entity HELPLANGENT FILE "helplang.ent"> 
        &HELPLANGENT;
<!entity HELPCHARENT FILE "helpchar.ent">
        &HELPCHARENT;

<metainfo>

  <title>CDE Help System Demo Volume

  <copyright>
  <image><term nogloss|Common Desktop Environment (CDE)|
  Copyright &copy; 1993, 1994 Hewlett-Packard Company
  Copyright &copy; 1993, 1994 International Business Machines Corp.
  Copyright &copy; 1993, 1994 Novell, Inc.
  Copyright &copy; 1993, 1994 Sun Microsystems, Inc.
  <\image>

  <abstract>
     Demonstration help volume for the CDE Help System.
  <\abstract>



<!-- CLASSESDEF -->

<otherfront id=CLASSESDEF><head>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>

<!-- SUBCLASSESDEF -->

<otherfront id=SUBCLASSESDEF><head>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>

<!-- WIDGETDEF -->

<otherfront id=WIDGETDEF><head>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>





<otherfront id=gifted-topic><head>He's dead, Jim!

<figure nonumber 
entity=dead-jim ghyperlink="dtaction Play sounds/deadjim.snd&" glinktype=Execute>
<\figure>

<otherfront id=head-down-topic><head>Nope, nothing in here.


<figure nonumber entity=head-down
ghyperlink="dtaction Play sounds/clunk.snd &" glinktype=Execute>
<\figure>


<otherfront id=sunset-topic><head>Online!


<figure nonumber
entity=sunset ghyperlink="dtaction Play sounds/haleluja.snd &" glinktype=Execute>
<\figure>


<otherfront id=tribe-topic><head>Learning products cost too much?

<figure nonumber
entity=tribe ghyperlink="dtaction Play sounds/tarzan.snd &" glinktype=Execute>
<\figure>


<otherfront id=whats-up-doc-topic><head>What's up?

<figure nonumber entity=bugs-bunny ghyperlink="dtaction Play sounds/whatsup.snd &" glinktype=Execute>
<\figure>

<!--

<esc>
<figure file graphics/whatsup.xwd link "dtaction Play sounds/whatsup.snd &" typelink 3>
</figure>
<\esc>

-->

<\metainfo>


<hometopic>The CDE Help System

<p indent gentity=HELPlogo gposition=left>
<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>



<!-- FEATURES -->

<s1 id=features>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.


<!-- OVERVIEW -->

<list bullet tight>
 * <xref HYPERTEXT>
 * <xref DEFINITIONS>
 * <xref GRAPHICS>
 * <xref AUDIO>
 * <xref COMMANDS>
 * <xref COMMUNICATION>
<\list>

<s2 id=OVERVIEW>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 "<link hyperlink="Intromgr _HOMETOPIC" JumpNewView>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 <link
hyperlink="browser _HOMETOPIC" JumpNewView>CDE Help Manager<\link>.

<\list>

<note>
See the <link dtappintegrate man>dtappintegrate Man Page<\link>
for specific information on registration of application help volumes.
<\note>
<!-- HYPERTEXT -->

<s2 id=HYPERTEXT>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.

<p gentity=SnapshotIcon glinktype=JumpNewView ghyperlink=HYPERTEXT>
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>


<!-- DEFINITIONS -->

<s2 id=DEFINITIONS>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.

<p indent>OSF/Motif graphical user interfaces are constructed using <link
WIDGETDEF Definition>widgets<\link>.  Widgets are organized by form and
function into <link CLASSESDEF Definition>classes<\link> and <link
SUBCLASSESDEF Definition>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 <link
hyperlink="Intromgr quick-start" JumpNewView>visual overview<\link> of the
application.





<!-- GRAPHICS -->

<s2 id=GRAPHICS>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|
<!--
<esc>
<figure file graphics/color.xwd>
</figure>
<newline>
<newline>
<\esc>

<esc>
<figure file graphics/hutlogo.xwd>
</figure>
<newline>
<newline>
<\esc>
-->

<figure nonumber entity=computer-bee>
<\figure>

<otherhead>We Do Bitmaps!

<figure nonumber entity=integral>
<\figure>

<!--
<esc>
<figure file graphics/libAnne.bm>
</figure>
<newline>
<newline>
<\esc>
-->

<!--
<esc>
<figure file graphics/hplogo.bm>
</figure>
<newline>
<newline>
<\esc>
-->

<figure nonumber entity=snapshot>
<\figure>

<otherhead>We Do Grayscale!

<figure nonumber entity=space-shuttle>
<\figure>


<s2 id=Audio>An Audio Sampler

			<idx|Audio Sampler|
<figure nonumber
entity=rooster ghyperlink="dtaction Play sounds/rooster.snd &" glinktype=Execute>
<\figure>


<figure nonumber
entity=clouds ghyperlink="dtaction Play sounds/thunder.snd &" glinktype=Execute>
<\figure>

<otherhead>Pop-Up Windows With Graphical Audio Links


<list bullet>

 * <link whats-up-doc-topic Definition>Whats up?<\link>

 * <link gifted-topic Definition>Our customer, after getting too many
   manuals ...<\link>

<!--
 * <link head-down-topic Definition>Our competitors ...<\link>
-->

 * <link sunset-topic Definition>I found it ...<\link>

<!--
 * <link tribe-topic Definition>A coffee talk ...<\link>
-->

<\list>


<otherhead>Some Text-Based Audio Links

<list plain loose>

 * <link hyperlink="dtaction Play sounds/monkey.snd &" Execute>
   Monkey<graphic entity=SoundIcon>
   <\link>

 * <link hyperlink="dtaction Play sounds/chord.snd &" Execute>
   Pleasant Chord<graphic entity=SoundIcon>
   <\link>

 * <link hyperlink="dtaction Play sounds/hal2.snd &" Execute>
   Hal 9000 <graphic entity=SoundIcon>
   <\link>

 * <link hyperlink="dtaction Play sounds/attack.snd &" Execute>
   Prepare to attack!  <graphic entity=SoundIcon>
   <\link>

 * <link hyperlink="dtaction Play sounds/beback.snd &" Execute>
   I'll be back!<graphic entity=SoundIcon>
   <\link>
<\list>

<!-- COMMANDS -->

<s2 id=COMMANDS>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.

<p gentity=clock ghyperlink="DtHelpExecAlias xclockAlias" glinktype=Execute>This
icon starts the ``xclock'' program if it is
installed on your system, and in your PATH.

<p gentity=xload ghyperlink="DtHelpExecAlias xloadAlias" glinktype=Execute>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 <link EXECUTE hyperlink="DtHelpExecAlias dtCalcAlias">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>



<!-- COMMUNICATION -->

<s2 id=COMMUNICATION>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.


<s3 id=controlTestId> 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>
* <link hyperlink="100" type=AppDefined> Move dthelpdemo's window<\link>
* <link hyperlink="101" type=AppDefined> Resize dthelpdemo's window<\link>
<\list>



<!-- design -->

<s1 id=design>The CDE Help System Design



<!-- MODEL -->

<list bullet tight>
 * <xref MODEL>
 * <xref TOOLKIT>
 * <xref API>
 * <xref HELPTAG>
<\list>

<s2 id=MODEL>The CDE Help System Use Model
				<idx|use model|
				<idx|prime directive|

The overriding principle for providing online help is:

<p indent>!!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 nonumber entity=ApplicationWithHelp>
<\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>

* <link QUICKHELP>Quick help<\link> presents a focussed node of
information for a given context.

* <link GENERALHELP>General help<\link> presents navigable information
that the user can explore.

<\list>


<!-- QUICKHELP -->

<s3 id=QUICKHELP>Quick Help

Quick help information is optimized -- by writing style and 
organization -- to get the user back on task with minimal interruption.

<figure entity=QuickHelpModel>
<\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>


<!-- GENERALHELP -->

<s3 id=GENERALHELP>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 nonumber entity=GeneralHelpModel>
<\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>


<!-- TOOLKIT -->

<s2 id=TOOLKIT>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.



<!-- HELPTAG -->

<s2 id=API>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>
 * <link DtHelpDialog man>DtHelpDialog()<\link>
 * <link DtHelpQuickDialog man>DtHelpQuickDialog()<\link>
 * <link DtCreateHelpDialog man>DtCreateHelpDialog()<\link>
 * <link DtCreateHelpQuickDialog man>DtCreateHelpQuickDialog()<\link>
 * <link DtHelpQuickDialogGetChild man>DtHelpQuickDialogGetChild()<\link>
<\list>

 * Function for implementing item help mode:

<list plain tight>
 * <link DtHelpReturnSelectedWidgetId man>DtHelpReturnSelectedWidgetId()<\link>
<\list>

 * Function for specifying the message catalog for the Xvh library:


<list plain tight>
 * <link DtHelpSetCatalogName man>DtHelpSetCatalogName()<\link>
<\list>
<\list>



<!-- HELPTAG -->

<s2 id=HELPTAG>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 <book|dthelpview| preview
client.
























