HP OpenVMS Systems Documentation
Common Desktop Environment: Help System Author's and Programmer's Guide
1 Introducing the Help System
Contents of Chapter:
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.
For Application Developers
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.
Part of the ApplicationHelp 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.
How Users Get HelpA 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 KeyWithin 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 MenuThe 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 ButtonsMany 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.
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 WindowsWhen 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
HyperlinksHelp 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
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.The general help dialog includes three dialog buttons: Backtrack, History, and Index. These features are also available as menu selections.
Help MenusA 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:
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
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
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
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.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.
Application HelpIf 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.
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 HelpAn 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.
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.
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.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 EditorsNew 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 MarkupIf 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 /
Think Structure, Not FormatIf 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:
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.
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
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.
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.
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 AccessedProviding useful information to the user requires considering the following:
Collaborate with the Help AuthorClose 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 PointsAn 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 DialogsThe 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):
Chapter 9, "Creating and Managing Help Dialog Boxes," describes the general help and quick help dialog boxes.
Package and Distribute HelpYour product package includes both the run-time help file (volume.
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.