Using Entities

When one is authoring complex documents or creating multiple related documents, certain content fragments tend to be repeated over and over again. For example, a series of XHTML Web pages might share a set of common footer tags. Entities are provided as a primitive macro facility to allow commonly repeated sequences of document content and even DTD declarations to be defined and referenced by name.

Listing 2.4 shows a simple entity declaration and reference.

Listing 2.4. A Simple Entity Example

<!DOCTYPE message [
  <!ELEMENT message (#PCDATA)>
  <!ENTITY my_message "Hello, world." >
]>
<message>&my_message;</message>

First, the entity is declared using the <!ENTITY> markup, and then the associated text ("Hello, world.") is included in the target document using a normal entity reference (&my_message;). The actual syntax of entity declarations and references changes based on the following:

• Where the replacement text comes from (an inline string or an external file)

• Where the entity will be referenced (within the DTD or the document)

• Whether the resulting replacement text will be read by the parser

Internal Versus External Entities

In Listing 2.4, the replacement text of the entity is contained in a string within the <!ENTITY> markup itself. For short, simple entities this is very convenient. For longer, multiline replacements, storing the entity value in an external file would be more appropriate. The XML entity syntax provides this capability by using the SYSTEM keyword (in place of a string) within the entity declaration, like so:

<!ENTITY wp SYSTEM "war_and_peace.txt">

Within the document, every occurrence of the &wp; entity reference would be replaced by the contents of the file war_and_peace.txt. The XML parser would then continue parsing, beginning with the text that was just included. This means that entity text can, in turn, contain entity references.

General and Parameter Entities

The second criteria (where the entity will be used) affects both the entity declaration and reference. The entity shown in Listing 2.4 is called a general entity, because it is referenced within the body of the document. If the entity is to be referenced within the DTD, it is called a parameter entity. For parameter entities, it is necessary to add a % character to the <!ENTITY> markup:

<!ENTITY % base_att_list 'xml:lang CDATA "en-us"'>
<!ELEMENT message (#PCDATA)>
<!ATTLIST message %base_att_list;>

The benefit of using a parameter entity to declare attributes like this is that if multiple tags have a common base set of attributes, the base set can be changed in a single location.

Parsed Versus Unparsed Entities

Earlier, I mentioned that the XML parser will continue parsing the text that is included as the result of reading an entity reference. The only time this is not true is in the case of the external unparsed entity. This special case is the result of including the NDATA keyword with a notation name in a normal general entity declaration, such as the flowers_gif entity declaration from Listing 2.3:

<!ENTITY flowers_gif SYSTEM "flowers.gif" NDATA gif>

Unparsed entities cannot be referenced within a document using the &entityname; syntax. The only way to refer to unparsed external entities is through the ENTITY attribute type. See the “Referencing External Entities” section of this chapter for an example of referencing an external unparsed entity.