| Previous | Table of Contents | Next |
This chapter is short—but important. Formatting DTDs is something that you do every time you write one. It is a simple practice, but very necessary.
You can look at a DTD in two ways: the whole DTD at once and the single line declaration. To format a DTD correctly, you need to consider both.
In this chapter, you learn:
By now you have seen different ways of looking at an SGML DTD. You have learned how to make declarations in SGML. When you designed the SGML environment and related elements together in Chapter 8, “Relating Elements to Each Other,” you did so at a distance.
The immediate problem is that new people eventually will have to work with your DTDs. Even if your documents and all your SGML code get thrown into the garbage, someone might resurrect them later. Your documents and DTDs might be around for a long time in this electronic age.
Bad things happen when people who need to understand your intentions cannot do so because you did not leave a trail for them to follow. All documents become old. Right now, it’s tempting to believe that no one but you needs to understand your documents—or perhaps the people who have been a part of your SGML design team. It’s tempting to think in terms of only the people who are working on a project today. Many more people, though, will be affected in the future by the decisions that you make today.
Consultants are likely to use your DTDs over the lifetime of your documents. They might add capabilities to your documents that you did not think useful—or possible. You prevent them from doing this if you do not format your DTDs adequately. Don’t put future users in the position of having to improvise because you failed to make allowances for them. Consultants are not the only ones to consider. There are also all of the readers and document users whose names you will never know.
Documents—especially electronic ones—are more likely than ever to outlive their creators. As archival capacities become more intelligent and efficient, the documents that you create today can remain online and accessible for years. Indeed, it is often more cost-efficient for system administrators to add storage capacity than to spend the time deleting old documents. The longevity of your documents increases the need for your DTDs to be understandable, efficient, and easy to follow.
Note:
When consultants cannot immediately understand your DTDs, they must make assumptions—sometimes inaccurate—about what you intended. Save them that trouble by making your DTDs clear.
Consider the DTD in listing 12.1. It looks busy and obscure. Elements are not grouped together, and there are no comments. Different components of the declarations are not aligned.
Listing 12.1 A Poorly Formatted but Parsable DTD
Notice, there are no historical comments about what the DTD is for, when it was revised, or whom to contact with questions.
<!DOCTYPE general PUBLIC "ISO 8879:1986//DTD General Document//EN" [
<!ENTITY % ISOnum PUBLIC
"ISO 8879:1986//ENTITIES Numeric and Special Graphic//EN">
<!ENTITY % ISOpub PUBLIC
"ISO 8879:1986//ENTITIES Publishing//EN">
%ISOnum; %ISOpub;]>
Notice, there are no comments about what any of these entities are used for.
<!ENTITY % doctype "general" >
<!ENTITY % p.em.ph "hp1|hp2|hp3|hp0|cit">
<!ENTITY % p.rf.ph "hdref|figref" >
<!ENTITY % p.rf.d "fnref|liref" >
<!ENTITY % p.zz.ph "q|(%p.em.ph;)|(%p.rf.ph;)|(%p.rf.d;)" >
<!ENTITY % ps.ul.d "ol|sl|ul|nl" >
<!ENTITY % ps.list "%ps.ul.d;|dl|gl">
<!ENTITY % ps.elem "xmp|lq|lines|tbl|address|artwork" >
<!ENTITY % ps.zz "(%ps.elem;)|(%ps.list;)" >
<!ENTITY % s.p.d "p|note" >
<!ENTITY % s.top "top1|top2|top3|top4" >
<!ENTITY % s.zz "(%s.p.d;)|(%ps.zz;)|(%s.top;)" >
<!ENTITY % i.float "fig|fn" >
<!ENTITY % fm.d "abstract|preface" >
<!ENTITY % bm.d "glossary|bibliog" >
<!ENTITY % m.ph "(#PCDATA|(%p.zz.ph;))*" >
<!ENTITY % m.p "(#PCDATA|(%p.zz.ph;)|(%ps.zz;))*" >
<!ENTITY % m.pseq "(p, ((%s.p.d;)|(%ps.zz;))*)" >
<!ENTITY % m.top "(th?, p, (%s.zz;)*)" >
<!ELEMENT %doctype; - - (frontm?, body, appendix?, backm?)
+(ix|%i.float;)>
Notice, there is nothing telling you that the entity declarations have ended and the element declarations have started.
<!ELEMENT frontm - O (titlep, (%fm.d;|h1)*, toc?, figlist?)>
<!ELEMENT body - O (h0+|h1+)>
<!ELEMENT appendix - O (h1+)>
<!ELEMENT backm - O ((%bm.d;|h1)*, index?)>
<!ELEMENT (toc|figlist|index) - O EMPTY >
<!ELEMENT titlep - O (title & docnum? & date? & abstract? &
(author|address|%s.zz;)*)>
<!ELEMENT (docnum|date|author)
- O (#PCDATA) >
<!ELEMENT title - O (tline+) >
<!ELEMENT tline O O %m.ph; >
<!ELEMENT h0 - O (h0t, (%s.zz;)*, h1+) >
<!ELEMENT (h1|%bm.d;|%fm.d;)
- O (h1t, (%s.zz;)*, h2*) >
<!ELEMENT h2 - O (h2t, (%s.zz;)*, h3*) >
<!ELEMENT h3 - O (h3t, (%s.zz;)*, h4*) >
<!ELEMENT h4 - O (h4t, (%s.zz;)*) >
<!ELEMENT (h0t|h1t|h2t|h3t|h4t)
O O %m.ph; >
| Previous | Table of Contents | Next |