10.4.2.1. Multiple sequences

If you wish to dictate that multiple elements must appear in a specific order between the opening and closing tags of a specific element, you can use a comma (,) to separate the two instances:

<!ELEMENT books (title, authors)>
<!ELEMENT title (#PCDATA)>
<!ELEMENT authors (#PCDATA)>

In the preceding declaration, the DTD states that within the opening <books> and closing </books> tags, there must first appear a <title> element consisting of parsed character data. It must be immediately followed by an <authors> element containing parsed character data. The <authors> element cannot precede the <title> element.

Here is a valid XML document for the DTD excerpt defined previously:

<books>
   <title>Webmaster in a Nutshell, Third Edition</title>
   <authors>Stephen Spainhour and Robert Eckstein</authors>
</books>

The previous example showed how to specify both elements in a declaration. You can just as easily specify that one or the other appear (but not both) by using the vertical bar (|):

<!ELEMENT books (title|authors)>
<!ELEMENT title (#PCDATA)>
<!ELEMENT authors (#PCDATA)>

This declaration states that either a <title> element or an <authors> element can appear inside the <books> element. Note that it must have one or the other. If you omit both elements or include both elements, the XML document is not considered valid. You can, however, use a recurrence operator to allow such an element to appear more than once. Let's talk about that now.

10.4.2.3. Mixed content

Using the rules of grouping and recurrence to their fullest allows you to create very useful elements that contain mixed content. Elements with mixed content contain child elements that can intermingle with PCDATA. The most obvious example of this is a paragraph:

<para>
This is a <emphasis>paragraph</emphasis> element. It
contains this <link ref="http://www.w3.org">link</link>
to the W3C. Their website is <emphasis>very</emphasis>
helpful.
</para>

Mixed content declarations look like this:

<!ELEMENT quote (#PCDATA|name|joke|soundbite)*>

This declaration allows a <quote> element to contain text (#PCDATA), <name> elements, <joke> elements, and/or <soundbite> elements in any order. You can't specify things such as:

<!ELEMENT memo (#PCDATA, from, #PCDATA, to, content)>

Once you include #PCDATA in a declaration, any following elements must be separated by or bars (|), and the grouping must be optional and repeatable (*).

10.4.2.4. Empty elements

You must also declare each of the empty elements that can be used inside a valid XML document. This can be done with the EMPTY keyword:

<!ELEMENT elementname EMPTY>

For example, the following declaration defines an element in the XML document that can be used as <statuscode/> or <statuscode></statuscode>:

<!ELEMENT statuscode EMPTY>

10.4.3.1. General entities

A general entity is an entity that can substitute other characters inside the XML document. The declaration for a general entity uses the following format:

<!ENTITY name "replacement_characters">

We have already seen five general entity references, one for each of the characters <, >, &, ', and ". Each of these can be used inside an XML document to prevent the XML processor from interpreting the characters as markup. (Incidentally, you do not need to declare these in your DTD; they are always provided for you.)

Earlier, we provided an entity reference for the copyright character. We could declare such an entity in the DTD with the following:

<!ENTITY copyright "&#xA9;">

Again, we have tied the &copyright; entity to Unicode value 169 (or hexadecimal 0xA9), which is the circled-C (©) copyright character. You can then use the following in your XML document:

<copyright>
&copyright; 2001 by MyCompany, Inc.
</copyright>

There are a couple of restrictions to declaring entities:

• You cannot make circular references in the declarations. For example, the following is invalid:

  <!ENTITY entitya "&entityb; is really neat!">
  <!ENTITY entityb "&entitya; is also really neat!">

• You cannot substitute nondocument text in a DTD with a general entity reference. The general entity reference is resolved only in an XML document, not a DTD document. (If you wish to have an entity reference resolved in the DTD, you must instead use a parameter entity reference.)

10.4.3.2. Parameter entities

Parameter entity references appear only in DTDs and are replaced by their entity definitions in the DTD. All parameter entity references begin with a percent sign, which denotes that they cannot be used in an XML document—only in the DTD in which they are defined. Here is how to define a parameter entity:

<!ENTITY % name "replacement_characters">

Here are some examples using parameter entity references:

<!ENTITY % pcdata "(#PCDATA)">
<!ELEMENT authortitle %pcdata;>

As with general entity references, you can't make circular references in declarations. In addition, parameter entity references must be declared before they can be used.

10.4.3.4. Unparsed entities

By the same token, you can use an unparsed entity to declare non-XML content in an XML document. For example, if you want to declare an outside image to be used inside an XML document, you can specify the following in the DTD:

<!ENTITY image1 SYSTEM
      "http://www.oreilly.com/ora.gif" NDATA GIF89a>

Note that we also specify the NDATA (notation data) keyword, which tells exactly what type of unparsed entity the XML processor is dealing with. You typically use an unparsed entity reference as the value of an element's attribute, one defined in the DTD with the type ENTITY or ENTITIES. Here is how you should use the unparsed entity declared previously:

<image src="image1"/>

Note that we did not use an ampersand (&) or a semicolon (;). These are only used with parsed entities.

10.4.3.5. Notations

Finally, notations are used in conjunction with unparsed entities. A notation declaration simply matches the value of an NDATA keyword (GIF89a in our example) with more specific information. Applications are free to use or ignore this information as they see fit:

<!NOTATION GIF89a SYSTEM "-//CompuServe//NOTATION
      Graphics Interchange Format 89a//EN">

10.4.5.1. Internal subsets

You can place parts of your DTD declarations inside the DOCTYPE declaration of the XML document, as shown:

<!DOCTYPE boilerplate SYSTEM "generic-inc.dtd" [
   <!ENTITY corpname "Acme, Inc.">
]>

The region between brackets is called the DTD's internal subset. When a parser reads the DTD, the internal subset is read first, followed by the external subset, which is the file referenced by the DOCTYPE declaration.

There are restrictions on the complexity of the internal subset, as well as processing expectations that affect how you should structure it:

• Conditional sections (such as INCLUDE or IGNORE) are not permitted in an internal subset.

• Any parameter entity reference in the internal subset must expand to zero or more declarations. For example, specifying the following parameter entity reference is legal:

  %paradecl;

  as long as %paradecl; expands to the following:

  <!ELEMENT para CDATA>

  However, if you simply write the following in the internal subset, it is considered illegal because it does not expand to a whole declaration:

  <!ELEMENT para (%paracont;)>

Nonvalidating parsers aren't required to read the external subset and process its contents, but they are required to process any defaults and entity declarations in the internal subset. However, a parameter entity can change the meaning of those declarations in an unresolvable way. Therefore, a parser must stop processing the internal subset when it comes to the first external parameter entity reference that it does not process. If it's an internal reference, it can expand it, and if it chooses to fetch the entity, it can continue processing. If it does not process the entity's replacement, it must not process the attribute list or entity declarations in the internal subset.

Why use this? Since some entity declarations are often relevant only to a single document (for example, declarations of chapter entities or other content files), the internal subset is a good place to put them. Similarly, if a particular document needs to override or alter the DTD values it uses, you can place a new definition in the internal subset. Finally, in the event that an XML processor is nonvalidating (as we mentioned previously), the internal subset is the best place to put certain DTD-related information, such as the identification of ID and IDREF attributes, attribute defaults, and entity declarations.