Using INCLUDE and IGNORE

Two important DTD directives are often used with parameter entities: INCLUDE and IGNORE. You use these directives to include or remove sections of a DTD; here's how you use them: <![ INCLUDE [DTD Section]]> and <![ IGNORE [DTD Section]]>. Using these directives, you can customize your DTD.

Here's an example showing what these two directives look like in practice:

<![ INCLUDE [
<!ELEMENT PRODUCT_ID (#PCDATA)>
<!ELEMENT SHIP_DATE (#PCDATA)>
<!ELEMENT SKU (#PCDATA)>
]]>

<![ IGNORE [
<!ELEMENT PRODUCT_ID (#PCDATA)>
<!ELEMENT SHIP_DATE (#PCDATA)>
<!ELEMENT SKU (#PCDATA)>
]]>

You might wonder what the big deal is here—after all, you can just use a comment to hide sections of a DTD. The usefulness of INCLUDE and IGNORE sections becomes more apparent when you use them together with parameter entities to parameterize DTDs. When you parameterize a DTD, you can include or ignore multiple sections of a DTD simply by changing the value of a parameter entity from IGNORE to INCLUDE or back again.

Here's an example; in this case, I'm going to let XML authors include or ignore sections of a DTD just by changing the value of a parameter entity named includer. To use a parameter entity in INCLUDE and IGNORE sections, you must work with the external DTD subset, so I'll set up an external DTD subset named order.dtd:

<?xml version = "1.0" standalone="no"?>
<!DOCTYPE DOCUMENT SYSTEM "order.dtd">
<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>Lettuce</PRODUCT>
                <NUMBER>6</NUMBER>
                <PRICE>$11.50</PRICE>
            </ITEM>
        </ORDERS>
    </CUSTOMER>
</DOCUMENT>

Here's what order.dtd looks like; first I set up the includer parameter entity, setting it to the text "INCLUDE" by default:

<!ENTITY % includer "INCLUDE">
<!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 use the value of this entity to set up an INCLUDE (or IGNORE) section in the DTD like this:

<!ENTITY % includer "INCLUDE">
<!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)>
<![ %includer; [
<!ELEMENT PRODUCT_ID (#PCDATA)>
<!ELEMENT SHIP_DATE (#PCDATA)>
<!ELEMENT SKU (#PCDATA)>
]]>

At this point, you can include or ignore the indicated section of the DTD just by changing the value of the includer entity. Using a technique like this makes it easy to centralize the entities that you need to use to customize a whole DTD at one time.

In fact, that's the way the XHTML 1.1 DTD works; XHTML is expressly built to be modular to allow devices that can't handle full XHTML to support partial implementations. The main XHTML 1.1 DTD is actually a DTD driver, which means that it includes the various XHTML 1.1 modules using parameter entities. For example, here's how the XHTML 1.1 DTD includes the DTD module (that is, a section of a DTD) that supports HTML tables, xhtml11-table-1.mod; note that it declares a parameter entity corresponding to that module and then uses an entity reference to include the actual module:

<!-- Tables Module ............................................... -->
<!ENTITY % xhtml-table.mod
     PUBLIC "-//W3C//ELEMENTS XHTML 1.1 Tables 1.0//EN"
            "xhtml11-table-1.mod" >
%xhtml-table.mod;

However, not all devices that support XHTML might be capable of supporting tables (for example, cell phones or PDAs). So, the XHTML 1.1 DTD also defines a parameter entity named xhtml-table.module that's set to "INCLUDE" by default and includes the table module with an INCLUDE section like this:

<!-- Tables Module ............................................... -->
<!ENTITY % xhtml-table.module "INCLUDE" >
<![%xhtml-table.module;[
<!ENTITY % xhtml-table.mod
     PUBLIC "-//W3C//ELEMENTS XHTML 1.1 Tables 1.0//EN"
            "xhtml11-table-1.mod" >
%xhtml-table.mod;]]>

Now you can customize the XHTML 1.1 DTD by changing the value of xhtml-table.module to "IGNORE" to exclude support for tables. Because all the various XHTML 1.1 DTD modules are part of INCLUDE sections based on parameter entities like this, that DTD is considered fully parameterized.