Entity declaration: Assigns an entity name to a string of characters or to an external file.
<!entity entityname "string">
Or:
<!entity entityname FILE "filename">
An entity name can contain up to 64 letters, digits, and hyphens. Case is not significant in entity names, but is often used to improve readability for the author. The first character must be a letter. No space is permitted between the < ( left angle bracket), ! (exclamation mark), and entity in an <!entity> declaration.
Entity declarations must always precede any other markup or text in the help volume.
Where you want the defined entity to appear, insert an entity reference using this syntax:
&entityname;
The entity reference consists of an & (ampersand), followed by the entity name (as defined in the entity declaration), and ends with a ; (semicolon).
There are four common reasons for defining an entity:
Text that is associated with an entity name appears only once so that changing the text requires making a change in only one place. All references to the entity automatically change when HelpTag reprocesses the files.
The inefficiency of typing the same long or complex text string many times can be avoided (along with typing mistakes) by typing just a short entity reference wherever that text string will appear. The full text string needs to be typed only once.
The <figure> and <graphic> elements do not accept a file name. The name of the file that contains the figure must be specified in an entity declaration.
It is convenient to put the help text into multiple files, yet HelpTag accepts only one source file. These needs can be balanced by creating one file that contains entity declarations and entity references that refer to the files that contain the actual help text.
The volume.htg source file can contain the following entity declarations and entity references so that the actual text can be put into the named files:
<!entity topic1 FILE "topic1"> <!entity topic2 FILE "topic2"> <!entity topic3 FILE "topic3"> &topic1; &topic2; &topic3;
The following entity declaration causes the words "Architectural Analysis of Aircraft Precision Components" to be displayed wherever the &apc; entity reference appears in the marked-up files.
<!entity apc "Architectural Analysis of Aircraft Precision Components">
The following entity declaration for a figure is placed at the beginning of the source file:
<!entity CloseUpFig FILE "figname.tif">
and the figure would be inserted where the following markup appears:
<figure entity=CloseUpFig> Close Up View <\figure>