Creating Structure within a Topic

Within the body of a help topic, you have the following elements to choose from to organize and present your information:

Paragraphs are used for bodies of text.
Lists are used for listed information. There are several types of lists: ItemizedLists (bulleted), OrderedLists (numbered), VariableLists (for defining lists of terms), and SegmentedLists (for comparably labelled sets of information).
Tables are for structured arrays of information. There are InformalTables (untitled) and Tables (which require a Title).
Graphics can be included within your text as inline elements or displayed between paragraphs as standalone block-oriented elements. A Graphic points to exterior files that contain the graphical data
Hyperlinks provide references to related topics. A hyperlink may lead to a subtopic, deeper in the hierarchy, or branch to a topic in a completely different part of the hierarchy, or even in another help volume.
Computer literals are computer-recognized text, such as file names and variable names, that can be displayed as either separate example listings or inline elements.
Notes, cautions, and warnings call the reader's attention to important information.
Emphasis is used to highlight important words and phrases within paragraph text.

To Start a Paragraph

Generally you use the <Para> tag to mark the start of a new paragraph. The DocBook DTD offers three kinds of paragraphs. Para may contain block-oriented elements (such as Lists and Figures). SimPara may contain only plain text and in-line elements. FormalPara requires a Title.

If you want the paragraph to maintain the line breaks that you enter in your source file, use the <LiteralLayout> tag.

Examples

Here is an example of a plain vanilla paragraph:

<para>The Application Builder provides an interactive, graphical environment that facilitates the development of desktop applications. </para>

The following LiteralLayout overrides the automatic word wrap in help windows and maintains the line breaks exactly as entered in the source file. The LiteralLayout element is especially useful for entering addresses.

<LiteralLayout>
Brown and Reed Financial Investors
100 Baltic Place  Suite 40
New York, New York
</LiteralLayout>

To Enter an ItemizedList

An ItemizedList is a list in which every item is marked with a bullet, dash, or other dingbat, or no mark at all. An ItemizedList contains one or more ListItems.

A ListItem in an ItemizedList can contain paragraphs and other block-oriented elements, including other lists.

You can use the Mark attribute to specify the mark you want used in the ItemizedList. There is no fixed list of values for the Mark attribute, but you can used the ISO text entity that designates the dingbat you want used. Your application might supply the mark that will be used for an ItemizedList.

Here is the syntax you use for the ItemizedList element:

<ItemizedList Mark="Bullet">
        <ListItem>
                <para> ... </para>
        </ListItem>
        <ListItem>
                <para> ... </para>
        </ListItem>
        ...
</ItemizedList>

Examples

Here is the markup for a simple ItemizedList:

<itemizedlist>
<listitem><para>Creating a Mail Message</para></listitem>
<listitem><para>Sending a Message</para></listitem>
<listitem><para>Reading Your Mail</para></listitem>
</itemizedlist>

The preceding markup would produce an ItemizedList that might appear as follows:

Creating a Mail Message
Sending a Message
Reading Your Mail

To Enter an OrderedList

An OrderedList contains ListItems marked with numbers or letters. A ListItem within an OrderedList can contain paragraphs and other block-oriented elements, including ItemizedLists and OrderedLists.

OrderedList has the Common attributes, and also Numeration, InheritNum, and Continuation attributes.

The Numeration attribute specifies how the ListItems in the OrderedList will be numbered or lettered. It may take the values Arabic, Upperalpha, Loweralpha, Upperromman, or Lowerroman. If no value is specified, the expectation should be that Arabic numbering is to be used.

The InheritNum attribute takes on the values Inherit or Ignore. If the value is Inherit, it specifies that the numbering of ListItems in a nested list should include the number of the ListItem within which it is nested. That is, if another Orderedlist is nested in the second ListItem, the ListItems of the nested list will be numbered 2a, 2b, 2c, etc., rather than simply a, b, c, etc.

The Continuation attribute takes on the values Continues or Restarts. If the value is Continues, the numbering of the OrderedList continues that of the immediately preceding OrderedList. If the value is Restarts (the default), the numbering of the OrderedList begins afresh. You need to supply the Continuation attribute only if this OrderedList continues the numbering of the preceding one.

Syntax Example

The following markup:

<OrderedList>
        <ListItem>
                <para>Creating a Mail Message</para>
        </ListItem>
        <ListItem>
                <para>Sending a Message</para>
        </ListItem>
        <ListItem>
                <para>Reading Your Mail</para>
                        </ListItem>
</OrderedList>

Produces the following list:

Creating a Mail Message
Sending a Message
Reading Your Mail

To Enter a SegmentedList

SegmentedList marks a list segmented into labelled parallel sets of information.

A SegmentedList may have an optional Title and TitleAbbrev, followed by any number of SegTitles, and one or more SegListItems. Each SegListItem has the same number of Segs as there are SegTitles in the SegmentedList to which it belongs.

