Entities

Entities are symbolic statements that represent text strings in a source file. Like other markup declarations, entity declarations must be enclosed within markup declaration delimiters (<! >). In addition, you must place entity declarations within the declaration subset of the DOCTYPE statement.

The declaration subset is delimited by left and right brackets ([ ]) or parentheses () and is coded within the DOCTYPE statement. If left and right brackets are coded, they must have the hex values of ‘AD’ and ‘BD’ respectively.

Within the markup declaration delimiters, you declare the entity with the term "entity", the name you are assigning to the entity, and the text string the name represents. The text string of the entity must be enclosed in single or double quotes.

<!doctype dm system (
<!entity name "text string">
)>

Entity names must have these characteristics:

1-17 characters
The first character must be alphabetic (A-Z, a-z, @, #, or $)
Remaining characters, if any, can be A-Z, a-z, @, #, $, 0-9, or _
Entity names are case-sensitive.
Entity names of more than 8 bytes must contain at least 1 underscore character.

This example declares an entity named "guar" for the phrase "full, unconditional, money-back guarantee":

<!doctype dm system [
<!entity guar "full, unconditional, money-back guarantee">
]>

Now that we've declared the entity, we can use the entity name in our source file text instead of the entire text string. To specify an entity name in text, you must precede the name with an ampersand (&) and follow it with a semicolon (;) or a blank, as we did in this panel text:

<!doctype dm system [
<!entity guar "full, unconditional, money-back guarantee">
]>
<panel name=widget21 width=40>Widgets
  <area>
    <info width=38>
      <p>You'll love the wide selection of merchandise
      in our Widgets department.
      <p>And, like all of our merchandise, Widgets come
      with our &guar;.
    </info>
  </area>
</panel>

As long as we declared the entity properly, the compiler recognizes the entity reference in the source file and replaces it with the text of the entity declaration. Figure 1 shows the result.

Figure 1. Entity reference for text substitution

                Widgets

 You'll love the wide selection of
 merchandise in our Widgets department.

 And, like all of our merchandise,
 Widgets come with our full,
 unconditional, money-back guarantee.

We can refer to the same entity in the text of the source file as many times as we like. If we should ever want to change the text of the entity, we only have to do it in one place: the declaration subset.

A change to the previous example will show you what we mean.

<!doctype dm system [
<!entity guar “partial, conditional, non-refundable guarantee”>
]>
<panel name=widget22 width=40>Widgets
  <area>
    <info width=38>
      <p>You'll love the wide selection of merchandise
      in our Widgets department.
      <p>And, like all of our merchandise, Widgets come
      with our &guar;.
    </info>
  </area>
</panel>

The only change we made was to the text of the entity declaration, not the entity name. Following reformatting, the text of the entity reference now looks like this:

Figure 2. Entity reference for text substitution

                Widgets

 You'll love the wide selection of
 merchandise in our Widgets department.

 And, like all of our merchandise,
 Widgets come with our partial,
 conditional, non-refundable guarantee.

If, for any reason you need to change the name of an entity, be sure to update all of the references to the entity name in your text.

You can also define the text of an entity in an external file and refer to that file in an entity declaration. If you do this, you must include the SYSTEM parameter in the entity declaration, to indicate to the conversion utility that the file is external.

Note: You must include the external file in the concatenation of DTL source files defined to the conversion utility.

For example, we'll define a text string we want to use as an entity in our source file in a file called WIDGETS. Here are the contents of the WIDGETS file:

doohickeys, whatnots, and gizmos

To declare this file in the entity declaration in our source file, we code it like this, with the SYSTEM parameter:

<!doctype dm system [
<!entity guar "full, unconditional, money-back guarantee">
<!entity widgets system>
]>

If we want to use the text string in our source file, we refer to the entity "widgets" (in this case, the file name also serves as the entity name).

<!doctype dm system [
<!entity guar "full, unconditional, money-back guarantee">
<!entity widgets system>
]>
<panel name=widget23 width=42>More Widgets
  <area>
    <info width=40>
      <p>The fine selection of items in our Widgets department
      includes &widgets;.
      <p>And, like all of our merchandise, Widgets come with
      our &guar;.
    </info>
  </area>
</panel>

Figure 3 shows the formatted result.

Figure 3. Entity reference for text substitution and file embedding

               More Widgets

 The fine selection of items in our
 Widgets department includes doohickeys,
 whatnots, and gizmos.

 And, like all of our merchandise,
 Widgets come with our full,
 unconditional, money-back guarantee.

Anytime we want to update or change the text of the entity, we only need to change the text in the WIDGETS file.

In the previous example, the name "widgets" serves as the external file name and as the entity name.

The SYSTEM parameter may optionally be followed by the file name for the included file. When the SYSTEM parameter is used but no file name is provided, the entity name is used as the file name.

For instance, if you want to declare a different entity name for the WIDGETS file, "things" for example, code it like this in the entity declaration:

<!doctype dm system [
<!entity guar “full, unconditional, money-back guarantee”
><!entity things system "widgets">
]>

Refer to the entity name, things, like this:

<!doctype dm system [
<!entity guar &“full, unconditional, money-back guarantee&”>
<!entity things system “widgets”>
]>
<panel name=widget24 width=42>More Widgets
  <area>
    <info width=40>
      <p>The fine selection of items in our Widgets department
      includes &things;.
      <p>And, like all of our merchandise, Widgets come with
      our &guar;.
    </info>
  </area>
</panel>

The formatted result of this markup is the same as that shown in Figure 3, assuming no changes were made to the text of the WIDGETS file.