713 lines
44 KiB
Plaintext
713 lines
44 KiB
Plaintext
<!-- $XConsortium: ch01.sgm /main/12 1996/10/22 12:20:04 rws $ -->
|
|
<!-- (c) Copyright 1995 Digital Equipment Corporation. -->
|
|
<!-- (c) Copyright 1995 Hewlett-Packard Company. -->
|
|
<!-- (c) Copyright 1995 International Business Machines Corp. -->
|
|
<!-- (c) Copyright 1995 Sun Microsystems, Inc. -->
|
|
<!-- (c) Copyright 1995 Novell, Inc. -->
|
|
<!-- (c) Copyright 1995 FUJITSU LIMITED. -->
|
|
<!-- (c) Copyright 1995 Hitachi. -->
|
|
<chapter id="HRDC.Intro.div.1">
|
|
<title id="HRDC.Intro.mkr.1">Introducing the Help System</title>
|
|
<para>This chapter introduces the Help System and briefly describes the user
|
|
interface. It shows how help information is organized, outlines how to create
|
|
and process help modules, and discusses the collaborative role of authors
|
|
and developers in the design and creation of application help.</para>
|
|
<informaltable id="HRDC.Intro.itbl.1" frame="All">
|
|
<tgroup cols="1">
|
|
<colspec colname="1" colwidth="4.0 in">
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry><para><!--Original XRef content: 'Developer's Toolkit2'--><xref role="JumpText"
|
|
linkend="HRDC.Intro.mkr.3"></para></entry></row>
|
|
<row rowsep="1">
|
|
<entry><para><!--Original XRef content: 'Overview of Online Help2'--><xref
|
|
role="JumpText" linkend="HRDC.Intro.mkr.4"></para></entry></row>
|
|
<row rowsep="1">
|
|
<entry><para><!--Original XRef content: 'Help Information Model3'--><xref
|
|
role="JumpText" linkend="HRDC.Intro.mkr.5"></para></entry></row>
|
|
<row rowsep="1">
|
|
<entry><para><!--Original XRef content: 'Help User Interface5'--><xref role="JumpText"
|
|
linkend="HRDC.Intro.mkr.7"></para></entry></row>
|
|
<row rowsep="1">
|
|
<entry><para><!--Original XRef content: 'Help Topic Organization11'--><xref
|
|
role="JumpText" linkend="HRDC.Intro.mkr.14"></para></entry></row>
|
|
<row rowsep="1">
|
|
<entry><para><!--Original XRef content: 'The Author's Job14'--><xref role="JumpText"
|
|
linkend="HRDC.Intro.mkr.18"></para></entry></row>
|
|
<row rowsep="1">
|
|
<entry><para><!--Original XRef content: 'Programmer's Job19'--><xref role="JumpText"
|
|
linkend="HRDC.Intro.mkr.27"></para></entry></row></tbody></tgroup></informaltable>
|
|
<para><indexterm><primary>introduction to Help System</primary></indexterm><indexterm>
|
|
<primary>CDE Help System, introduction to</primary></indexterm></para>
|
|
<sect1 id="HRDC.Intro.div.2">
|
|
<title id="HRDC.Intro.mkr.2">Introduction to the Help System</title>
|
|
<para>The Help System provides a complete set of tools to develop online help
|
|
for application software. It enables authors to write online help that includes
|
|
graphics and text formatting, hyperlinks, and communication with the application.
|
|
</para>
|
|
<para>The Help System also provides a programmer's toolkit for integrating
|
|
online help into an application. The Help System application program interface
|
|
supplies two specialized help dialogs and supporting routines that are used
|
|
to display, navigate, search, and print online help modules.</para>
|
|
<sect2 id="HRDC.Intro.div.3">
|
|
<title id="HRDC.Intro.mkr.3">Developer's Toolkit</title>
|
|
<para>The Help System Developer's Toolkit contains tools to write, process,
|
|
and view online help and contains an application programming library.</para>
|
|
<sect3 id="HRDC.Intro.div.4">
|
|
<title>For Authors</title>
|
|
<itemizedlist remap="Bullet1"><listitem><para><emphasis>DocBook markup language</emphasis> —a set of tags used in text files to mark organization and
|
|
content of your online help.</para>
|
|
</listitem><listitem><para><emphasis>DocBook software</emphasis>—a set
|
|
of software tools for converting the DocBook files you write into run-time
|
|
help files.</para>
|
|
</listitem><listitem><para><emphasis>Helpview application</emphasis>—a
|
|
viewer program for displaying your online help so you can read and interact
|
|
with it just as your audience will.</para>
|
|
</listitem></itemizedlist>
|
|
<para>Refer to <!--Original XRef content: 'Chapter 2, “Organizing
|
|
and Writing a Help Volume'--><xref role="ChapNumAndTitle" linkend="HRDC.OrgH.mkr.1">,
|
|
to learn more about creating and processing online help.</para>
|
|
<sect4 id="HRDC.Intro.div.5">
|
|
<title>For Application Developers</title>
|
|
<itemizedlist remap="Bullet1"><listitem><para><emphasis>DtHelp programming
|
|
library</emphasis>—an application program interface (API) for integrating
|
|
help windows into your application.</para>
|
|
</listitem><listitem><para><emphasis>A sample program</emphasis>—a simple
|
|
example that shows how to integrate the Help System into a Motif application
|
|
(see <!--Original XRef content: 'page 19'--><xref role="PageNum" linkend="HRDC.Intro.mkr.28">).
|
|
</para>
|
|
</listitem></itemizedlist>
|
|
<para>Chapters 9 through 13 discuss the application programming library.</para>
|
|
</sect4>
|
|
</sect3>
|
|
</sect2>
|
|
</sect1>
|
|
<sect1 id="HRDC.Intro.div.6">
|
|
<title id="HRDC.Intro.mkr.4">Overview of Online Help</title>
|
|
<para>It's virtually impossible—and certainly impractical—for
|
|
anyone to learn and remember <emphasis>everything</emphasis> there is to
|
|
know about the computer hardware and software they use to do their job. Nearly
|
|
every computer user needs help at one time or another.</para>
|
|
<para>Online help, unlike a printed manual, has the power of the computer
|
|
at its disposal. Most importantly, this power makes it possible to adapt
|
|
the information to the user's current context. <emphasis>Context-sensitive</emphasis> help provides just enough help to get the user back on task. In
|
|
developing your online help, remember that users need different types of help
|
|
at different times. By anticipating users' questions, you can design your
|
|
application help to respond in a logical and intuitive manner.</para>
|
|
</sect1>
|
|
<sect1 id="HRDC.Intro.div.7">
|
|
<title id="HRDC.Intro.mkr.5">Help Information Model<indexterm><primary>information model, help</primary></indexterm><indexterm><primary>model, help
|
|
information</primary></indexterm></title>
|
|
<para>There are two general styles of online help:</para>
|
|
<itemizedlist remap="Bullet1"><listitem><para><emphasis>Application help</emphasis>,
|
|
whose primary role is to be an integrated part of a Motif application.<indexterm>
|
|
<primary>Motif</primary></indexterm><indexterm><primary>Motif</primary>
|
|
</indexterm></para>
|
|
</listitem><listitem><para><emphasis>Standalone help</emphasis>, whose primary
|
|
role is to provide online access to task, reference, or tutorial information,
|
|
independent of any application software.<indexterm><primary>standalone help</primary></indexterm></para>
|
|
</listitem></itemizedlist>
|
|
<para>If you are developing online help for an application, you may choose
|
|
to organize the information exclusively for access within the application.
|
|
Or, you may design the information such that it can be browsed without the
|
|
application present, as in standalone help.</para>
|
|
<sect2 id="HRDC.Intro.div.8">
|
|
<title>Part of the Application</title>
|
|
<para>Help promotes a high degree of integration between the application and
|
|
its online help. From the user's perspective, the help is part of the application.
|
|
This approach minimizes the perceived “distance” away from the
|
|
application that the user must travel to get help.</para>
|
|
<para>Staying close to the application makes users more comfortable with online
|
|
help and gets them back on task as quickly as possible.</para>
|
|
</sect2>
|
|
<sect2 id="HRDC.Intro.div.9">
|
|
<title id="HRDC.Intro.mkr.6">Types of Help<indexterm><primary>getting help</primary></indexterm><indexterm><primary>help, how users get</primary></indexterm></title>
|
|
<para>Online help can be divided into three general categories:</para>
|
|
<itemizedlist remap="Bullet1"><listitem><para><emphasis>Automatic help</emphasis>—The
|
|
application determines when help is needed and what to present. This is sometimes
|
|
called system-initiated help.</para>
|
|
</listitem><listitem><para><emphasis>Semiautomatic help</emphasis>—The
|
|
user decides when help is needed, but the system determines what to present.
|
|
Semiautomatic help is initiated by a user's gesture or request for help,
|
|
such as pressing F1. The system's response is called context-sensitive help
|
|
because it considers the user's current context in deciding what information
|
|
to display.</para>
|
|
</listitem><listitem><para><emphasis>Manual help</emphasis>—The user
|
|
requests specific information, such as from a Help menu.</para>
|
|
</listitem></itemizedlist>
|
|
</sect2>
|
|
<sect2 id="HRDC.Intro.div.10">
|
|
<title>How Users Get Help</title>
|
|
<para>A user can request help in several ways. Most applications provide a
|
|
Help menu and Help key as well as Help buttons in dialog boxes.</para>
|
|
<sect3 id="HRDC.Intro.div.11">
|
|
<title>Help Key</title>
|
|
<para>Within most applications, the primary way for a user to request help
|
|
is by pressing the <emphasis>help key</emphasis>. In recent years, the F1
|
|
function key has become a defacto standard help key for many workstation
|
|
and personal computer products.</para>
|
|
<para>The Style Guide and Certification Checklist recommends the use of F1
|
|
as the help key, and the Motif programmer's toolkit even provides some
|
|
built-in behavior to make it easier to implement the help key in Motif
|
|
applications.</para>
|
|
<para>Some computers provide a Help key on the keyboard.</para>
|
|
</sect3>
|
|
<sect3 id="HRDC.Intro.div.12">
|
|
<title>Help Menu</title>
|
|
<para>The Help menu is a common way to provide access to help information.
|
|
Motif applications provide a Help menu, which is right-justified in the
|
|
menu bar. The <citetitle>Style Guide and Certification Checklist</citetitle>
|
|
makes recommendations regarding the commands contained in a Help menu.</para>
|
|
<figure>
|
|
<title>Application Help menu</title>
|
|
<graphic id="HRDC.Intro.grph.1" entityref="HRDC.Intro.fig.1"></graphic>
|
|
</figure>
|
|
</sect3>
|
|
<sect3 id="HRDC.Intro.div.13">
|
|
<title>Help Buttons</title>
|
|
<para>Many dialog boxes also provide a Help button to get help on the dialog.
|
|
The <citetitle>Style Guide and Certification Checklist</citetitle> recommends
|
|
that choosing the Help button in a dialog box be equivalent to pressing the
|
|
Help key while using that dialog. Exceptions should be made for complex dialogs,
|
|
where help on individual controls within the dialog box is appropriate.</para>
|
|
</sect3>
|
|
</sect2>
|
|
</sect1>
|
|
<sect1 id="HRDC.Intro.div.14">
|
|
<title id="HRDC.Intro.mkr.7">Help User Interface<indexterm><primary>overview</primary><secondary>Help graphical user interface</secondary></indexterm></title>
|
|
<para>This section is an overview of the graphical interface provided by the
|
|
Help System. For a detailed description of Help features and capabilities,
|
|
refer to the <citetitle>User's Guide</citetitle>; or, to view the corresponding
|
|
online help, you can open the desktop Front Panel Help Viewer (see <!--Original
|
|
XRef content:
|
|
'“To Display the Help Index Volume&rdquo--><!--r; on
|
|
page 97'--><xref role="SecTitleAndPageNum" linkend="hrdc.crhv.mkr.12">).
|
|
Then choose, Common Desktop Environment and Desktop Help System.</para>
|
|
<para>While using an application, a user can request help by pressing the
|
|
Help key or by selecting the application's Help menu. In addition, applications
|
|
integrating the Help System can be installed so that their respective help
|
|
modules are accessible from the desktop Help Viewer. This enables a user
|
|
to browse help information supplied by different applications without having
|
|
to run each application.</para>
|
|
<sect2 id="HRDC.Intro.div.15">
|
|
<title>Help Windows</title>
|
|
<para>When a user requests help, the Help System displays a help window. There
|
|
are two types of help windows: general help and quick help. A general help
|
|
window has a menu bar, topic tree, and a topic display area. The topic tree
|
|
lists help topics that a user can choose. The lower portion of the window—the
|
|
topic display area—displays the selected topic.</para>
|
|
<para>A quick help window is a streamlined help window. It has only a topic
|
|
display area and one or more dialog buttons. Quick help windows are often
|
|
used for short, self-contained information such as a definition.</para>
|
|
<figure>
|
|
<title>General help and quick help window</title>
|
|
<graphic id="HRDC.Intro.grph.2" entityref="HRDC.Intro.fig.2"></graphic>
|
|
</figure>
|
|
</sect2>
|
|
<sect2 id="HRDC.Intro.div.16">
|
|
<title>Hyperlinks</title>
|
|
<para>Help topics often contain hyperlinks that “jump” to related
|
|
help information. Both text and graphics can be used as hyperlinks. <!--Original
|
|
XRef content: 'Figure 1‐3 on page 7'--><xref role="CodeOrFigOrTabAndPNum"
|
|
linkend="HRDC.Intro.mkr.8"> shows formatting styles used to identify hyperlinks.
|
|
</para>
|
|
<para><indexterm><primary>hyperlink</primary><secondary>display formats</secondary>
|
|
</indexterm>Solid or dashed underscores identify words or phrases that are
|
|
hyperlinks. The solid underscore, or standard hyperlink, is most common.
|
|
When the hyperlink is selected, the related topic is displayed. An author
|
|
designates whether the hyperlink topic is displayed in the current help window
|
|
or a new window. The dashed underscore represents a definition link. When
|
|
selected, the related topic is displayed in a quick help window. A gray, open-corner
|
|
box (dashed or solid line) designates a graphic hyperlink.</para>
|
|
<figure>
|
|
<title id="HRDC.Intro.mkr.8">Formats for graphic and text hyperlinks</title>
|
|
<graphic id="HRDC.Intro.grph.3" entityref="HRDC.Intro.fig.3"></graphic>
|
|
</figure>
|
|
</sect2>
|
|
<sect2 id="HRDC.Intro.div.17">
|
|
<title>Help Navigation<indexterm><primary>topic tree</primary><secondary>selecting topic</secondary></indexterm></title>
|
|
<para>The topic tree<indexterm><primary>topic tree</primary><secondary>in
|
|
general help dialog</secondary></indexterm> shown in <!--Original XRef content:
|
|
'Figure 1‐4'--><xref role="CodeOrFigureOrTable" linkend="HRDC.Intro.mkr.9">
|
|
is an outline of topics in the current help volume. The first topic at the
|
|
top of the list is the <emphasis>home topic,</emphasis> or beginning of the
|
|
help volume. An arrow (fi) points to the current topic and shows the
|
|
user's location in the help volume.</para>
|
|
<figure>
|
|
<title id="HRDC.Intro.mkr.9">Topic tree in a general help dialog box</title>
|
|
<graphic id="HRDC.Intro.grph.4" entityref="HRDC.Intro.fig.4"></graphic>
|
|
</figure>
|
|
<para>To display a help topic, a user selects a title in the topic tree or
|
|
a hyperlink within the topic display area. The user can browse the outline
|
|
of topics by scrolling the list and then select any topic. Navigation commands
|
|
enable the user to return to previous topics or to the beginning of the help
|
|
volume.</para>
|
|
<sect3 id="HRDC.Intro.div.18">
|
|
<title>Help Navigation Buttons<indexterm><primary>navigation, help buttons</primary></indexterm></title>
|
|
<para><indexterm><primary>buttons, navigation</primary></indexterm>The general
|
|
help dialog includes three dialog buttons: Backtrack, History, and Index.
|
|
These features are also available as menu selections.</para>
|
|
<itemizedlist remap="Bullet1"><listitem><para><emphasis>Backtrack</emphasis>
|
|
— returns to the previous topic. To retrace topics visited, press Backtrack
|
|
repeatedly until the desired topic is displayed.</para>
|
|
</listitem><listitem><para><emphasis>History</emphasis> — displays the <emphasis>History</emphasis> dialog box. This dialog box lists the help volumes and
|
|
topics that have been visited. To return to any topic in the list, select
|
|
its title.</para>
|
|
</listitem><listitem><para><emphasis>Index</emphasis> — displays the <emphasis>Index Search</emphasis> dialog box. This dialog lists
|
|
all the words and phrases that the author has marked as index entries. Selecting
|
|
an index entry, then one of the topics where the entry occurs, displays that
|
|
topic in the general help dialog. <!--Original XRef content: ''--><xref role="CodeOrFigureOrTable"
|
|
linkend="HRDC.Intro.mkr.10"></para>
|
|
</listitem></itemizedlist>
|
|
<para>When using the Help Viewer from the desktop Front Panel, the general
|
|
help dialog includes an additional dialog button called Top Level. After
|
|
exploring different help volumes, a user can select this button to return
|
|
to the top-level of the desktop index help volume.</para>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="HRDC.Intro.div.19">
|
|
<title>Help Menus</title>
|
|
<para><indexterm><primary>home topic</primary><secondary>menu command</secondary>
|
|
</indexterm>A general help dialog menu bar has five menus: File, Edit, Search,
|
|
Navigate, and Help. The Search and Navigate menus contain commands for the
|
|
index and navigation buttons described previously. In addition, the Navigate
|
|
menu has a Home Topic command that returns to the beginning of the help volume.
|
|
The remaining menus provide these features:</para>
|
|
<itemizedlist remap="Bullet1"><listitem><para><emphasis>File menu</emphasis> —
|
|
duplicates a help window, prints a help topic or the current help volume,
|
|
or closes the help window.</para>
|
|
<indexterm><primary>menu</primary><secondary>File</secondary></indexterm>
|
|
<indexterm><primary>menu</primary><secondary>Edit</secondary></indexterm>
|
|
<indexterm><primary>menu</primary><secondary>Help</secondary></indexterm>
|
|
<indexterm><primary>menu</primary><secondary>Navigate</secondary></indexterm>
|
|
</listitem><listitem><para><emphasis>Edit menu</emphasis> — copies text
|
|
from the help window to another application.</para>
|
|
</listitem><listitem><para><emphasis>Help menu —</emphasis> provides
|
|
help information that describes features of the help dialogs and how to use
|
|
them.</para>
|
|
</listitem></itemizedlist>
|
|
</sect2>
|
|
<sect2 id="HRDC.Intro.div.20">
|
|
<title id="HRDC.Intro.mkr.10">Help Index</title>
|
|
<para><indexterm><primary>index</primary><secondary>Index search dialog index</secondary></indexterm>A help volume has an index of important words and
|
|
phrases that the user can search to find help topics on a subject. A user
|
|
can browse or search the index of the current volume, selected volumes, or
|
|
all help volumes available on the system. Regular expressions such as * (asterisk)
|
|
and ? (question mark) can be used to search for topics. To view the corresponding
|
|
help topic, the user selects the index entry.</para>
|
|
<figure>
|
|
<title id="HRDC.Intro.mkr.11">Index search dialog box</title>
|
|
<graphic id="HRDC.Intro.grph.5" entityref="HRDC.Intro.fig.5"></graphic>
|
|
</figure>
|
|
<para>Because the help index can be large even for a single volume, index
|
|
entries can be expanded or contracted. A prefix notation, either a + (plus)
|
|
or - (minus) sign, is used to show whether an index entry is expanded or
|
|
contracted. A minus sign indicates that all of the entries are displayed,
|
|
whereas a plus sign indicates that the entry can be expanded to show additional
|
|
index entries.</para>
|
|
<para>In <!--Original XRef content: 'Figure 1‐6 on page 10'--><xref
|
|
role="CodeOrFigOrTabAndPNum" linkend="HRDC.Intro.mkr.12">, the -36 prefix
|
|
means there are 36 index entries displayed. The +3 notation identifies contracted
|
|
entries. Selecting a contracted entry causes the list to expand, and the
|
|
+ sign changes to a - sign. The last index entry shown in the figure has
|
|
been expanded in this manner.</para>
|
|
<figure>
|
|
<title id="HRDC.Intro.mkr.12">Index entry prefix notation</title>
|
|
<graphic id="HRDC.Intro.grph.6" entityref="HRDC.Intro.fig.6"></graphic>
|
|
</figure>
|
|
</sect2>
|
|
<sect2 id="HRDC.Intro.div.21">
|
|
<title>Printing from Help<indexterm><primary>printing</primary><secondary>help information</secondary></indexterm></title>
|
|
<figure>
|
|
<title id="HRDC.Intro.mkr.13">Print dialog box</title>
|
|
<graphic id="HRDC.Intro.grph.7" entityref="HRDC.Intro.fig.7"></graphic>
|
|
</figure>
|
|
</sect2>
|
|
</sect1>
|
|
<sect1 id="HRDC.Intro.div.22">
|
|
<title id="HRDC.Intro.mkr.14">Help Topic Organization<indexterm><primary>help</primary><secondary>topic organization</secondary></indexterm></title>
|
|
<para>An author organizes help information into a logical framework. Most
|
|
times, but not always, this results in an outline, or a hierarchy of topics.
|
|
The topic hierarchy in <!--Original XRef content: 'Figure 1‐8'--><xref
|
|
role="CodeOrFigureOrTable" linkend="HRDC.Intro.mkr.15"> consists of a main
|
|
level, three sections, and subordinate topics. Although Help has been optimized
|
|
for information that is organized in a hierarchy, you are free to create
|
|
any kind of organization you want.</para>
|
|
<figure>
|
|
<title id="HRDC.Intro.mkr.15">Hierarchy of topics</title>
|
|
<graphic id="HRDC.Intro.grph.8" entityref="HRDC.Intro.fig.8"></graphic>
|
|
</figure>
|
|
<sect2 id="HRDC.Intro.div.23">
|
|
<title>Help Topic<indexterm><primary>topic</primary><secondary>defined</secondary>
|
|
</indexterm><indexterm><primary>help topic</primary><secondary>defined</secondary></indexterm></title>
|
|
<para id="HRDC.Intro.mkr.16">A <emphasis>help topic</emphasis> is a unit of
|
|
information identified with a unique ID. A set of tags provided by the Help
|
|
System is used to mark help topics and create a structural framework. The
|
|
Help Viewer, which is part of the Help System, is able to directly access
|
|
and display a help topic.</para>
|
|
</sect2>
|
|
<sect2 id="HRDC.Intro.div.24">
|
|
<title><indexterm><primary>help volume</primary><secondary>defined</secondary>
|
|
</indexterm><indexterm><primary>volume</primary><secondary>defined</secondary>
|
|
</indexterm>Help Volume<indexterm><primary>volume</primary><secondary>as
|
|
collection of topics</secondary></indexterm><indexterm><primary>topic</primary>
|
|
<secondary>volume as collection of</secondary></indexterm></title>
|
|
<para>A <emphasis>help volume</emphasis> is a collection of topics that describe
|
|
an application or a particular subject. If you are developing application
|
|
help, typically there's one help volume per application. However, for complex
|
|
applications, or a collection of related applications, you might develop
|
|
several help volumes.</para>
|
|
</sect2>
|
|
<sect2 id="HRDC.Intro.div.25">
|
|
<title><indexterm><primary>help family</primary><secondary>defined</secondary>
|
|
</indexterm>Help Family<indexterm><primary>family</primary><secondary>definition
|
|
of</secondary></indexterm><indexterm><primary>group of related volumes, family
|
|
as</primary></indexterm><indexterm><primary>related volumes, family as group
|
|
of</primary></indexterm><indexterm><primary>volume</primary><secondary>family
|
|
of volumes</secondary></indexterm></title>
|
|
<para>Often, software is available as a set of related applications known
|
|
as a <emphasis>product family</emphasis>. For example, a set of office productivity
|
|
applications may include a word processor, a spreadsheet application, and
|
|
a drawing program. Because each application may have its own help volume,
|
|
it may be desirable to group the related help volumes in a <emphasis>help
|
|
family.</emphasis> A help family can include a single help volume or several
|
|
volumes.</para>
|
|
<para>Assembling your help volumes into a help family is optional. It is required
|
|
only if you want your help available for browsing within a <emphasis>help
|
|
browser</emphasis> such as the Help Viewer in the Front Panel.</para>
|
|
<para>Refer to <!--Original XRef content: '“To Create a Help Family”
|
|
on page 95'--><xref role="SecTitleAndPageNum" linkend="HRDC.CrHV.mkr.11">
|
|
for a description of help family files and how they are used.</para>
|
|
</sect2>
|
|
<sect2 id="HRDC.Intro.div.26">
|
|
<title>Help Index Volume<indexterm><primary>volume</primary><secondary>desktop
|
|
index volume</secondary></indexterm><indexterm><primary>help index</primary>
|
|
</indexterm><indexterm><primary>help index volume</primary><secondary>defined</secondary></indexterm></title>
|
|
<para>The desktop provides a special help volume called the <emphasis>index</emphasis> volume that lists help installed on your system. Clicking the
|
|
Help Viewer control in the Front Panel displays the index volume shown in
|
|
<!--Original XRef content: 'Figure 1‐9'--><xref role="CodeOrFigureOrTable"
|
|
linkend="HRDC.Intro.mkr.17"> on <!--Original XRef content: 'page 13'--><xref
|
|
role="PageNum" linkend="HRDC.Intro.mkr.17">.</para>
|
|
<para>It lists help families (underlined titles) and any volumes that are
|
|
members of the help family.</para>
|
|
<figure>
|
|
<title id="HRDC.Intro.mkr.17">Index help volume</title>
|
|
<graphic id="HRDC.Intro.grph.9" entityref="HRDC.Intro.fig.9"></graphic>
|
|
</figure>
|
|
<para>The index volume allows access to application-specific help without
|
|
using the application. Or, if you are writing standalone help, this is the
|
|
only way for users to get to your help. Even if you have only a single help
|
|
volume, it must belong to a help family to be browsable using the Help Viewer.
|
|
</para>
|
|
<para><!--Original XRef content: '“Adding Your Help to the Browser
|
|
Volume” on page 94'--><xref role="SecTitleAndPageNum" linkend="HRDC.CrHV.mkr.8">
|
|
describes how to create a family file and what you need to do to make your
|
|
help volume accessible from the index volume.</para>
|
|
</sect2>
|
|
</sect1>
|
|
<sect1 id="HRDC.Intro.div.27">
|
|
<title id="HRDC.Intro.mkr.18">The Author's Job<indexterm><primary>author</primary><secondary>responsibilities</secondary></indexterm><indexterm>
|
|
<primary>job of author</primary></indexterm><indexterm><primary>responsibility</primary><secondary>author</secondary></indexterm></title>
|
|
<para>Writing online help differs from writing printed manuals, so it is important
|
|
to understand who you are writing for, how the information is accessed, and
|
|
how the information fits into an application.</para>
|
|
<sect2 id="HRDC.Intro.div.28">
|
|
<title>Objectives for Online Help<indexterm><primary>goals for online help</primary></indexterm><indexterm><primary>online help</primary><secondary>objectives</secondary></indexterm></title>
|
|
<para>The two most important objectives for designing quality online help
|
|
are:</para>
|
|
<itemizedlist remap="Bullet1"><listitem><para><emphasis>Get the user back
|
|
on task as quickly and successfully as possible.</emphasis></para>
|
|
</listitem><listitem><para><emphasis>Educate the user to prevent future need
|
|
for assistance</emphasis>.</para>
|
|
</listitem></itemizedlist>
|
|
<para>Applying these objectives will help you make decisions regarding what
|
|
type of help is best and what amount of detail is needed.</para>
|
|
</sect2>
|
|
<sect2 id="HRDC.Intro.div.29">
|
|
<title id="HRDC.Intro.mkr.19">Know Your Audience<indexterm><primary>audience</primary><secondary>knowing</secondary></indexterm></title>
|
|
<para>Just as with any writing, to do a good job, you must know your audience
|
|
and understand what they require from the information you are writing. Most
|
|
importantly, with online help, you need to know the tasks they are attempting
|
|
and the problems they may encounter.</para>
|
|
</sect2>
|
|
<sect2 id="HRDC.Intro.div.30">
|
|
<title id="HRDC.Intro.mkr.20">Consider How Your Help Is Accessed<indexterm>
|
|
<primary>help</primary><secondary>types of access</secondary></indexterm><indexterm>
|
|
<primary>application help</primary></indexterm></title>
|
|
<para>It is just as important to understand how users will access your help
|
|
as it is to identify your audience correctly.</para>
|
|
<sect3 id="HRDC.Intro.div.31">
|
|
<title>Application Help</title>
|
|
<para>If you are writing help for an application, you need to decide which
|
|
topics are browsable and which topics are available from the application
|
|
as <emphasis>context-sensitive help</emphasis>. A topic is browsable if you
|
|
can navigate to it using the topic tree or hyperlinks. Topics designed exclusively
|
|
for context-sensitive help might not be browsable because the only way to
|
|
display the topic may be from within a particular context in the application.
|
|
</para>
|
|
<para>You must also decide if you want your application's help volume to be <emphasis>registered</emphasis>. Registered help volumes can be displayed by other applications
|
|
(such as the Help Viewer), making the information more widely accessible.
|
|
If another help volume contains hyperlinks to topics in your help volume,
|
|
your help volume must be registered.</para>
|
|
<para>See <!--Original XRef content: '“Registering Your Application
|
|
and Its Help” on page 247'--><xref role="SecTitleAndPageNum"
|
|
linkend="HRDC.Inst.mkr.9"> for information about installing and registering
|
|
your application.</para>
|
|
</sect3>
|
|
<sect3 id="HRDC.Intro.div.32">
|
|
<title>Standalone Help Volumes<indexterm><primary>standalone help</primary>
|
|
</indexterm><indexterm><primary>volume</primary><secondary>standalone help</secondary></indexterm></title>
|
|
<para>If you are writing a standalone help volume (a help volume not associated
|
|
with an application), you may choose to do things differently.</para>
|
|
<para>First, you must provide a path for users to get to all the topics you've
|
|
written. That is, every topic must be browsable through at least one hyperlink.
|
|
Also, because there's no application associated with your help, you must
|
|
rely on a help viewer (such as Help Viewer) to display your help volume.</para>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="HRDC.Intro.div.33">
|
|
<title>Evaluate How to Present Help</title>
|
|
<para>An application can incorporate different types of help. It is important
|
|
to evaluate what kind of help is best suited for your application. For example,
|
|
the same help information may be presented in a variety of ways. Some choices
|
|
include key features, a tutorial, examples, task instructions, shortcuts,
|
|
troubleshooting, reference information, glossary of terms, or referral to
|
|
hard copy or other online documentation. A help volume often combines different
|
|
presentations.</para>
|
|
</sect2>
|
|
<sect2 id="HRDC.Intro.div.34">
|
|
<title id="HRDC.Intro.mkr.21">Collaborate with the Application Programmer<indexterm>
|
|
<primary>author</primary><secondary>collaboration with application programmer</secondary></indexterm><indexterm><primary>application programmer, collaborating
|
|
with</primary></indexterm><indexterm><primary>programmer, application</primary>
|
|
<secondary>collaborating with</secondary></indexterm></title>
|
|
<para>If you are writing application help, you should work closely with the
|
|
application programmer. The degree to which the Help System is integrated
|
|
into an application is a design decision that you make collectively.</para>
|
|
<para>If an application and its help have very loose ties, there may be only
|
|
a handful of topics that the application is able to display directly. This
|
|
is easier to implement.</para>
|
|
<para>In contrast, the application could provide specific help for nearly
|
|
every situation in the application. This requires more work, but benefits
|
|
the user if done well.</para>
|
|
<para>It's up to you and your project team to determine the right level of
|
|
help integration for your project.</para>
|
|
</sect2>
|
|
</sect1>
|
|
<sect1 id="HRDC.Intro.div.35">
|
|
<title id="HRDC.Intro.mkr.22">Author's Workflow<indexterm><primary>author</primary><secondary>workflow</secondary></indexterm></title>
|
|
<para>After designing your help, you create and process help topics to produce
|
|
a help volume. Your focus as an author is on these key tasks:</para>
|
|
<itemizedlist remap="Bullet1"><listitem><para>Write help topics</para>
|
|
</listitem><listitem><para>Create run-time help files</para>
|
|
</listitem><listitem><para>View the help volume</para>
|
|
</listitem></itemizedlist>
|
|
<sect2 id="HRDC.Intro.div.36">
|
|
<title id="HRDC.Intro.mkr.23">Write Help Topics with DocBook</title>
|
|
<para>Online help is written in ordinary text files. You use special codes,
|
|
or <symbol role="Variable">tags</symbol>, to markup <symbol role="Variable">elements</symbol> within the information. The tags form a markup language
|
|
called DocBook.</para>
|
|
<para>The DocBook markup language defines a hierarchy of <symbol role="Variable">elements</symbol> that define high-level elements, such as chapters, sections,
|
|
and subsections, and low-level elements such as paragraphs, lists, and emphasized
|
|
words.</para>
|
|
<para><!--Original XRef content: '“General Markup Guidelines”
|
|
on page 28'--><xref role="SecTitleAndPageNum" linkend="HRDC.OrgH.mkr.4">
|
|
gives a brief description of using markup.</para>
|
|
<sect3 id="HRDC.Intro.div.38">
|
|
<title id="HRDC.Intro.mkr.24">Formal Markup<indexterm><primary>formal markup</primary><secondary>defined</secondary></indexterm><indexterm><primary>markup</primary><secondary>formal (SGML)</secondary></indexterm><indexterm>
|
|
<primary>structured editor</primary></indexterm><indexterm><primary>editor,
|
|
structured</primary></indexterm></title>
|
|
<para><emphasis><indexterm><primary>markup language</primary><secondary>formal
|
|
markup, SGML-compliant</secondary></indexterm>Formal markup</emphasis> is
|
|
a Standard Generalized Markup Language (SGML) that an author can use to create
|
|
fully compliant SGML help topics. It requires start and end tags for <emphasis>all</emphasis> elements. Additionally, the structure of each element must
|
|
be explicitly tagged. Therefore, the number of tags increases significantly
|
|
using formal markup. Although an author can enter formal markup using a standard
|
|
editor, a structured editor is recommended.</para>
|
|
<sect4 id="HRDC.Intro.div.39">
|
|
<title>Structured Editors</title>
|
|
<para>New tools, called structured editors, are becoming available in response
|
|
to the need to create SGML markup efficiently. Typically, a structured editor
|
|
provides a context-sensitive menu. That is, the elements that appear in the
|
|
menu dynamically change based on the location of the cursor in the document.
|
|
</para>
|
|
<para>For example, if you are entering a list, then the menu contains only
|
|
elements that are valid within the context of a list element. This built-in
|
|
“intelligence” allows an author to create markup easily.</para>
|
|
<para>When an author chooses an element, such as section, title, or list,
|
|
the editor generates the corresponding start, end, and any intermediate structural
|
|
tags. For example, when an author selects a chapter element, the editor automatically
|
|
inserts the intermediate tags required by this element. The author simply
|
|
types the chapter title. Viewing the generated tags is optional; authors can
|
|
suppress the tags.</para>
|
|
</sect4>
|
|
<sect4 id="HRDC.Intro.div.40">
|
|
<title>Using Formal Markup</title>
|
|
<para>Before you use formal markup, first read the chapters in <citetitle>P<?Pub Caret1>art 2 - The Author's Job</citetitle> to become familiar with
|
|
the set of DocBook elements.</para>
|
|
<para><!--Original XRef content: ''--><xref role="Blank" linkend="HRDC.Sgml.mkr.1"> <!--Original
|
|
XRef content: 'Chapter 8, “Reading the DocBook Document Type
|
|
Definition'--><xref role="ChapNumAndTitle" linkend="HRDC.Sgml.mkr.1"> explains
|
|
key components of the Document Type Definition (DTD) and shows you how to
|
|
create formal markup. The complete DocBook Document Type Definition appears
|
|
in the <citetitle>Guide to the DocBook DTD</citetitle>.</para>
|
|
<note>
|
|
<para>The Developer's Kit includes the DocBook Document Type Definition. The
|
|
file is located in the <filename>/usr/dt/dthelp/dtdocbook/SGML/docbook.dtd</filename> directory and is named <filename>DocBook.dtd</filename>.</para>
|
|
</note>
|
|
</sect4>
|
|
</sect3>
|
|
<sect3 id="HRDC.Intro.div.41">
|
|
<title>See Also</title>
|
|
<itemizedlist><listitem><para>The <citetitle>Guide to the DocBook DTD</citetitle>
|
|
gives a detailed description of each major tag listed in alphabetical order.
|
|
</para>
|
|
</listitem><listitem><para><!--Original XRef content: 'Chapter 8, “Reading
|
|
the DocBook Document Type Definition'--><xref role="ChapNumAndTitle" linkend="HRDC.Sgml.mkr.1">
|
|
describes formal markup.</para>
|
|
</listitem><listitem><para><filename moreinfo="RefEntry">docbook.dtd(4)</filename> man page</para>
|
|
</listitem></itemizedlist>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="HRDC.Intro.div.42">
|
|
<title>Think Structure, Not Format</title>
|
|
<para>If you are familiar with other publishing systems, you may be accustomed
|
|
to formatting information as you like to see it. Authoring with DocBook requires
|
|
you to think about structure and content, not format.</para>
|
|
<para>As you write, you use tags to mark certain types of information. When
|
|
you do so, you are identifying <emphasis>what</emphasis> the information is,
|
|
but not how it should be formatted.</para>
|
|
<para>For instance, to refer to a book title, include markup like this:</para>
|
|
<programlisting><CiteTitle>System Administrator's Reference Guide</CiteTitle>
|
|
</programlisting>
|
|
<para>This abstraction separates structure and content from format, which
|
|
allows the same information to be used by other systems and perhaps formatted
|
|
differently. For instance, Help displays book titles using an italic font.
|
|
However, on another system an italic font may not be available, so the formatter
|
|
could decide that book titles are underlined.</para>
|
|
</sect2>
|
|
<sect2 id="HRDC.Intro.div.43">
|
|
<title id="HRDC.Intro.mkr.25">Create Run-Time Help Files<indexterm><primary>creating</primary><secondary>run-time help files</secondary></indexterm><indexterm>
|
|
<primary>run-time files</primary><secondary>creating</secondary></indexterm><indexterm>
|
|
<primary>files, run-time help</primary><secondary>creating</secondary></indexterm></title>
|
|
<para>The text files you write must be “compiled” using the DocBook
|
|
software to create <emphasis>run-time help files</emphasis>. It's the run-time
|
|
help files that are accessed when the user requests help. Run-time files
|
|
use the Semantic Delivery Language (SDL) format. This delivery language is
|
|
based on an SGML document type definition designed expressly for online information
|
|
delivery.<indexterm><primary>Semantic Delivery Language (SDL)</primary></indexterm><indexterm>
|
|
<primary>SDL (Semantic Delivery Language)</primary></indexterm></para>
|
|
<para>The Help System defines desktop actions and data types for help-specific
|
|
files. This lets you easily create a run-time file from your desktop by selecting
|
|
the icon of a help source file and choosing a menu command that processes
|
|
the file.<indexterm><primary>help</primary><secondary>actions</secondary>
|
|
</indexterm><indexterm><primary>actions, help</primary></indexterm><indexterm>
|
|
<primary>help</primary><secondary>data types</secondary></indexterm><indexterm>
|
|
<primary>data types, help</primary></indexterm> A <filename>.sdl</filename>
|
|
extension is used to identify run-time help files. If any errors occurred
|
|
during processing, they are reported in an error file ( <symbol role="Variable">volume</symbol><filename>.log</filename>).</para>
|
|
<para>Refer to <!--Original XRef content: '“Creating Run-Time Help
|
|
Files” on page 89'--><xref role="SecTitleAndPageNum" linkend="HRDC.CrHV.mkr.2">
|
|
for complete instructions to create a run-time help file. For general information
|
|
about desktop actions and data types, refer to the <citetitle>Advanced User's
|
|
and System Administrator's Guide</citetitle>.</para>
|
|
</sect2>
|
|
<sect2 id="HRDC.Intro.div.44">
|
|
<title id="HRDC.Intro.mkr.26">Review Help as the User Will See It<indexterm>
|
|
<primary>reviewing</primary><secondary>help as user will see it</secondary>
|
|
</indexterm><indexterm><primary>user'</primary></indexterm><indexterm><primary>s perspective, seeing help from</primary></indexterm><indexterm><primary>perspective, seeing help from user'</primary></indexterm><indexterm><primary>σ</primary></indexterm></title>
|
|
<para>During the authoring process, you will need to display your help so
|
|
you can interact with it just as your audience will. To display a help volume
|
|
from the desktop, double-click the file icon of the run-time help volume (<symbol role="variable">volume</symbol>.<filename>sdl</filename>). Or, you can also
|
|
display any help topic using the <command>dthelpview</command> command. <!--Original
|
|
XRef content: 'Chapter 4, “Processing and Displaying
|
|
a Help Volume'--><xref role="ChapNumAndTitle" linkend="HRDC.CrHV.mkr.1">,
|
|
describes both methods.</para>
|
|
<para>If you are writing application help, and the Help System has been integrated
|
|
into your application, you can view your help by running the application
|
|
and making help requests just as the user will.</para>
|
|
</sect2>
|
|
</sect1>
|
|
<sect1 id="HRDC.Intro.div.45">
|
|
<title id="HRDC.Intro.mkr.27">Programmer's Job<indexterm><primary>programmer,
|
|
application</primary><secondary>responsibility</secondary></indexterm><indexterm>
|
|
<primary>responsibility</primary><secondary>programmer</secondary></indexterm></title>
|
|
<para>As a programmer, you add code into your application so that when a user
|
|
requests context-sensitive help, the application displays help information
|
|
that is relevant to what the application is doing at that time.</para>
|
|
<note>
|
|
<para id="HRDC.Intro.mkr.28">The<filename>/usr/dt/share/examples/dthelp</filename>
|
|
directory contains source code for a sample program called <command>dthelpdemo</command>. It demonstrates how to add help dialogs to a Motif application.<indexterm>
|
|
<primary>sample application, integrated help</primary></indexterm></para>
|
|
</note>
|
|
<sect2 id="HRDC.Intro.div.46">
|
|
<title id="HRDC.Intro.mkr.29">Consider How Your Help Is Accessed</title>
|
|
<para>Providing useful information to the user requires considering the following:
|
|
</para>
|
|
<itemizedlist remap="Bullet1"><listitem><para>What confusing situation commonly
|
|
arise? Specific help in these situations can save users lots of time.</para>
|
|
</listitem><listitem><para>Why is the user asking for help now instead of
|
|
earlier or later? If there are several steps in a process and the user is
|
|
not at the first step, branch to information that is specific to the step
|
|
being done. This is more helpful than displaying the same information at each
|
|
step. If the user is at the first step, make available both detailed information
|
|
about the first step and an overview of all the steps.</para>
|
|
</listitem><listitem><para>Is the user requesting context-specific help or
|
|
just browsing the help information? If it is context-specific, supply information
|
|
that's relevant to the task now being done.</para>
|
|
</listitem></itemizedlist>
|
|
</sect2>
|
|
<sect2 id="HRDC.Intro.div.47">
|
|
<title id="HRDC.Intro.mkr.30">Collaborate with the Help Author</title>
|
|
<para>Close collaboration with the online help author is needed because the
|
|
author needs to know how each context-specific topic is reached and the programmer
|
|
needs to know what is explained in each context-specific topic. Without such
|
|
coordination, the user may see irrelevant, ambiguous, or misleading information.
|
|
</para>
|
|
<para>Collaboration makes the best use of the programmer's understanding of
|
|
the application and the author's understanding of how to best communicate
|
|
relevant information to the user.</para>
|
|
</sect2>
|
|
<sect2 id="HRDC.Intro.div.48">
|
|
<title>Identify Help Entry Points</title>
|
|
<para>An application provides online help by establishing help <emphasis>entry points</emphasis>. Entry points are defined in the application and associated
|
|
with specific help topics. Each of the ways that a user can request help—the
|
|
Help key, button, or menu—represent entry points. For example, consider
|
|
an application with a Print dialog box that has a Help button. The author
|
|
writes a help topic that describes the contents of the dialog box and supplies
|
|
you with the ID of the topic. You can then associate the ID of the help topic
|
|
with the Help button using a callback routine.</para>
|
|
</sect2>
|
|
<sect2 id="HRDC.Intro.div.49">
|
|
<title id="HRDC.Intro.mkr.31">Create and Manage Help Dialogs</title>
|
|
<para>The Help System application program interface is designed especially
|
|
for use with Motif applications. Specifically, Help extends the Motif
|
|
widget set by providing two new widget classes (plus convenience functions
|
|
to manipulate them):</para>
|
|
<itemizedlist remap="Bullet1"><listitem><para><emphasis>General help dialog</emphasis>, which provides a help window that includes a menu bar and a topic
|
|
tree, in addition to a help topic display area.</para>
|
|
</listitem><listitem><para><emphasis>Quick help dialog</emphasis>, which provides
|
|
a simple help window with a topic display area and a few dialog buttons.</para>
|
|
</listitem></itemizedlist>
|
|
<para>You can use either or both of these types of help windows within your
|
|
application. Once the application is compiled (with the Help library), the
|
|
help windows become part of the application.</para>
|
|
<para><!--Original XRef content: 'Chapter 9, “Creating and Managing
|
|
Help Dialog Boxes'--><xref role="ChapNumAndTitle" linkend="HRDC.CrDia.mkr.1">,
|
|
describes the general help and quick help dialog boxes.</para>
|
|
</sect2>
|
|
<sect2 id="HRDC.Intro.div.50">
|
|
<title>Package and Distribute Help</title>
|
|
<para>Your product package includes both the run-time help file ( <symbol role="variable">volume</symbol>.<filename>sdl</filename>) and its graphics files. Additionally,
|
|
you can provide a help family file that enables your volume to be viewed using
|
|
the Front Panel Help Viewer.</para>
|
|
<para>If the help volume uses execution links, you should collaborate with
|
|
the author to include the appropriate execution link resources in your application's
|
|
application defaults file. <!--Original XRef content: 'Chapter 13, “Preparing
|
|
an Installation Package'--><xref role="ChapNumAndTitle" linkend="HRDC.Inst.mkr.1">,
|
|
discusses which help files are delivered with your application.</para>
|
|
</sect2>
|
|
</sect1>
|
|
</chapter>
|
|
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 16:48:20-->
|
|
<?Pub *0000050603>
|