test

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

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 runtime 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 II - 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