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 dthelptag command.

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 required for accessing graphics files. The <figure> and <graphic> elements have a required parameter that you use to specify an entity name, which refers to a graphic image file.

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

Rules for Entity Declarations

• Entity names may contain letters (A - Z and a - z), digits (0 - 9), 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 64 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"> 

   Where Entityname is the name of the entity and text is the string that you want substituted for every reference to the entity. Remember, all entity declarations must come before any other markup in 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 HelpTag 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 HelpTag software, the entity reference is replaced with the value of the entity. So, the sentence reads:

Welcome to the Society of Agricultural Engineers.

To Create a File Entity

1. Declare an entity as follows:

   <!entity Entityname FILE  "filename"> 

   Where Entityname is the name of the entity and filename is the name of the file. The keyword FILE 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 HelpTag software to properly recognize the entity reference.

   • If the file is a graphics file, include the name of the entity as a parameter in one of the following markup lines:

     <figure entity=Entityname ... > 

     Or:

     <graphic entity=Entityname ... > 

     Or:

     <p gentity=Entityname ... > 

     ---

     Note -

     Do not include any path in the file name. If the file is not in the current directory when you run the HelpTag software, add the appropriate search path to the helptag.opt file. (See "To Create a RunTime Help Volume".)

     ---

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 <metainfo> ...</metainfo> section. You could include them in your volume.htg file like this:

<!entity MetaInformation   FILE  "metainfo">
<!entity MyFirstFile       FILE  "file1">
 <!entity MySecondFile      FILE  "file2">
 <!entity MyThirdFile       FILE  "file3">

 &MetaInformation;

 <hometopic>  My Home Title

 Welcome to my application's help volume.

 &MyFirstFile;
 &MySecondFile;
 &MyThirdFile;

Example: A Graphic File Entity

Suppose a simple help volume has a figure in the home topic and the graphic image for the figure is stored in a file named picture.tif. The following example shows how that image would be used in a figure.

<!entity MetaInformation  FILE  "metainfo">
<!entity MyPicture        FILE  "picture.tif">

 &MetaInformation;

 <hometopic> A Sample Graphic

 Welcome to my application's help volume

 <figure nonumber entity=MyPicture>
 A Picture
 <\figure> 

The text A Picture is the caption of the figure.

The markup produces this output:

See Also

• "Displaying Graphics"