About DTD integration

Before you start integrating another set of DTDs into your topic and map shells, it's important to understand a few basic things about that process. The following explanation is quite simplified. If you want to understand DITA DTDs in more detail, there are many good online references available.

First of all, referring to "a set of DTDs" is a little misleading. A set of DTDs typically includes not only .dtd files but also .mod and .ent files. Saying "a set of DTDs" is shorthand for all of these files.

Looking at a set of DTDs within a DTD plugin, you can see that sometimes there is a .dtd file, a .mod (model) file, and a .ent (entity) file with the same name. A .dtd file typically defines a topic or map type. For example, if you specialize a "report" topic type in addition to topic, concept, task, reference, and troubleshooting, then you will likely have a report.dtd, report.mod, and report.ent file.

Sometimes there is only a .mod and a .ent file with the same name. This arrangement typically indicates a set of specialized elements that are used in several of your specialized topic or map types. They are not actual topic or map types, so they don't have a .dtd file, but the various .dtd files in the set do reference these .mod and .ent files.

Sometimes there is only a .mod file. This case usually indicates an element constraint; you have redefined an element's model to disallow child elements that are allowed in the "generic" DITA standard. The IXIASOFT section and paragraph constraints are examples of this.

Sometimes there is only a .ent file. This case usually indicates a domain constraint, where you have, for example, redefined the highlight domain to allow only <sub> and <sup> and disallow all the other elements in that domain (<b>, <i>, etc.).

When you are integrating a set of DTDs into your topic and map shells, you are primarily concerned with the .dtd files. Each .dtd file integrates the necessary "default" .mod and .ent files (meaning the DITA "out of the box" files such as concept.mod or reference.ent) as well as the necessary custom .mod and .ent files. During the integration process, you work your way through each .dtd file. You disregard the "default" .mod and .ent integrations to find only the custom ones, which you then copy and paste into the corresponding section in your topic and map shells.

As you might imagine, there is no one-size-fits-all procedure for this process. The pattern you follow is essentially the same but there are variances depending on the nature of the DTDs you are integrating.