This chapter describes elements that you can use to structure your text. It also explains how to include graphics and how to create hyperlinks to other help topics. A help topic is a unit of information identified with a unique ID. Help topics are grouped into a logical framework that best describes the product for which you are writing online help. The hierarchy of elements provided by DocBook gives you the framework for organizing the help topics you write. The hierarchy of elements is as follows: Chapter, Sect1, Sect2, Sect3, Sect4, and Sect5. A topic's position within the hierarchy is determined by the element which contains it, and how that element is embedded in higher level elements. For example, if a topic that is tagged as Sect2 follows a topic tagged as Sect1, that makes it a subtopic of the Sect1 topic. An ID is required if the topic is to be accessed either from the application (if you are writing application help) or from a hyperlink. Typically both the element that contains the topic and its title will be marked with IDs. ID is one of the attributes of the elements Chapter, Sect1, Sect2, Sect3, Sect4, Sect5, and Title. The following line marks the start of a topic using the <Sect1> tag: <sect1 id="HRDC.WrTop.div.2"> A Title is required for the elements Chapter, Sect1, Sect2, Sect3, Sect4, Sect5, and immediately follows the start tag of the element. The markup would look like this: <sect1 id="HRDC.WrTop.div.2"> <title>Help Topics</title> , describes the general structure of a help volume, including how to create a topic hierarchy. 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. 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. 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> 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> 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 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. 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 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. 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 Ethnic Groups Languages Japan Japanese, Koreans, Ainu Japanese Spain Spanish, Basques Castillian, Catalan, Basque Belgium Flemish, Walloons Dutch, French 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. 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 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. Do not include character sequences within a ProgramListing that could be interpreted as DocBook markup tags. To avoid this problem, use "&lt;" (the entity reference for the opening angle bracket) rather than "<" to begin the names of markup tags. 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 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. The following markup for a note, warning, and caution produces the output shown in . <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>

