test

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

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 Chapter 5, 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.