Special Edition Using SGML:Defining the Elements

Step 4: Keep Listing Elements Until None Are Left

This step doesn’t take long with simple document types. As you proceed, keep in mind the difference between content and structure. Structure is the logical place for the data, whereas content is the description of the data itself.

Suppose, for example, that the service bulletin’s paragraphs can have a parts description table. One column contains the part number, and the other column contains the description. You obviously need a table element. The column headings need tags because they are a subelement of the table element.

Structurally, the column heads have tags such as <COLHEAD1>Part Number<\COLHEAD1> and <COLHEAD2>Part Description<\COLHEAD2>. You also could use just <COLHEAD>. As for content, the tags might look like <PARTNUM>Part Number<\PARTNUM> and <PARTDESC>Part Description<\PARTDESC>. For now, though, think only of structure.

• See “Handling Tables,” p. 421

Note:
Tables are a complex issue in SGML. The <COLHEAD> example above is just to illustrate the importance of focusing on structural elements at this point. If your table needed to be part of a searchable database, <COLHEAD> would probably not suffice as an element name. For more discussion about the implications of format and content in tables, see Chapter 25, “Handling Specialized Content and Delivery.” If you want tables in your service bulletins, flag this fact and be sure you enlist the help of experienced SGML practitioners in your document analysis.

Step 5: Compare the Elements for Relationships and Groups

Now that you have identified all the structural elements in your service bulletin, try to assemble an experimental service bulletin using these elements. But as you do, pay close attention to the relationships that they have to each other. You’re looking for occurrence, hierarchy, and sequence. Three questions can guide you:

• What is the sequence of the elements?

• What elements are included by other elements?

• What elements can pop up anywhere?

• See “Sequencing Elements,” “Element Occurrence,” “Element Hierarchy,” and “Element Groups,” pp. 144-146, 150

Elements that can pop up anywhere sometimes include footnotes, warnings and cautions, notes, and special text.

Look through the copies of your sample service bulletins. Your documents are the final proof of the quality and accuracy of your analysis. If you analyzed correctly, the experimental service bulletin you try to create now will match the real-world documents in their structure. Otherwise, you might need another element or element group, or you might need to modify your elements’ content models. In any case, review the elements and their relationships. Check whether you should create new elements or consolidate elements you identified.

For example, in your service bulletin, you might like to add a <FrontMatter> element to group your <background>, <action>, and <effectivity> elements into. You might also add <Planning> and <Material> elements to group other elements into. This would be an example of adding elements to your structural definition, which you do in the next step.

Step 6: Check for Missing Elements

If you decide that you need more elements, create them now. You should check them to make sure that they are not already covered in another element description or content model. If they are, rename elements to avoid confusion. For example, if you discover a <material> element inside the <FrontMatter> element and another <material> element that is at the same level of hierarchy as the <FrontMatter> element, you should rename them to avoid confusion. In a service bulletin, you could easily expect to see a brief section about affected materials in the front matter, and another fully-detailed section about materials deeper in the document. These elements are structurally different, so they require different element names.

Some things you should look for are:

• Extra formatted items (such as a bulleted list)

• Included elements (such as a bullet graphic)

• Subtle changes in structure or appearance (like extra spacing after certain paragraphs)

Step 7: Construct a Structure Tree

Create a diagram like the one in figure 7.3. Add occurrence symbols like the ones shown in figure 7.4 to help you keep track of elements. Go through the whole document, and account for its entire structure.

You should test whether anything in your document type samples can be accounted for by more than one element. In other words, is there any ambiguity in your element definitions?

Some SGML software can help you to create a structure tree. Figure 7.6 shows a structure tree of the ATA service bulletin model.

Fig. 7.6 Software like Microstar’s Near & Far Author can help you create structure diagrams.

• See “Near & Far Author” and “Near & Far,” pp. 440, 461

Step 8: Assemble an Element Dictionary

Collect the element descriptions from step 3. These should have been modified throughout this process as you modified your elements. The purpose behind a dictionary of elements is to help people who will use your model later. Unless you work with it every day, it’s easy to forget all the details of a model. You need to have a way of recording what your elements mean.

A dictionary of the elements for each document type is useful not only for you but also for anybody else who maintains your DTDs, such as SGML consultants or even ambitious authors. The only time you can have too much documentation is when several people keep documentation that is not consistent. Therefore, make sure that revisions to your dictionary are consistent.

As element definitions and content models are modified with use over time, DTDs must be modified. DTDs and element definitions should track each other exactly. If Revision A of the Service Bulletin DTD affects the <material> element’s content model, there should be a Revisions A in the element dictionary that tracks with that change. Don’t let revisions to the element dictionary and the DTD get out of sync. You should maintain a controlled copy of this dictionary. You will probably want to set up a procedure for updating the dictionary that involves input from the people who use it.

Table of Contents