Inline elements are used to mark words or phrases within a paragraph of text. These elements affect the font used to format particular items. Use the Emphasis element as shown: <emphasis>text </emphasis> Here's how you might emphasize an important word: A thousand times <emphasis>no</emphasis> Use the CiteTitle element as shown: <CiteTitle> title of a Book</CiteTitle> Here's how you would cite the title of this guide: <CiteTitle>The Help System Author's and Programmer's Guide<CiteTitle> Use the Title element as shown: <Title> title of the Book, Chapter, or Section</Title> Here's how you would cite the title of this section: <Title>To Mark the Title of a Book, Chapter, or Section</Title> To display data presented to the user by a computer use the ComputerOutput element as follows: <computeroutput> text</computeroutput> To display the name of a computer file, use the Filename element as follows: <filename>some filename</filename> This markup: Add the entity to your <filename>Volume.sgm</filename> file. produces this output: Add the entityto your Volume.sgm file. To dispaly a variable, use the Symbol element as shown: <symbol Role="Variable"> text</symbol> This command-line syntax uses a variable to show that the user supplies a file name. dtpad <symbol Role="Variable">filename</symbol> It produces this output: dtpad filename Symbol can appear within ComputerOutputs or ProgramListings. A hyperlink references a specific topic or location in a help volume. This requires that the element you want to reference is given a unique ID. All the DocBook elements with the common attributes can be assigned IDs, including Chapters, Sects, Titles, Lists, Graphics, and Tables. Four DocBook elements are used in creating hyperlinks: Link, Anchor, OLink, and XRef. Link marks a hypertext link. Link may contain in-line elements, and it has Linkend and Type attributes. The Linkend attribute is required. It specifies the target of the link by giving the ID of the element the Link is linked to. Link uses the SGML mechanism of IDREF in pointing to an element by its ID. An SGML application may report an IDREF error when the ID specified in a Linkend attribute does not occur in the document set being processed. Link has a Type attribute which may take the following values: Jump, JumpNewView, AppDefined, and Man. A Jump link is the most common type of hyperlink. When the user chooses a Jump link, the related topic is displayed. JumpNewView links are intended for cross-volume links. When the user chooses a JumpNewView link, a new dialog box containing information is displayed. An AppDefined link is for invoking some application behavior. To invoke this behavior, the help must be displayed in dialogs created by the application. A Man link, when activated, displays a “man page” which gives a brief online explanation of a system command. The information on man pages is not supplied through the DocBook system. Anchor marks a target for a Link. Anchor is an inline element that may appear almost anywhere. Anchor is an empty element, with no content. (Of course any element with an ID can serve as the target of a Link.) Anchor has a required ID attribute. At the minimum, only the Anchor start tag is present, with an ID. OLink marks a link that may perform some operation to find its target. OLink has a TargetDocEnt attribute, the value of which is the name of a text or data entity already specified by the user. OLink has a LinkMode attribute which points by an ID to a ModeSpec (located for convenience in the BookInfo or DocInfo), which contains instructions for operating on the entity named by the TargetDocEnt attribute. For example, the TargetDocEnt may be another book, and the LinkMode attribute may specifiy a ModeSpec that calls for all second-level headings to be searched for a particular phrase. XRef marks a cross reference link to another part of the document. Like Link, XRef has Linkend attribute, but like Anchor, it may have no content. The Title of the element specified by the Linkend attribute is used as they text of the cross reference. This Link gives the label of a hot spot explicitly: To go there,<Link Linkend="H1-122-ch10-1> click here.</Link> This Link points to a section and displays its title as the hot spot: Click to go to <Link Linkend="S1-123-ch12-1" Endterm="T1-123-ch12-1"></Link> The following example references the section of the document that has the ID "ch05-s1" and supplies the text of its Title. See <Xref Linkend="ch05-s1"> for more information. It might be displayed like this: "See Terminal Emulation and Terminal Type for more information." There is an Anchor <anchor id=“077-ch02-AN-7”> in this sentence. If you are linking to a term in the Glossary, use the GlossTerm element as shown: <GlossTerm>text</GlossTerm> Whenever you use the GlossTerm element in the text, be sure you include a corresponding GlossEntry in the Glossary that gives the definition of the term. Help supports four graphics formats: Tagged Image File Format (TIFF)—Color, grayscale, and black-and-white images created by many standard drawing and scanning applications (filename.tif). X Window dump—Screen dumps from the X Window System™ created with the xwd utility ( filename.xwd) X pixmap—Color icon images (filename.pm). X bitmap—Two-color icon images (filename.bm). Each graphic is maintained as a separate file. The file format is determined using the file name extensions listed. The Graphic element points via its attributes to an external file containing graphical data. A Graphic may be contained within a Figure. Figure must have a Title, and may also contain a Link. A Graphic is to be rendered as an object, not in-line. For in-line objects, use the InlineGraphic element. Graphic has the following attributes: Fileref, Entityref, and ID. The value of the Fileref attribute should be a filename, qualified by a pathname if desired. The value of the Entityref attribute should be that of an external data entity. Here are some examples of the syntax of Graphic: <graphic id="ABUG.edprp.igrph.1" entityref="ABUG.edprp.fig.1"></graphic> <graphic id="ABUG.crobj.igrph.2" entityref="ABUG.crobj.fig.2"></graphic> <graphic id="ABUG.crobj.igrph.1" entityref="ABUG.crobj.fig.1"></graphic> Declare a file entity to identify the image file to be included in the Graphic that will be contained inside the Figure. <!entity graphic-entity SYSTEM “filename.ext”> Use the Graphic element as shown: <Graphic id="id"> entityref=" graphic-entity"<Graphic> Where graphic-entity is the entity name for the graphic file you want to display. If you want the Figure to be a hyperlink, use InlineGraphic instead of Graphic, and put it inside a Link element. Many special characters and symbols are available within DocBook. You display a particular character by entering the appropriate entity reference. Refer to , for a complete list of the available characters. Refer to , to determine the entity name for the character you want to display. Determine which ISO entity file contains the special character, and add the following two lines among your other entity declarations (where entity-name is a meaningful name to you): <!entity & ISOset PUBLIC "ISOsetpublicID"> % ISOset; Wherever you want to display the special character, enter its entity reference: &entity-name; To entity for the copyright symbol (©) is included in the ISO numeric set, so you must first include the ISO numeric entities (at the top of your help volume with your other entity declarations) as shown here: <!ENTITY % ISOnumeric PUBLIC "ISO 8879-1986//ENTITIES Numeric and Special Graphic//EN"> %ISOnumeric; Then you can place the following entity reference where the copyright symbol is to appear: &copy; To display the uppercase Greek letter sigma (∑), you must first include the ISO Greek entities (at the top of your help volume with your other entity declarations) as shown here: <!ENTITY % ISOgreek PUBLIC "ISO 8879-1986//ENTITIES Greek Symbols//EN"> %ISOgreek; Then you can place the following entity reference where the sigma character is to appear: &Sigma; As with any entity, case is not significant in the entity names for special characters. Frequently it is useful to include within your source files comments that are not intended to be part of the help text. Text marked with the Comment element is always ignored by the DocBook software. Comments can be used to make notes to yourself or to another author, or to exclude some markup without taking it out of the file. A Comment may appear almost anywhere in the document, and may contain paragraphs and other block-oriented elements, but a Comment cannot be nested within another Comment. <comment> comment text here </comment> Use the comment begin marker <Comment> and end marker </Comment> as shown: <comment> comment text here </comment> Here's an example that has two comments, a line before the paragraph, and a single word within the paragraph. <Comment>Here is my rough draft of the introduction: </Comment> Welcome to my application. This software is <Comment>perhaps</Comment>the fastest and most efficient software you'll ever own. The index for a help volume is similar to the index for a book. As an author, it is important to create index entries for your topics that will allow users to search for keywords or concepts. Creating a thorough index ensures that users will be able to find topics quickly and accurately. In the DocBook markup, an IndexTerm is the tag for a word or phrase in the help volume text that you want to be included in the index. An IndexEntry is the element in the Index that holds the references to the IndexTerm. Thus IndexEntries might be constructed by extracting and processing the IndexTerms. IndexTerms are words or phrases to be indexed. IndexTerms may occur almost anywhere in the text flow, but are not part of the text itself. That is, the contents of IndexTerm do not appear in the text itself. An IndexTerm must contain a Primary, and may contain a See and one or more SeeAlsos, as well as a Secondary. Secondary, in turn, may contain a See and one or more SeeAlsos, as well as a Tertiary. IndexTerm has the Common attributes, and also SpanEnd and Significance attributes. An empty IndexEntry with the SpanEnd attribute is used to mark the end of a span of text that begins earlier at an IndexTerm that does have content. The value of the SpanEnd attribute must be the ID of that earlier IndexTerm. The Significance attribute may have the value Preferred, indicating that the IndexTerm is the most pertinent of the series, or the value Normal (the default). Within the topic you want to index, use the IndexTerm element as shown: <para>This text deals with two subjects that should be listed in the index: how to rotate your terminal and how to adjust its height.</para> <IndexTerm> <Primary>rotating your terminal</Primary> </IndexTerm> <IndexTerm> <Primary>terminal <Secondary>rotation of</Secondary> </Primary> </IndexTerm> <IndexTerm> <Primary>terminal <Secondary>adjustment of</Secondary> <SeeAlso>troubleshooting</SeeAlso> </Primary> </IndexTerm> Like a glossary in a book, your help volume can contain a glossary that defines important terms. The glossary, which is marked using the Glossary element, is the last topic in your help volume. The glossary contains the definitions for all the terms that are marked with the <GlossTerm> tag. Glossary contains the following components in the following order: Title (optional) TitleAbbrev (optional) one or more GlossEntries The GlossTerm tag is used to mark a term in the document text that is glossed in the Glossary. Note that the GlossTerm element is also used to contain those terms as they occur in GlossEntries in the Glossary. Each key word or phrase that you enter with the GlossTerm element automatically becomes a link to the term's definition in the Glossary. Terms are defined in the Glossay by using the GlossEntry element. A GlossEntry contains, in order, a required GlossTerm, an optional Acronym, and an optional Abbrev, followed by any number of GlossSees and GlossDefs, in any order. GlossDef is the definition of a GlossTerm in a GlossEntry. It may contain, in any order, Comments, GlossSeeAlsos, paragraphs, and other block-oriented elements. GlossDef has the Common attributes and also the Subject attribute. The Subject attribute may hold a list of subject areas as keywords, separated only by spaces. <Glossary> ... <GlossEntry> <GlossTerm> term </GlossTerm> <GlossDef> text of definition </GlossDef> </GlossEntry> ... </Glossary>