How to Build A New Custom DTD

The Concept

The basic idea for a new DTD is that all lower-level elements (paragraphs, lists, figures, etc.) will be defined in modules, either the modules of the Suite or in new DTD-specific modules, not in the DTD itself. The DTD will be fairly short and include only definitions of the topmost element(s), at least the document element and maybe its children.

Modules are defined using External Parameter Entities in with the Suite Module of Modules or in the DTD-specific Module of Modules. Modules are called (referenced) in the DTD, in the order needed to define the Parameter Entities in sequence.

Version 2.0 of this Journal Archiving and Interchange was written as an example of the new best-practice customization technique. A new DTD that follows this plan will probably consist of the following modules:

• A DTD module to define the top-level elements (e.g., yournew.dtd);
• A DTD-specific definition of element classes to add new classes and over-ride the default classes; (for example, %yournew-classes.ent;)
• A DTD-specific definition of element mixes to add new mixes and over-ride the default mixes; (for example, %yournew-mixes.ent;);
• A DTD-specific module of content model over-rides (for example, %yournew-models.ent;).
• A DTD-specific Module of Modules to name the non-Suite modules in the DTD (for example, %yournew-modules.ent;)
• DTD-specific modules to hold new types of element declarations (e.g., %taxonomic-key.ent; or %help-topic-meta.ent;); and
• All or most of the modules in the base Suite.

Example: Making a New DTD Using the Suite

To show the process, here is a series of instructions for making a new DTD, illustrated by showing how Journal Archiving and Interchange DTD was created from the modules of the whole Suite.

1. Modules —Write a new DTD-specific Module of Modules, which defines all new customization modules the DTD needs. (As an example, the Archiving DTD created the module %archivecustom-modules.ent;, which contains the definitions of the class-over-ride module %archivecustom-classes.ent;, the mix-over-ride module %archivecustom-mixes.ent;, and the models-over-ride module %archivecustom-models.ent;.)
2. Class Over-rides —Write a DTD-specific class-over-ride module, defining any over-rides to the Suite classes. These classes were defined in the default classes module. (As an example, the Archiving DTD created the module %archivecustom-classes.ent;, in which a new model for %contrib-info.class; was declared and an entirely new class %x.class; was added.)
3. Mix Over-rides —Write a DTD-specific mix-over-ride module, defining any over-rides to the Suite mixes. These mixes were defined in the default mixes module. (As an example, the Archiving DTD created the module %archivecustom-mixes.ent;, in which a new mix %all-phrase; was declared and then used in many existing mixes, such as%simple-phrase;.)
4. Model Over-rides —Create a DTD-specific content-model-over-ride module, defining any over-rides to the content models and attribute lists for the DTD Suite. (As an example, the Archiving DTD created the module %archivecustom-models.ent;, in which element collections (suffixed “-element”) that will be mixed with #PCDATA were redefined, full content models over-rides (suffixed “-model”) were redefined, and some new attributes and attribute lists were added.
5. New Elements —Write any new element modules needed. These will define any new block-level or phrase-level elements. (As an example, the Archiving DTD did not need any new elements not in the Suite, but the new NLM Book DTD added modules for book metadata and book component parts.)
6. DTD Module —Use the modules just described in the construction of a new DTD module. Within that DTD module:
   • Use an External Parameter Entity Declaration to name and then call the DTD-specific modules of modules (For the Archiving DTD, the module %archivecustom-modules.ent;.)
   • Use an External Parameter Entity Declaration to name and then call the DTD Suite modules of modules, which names all the potential modules. (For the Archiving DTD, the module %modules.ent;.);
   • Use an External Parameter Entity reference to call the DTD-specific class over-rides (For the Archiving DTD, the module %archivecustom-classes.ent;.);
   • Use an External Parameter Entity reference to call the DTD Suite default classes (For the Archiving DTD, the module %default-classes.ent;.);
   • Use an External Parameter Entity reference to call the DTD-specific mix over-rides (For the Archiving DTD, the module %archivecustom-mixes.ent;.);
   • Use an External Parameter Entity reference to call the DTD Suite default mixes (For the Archiving DTD, the module %default-mixes.ent;.);
   • Use an External Parameter Entity reference to call the DTD-specific content models and attribute list over-rides (For the Archiving DTD, the module %archivecustom-models.ent;.);
   • Use an External Parameter Entity reference to call in the standard Common Module (%common.ent;) that defines elements and attributes so common they are used by many modules.
   • Select, from the Module to Name the Modules, those modules which contain the elements needed for the DTD (for instance, selecting lists and not selecting math elements) and calling in each of the modules needed; (The Archive DTD calls these in alphabetical order, since the order does not matter.)
   • Define the document element and any other unique elements and entities needed for this DTD. (For example, the Archiving DTD declares only six elements — <article> [the top-level element] and its components: <front>, <body>, <back>, <sub-article>, and <response>.)