Author's Workflow

Write Help Topics with DocBook

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

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

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

Using Formal Markup

Before you use formal markup, first read the chapters in Part 2 - The Author's Job to become familiar with the set of DocBook elements.

Chapter 7 “Reading the DocBook Document Type Definition” 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 Guide to the DocBook DTD.

	NOTE: The Developer's Kit includes the DocBook Document Type Definition. The file is located in the /usr/dt/dthelp/dtdocbook/SGML/docbook.dtd directory and is named DocBook.dtd.

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 DocBook 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:

<CiteTitle>System Administrator's Reference Guide</CiteTitle>

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 DocBook 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.log).

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