6. Developing DTDs with defined and extended modules

Contents

This section is informative.

The primary purpose of defining XHTML modules and a general modularization methodology is to ease the development of document types that are based upon XHTML. These document types may extend XHTML by integrating additional capabilities (e.g. [SMIL] or [MathML]), or they may define a subset of XHTML for use in a specialized device. Regardless of the application, XHTML modules are up to the task. This section describes the techniques that document type designers must use in order to take advantage of this modularization architecture. It does this by applying the techniques defined in the previous sections in progressively more complex ways, culminating in the creation of a complete document type from disparate modules.

Note that in no case do these examples require the modification of the XHTML-provided module files themselves. The XHTML module files are completely parameterized, so that it is possible through separate module definitions and driver files to customize the definition and the content model of each element and each element's hierarchy.

Finally, remember that most users of XHTML are not expected to be DTD authors. DTD authors are generally people who are defining specialized markup that will improve the readability, simplify the rendering of a document, or ease machine-processing of documents, or they are client designers that need to define the specialized DTD for their specific client. Consider these cases:

6.1. Defining additional attributes

In some cases, an extension to XHTML can be as simple as additional attributes. Attributes can be added to an element just by specifying an additional ATTLIST for the element, for example:

<!ATTLIST a
      myml:myattr   CDATA        #IMPLIED
>

would add the "myattr" attribute, in the "myml" namespace, with a value type of CDATA, to the "a" element. This works because XML permits the definition or extension of the attribute list for an element at any point in a DTD.

Naturally, adding an attribute to a DTD does not mean that any new behavior is defined for arbitrary clients. However, a content developer could use an extra attribute to store information that is accessed by associated scripts via the Document Object Model (for example).

6.2. Defining additional elements

Defining additional elements is only slightly more complicated than defining additional attributes. Basically, DTD authors should write the element declaration for each element:

