Creating Internal Parameter Entities

As we've seen, you use general entity references in documents so that the XML processor will replace them with the entity to which they refer. However, you can use general entities only in a limited way in DTDs— that is, you can use them to insert text that will itself be inserted into the document content, but you can't use them to work with the declarations themselves in the DTD.

To actually work with element and attribute declarations, you use parameter entities. Parameter entity references can be used in only the DTD. In fact, there's an additional restriction: Any parameter entity references that you use in any DTD declaration must appear only in the DTD's external subset (the external subset is that part of the DTD that is external). You can use parameter entities in the internal subset, but only in a limited way, as we'll see.

Unlike general entity references, parameter entity references start with %, not &. Creating a parameter entity is just like creating a general entity, except that you include a % in the <!ENTITY> element, like this:

 <!ENTITY % NAME DEFINITION
				

You can also declare external parameter entities using the SYSTEM and PUBLIC keywords, like this (where FPI stands for a formal public identifier):

<!ENTITY % NAME SYSTEM URI>
<!ENTITY % NAME PUBLIC FPI URI>

Here's an example using an internal parameter entity; in this case, I'll declare a parameter entity named BR that stands for the text <!ELEMENT BR EMPTY> inside this DTD:

<?xml version = "1.0" standalone="yes"?>
<!DOCTYPE DOCUMENT [
<!ENTITY % BR "<!ELEMENT BR EMPTY>">
<!ELEMENT DOCUMENT (CUSTOMER)*>
<!ELEMENT CUSTOMER (NAME,DATE,ORDERS)>
<!ELEMENT NAME (LAST_NAME,FIRST_NAME)>
<!ELEMENT LAST_NAME (#PCDATA)>
<!ELEMENT FIRST_NAME (#PCDATA)>
<!ELEMENT DATE (#PCDATA)>
<!ELEMENT ORDERS (ITEM)*>
<!ELEMENT ITEM (PRODUCT,NUMBER,PRICE)>
<!ELEMENT PRODUCT (#PCDATA)>
<!ELEMENT NUMBER (#PCDATA)>
<!ELEMENT PRICE (#PCDATA)>
]>
    .
    .
    .

Now I can reference that parameter entity this way to include the element declaration <!ELEMENT BR EMPTY> in the DTD:

<?xml version = "1.0" standalone="yes"?>
<!DOCTYPE DOCUMENT [
<!ENTITY % BR "<!ELEMENT BR EMPTY>">
<!ELEMENT DOCUMENT (CUSTOMER)*>
<!ELEMENT CUSTOMER (NAME,DATE,ORDERS)>
<!ELEMENT NAME (LAST_NAME,FIRST_NAME)>
<!ELEMENT LAST_NAME (#PCDATA)>
<!ELEMENT FIRST_NAME (#PCDATA)>
<!ELEMENT DATE (#PCDATA)>
<!ELEMENT ORDERS (ITEM)*>
<!ELEMENT ITEM (PRODUCT,NUMBER,PRICE)>
<!ELEMENT PRODUCT (#PCDATA)>
<!ELEMENT NUMBER (#PCDATA)>
<!ELEMENT PRICE (#PCDATA)>
%BR;
]>
<DOCUMENT>
    <CUSTOMER>
        <NAME>
            <LAST_NAME>Smith</LAST_NAME>
            <FIRST_NAME>Sam</FIRST_NAME>
        </NAME>
        <DATE>October 15, 2001</DATE>
        <ORDERS>
            <ITEM>
                <PRODUCT>Tomatoes</PRODUCT>
                <NUMBER>8</NUMBER>
                <PRICE>$1.25</PRICE>
            </ITEM>
            <ITEM>
                <PRODUCT>Oranges</PRODUCT>
                <NUMBER>24</NUMBER>
                <PRICE>$4.98</PRICE>
            </ITEM>
            .
            .
            .
            <ITEM>
                <PRODUCT>Asparagus</PRODUCT>
                <NUMBER>12</NUMBER>
                <PRICE>$2.95</PRICE>
            </ITEM>
            <ITEM>
                <PRODUCT>Lettuce</PRODUCT>
                <NUMBER>6</NUMBER>
                <PRICE>$11.50</PRICE>
            </ITEM>
        </ORDERS>
    </CUSTOMER>
</DOCUMENT>

Notice that I haven't really saved much time here; I might as well have just put the declaration <!ELEMENT BR EMPTY> directly into the DTD. On the other hand, you can't do much more with internal parameter entities (those that are defined in the DTD's internal subset) because you can't use them inside any other declarations. If you want to find out what people really use parameter entities for, we have to take a look at external parameter entities.