# Organizing and Writing a Help Volume

This chapter describes the organization and components of a help source file. It also provides a step-by-step example that shows how to process a help source file to create an online help volume.

## Help Volume Components

A help volume has the following major types of components: entity declarations, a top-level volume topic (contained in the Part element) meta information (contained in the DocInfo element), book components (like Chapters, Sections, Lists, and Tables), the index and the glossary.

### The Top Level Element: Part

The Part is the top-level element in the structure of a help volume. All other components are subelements of Part in the structural hierarchy.

The structural hierarchy under Part may be several levels deep with Chapters containing Sect1s, Sect1s containing Sect2s, Sect2s containing Sect3s, and so on. To help prevent users from getting lost, however, you should keep your hierarchy as shallow as possible.

Part may contain the following components in the following order: an optional DocInfo, a required Title, an optional TitleAbbrev, an optional PartIntro, and one or more other book components, like Chapters.

Part has the common attributes and a label attribute.

### Topics and Subtopics

Topics and subtopics form a hierarchy below the Part. Typically, the first level of topics is divided into chapters, using the Chapter element. Within a chapter, topics are organized into sections, with subtopics of a Sect1 tagged as Sect2s, subtopics of a Sect2 tagged as Sect3s, and so on.

HRDC.OrgH.mkr.3 shows a simple hierarchy that includes three chapters. Each chapter contains several first-level sections. The third chapter adds two second-level sections.

#### Help volume structural organization

    Part
            DocInfo
            Title
            Chapter
                    Sect1
                    Sect1
                    Sect1
            Chapter
                    Sect1
                            Sect2
                                    Sect3
                            Sect2
                    Sect1
                    Sect1
                            Sect2
                            Sect2
                                    Sect3

### Entities

An author-defined entity can represent a string of characters or a file name. An entity declaration defines the entity name and the string or file it represents.

Entities are useful for:

- Referencing a common string of text. This is useful if there is some likelihood that the text may change or you simply don't want to type it repeatedly. Each place you want the text inserted, you reference the entity name.

- Referencing an external file. Entities are often used for accessing graphics files. The <Graphic> element has an Entityref attribute, which refers to a graphic image file.

All entity declarations must be entered before any other markup in your help volume. To include an entity that you have defined, you use an entity reference.

Entity references can be used anywhere within your help volume inside a document type declaration. When you process your help volume with the DocBook software, each entity reference is replaced with the text or file that the entity represents. HRDC.OrgH.mkr.22describes how to define and use entities.

### Meta Information

Meta information is information about your information.

In DocBook markup, meta information about a help volume is contained in the DocInfo element.

DocInfo may contain the following elements in the following order:

- Title (required)

- TitleAbbrev (optional)

- Subtitle (optional)

- one or more AuthorGroups (required)

