Common Desktop Environment: Help System Author's and Programmer's Guide

1 Introducing the Help System

Contents of Chapter:
Introduction to the Help System
Developer's Toolkit
Overview of Online Help
Help Information Model
Part of the Application
Types of Help
How Users Get Help
Help User Interface
Help Windows
Hyperlinks
Help Navigation
Help Menus
Help Index
Printing from Help
Help Topic Organization
Help Topic
Help Volume
Help Family
Help Browser Volume
The Author's Job
Objectives for Online Help
Know Your Audience
Consider How Your Help Is Accessed
Evaluate How to Present Help
Collaborate with the Application Programmer
Author's Workflow
Write Help Topics with HelpTag
Think Structure, Not Format
Create Run-Time Help Files
Review Help as the User Will See It
Programmer's Job
Consider How Your Help Is Accessed
Collaborate with the Help Author
Identify Help Entry Points
Create and Manage Help Dialogs
Package and Distribute Help
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.

Introduction to the Help System

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.

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.

Developer's Toolkit

The Help System Developer's Toolkit contains tools to write, process, and view online help and contains an application programming library.

For Authors
Refer to Chapter 2, "Organizing and Writing a Help Volume," to learn more about creating and processing online help.

For Application Developers
Chapters 9 through 13 discuss the application programming library.

Overview of Online Help

It's virtually impossible--and certainly impractical--for anyone to learn and remember everything 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.

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." Context-sensitive 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.

Help Information Model

There are two general styles of online help:

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.

Part of the Application

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.

Staying close to the application makes users more comfortable with online help and gets them back on task as quickly as possible.

Types of Help

Online help can be divided into three general categories:

How Users Get Help

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.

Help Key

Within most applications, the primary way for a user to request help is by pressing the help key. In recent years, the F1 function key has become a defacto standard help key for many workstation and personal computer products.

The CDE Style Guide and Certification Checklist recommends the use of F1 as the help key, and the OSF/Motif programmer's toolkit even provides some built-in behavior to make it easier to implement the help key in OSF/Motif applications.

Some computers provide a Help key on the keyboard.

Help Menu

The Help menu is a common way to provide access to help information. OSF/Motif applications provide a Help menu, which is right-justified in the menu bar. The CDE Style Guide and Certification Checklist makes recommendations regarding the commands contained in a Help menu.

Figure 1-1 Application Help menur

Help Buttons

Many dialog boxes also provide a Help button to get help on the dialog. The CDE Style Guide and Certification Checklist 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.

Help User Interface

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 CDE User's Guide; or, to view the corresponding online help, you can open the desktop Front Panel Help Viewer (see "To Display the Browser Volume"). Then choose Common Desktop Environment and Desktop Help System.

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.

Help Windows

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.

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.

Figure 1-2 General help and quick help window



Hyperlinks

Help topics often contain hyperlinks that "jump" to related help information. Both text and graphics can be used as hyperlinks. Figure 1-3 shows formatting styles used to identify hyperlinks.

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.

Figure 1-3 Formats for graphic and text hyperlinks

Help Navigation

The topic tree shown in Figure 1-4 is an outline of topics in the current help volume. The first topic at the top of the list is the home topic, or beginning of the help volume. An arrow () points to the current topic and shows the user's location in the help volume.

Figure 1-4 Topic tree in a general help dialog box

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.

Help Navigation Buttons

The general help dialog includes three dialog buttons: Backtrack, History, and Index. These features are also available as menu selections.

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 browser help volume.

Help Menus

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:

Help Index

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.

Figure 1-5 Index search dialog box

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.

In Figure 1-6, 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.

Figure 1-6 Index entry prefix notation

Printing from Help

The user can print an individual help topic, a table of contents and index, or the entire help volume. Printed output is text-only. Printing options, such as paper size, number of copies, and destination printer, can also be set in the Print dialog box.

Figure 1-7 Print dialog box

Help Topic Organization

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 Figure 1-8 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.

Figure 1-8 Hierarchy of topics

Help Topic

A help topic 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.

Help Volume

A help volume 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.

Help Family

Often, software is available as a set of related applications known as a product family. 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 help family. A help family can include a single help volume or several volumes.

Assembling your help volumes into a help family is optional. It is required only if you want your help available for browsing within a help browser such as the Help Viewer in the Front Panel.

Refer to "To Create a Help Family" for a description of help family files and how they are used.

Help Browser Volume

The desktop provides a special help volume called the browser volume that lists help installed on your system. Clicking the Help Viewer control in the Front Panel displays the browser volume shown in Figure 1-9.

