XML in a Nutshell, 3rd Edition

Conditional Inclusion

XML offers the IGNORE directive for the purpose of “commenting out” a section of declarations. For example, a parser will ignore the following declaration of a production_note element, as if it weren’t in the DTD at all:

<![IGNORE[
  <!ELEMENT production_note (#PCDATA)>
]]>

This may not seem particularly useful. After all, you could always simply use an XML comment to comment out the declarations you want to remove temporarily from the DTD. If you feel that way, the INCLUDE directive is going to seem even more pointless. Its purpose is to indicate that the given declarations are actually used in the DTD. For example:

<![INCLUDE[
  <!ELEMENT production_note (#PCDATA)>
]]>

This has exactly the same effect and meaning as if the INCLUDE directive were not present. However, now consider what happens if we don’t use INCLUDE and IGNORE directly. Instead, suppose we define a parameter entity like this:

<!ENTITY % notes_allowed "INCLUDE">

Then we use a parameter entity reference instead of the keyword:

<![%notes_allowed;[
  <!ELEMENT production_note (#PCDATA)>
]]>

The notes_allowed parameter entity can be redefined from outside this DTD. In particular, it can be redefined in the internal DTD subset of a document. This provides a switch individual documents can use to turn the production_note declaration on or off. This technique allows document authors to select only the functionality they need from the DTD.