Syntax Example

The following is a markup for a SegmentedList:

<SegmentedList>
        <SegTitle>Nation</SegTitle>
        <SegTitle>Ethnic Groups</SegTitle>
        <SegTitle>Languages</SegTitle>
        <SegListItem>
                <Seg>Japan</Seg>
                <Seg>Japanese, Koreans, Ainu</Seg>
                <Seg>Japanese</Seg>
        </SegListItem>
        <SegListItem>
                <Seg>Spain</Seg>
                <Seg>Spanish, Basques</Seg>
                <Seg>Castillian, Catalan, Basque</Seg>
        </SegListItem>
        <SegListItem>
                <Seg>Belgium</Seg>
                <Seg>Flemish, Walloons<</Seg>
                <Seg>Dutch, French</Seg>
        </SegListItem>
</SegmentedList>

Would produce a list which might appear like this:

Nation: Japan

Ethnic Groups: Japanese, Koreans, Ainu

Languages: Japanese

Nation: Spain

Ethnic Groups: Spanish, Basques

Languages: Castillian, Catalan, Basque

Nation: Belgium

Ethnic Groups: Flemish, Walloons

Languages: Dutch, French

To Enter a VariableList

The VariableList element is used to create a list of terms and their definitions.

VariableList may have an optional Title and TitleAbbrev, followed by one or more required VarListEntries.

VarListEntry is a required component of a VariableList. VarListEntry contains a Term element, which marks the term being defined, and a ListItem element, which holds the definition of the term.

Example

Here is the syntx of the markup for a VariableList:

<VariableList>
        <varlistentry>
                <term>first term</term>
                <listitem><para>definition of first term </para><listitem>
        </varlistentry>
        <varlistentry>
                <term>second term</term>
                <listitem><para>definition of second term </para><listitem>
        </varlistentry>
        ...
</VariableList>

To Show a Computer Listing

To show sections of program source code without changing the spacing or line breaks, use the ProgramListing element. Line breaks and leading white space are considered significant in a ProgramListing and preserved as-is.

ProgramListing may contain inline elements, including LineAnnotations. (LineAnnotations are comments on the code by the document author, not the comments written into the code itself by the author of the code.

A ProgramListing may be embedded within the Example element. Example typically contains a required Title and a ProgramListing.

ProgramListing has a Width attribute, which takes on numerical values representing the maximum width of the contents.

Line breaks appear where you enter them in your source file. If the example is too wide for the help window, a horizontal scroll bar appears so the user can scroll to see all the example text.




	WARNING! Do not include character sequences within a ProgramListing that could be interpreted as DocBook markup tags. To avoid this problem, use "<" (the entity reference for the opening angle bracket) rather than "<" to begin the names of markup tags.

Example

In the following markup the ProgramListing element is used to represent a directory listing in a terminal window.

<programlisting>In this tutorial, you will edit these graphics files:
H_ActionIcons.xwd     H_HelpWindows.xwd
H_AppHelp.xwd         H_Hyperlinks.xwd
H_Canonical.xwd       H_Icons.xwd
H_FrontPanel.xwd      H_InlineGraphic.xwd
</programlisting>

The markup produces this output:

In this tutorial, you will edit these graphics files:
H_ActionIcons.xwd     H_HelpWindows.xwd
H_AppHelp.xwd         H_Hyperlinks.xwd
H_Canonical.xwd       H_Icons.xwd
H_FrontPanel.xwd      H_InlineGraphic.xwd

To Add a Note, Caution, or Warning

Use the Note, Caution, and Warning elements as follows:

<note>
Body
of note here.
</note>
 
<caution>
Body of caution here
</caution>
 
<warning>
Body of warning here.
</warning>

The icons associated with the Note, Caution, and Warning elements are obtained from the following graphics files, relative to your .sdl file:

graphics/noteicon.pm

graphics/cauticon.pm

graphics/warnicon.pm

The default icons are in/usr/dt/appconfig/help/C/graphics. If you create your own icons, be sure to keep them small, so they will fit into the area allotted.

Example

The following markup for a note, warning, and caution produces the output shown in Figure 3-1 “Note, warning, and caution help icons”

<note>
Before installing your application, complete the options checklist to determine the amount of disk space required.
</note>
 
<warning>
This product is highly acidic and can cause skin irritation. Wearing protective gloves is mandatory when applying this product.
</warning>
 
<caution>
Do not place your fingers near the parrot cage!
</caution>

Figure 3-1 Note, warning, and caution help icons

Creating Structure within a Topic

Technical documentation

» Table of Contents

» Glossary

» Index

To Start a Paragraph

Examples

To Enter an ItemizedList

Examples

To Enter an OrderedList

Syntax Example

To Enter a SegmentedList

Syntax Example

To Enter a VariableList

Example

To Show a Computer Listing

Example

To Add a Note, Caution, or Warning

Example