853 lines
23 KiB
Plaintext
853 lines
23 KiB
Plaintext
|
|
|
|
<!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 © 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>
|
|
|
|
|
|
|
|
<!-- 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.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|