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. 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 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 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. shows a simple hierarchy that includes three chapters. Each chapter contains several first-level sections. The third chapter adds two second-level sections.

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

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. describes how to define and use entities. 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. shows you how to create a meta information section. 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. 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 ). 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. 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. 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 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. 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. 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. 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 . File Manager represents help files as file icons with a question mark. In on , 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.

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. dthelpaction(4) man page 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: Create the source directory for help files. Create the master DocBook file. Create the run-time help files. 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 and in the Guide to the DocBook DTD. Create a directory named helpfiles where you will create and process your help files. 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. 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> 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.sgmfile. <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 a text file whose name is of the form volume.sgm. In this example, the file is named voiceact.sgm. 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> 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. 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. 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 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 , on , on 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. 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.) describes assigning IDs to topics describes how to create hyperlinks 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. 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 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. 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. 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) Enter the <DocInfo> tag to start the section, and follow immediately with the required Title element, as shown: <DocInfo> <title>Volume Title Here</title> Enter the optional TitleAbbrev and Subtitle elements if needed. Enter the required AuthorGroup element, which contains one or more Authors, Collabs, or CorpAuthors, in any order. 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> 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. 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. 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”. 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. 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. 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. 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) 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. <anchor id="id-string"> There is an Anchor <anchor id=“077-ch02-AN-7”> in this sentence. 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. 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. 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. 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. 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. 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. 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> 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; 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: