Designing Components for DTDs

Often you’ll have several DTDs you deal with on a regular basis. You’ll increase your overall efficiency if you design modular components or groups of structures that can be used by several DTDs. When there are many different types of documents with similar structures, these modular components make maintaining your DTDs a lot easier (see fig. 4.4).

Fig. 4.4  DTD components help you reuse parts of your DTDs. They also make maintaining your DTDs much easier.

Many times, especially in big companies, there’s more than one developer of DTDs. Usually, there is a team that develops the DTDs. Often, other people have to maintain the DTDs after the original developers are gone. The people who maintain the DTDs will change over time also. Making modular DTD components makes maintaining them far easier for everybody over the life of your documents and DTDs.

---

• See “When (and Why) To Use DTD Components” and “How To Make Components,” pp. 190, 197

• See “Maintaining Your DTD,” p. 239

---

---

Note:  
SGML’s tremendous flexibility allows you to handle groups of document structures in many different ways to suit your own objectives. For example, if you observe that your magazine articles and your service bulletins both require math equation structures, you might find it helpful to build a common DTD that contains these structures so both your service bulletins and magazine article DTDs can take advantage of the same common structures. Common DTDs contain groups of structures that can be used by multiple DTDs. This makes maintenance much more convenient and orderly than having duplicate structures in several DTDs.

---

DTDs are like computer programs. They grow and evolve as people’s needs evolve. Even if you have a single DTD to manage, you’re still going to have to “tweak” it in time.

There are basically three ways to make modular components for DTDs, and they all depend on using parameter entities in DTDs:

•  Make DTD components by fragment assembly. These are sometimes called DTD fragments. They are collections of common DTD structures that you reuse as much as you can between like DTDs. Keep a collection of these element subassemblies and use them to make whole DTDs. The earlier note about the common DTD for equations and tables is an example of this.

•  Make DTD components with parameter entities. Sometimes you don’t want to build entire DTDs with common elements, but you can still make parameter entities that perform “extra duty” so they can be used in multiple contexts and document types. Then, when you want to maintain the DTD component, just fix the one entity and you’ve fixed all DTDs that refer to that parameter entity. If you just want to use a small part of a table structure—a table caption definition, for instance—you can put the caption structure into a parameter entity and then define that entity as an element in your DTD.

•  Make DTD components by redefining entities. You can redefine an entity within a DTD and then call another DTD or subassembly that defines the same entity. Thus, you’re getting double duty out of that entity. For example, perhaps you want to use an existing table entity structure from the public domain but want to modify its caption element for your own needs. You could refer to the public entity, redefine the caption element in another one of your DTDs, and then refer to that DTD’s redefinition. This way you can have the public table definition customized with your own caption definition.

---

• See “Fragment Assembly,” p. 198

• See “DTD Redefinition,” p. 198

• See “Defining Parameter Entities as Elements,” p. 199

---

Evaluating DTDs

You evaluate DTDs by parsing them. The parser checks the DTD for compliance with the SGML standard and reports errors. Not only must your DTD specify your document design, it must do so within the rules of the SGML standard.

---

• See “Evaluating Your DTD,” p. 233

---

Parsing a DTD is different from parsing an SGML document. The parser ensures that a document instance conforms to the definition specified in its DTD. The same parser ensures that the DTD follows the logic and syntax rules specified in the SGML standard. The DTD must strictly follow the international SGML standard so that when document instances are compared to it, the parser’s analysis will be accurate.

Formatting the DTD for People (Not Machines)

If you don’t want to be the cause of someone else’s misery, you’ll format your DTDs for people, not just the parser. Structure your declarations into groups so they can be easily located in the DTD. Add comments and notes throughout, just as you would in a computer program, so the next person can pick up the threads that you leave behind. Remember, there might be four or five different people—or more—who will maintain a DTD over its lifetime.

---

• See “Why Formatting DTDs Is Important,” p. 201

---

Following Good SGML Practice

Because SGML is designed to be flexible, its conventions can tempt you to be too flexible and make unwise design decisions in your DTDs. Here are some common examples of poor decisions that you could make:

•  You decide to use an element when you should have used an attribute

•  You fail to handle content models properly, so you have ambiguous content that parses but causes your users a lot of problems

•  Your DTDs parse, but you didn’t test them under the same circumstances under which they will be used in production, so the DTDs don’t actually work as promised