Special Edition Using SGML:Following Good SGML Practice

Handling Inclusions and Exclusions

Inclusions and exclusions are both examples of exceptions in SGML. Including and excluding elements from content models is a powerful feature in SGML. It is also one of the easiest aspects of DTD development to abuse.

Note:
Inclusions and exclusions are exceptions to a specific content model. An exception refers to something added to or removed from a content model. For example:
<!ELEMENT friedchk - - (KFC|homemade|other) +(fatfree) >

The fatfree value is being added to the normal content value, so it is an exception to the normal content. It is an inclusion. In:

<!ELEMENT friedchk - - (KFC|homemade|other) -(KFC) >

the exception is KFC, which is being removed from the content model. It is an exclusion.

Exception Reminders

You need to remember several things about all exceptions to content models:

• Exceptions apply to all parts of the element’s content model; for example, if you add a locator to an endnote element’s content model, each of the elements in the model can now have a locator

• Exceptions are not just simple additions for the sake of convenience; they apply pervasively throughout the document

• You can avoid many of these problems by using simple data models and good DTD design principles

• Exclusions appear before inclusions when they both appear after the same content model

Common Mistakes

You can abuse the use of exceptions if you are not careful. In fact, there are several common ways mistakes can be made with exceptions.

Inclusion at Too High of a Level. Sometimes you can include content values in such high-level elements that you must exclude them later in the smaller submodels of content. It’s easy to get confused with long attribute lists and long content models for entities. Don’t make inclusion statements on content models that are top-level and are the larger DTD elements. When you make inclusions at such a high level of structural order, you will likely have to make an exclusion statement later just to compensate. It is much better to simply modify the content model itself without an exclusion statement. Consider figure 14.11.

Fig. 14.11 Don’t make inclusions at too high of a document level.

This shows that the inclusion added to the <CHAPTER> element had to be removed from the <EQUATION> element later on.

Excluding Explicitly Declared Content. Sometimes people exclude content that was explicitly declared in the content model. For whatever reason, they choose not to update the content model itself, but to declare the exception to the content model anyway. This is not always a good practice. You should probably just update the content model. If you’re not updating the content model, it probably means that you have not defined the structure of the document very thoroughly. If you’re trying to patch together the content model with exception statements, you are glossing over a deeper structural problem with your DTD. If you run across something that looks like the following, there is a deeper problem in your document design that you should be looking at:

    <!ELEMENT chapter - - (body, heading)   >

    <!ELEMENT body - o (P|A|MA|W|CAU|subsec) -(subsec) >

If <BODY> doesn’t need the <SUBSEC> element, the content model itself should be updated. Don’t try to remove the <SUBSEC> element with an exclusion. Make the fix at the structural level, not at a superficial level.

Inclusion at Too Low of a Level. This is just the opposite of including at too high of a level. This accident usually happens when a vital element has been accidentally excluded at a higher level of DTD structure. It then must be included in a content model at a lower level. The moral of the story is to not exclude it in the first place—create another element with a different content model. You can also create an entity to serve the type of special need that you were trying to fix with the inclusion. Figure 14.12 shows an example of the problem.

Fig. 14.12 Don’t use inclusion at too low of a level in the document type.

For whatever reason, at the higher level it looked like a good idea to exclude <E>. When you got down to the element <LITTLE>, you needed to put the content back in. Figure 14.13 shows a fix.

Fig. 14.13 You can use entities to overcome the problem illustrated in figure 14.12.

Now the <E> element can remain apart from the higher element’s content while still being allowed within the <LITTLE> element. This is a handy use for entities, and one reason why you run into them so often.

A more concrete example will further explain this problem. Suppose you want to enforce the exclusion of footnotes at the <BIG> level of a document type, but you want to allow authors to include footnotes (the <E> element) inside the <LITTLE> element. By using <E> as the content model for the %extra; entity, you can enforce the exclusion of footnotes at the higher level, but permit including it at the lower level. The parser will return an error to authors who include footnotes any higher than the <LITTLE> element.

Inclusion Instead of OR Connectors. Sometimes people want to use inclusion instead of adding another OR connector to the content model. This might be faster, but it’s much more dangerous. This is a good example of a structure that would satisfy the parser quickly, but it’s dangerous in that you leave a half-completed content model for someone else to clean up later. Here’s an example:

    <!ELEMENT chapter - - (heading,section)   >
    <!ELEMENT section - o (para*) +(note|%text;|ref|list|%P;) >

Don’t ever do anything like this. Restructure your content model instead, or use a parameter entity to alter the content model.

• See “Entities,” p. 58
• See “Entities: Their Use and the ENTITY Markup Declaration,” p. 184

This scenario probably happened because several people worked on content models for elements, and they did not agree on the values beforehand. One person thought he would make a quick fix. It parsed the DTD, but it’s a dangerous design. He should have made the fix properly by correcting the content model together with his partners.

Table of Contents