It lists help families (underlined titles) and any volumes that are members of the help family.

Figure 1-9 Browser help volume

The browser 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.

"Adding Your Help to the Browser Volume" describes how to create a family file and what you need to do to make your help volume accessible from the browser volume.

The Author's Job

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.

Objectives for Online Help

The two most important objectives for designing quality online help are:

Applying these objectives will help you make decisions regarding what type of help is best and what amount of detail is needed.

Know Your Audience

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.

Consider How Your Help Is Accessed

It is just as important to understand how users will access your help as it is to identify your audience correctly.

Application Help

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 context-sensitive help. 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.

You must also decide if you want your application's help volume to be registered. 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.

See "Registering Your Application and Its Help" for information about installing and registering your application.

Standalone Help Volumes

If you are writing a standalone help volume (a help volume not associated with an application), you may choose to do things differently.

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.

Evaluate How to Present Help

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.

Collaborate with the Application Programmer

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.

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.

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.

It's up to you and your project team to determine the right level of help integration for your project.

Author's Workflow

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:

Write Help Topics with HelpTag

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 HelpTag.

The 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.

"General Markup Guidelines" gives a brief description of using markup. For a detailed description of each element see "HelpTag Markup Reference".

Shorthand Markup

The tag set can be used in two different ways to produce run-time help files: shorthand markup or formal markup. The first approach, called shorthand markup, is optimized for authors using a standard text editor to "hand-tag" information. That is, the author types the tags in addition to the actual help topic text. To minimize the impact of hand-tagging, shorthand markup incorporates several shortcuts. First, it reduces the number of required start and end tags. It also offers simple character combinations for frequently used markup and stylistic changes.

Formal Markup

Formal markup 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 all 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.

Structured Editors
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.

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.

When an author chooses an element, such as section, head, 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.

Note: Either markup approach-- shorthand or formal-- produces identical online information when compiled and displayed. Choosing which markup approach to use depends on the requirements for your help information and your available authoring tools.

Using Formal Markup
If you intend to use formal markup, first read the chapters in Part 2 - The Author's Job to become familiar with the set of HelpTag elements. Although shorthand and formal markup share the same tag set, there are several important differences.

Chapter 8, "Reading the HelpTag Document Type Definition," explains key components of the Document Type Definition (DTD) and shows you how to create formal markup. The complete HelpTag Document Type Definition appears in Appendix A.

Note: The Developer's Kit includes the HelpTag Document Type Definition. The file is located in the /usr/dt/dthelp/dthelptag/dtd directory and is named helptag.dtd.

See Also

Think Structure, Not Format

If you are familiar with other publishing systems, you may be accustomed to formatting information as you like to see it. Authoring with HelpTag requires you to think about structure and content, not format.

As you write, you use tags to mark certain types of information. When you do so, you are identifying what the information is, but not how it should be formatted.

For instance, to refer to a book title, include markup like this: 

<book>System Administrator's Reference Guide</book>
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.

Create Run-Time Help Files

The text files you write must be "compiled" using the HelpTag software to create run-time help files. 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.

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. A .sdl extension is used to identify run-time help files. If any errors occurred during processing, they are reported in an error file (volume.err).

Refer to "Creating Run-Time Help Files" for complete instructions to create a run-time help file. For general information about desktop actions and data types, refer to the CDE Advanced User's and System Administrator's Guide.

Review Help as the User Will See It

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 (volume.sdl). Or, you can also display any help topic using the dthelpview command. Chapter 4, "Processing and Displaying a Help Volume," describes both methods.

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.

Programmer's Job

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.

Note: The/usr/dt/share/examples/dthelp directory contains source code for a sample program called dthelpdemo. It demonstrates how to add help dialogs to an OSF/Motif application.

Consider How Your Help Is Accessed

Providing useful information to the user requires considering the following:

Collaborate with the Help Author

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.

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.

Identify Help Entry Points

An application provides online help by establishing help entry points. 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.

Create and Manage Help Dialogs

The Help System application program interface is designed especially for use with OSF/Motif applications. Specifically, Help extends the OSF/Motif widget set by providing two new widget classes (plus convenience functions to manipulate them):

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.

Chapter 9, "Creating and Managing Help Dialog Boxes," describes the general help and quick help dialog boxes.

Package and Distribute Help

Your product package includes both the run-time help file (volume.sdl) 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.

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. Chapter 13, "Preparing an Installation Package," discusses which help files are delivered with your application.

Generated with CERN WebMaker