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

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.

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

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>

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:

Using Entities

Technical documentation

» Table of Contents

» Glossary