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 helptag 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: All entity declarations must come before any other markup in your help volume. Entity names may contain letters (A - Z and a - z), digits (0 - 9), plus (+), and minus (-), 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

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.
For each location where you want the text string to be inserted, enter the entity reference as follows:
&EntityName;
The "&" and ";" characters are required for the HelpTag software to properly recognize the entity reference.

Example. The following line declares a text entity named "ProductName" that contains the string "HP Visual User Environment":

   <!entity ProductName "HP Visual User Environment">

The following sentence includes a reference to the entity:

   Welcome to the &ProductName;!

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 HP Visual User Environment!

To create a file entity

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

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 run `helptag'”.)

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 entity=MyPicture>

   A Picture

   <\figure>

The text "A Picture" is the figure's caption.

See Also.

“Displaying Graphics”

Using Entities

Technical documentation

» Table of Contents

» Glossary

» Index

To create a text entity

To create a file entity