<!ELEMENT myml:myelement ( #PCDATA | myml:myotherelement )* >
<!ATTLIST myml:myelement
          myattribute    CDATA    #IMPLIED
>

<!ELEMENT myml:myotherelement EMPTY >

After the elements are defined, they need to be integrated into the content model. Strategies for integrating new elements or sets of elements into the content model are addressed in the next section.

6.3. Defining the content model for a collection of modules

Since the content model of XHTML modules is fully parameterized, DTD authors may modify the content model for every element in every module. The details of the DTD module interface are defined in XML DTD Modules. However, basically there are two ways to approach this modification:

  1. Re-define the "<element>.content" entity for each element.
  2. Re-define one or more of the global content model entities (normally the *.extras parameter entity).

The strategy taken will depend upon the nature of the modules being combined and the nature of the elements being integrated. The remainder of this section describes techniques for integrating two different classes of modules.

6.3.1. Integrating a stand-alone module into XHTML

When a module (and remember, a module can be a collection of other modules) contains elements that only reference each other in their content model, it is said to be "internally complete". As such, the module can be used on its own (for example, you could define a DTD that was just that module, and use one of its elements as the root element). Integrating such a module into XHTML is a three step process:

  1. Decide what element(s) can be thought of as the root(s) of the new module.
  2. Decide where these elements need to attach in the XHTML content tree.
  3. Then, for each attachment point in the content tree, add the root element(s) to the content definition for the XHTML elements.

Consider attaching the elements defined above. In that example, the element myelement is the root. To attach this element under the img element, and only the img element, of XHTML, the following would work:

<!ENTITY % Img.content "( myml:myelement )*">

A DTD defined with this content model would allow a document like the following fragment:

<img src="...">
<myml:myelement xmlns:myml="http://www.my.org/DTDs/myml1_0.dtd">This is content of a locally defined element</myml:myelement>
</img>

It is important to note that normally the img element has a content model of EMPTY. By adding myelement to that content model, we are really just replacing EMPTY with myml:myelement. In the case of other elements that already have content models defined, the addition of an element would require the restating of the existing content model in addition to myml:myelement.

6.3.2. Mixing a new module throughout the modules in XHTML

Extending the example above, to attach this module everywhere that the %Flow.mix content model group is permitted, would require something like the following:

<!ENTITY % Misc.extra
     "| script | noscript | myml:myelement" >

Since the %Misc.extra content model class is used in the %Misc.class parameter entity, and that parameter entity is used throughout the XHTML Modules, the new module would become available throughout an extended XHTML document type.

6.4. Creating a new DTD

So far the examples in this section have described the methods of extending XHTML and XHTML's content model. Once this is done, the next step is to collect the modules that comprise the DTD into a single DTD driver, incorporating the new definitions so that they override and augment the basic XHTML definitions as appropriate.

When defining a new DTD, it is essential that any non-W3C elements and attributes be in their own XML Namespace. This namespace and its prefix must be declared in the document instance - either on the root element or when it is actually used.

6.4.1. Creating a simple DTD

Using the trivial example above, it is possible to define a new DTD that uses and extends the XHTML modules pretty easily. The following is a complete, working extended DTD:

<!ELEMENT myml:myelement ( #PCDATA | myml:myotherelement )* >
<!ATTLIST myml:myelement
     myattribute    CDATA   #IMPLIED
>

<!ELEMENT myml:myotherelement EMPTY >

<!ENTITY % Misc.extra
     "| script | noscript | myml:myelement" >

<!ENTITY % xhtml11.dtd PUBLIC "-//W3C//DTD XHTML 1.1//EN" 
       "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
%xhtml11.dtd;

When using this DTD, it is necessary to define the XML Namespace prefix. The start of a document using this new DTD might look like:

<!DOCTYPE html PUBLIC "-//MYORG//DTD XHTML-MyML 1.0//EN"
                "http://www.my.org/dtd/myml1_0.dtd" >
<html xmlns="http://www.w3.org/1999/xhtml" 
       xmlns:myml="http://www.my.org/dtd/myml1_0.dtd">
...

6.4.2. Creating a DTD by extending XHTML

Next, there is the situation where a complete, additional, and complex module is added to XHTML (or to a subset of XHTML). In essence, this is the same as in the trivial example above, the only difference being that the module being added is incorporated in the DTD by reference rather than explicitly including the new definitions in the DTD.

One such complex module is the DTD for [MathML]. In order to combine MathML and XHTML into a single DTD, an author would just decide where MathML content should be legal in the document, and add the MathML root element to the content model at that point:

<!ENTITY % XHTML1-math
     PUBLIC "-//W3C//MathML 1.0//EN"
            "http://www.w3.org/DTDs/MathML/MathML1.dtd" >
%XHTML1-math;

<!ENTITY % Inlspecial.extra "a | img | object | map | mathml:math" >

<!ENTITY % xhtml11.dtd
     PUBLIC "-//W3C//XHTML 1.1//EN"
            "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd" >
%xhtml11.dtd;

Note that, while this is a valid example, it does not create a working DTD at this time. The reason for this is that the MathML DTD defines two elements (var and select) that conflict directly with XHTML. This conflict needs to be resolved in order for the new DTD to work correctly. Further, the elements in the MathML DTD must be declared such that they have a namespace prefix on them because XHTML requires that new elements and attributes be in their own namespaces.

6.4.3. Creating a DTD by removing and replacing XHTML modules

Another way in which DTD authors may use XHTML modules is to define a DTD that is a subset of XHTML (because, for example, they are building devices or software that only supports a subset of XHTML). Doing this is only slightly more complex than the previous example. The basic steps to follow are:

  1. Take the XHTML 1.1 DTD as the basis of the new document type.
  2. Select the modules to remove from that DTD.
  3. Define a new DTD that "IGNOREs" the modules.

For example, consider a device that uses XHTML modules, but without forms or tables. The DTD for such a device would look like this:

<!ENTITY % xhtml-form.module "IGNORE" >
<!ENTITY % xhtml-table.module "IGNORE" >

<!ENTITY % xhtml11.mod
     PUBLIC "-//W3C//DTD XHTML 1.1//EN"
            "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd" >
%xhtml11.mod;

Note that this does not actually modify the content model for the XHTML 1.1 DTD. However, since XML ignores elements in content models that are not defined, the form and table elements are dropped from the model automatically.

6.4.4. Creating a DTD from whole cloth

Finally, some DTD authors may wish to start from scratch, using the XHTML Modularization framework as a toolkit for building a new markup language. This language must be made up of the minimal, required modules from XHTML. It may also contain other XHTML-defined modules or any other module that the author wishes to employ. In this example, we will take the basic XHTML required modules, add some XHTML-defined modules, and also add in the module we defined above.

The first step is to use the XHTML-provided template for a new module, modified for our new elements and attributes.

<!-- ...................................................................... -->
<!-- My Elements Module ................................................... -->
<!-- file: myelements-1_0.mod

     PUBLIC "-//MY COMPANY//ELEMENTS XHTML-MY Elements 1.0//EN"
     SYSTEM "http://www.my.org/DTDs/myelements-1_0.mod"

     xmlns:myml="http://www.my.org/DTDs/mylanguage-1_0.dtd"
     ...................................................................... -->

<!-- My Elements Module

     myns:myelement
     myns:myotherelement

     This module has no purpose other than to provide structure for some
     PCDATA content.
-->

<!ELEMENT myns:myelement ( #PCDATA | myns:myotherelement )* >
<!ATTLIST myns:myelement
          myattribute    CDATA    #IMPLIED
>

<!ELEMENT myns:myotherelement EMPTY >

<!-- end of myelements-1_0.mod -->

Next, use the XHTML-provided template for a new DTD, modified as appropriate for our new markup language:

<!-- ....................................................................... -->
<!-- MYLANGUAGE DTD  ....................................................... -->
<!-- file: mylanguage.dtd
-->

<!-- MYLANGUAGE DTD
-->
<!-- This is the DTD driver for mylanguage.

     Please use this formal public identifier to identify it:

         "-//MY COMPANY//DTD XHTML-MYML 1.0//EN"

     And this namespace for myml-unique elements:

         xmlns:myml="http://www.my.org/DTDs/mylanguage-1_0.dtd"
-->
<!ENTITY % XHTML.version  "-//MY COMPANY//DTD XHTML-MYML 1.0//EN" >

<!-- Reserved for use with the XLink namespace:
-->
<!ENTITY % XLINK.ns "" >
<!ENTITY % XLinkns.attrib "" >


<!-- reserved for future use with document profiles -->
<!ENTITY % XHTML.profile  "" >

<!-- Internationalization features
     This feature-test entity is used to declare elements
     and attributes used for internationalization support. Set it to INCLUDE
     or IGNORE as appropriate for your markup language.
-->
<!ENTITY % XHTML.I18n            "IGNORE" >

<!-- ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: -->

<!-- Redeclare the Misc.extra to include myelement to hook it into the
     content model.
-->

<!ENTITY % Misc.extra
     "| script | noscript | myml:myelement" >

<!-- Define the Content Model 
     Remember that you can modify this content model or replace it simply be
     changing the following ENTITY declaration.
-->
<!ENTITY % xhtml-model.mod
     PUBLIC "-//W3C//ENTITIES XHTML 1.1 Document Model 1.0//EN"
     SYSTEM "http://www.w3.org/TR/xhtml11/DTD/xhtml11-model-1.mod" >

<!-- Pre-Framework Redeclaration placeholder  .................... -->
<!-- this serves as a location to insert markup declarations
     into the DTD prior to the framework declarations.
-->
<!ENTITY % xhtml-prefw-redecl.module "IGNORE" >
<![%xhtml-prefw-redecl.module;[
%xhtml-prefw-redecl.mod;
<!-- end of xhtml-prefw-redecl.module -->]]>

<!-- The events module should be included here if you need it. In this
     skeleton it is IGNOREd.
-->
<!ENTITY % xhtml-events.module "IGNORE" >

<!-- Modular Framework Module  ................................... -->
<!ENTITY % xhtml-framework.module "INCLUDE" >
<![%xhtml-framework.module;[
<!ENTITY % xhtml-framework.mod
     PUBLIC "-//W3C//ENTITIES XHTML 1.1 Modular Framework 1.0//EN"
            "xhtml11-framework-1.mod" >
%xhtml-framework.mod;]]>

<!-- Post-Framework Redeclaration placeholder  ................... -->
<!-- this serves as a location to insert markup declarations 
     into the DTD following the framework declarations.
-->
<!ENTITY % xhtml-postfw-redecl.module "IGNORE" >
<![%xhtml-postfw-redecl.module;[
%xhtml-postfw-redecl.mod;
<!-- end of xhtml-postfw-redecl.module -->]]>

<!-- Basic Text Module (Required)  ............................... -->
<!ENTITY % xhtml-text.module "INCLUDE" >
<![%xhtml-text.module;[
<!ENTITY % xhtml-text.mod
     PUBLIC "-//W3C//ELEMENTS XHTML 1.1 Basic Text 1.0//EN"
            "xhtml11-text-1.mod" >
%xhtml-text.mod;]]>

<!-- Hypertext Module (required) ................................. -->
<!ENTITY % xhtml-hypertext.module "INCLUDE" >
<![%xhtml-hypertext.module;[
<!ENTITY % xhtml-hypertext.mod
     PUBLIC "-//W3C//ELEMENTS XHTML 1.1 Hypertext 1.0//EN"
            "xhtml11-hypertext-1.mod" >
%xhtml-hypertext.mod;]]>

<!-- Lists Module (required)  .................................... -->
<!ENTITY % xhtml-list.module "INCLUDE" >
<![%xhtml-list.module;[
<!ENTITY % xhtml-list.mod
     PUBLIC "-//W3C//ELEMENTS XHTML 1.1 Lists 1.0//EN"
            "xhtml11-list-1.mod" >
%xhtml-list.mod;]]>

<!-- Your modules can be included here.  Use the basic form defined above, and
     be sure to include the public FPI definition in your catalog file for
     each module that you define. You may also include W3C-defined modules at
     this point.
-->

<!-- My Elements Module   ........................................ -->
<!ENTITY % myelements.mod
     PUBLIC "-//MY COMPANY//ELEMENTS XHTML-MY Elements 1.0//EN"
            "http://www.my.org/DTDs/myelements-1_0.mod" >
%myelements.mod;>


<!-- Document Structure Module (required)  ....................... -->
<!ENTITY % xhtml-struct.module "INCLUDE" >
<![%xhtml-struct.module;[
<!ENTITY % xhtml-struct.mod
     PUBLIC "-//W3C//ELEMENTS XHTML 1.1 Document Structure 1.0//EN"
            "xhtml11-struct-1.mod" >
%xhtml-struct.mod;]]>

<!-- end of SKELETAL DTD  .................................................. -->
<!-- ....................................................................... -->

6.5. Using the new DTD

Once a new DTD has been developed, it can be used in any document. Using the DTD is as simple as just referencing it in the DOCTYPE declaration of a document:

<!DOCTYPE html PUBLIC "-//MY COMPANY//DTD XHTML-MYML 1.0//EN"
          "http://www.my.org/DTDs/myorg.dtd">
<html xmlns:myml="http://www.my.org/DTDs/mylanguage-1_0.dtd">
<head>
<title>MyOrg Document</title>
</head>
<body>
<p>This is an example document using the new elements:
<myml:myelement>A test element <myml:myotherelement /> </myml:myelement>
</p>
</body>
</html>