- any number of Abstracts (optional brief descriptions of the volume's contents)

- a RevHistory (optional)

- any number of LegalNotices (optional, giving information on trademarks, copyrights, etc.)

The Help System uses the meta information in DocInfo to display the Title of a help volume and its copyright information. The Abstract description is displayed by the desktop Help Viewer in the Front Panel. Other applications capable of displaying help volumes could also make use of this information.

HRDC.OrgH.mkr.15 shows you how to create a meta information section.

### Glossary

The glossary includes definitions for important terms that you've used throughout your help volume. If a term is entered using the GlossTerm element, then it automatically becomes a link that, when selected, displays the glossary entry for that term.

## General Markup Guidelines

Online help is written in ordinary text files. You use special codes, called tags, to markup elements within the information. The tags form a markup language called DocBook.

If a standard text editor is used, DocBook markup is typed. If the editor provides a macro package, tags can be stored and inserted using command keys. DocBook markup can also be generated using a structured editor (see HRDC.Intro.mkr.24).

The DocBook markup language defines a hierarchy of elements that define high-level elements, such as chapters and sections, block-oriented elements, such as paragraphs, lists, and tables, and low level in-line elements such as emphasized words and symbols.

### Markup in Your Source Files

The markup for most elements consists of a start tag and an end tag. Start tags are entered with the element name between angle brackets (< and >). End tags are similar, but the element name is preceded by a / (forward slash). Case is not significant in DocBook markup tags.

    <Element attribute name="attribute value"> ... text ... </Element>

For example, to mark the start and end of a book title you use markup like this:

    <Title id="GSNW">Geographical Survey of Northern Wisconsin</Title>

Where <Title> is the start tag, and </Title> is the end tag, and GSNW is the value of the ID attribute of the Title element. If the element has more than one attribute with a specified value, the attribute name="attribute value" expressions are separated by spaces.

## A Help Volume at a Glance

The following schematic markup illustrates important elements of a help volume and the tags used to enter them. Indentation is used here simply to highlight the hierarchical relationship of the elements; you don't need to indent the help files that you write.

    DocType
    Part
            DocInfo
                    Title
                    AuthorGroup
                    Abstract
                    LegalNotice
            Title
            PartIntro
            Chapter
                    Title
                    Sect1
                            Title
                            Para
                            Para
                            Sect2
                                    Title
                                    Para
                                    Sect3
                                            Title
                                            Para
                                            Para
                            Sect2
                                    Title
                                    Para
            Chapter
                    Title
                    Sect1
                            Title
                            Para
                            Para
                            Sect2
                                    Title
                                    Para
                            Sect2
                                    Title
                                    Para
            Glossary

## Help Source Files

Online help is written in ordinary text files. You process, or compile, these files with the DocBook software to create run-time help files that can be read by the Help System.

### Creating Your volume.sgm File

DocBook expects a primary control file named volume`.sgm`, where volume is a name you choose.

Be sure your volume name is unique and meaningful. If your volume name is too general, it may conflict with another volume that someone else has created. If you are writing application help, one recommended practice is to use the application's class name.

#### Multiple Source Files

The named volume`.sgm` file contains entity declarations and entity references to files that make up the help volume. Although DocBook expects a single volume`.sgm` file as input, you can separate your work into multiple source files. Additional files are sourced into the volume`.sgm` file using file entities. A file entity is like a pointer to another file. That file, in effect, is inserted wherever the entity's name appears in the volume`.sgm` file. The referenced files can also contain entity references to yet other files.

#### Example

Suppose a help volume has six chapters and each chapter is a separate file. The files are: HomeTopic, Metainfo, TOC, Tasks, Reference, and Glossary. The volume`.sgm` file for the help volume includes file entities for each of the six files and a list of entity references that instruct the DocBook software to process the files.

    ...
    <!entity HomeTopic        FILE “HomeTopic”>
    <!entity MetaInformation  FILE “Metainfo”>
    <!entity TableOfContents  FILE “TOC”>
    <!entity Tasks            FILE “Tasks”>
    <!entity Reference        FILE “Reference”>
    <!entity Glossary         FILE “Glossary”>
    ...
    &HomeTopic;
    &MetaInformation;
    &TableOfContents;
    &Tasks;
    &Reference;
    &Glossary;

The details of running DocBook are covered in HRDC.CrHV.mkr.3.

## Help Files in File Manager

File Manager represents help files as file icons with a question mark. In HRDC.OrgH.mkr.10 on HRDC.OrgH.mkr.10, there is one source file (the one with the `.sgm`) and one run-time file (`.sdl` extension). If you double-click a markup file, your standard editor opens the file for editing. Double-clicking a (`.sdl` extension) file displays the run-time file using the Help Viewer.

### File Manager view of help files

To create a run-time help volume, first select the `.sgm` file icon in File Manager. Then, choose Compile from the File Manager Selected menu.

### See Also

- `dthelpaction(4)` man page

## Writing Your First Help Volume: A Step-by-Step Example

Typically you organize your help files in a `help` directory. This step-by-step example demonstrates how to create and view a standalone help volume. (As a standalone volume, it does not involve interaction with an application.)

To create and process a help volume, you follow these steps:

1. Create the source directory for help files.

2. Create the master DocBook file.

3. Create the run-time help files.

4. Display the help volume.

Each task is described in the section that follows. The markup language used in the text files is introduced later in this chapter. DocBook markup is described more fully in HRDC.WrTop.mkr.1 and in the Guide to the DocBook DTD.

### Create the Source Directory

1. Create a directory named `helpfiles` where you will create and process your help files.

2. Create a text file named `Commands.sgm` in the directory just created.

   For this example, all the information is put into a single file. Typically, you will use multiple files to fully explain the system or application you are writing help for.

   The `Commands.sgm` file contains text and element tags. The element tags within the < and > (angle brackets) indicate the structure of the information.

3. Type the following markup text in the `Commands.sgm` file.

       <Chapter>
       <Title id="CommandSummary-id>Command Summary</Title>
       <Indexterm><Primary>commands<Primary></Indexterm>
       <Para>Your&product; is capable of the following operations:</Para>
       <ItemizedList>
       <ListItem><Para><Link Linkend="ChannelChange-id">ChannelChange</Link></Para></ListItem>
       <ListItem><Para><Link Linkend="VolumeUp-id"> VolumeUp </Link>       </Para></ListItem>
       <ListItem><Para><Link Linkend="VolumeDown-id"> VolumeDown </Link></Para></ListItem>
       <ListItem><Para><Link Linkend="VolumeMute-id"> VolumeMute </Link></Para></ListItem>
       </ItemizedList>
       <Para>Choose one of the hyperlinks (underlined phrases)
       to find out how to perform that operation.</Para>
       <Sect1 id="ChannelChange-s">
       <Title id="ChannelChange-t">Changing the Channel</Title>
       <Indexterm><Primary>channel<Secondary>changing</Secondary><Primary></Indexterm>
       <Para>Speak the command:
       <Programlisting> channel</Programlisting>
       followed by a number from <Command>one</Command>to <Command>ninety-nine</Command>.</Para>
       </Sect1>
       <Sect1 id="VolumeUp-s">
       <Title id="VolumeUp-t">Turning Up the Volume</Title>
       <Indexterm><Primary>volume<Secondary>changing</Secondary></Primary></Indexterm>
       <Para>Speak the command:
       <Programlisting>volume up</Programlisting></Para>
       <Para>For additional volume, speak the command:
       <Programlisting>more</Programlisting></para>
       <Para>(See also <Link Linkend="VolumeDown-id">VolumeDown</Link>)</Para>
       </Sect1>
       <Sect1 id="VolumeDown-s">
       <Title id="VolumeDown-t">Turning Down the Volume</Title>
       <Indexterm><Primary>volume<Secondary>changing</Secondary></Primary></Indexterm>
       <Para>Speak the command:
       <Programlisting>volume down</Programlisting></Para>
       <Para>To reduce the volume further, speak the command:
       <Programlisting>more</Programlisting></Para>
       <Para>(See also <Link Linkend="VolumeUp-id"> VolumeUp </Link> and <Link Linkend="VolumeMute-id">VolumeMute</Link>)</Para>
       </Sect1>
       <Sect1 id="VolumeMute-s">
       <Title id="VolumeMute-t">Turning Off the Sound</Title>
       <Indexterm><Primary>volume<Secondary>changing</Secondary></Primary></Indexterm>
       <Indexterm><Primary>sound<Secondary>on/off</Secondary></Primary></Indexterm>
       <Para>Speak the command:
       <Programlisting>sound off</Programlisting></Para>
       <Para>To restore the sound, speak the command:
       <Programlisting>sound on</Programlisting></Para>
       <Para>(See also <Link Linkend="VolumeDown-id">VolumeDown</Link> and <Link Linkend="VolumeUp-id">VolumeUp</Link></Para>
       </Sect1>
       </Chapter>

4. Create a text file that gives the information a title, provides copyright information, and provides other information about the online help.

   In this example, the following text is put into a file called `Metainfo.sgm` in the same directory as the `Commands.sgm`file.

       <DocInfo>
        <Title> Using the &product;</Title>
               <AuthorGroup><Author>Jim Jonas</Author>
                       </AuthorGroup>
               <Abstract> Help for Using the &product;.
                       </Abstract>
               <LegalNotice>
               <BlockQuote>
               <para>&copy; 1995 Voice Activation Company.
               All rights reserved.</para>
               </BlockQuote>
                       </LegalNotice>
       </DocInfo>

### Create the Master DocBook File

1. Create a text file whose name is of the form volume`.sgm`. In this example, the file is named `voiceact.sgm`.

2. In the `voiceact.sgm` file, define entities that associate the names of the `Commands.sgm` and `Metainfo.sgm` files with entity names. Also, define any entities that are used (either directly or indirectly) in the `Commands.sgm` and `Metainfo.sgm` files. Finally, refer to the `Commands.sgm` and `Metainfo.sgm` files by their entity names.

In this example, the contents of the `voiceact.sgm` file look like this. The text within the `<!--…-->` elements are comments, which are ignored.

    <!-- Declare an entity for each of the source text files. -->
    <!entity MetaInformation  FILE “Metainfo”>
    <!entity Commands   FILE “Commands”>

    <!-- Define an entity that names the product and includes
            the trademark symbol (&tm;). -->

    <!entity product “VoAc&tm; Voice-Activated Remote Control”>

    <!-- Include the text files. -->
    <Part>
    &MetaInformation;
    &Commands;
    </Part>

### Create the Run-Time Help Files

1. Verify that the `/usr/dt/bin` directory is in your search path by typing this command in a terminal window:

   `echo $PATH`

   If the directory is not in your path, add it to your PATH environment variable. If you're not sure how to do this, refer to your system documentation or ask your system administrator.

2. Open File Manager and change to the `helpfiles` directory. Select the `voiceact.sgm` file icon and choose Compile from the Selected menu in File Manager.

   This executes the DocBook software which creates a run-time version of your online help volume (`voiceact.sdl`). Status and error messages are placed in a new file, whose name is of the form volume`.log`.

3. Open the `voiceact.log` file to check that your file processed without errors. If errors occurred, fix them by editing or renaming the text files as needed.

You can run DocBook manually in a terminal window.

To do so, execute the following command:

`dtdocbook voiceact.sgm`

### Display the Help Volume

From the `helpfiles` directory, double-click the `voiceact.sdl` file icon.

This displays the help volume using the desktop Help Viewer. You can now scroll through the information and jump to related information by choosing hyperlinks.

You can run the Help Viewer manually in a terminal window.

To do so, execute the following command, which displays the new help volume:

`dthelpview -h voiceact.sdl`

#### See Also

- hrdc.crhv.mkr.1, on hrdc.crhv.mkr.1

- hrdc.cmds.mkr.1, on hrdc.cmds.mkr.1

## Creating a Topic Hierarchy

The topic hierarchy within your help volume begins with the Part. Each help volume must have one Part. The first level of subtopics below Part must be entered with <Chapter> tags.

Additional levels of subtopics are entered with <Sect1>, <Sect2>, <Sect3>, <Sect4>, and <Sect5>. The DocBook markup language supports five topic levels, but bear in mind that information more than three or four levels deep often leads many readers to feel lost.

When a help volume is displayed, the help window displays a list of topics in its topic tree. Any topic entered with a <Chapter>, <Sect1>, <Sect2>, <Sect3>, <Sect4>, or <Sect5> tag automatically appears in the topic tree. This provides an easy way to browse and view topics.

To enable users to display other related information from within a topic, you create hyperlinks. To do so, you assign a unique ID to each destination topic. Hyperlinks make it possible to reference a specific ID anywhere in your help information.

### Example

Suppose you want to create a hierarchy to match this simple outline:

    Tutorial for New Users
            Module 1: Getting Started
            Module 2: Creating Your First Report
            Module 3: Printing the Report
            Module 4: Saving Your Work and Quitting
    Task Reference
            Starting and Stopping
                    To Start the Program
                    To Quit the Program
            Creating Reports
                    To Create a Detailed Report
                    To Create a Summary Report
    Concepts for Advanced Users
            Using Report Hot Links
            Sharing Reports within a Workgroup
    Reference
            Command Summary
            Report Attributes Summary

Then the general outline of your help volume would look like this.

    <Part>
    <title>Welcome to ReportMaster</title>

    <chapter>
            <title>Tutorial for New Users</title>
            overview of chapter topic
            <sect1>
            <title>Module 1: Getting Started</title>
                    body of topic
                    </sect1>
            <sect1>
            <title>Module 2: Creating Your First Report</title>
                    body of topic
                    </sect1>
            <sect1>
            <title>Module 3: Printing the Report</title>
                    body of topic
                    </sect1>
            <sect1>
            <title>Module 4: Saving Your Work and Quitting</title>
                    body of topic
                    </sect1>
    </chapter>

    <chapter>
            <title>Task Reference</title>
            overview of chapter topic
    <sect1>
            <title>Starting and Stopping</title>
            body of topic
            <sect2>
                    <title>To Start the Program</title>
                    body of topic
                    </sect2>
            <sect2>
                    <title>To Quit the Program</title>
                    body of topic
                    </sect2>
    <sect1>
            <title>Creating Reports</title>
            body of topic
            <sect2>
                    <title>To Create a Detailed Report</title>
                    body of topic
                    </sect2>
            <sect2>
                    <title>To Create a Summary Report</title>
                    body of topic
                    </sect2>
            </sect1>
    </chapter>

    <chapter>
            <title>Concepts for Advanced Users</title>
            overview of chapter topic
            <sect1>
            <title>Using Report Hot Links</title>
                    body of topic
                    </sect1>
            <sect1>
            <title>Sharing Reports within a Workgroup</title>
                    body of topic
                    </sect1>
    </chapter>

    <chapter>
            <title>Reference</title>
            overview of chapter topic
            <sect1>
            <title>Command Summary</title>
                    body of topic
                    </sect1>
            <sect1>
            <title>Report Attributes Summary</title>
                    body of topic
                    </sect1>
    </chapter>
    </part>

(The body of each topic and IDs for the topics are not shown. Spacing and indentations are only for ease of reading, and are not significant.)

#### See Also

- HRDC.OrgH.mkr.18describes assigning IDs to topics

- HRDC.WrTop.mkr.14describes how to create hyperlinks

### To Create a Part

- Use the Part element as follows:

    <Part>
            <DocInfo>
                    <Title>Volume Title</Title>
                    <AuthorGroup>
                            <Author>author's name here</Author>
                    </AuthorGroup>
                    <Abstract>
                            <Para>abstract here</Para>
                    </Abstract>
                    <LegalNotice>
                            <BlockQuote>
                            <Para>copyrights etc. </Para>
                            </BlockQuote>
                    </LegalNotice>
            </DocInfo>
            <Title>Volume Title</Title>
            </PartIntro><Para>This is the home topic.</Para></PartIntro>
            <Chapter Id="chapid">
                    <Title>This Chapter</Title>
                    <Sect1 Id="sect1id">
                            <Title>Sect1 Heading</Title>
                            <Sect2 Id="sect2id">
                                    <Title>Sect2 Heading</Title>
                    ...
                    ...
                    ...
                            </sect2>
                    </sect1>
            </chapter>
    </Part>

Part may contain the following components in the following order: an optional DocInfo, a required Title, an optional TitleAbbrev, an optional PartIntro, and one or more other book components, like Chapters and Sections.

Note that the Title of the help volume appears twice, if a DocInfo is present: once within DocInfo, and again as the first element following DocInfo.

#### Example

Here's a sample Part with a PartIntro that includes hyperlinks to the Part's four subtopics:

    </Part>
    <title>Report Master</title>
    <PartIntro>
    <Para>Welcome to the online help for Report Master. Please choose one of the following hyperlinks:</Para>
    <itemizedlist>
    <listitem><para><Link Linkend="Tutorial-id">Tutorial</Link> </para></listitem>
    <listitem><para><Link Linkend="Tasks-id">Tasks</Link></para></listitem>
            <listitem><para><Link Linkend="Concepts-id">VolumeDown</Link></para></listitem>
            <listitem><para><Link Linkend="Reference-id">VolumeMute</Link></para></listitem>
    </itemizedlist>.
    <Para>If you need help, press F1.</Para>
    </PartIntro>
    ...
    </Part>

The preceding markup produces this output:

### To Add a Topic to the Hierarchy

- To add another topic at the same level, close the element using its end tag, then repeat the same element by opening it with its start tag.

  To add a subtopic (a topic one level deeper in the hierarchy), use the element that is one level deeper than the preceding topic.

#### Example

If the current topic is a <Sect1>, enter a subtopic using <Sect2>.

    <sect1>
            <title>Creating Reports</title>
            body of the topic
            <sect2>
                    <title>To Create a Detailed Report</title>
                    body of the first subtopic
                    </sect2>
            <sect2>
                    <title>To Create a Summary Report</title>
                    body of the second subtopic
                    </sect2>
    </sect1>

The second Sect2 is also a subtopic of the Sect1.

Sometimes parent-child-sibling metaphors are used to describe the relationships topics in a hierarchy. In the preceding example, the Sect1 topic is the “parent” of both Sect2s (the “children” topics). The two Sect2s are “siblings” of one another. All three topics are “descendents” of the Chapter's topic.

## Creating Meta Information Topics

The DocInfo meta information section is primarily intended for information about information. In the DocBook markup language, Meta information for a help volume is contained in the DocInfo element that may occur as the first component of a Part. DocInfo contains information about the help volume's title and authors, may contain legal notices about copyrights and trademarks, and abstracts of the volume's contents.

DocInfo may contain the following elements in the following order:

- Title (required)

- TitleAbbrev (optional)

- Subtitle (optional)

- one or more AuthorGroups (required)

- any number of Abstracts (optional)

- a RevHistory (optional)

- any number of LegalNotices (optional)

### To Create a Meta Information Section

1. Enter the <DocInfo> tag to start the section, and follow immediately with the required Title element, as shown:

       <DocInfo>
               <title>Volume Title Here</title>

2. Enter the optional TitleAbbrev and Subtitle elements if needed.

3. Enter the required AuthorGroup element, which contains one or more Authors, Collabs, or CorpAuthors, in any order.

4. Enter the optional Abstract and LegalNotice elements if needed, following these syntax models:

       <Abstract Id="SDL-RESERVED-abstract">
               <Para>abstract here</Para>
       </Abstract>

       <LegalNotice Id="SDL-RESERVED-copyright">
               <BlockQuote>
                       <Para>© year & copyright holder's name</Para>
               </BlockQuote>
       </LegalNotice>

5. Enter the DocInfo end tag to end the section.

The Abstract section is recommended. Applications that access help volumes can use this information to present a brief description of the volume. Because the abstract might be displayed in plain text windows avoid including any DocBook markup in the abstract.

#### Example

Here's a markup for typical meta information section contained in the DocInfo element:

    <DocInfo>
    <title>Report Master, Version 1.0</title>

    <AuthorGroup>
            <Author>Jim Jonas</Author>
    </AuthorGroup>

    <Abstract>
            <Para>This is the online help for the mythical Report Master application. This help includes a self-guided tutorial, a summary of common tasks, general concepts, and quick reference summaries.</Para>
    </Abstract>

    <LegalNotice>
            <BlockQuote>
                    <Para>
            Version 1.0
            &copy; Copyright Reports Incorporated 1995
            All rights reserved.
                    </Para>
            </BlockQuote>
    </LegalNotice>
    </DocInfo>

The BlockQuote element is used to preserve the line breaks in the copyright notice. The `&copy;` entity inserts the copyright symbol.

## Adding a Nonhierarchical Topic

Topics entered with the Chapter, Sect1, Sect2, Sect3, Sect4, Sect5 element tags automatically appear in the topic tree. When a title is selected in the topic tree, the corresponding help topic is displayed in a general help dialog box.

Sometimes you may want to create and display a topic independent of the structural hierarchy you have created. These nonhierarchical topics are useful for creating custom definition links that pop-up a topic in a quick help dialog box.

Appendix is the tag for a free-floating heading not tied to the Sect hierarchy. It may contain inline elements.

Appendix has the common attributes, including the ID attribute and the XRefLabel atttribute, and also the Label attribute. When using the Appendix element for nonhierarchical topics, the value of the Role attribute should be “notoc”.

### To Add a Nonhierarchical Topic

- Add the nonhierarchical topic using the BridgeHead element as follows:

      <Appendix id="bh-some-id" role="notoc">
              text of the topic
      </Appendix>

Presumably, a definition link to display this topic will exist within some other topic in the help volume.

The link might look like this:

    Here's a sample of a pop-up <link linkend="bh-some-id">
    definition link.</link>

The words “definition link” become the active hyperlink and will be displayed with a dashed underline. Selecting the link displays the text of the topic in a quick help dialog box.

#### See Also

- hrdc.wrtop.mkr.14

## Accessing Topics

Many elements in the DocBook language support an ID attribute. An ID is a unique name used internally to identify topics and elements within topics. Since ID is one of DocBook's common attributes, any element with the common attributes can support an ID attribute.

An ID is defined only once, but multiple hyperlinks and cross-references can refer to the same ID. IDs are not seen by the user.

If you are writing help for an application, IDs are also used by the application to identify particular topics to display when the user requests help.

For example, you might write several topics that describe an application's menus. The IDs that you assign to the topics are used by the application developer. By defining identical IDs within the application code, the developer can integrate specific topics. This allows the application to access and display the correct topic when help is requested for a particular menu.

### Rules for ID Names

- ID strings may contain letters (A - Z and a - z), digits (0 - 9), the period (.), and the minus (−) sign. ID strings must begin with a letter, and be unique at least within the document in which they occur.

- Case in ID strings is not significant, but is often used to increase readability.

- ID strings cannot be longer than 128 characters.

- Each ID within a single help volume must be unique.

### Built-in IDs

A few elements have built-in IDs, and so do not support an author-defined ID. Each of the following elements have predefined IDs (shown in parentheses):

<PartIntro> | ( _hometopic)
<LegalNotice> in <DocInfo> | ( _copyright)
<Abstract> in <DocInfo> | ( _abstract)
<Glossary> | ( _glossary)
<Title> in <DocInfo> | ( _title)

### To Add an ID to a DocBook Element

- You include the ID string in the opening tag of the element as follows:

      <Element ID="id-string">

  Note that the value of the ID string is enclosed in quotation marks.

All the DocBook elements with the common attributes support an author-defined ID. These are:

- Abbrev

- Abstract

- Anchor

- Appendix

- Author

- BlockQuote

- BridgeHead

- Chapter

- ComputerOutput

- CorpAuthor

- DocInfo

- Entry

- EntryTbl

- Example

- Figure

- Glossary

- GlossDiv

- GlossEntry

- GlossTerm

- Graphic

- Index

- IndexDiv

- IndexEntry

- InformalTable

- ItemizedList

- KeyCap

- LiteralLayout

- OrderedList

- Part

- PrimaryIE

- ProgramListing

- Quote

- RefEntry

- Reference

- Screen

- Sect1 - Sect5

- See

- SeeAlso

- SeeIE

- Seg

- SegListItem

- SegmentedList

- SegTitle

- Sidebar

- SpanSpec

- Table

- TBody

- TFoot

- TGroup

- Term

- Title

- TitleAbbrev

- ToC

- UserInput

- VariableList

- VarListEntry

In addition to including IDs with DocBook elements that support them, you can use the Anchor element to set an ID at an arbitrary point within a document. The Anchor can then mark a target for a Link, which will take the Anchor's ID string for the value of its Linkend attribute. Anchor is an inline element that may appear almost anywhere. Anchor is an empty element, with no content.

Anchor can have ID, Pagenum, Remap, Role, and XRefLabel attributes, but only the ID attribute is required. At the minimum, only the Anchor start tag is present, with an ID.

When you activate a link to a location ID, the Help Viewer displays the topic containing the ID and scrolls the window to the ID position.

#### Syntax of the Anchor element

    <anchor id="id-string">

#### Example of the Anchor element

    There is an Anchor <anchor id=“077-ch02-AN-7”> in this sentence.

## Using Entities

An entity can represent a string of characters or the contents of a file.

An entity declaration defines the entity by associating the entity name with a specific character string or file name.

An entity reference is replaced by the string or file contents when you process the help volume with the `dtdocbook` command.

Entities are useful for:

- Referencing a given string of text. This is useful if there is some likelihood that the given string of text may subsequently need to be changed, or if you simply don't want to type it repeatedly.

  Once you have declared an entity to stand for a given string of text, each place you want the text inserted, you simply reference the entity name.

- Referencing an external file, particularly a graphics file. Entities provide one way of accessing graphics files.

  The Graphic element points via its attributes to an external file containing graphical data.

  The file that contains the graphical data can be specified by using Graphic's Fileref attribute with the value of the filename, qualified by a pathname if desired.

  Alternatively, if the file that contains the graphical data has been declared an entity, it can be specified by using Graphic's Entityref with the value of the entity name.

File entities are also useful for splitting your DocBook source into multiple files. Use entity references to include other files into your master DocBook file for processing.

### Rules for Entity Declarations

- Entity names may contain letters (A - Z and a - z), digits (0 - 9), the period (.), and the minus (−) sign, and must begin with a letter.

- Case is not significant in entity names, but is often used to increase readability.

- Entity names cannot be longer than 128 characters.

- Each entity name must be unique within a single volume.

### To Create a Text Entity

1. Declare an entity as follows:

       <!entity Entityname "text string">

   Where Entityname is the name of the entity and tex stringt is the string that you want substituted for every reference to the entity. Remember, all entity declarations must be contained in the document type declaration of your help volume.

2. For each location where you want the text string to be inserted, enter the entity reference as follows:

       &Entityname;

   The `&` (ampersand) and `;` (semicolon) characters are required for the DocBook software to properly recognize the entity reference.

#### Example

The following line declares a text entity named Assoc that contains the string “Society of Agricultural Engineers”:

    <!entity Assoc "Society of Agricultural Engineers">

The following sentence includes a reference to the entity:

    Welcome to the &Assoc;.

When the help volume is processed with the DocBook software, the entity reference is replaced with the value of the entity. So, the sentence will read:

Welcome to the Society of Agricultural Engineers.

### To Create a File Entity

1. Declare an entity as follows:

       <!entity Entityname SYSTEM "filename">

   Where Entityname is the name of the entity and filename is the name of the file. The keyword SYSTEM is required.

2. Reference the entity as follows:

   - If the file is a text file, enter the following entity reference at each location where you want the contents of the file inserted.

         &Entityname;

     The & (ampersand) and; (semicolon) characters are required for the DocBook software to properly recognize the entity reference.

   - If the file is a graphics file, include the name of the entity as the value of the Entityref attribute like this:

         <Graphic ID="some-graphic-id"Entityref=" Entityname"></Graphic>

#### Example: Text File Entities

Suppose you wrote the text for your help volume in three files named `file1`, `file2`, and `file3`, plus a fourth file containing your <docinfo> … </docinfo> section. You could include them in your volume`.sgm` file like this:

    <!DOCTYPE DOCBOOK [
    <!entity DocInformation SYSTEM "docinfo">
    <!entity MyFirstFile SYSTEM "file1">
    <!entity MySecondFile SYSTEM "file2">
    <!entity MyThirdFile SYSTEM "file3">
    ...
    >]

    <Part>
    &DocInformation;
    <Title>My Home Title</Title>

    &MyFirstFile;
    &MySecondFile;
    &MyThirdFile;

#### Example: A Graphic File Entity

Suppose a simple help volume has a Part with a Graphic in it, and graphic data for the Graphic is stored in a file named `picture.tif`. The following example shows how that Graphic would be included by using an entity reference.

    <!DOCTYPE DOCBOOK [
    <!entity DocInformation SYSTEM “docinfo”>
    <!entity MyPicture SYSTEM “picture.tif”>
    ...
    ]>
    <Part>
    &DocInformation;
    <PartIntro><Title>A Simple Graphic</Title>
    <Para>Welcome to my application's help volume.</Para>
    </Part>
    <Figure>
    <Title>A Picture</Title>
    <Graphic entityref="MyPicture"> </Graphic>
    </Figure>
    </PartIntro>
    </Part>

The text “A Picture” is the figure's caption.

The markup produces this output:

#### See Also

- HRDC.WrTop.mkr.23