Defining Your Environment

This is the process of understanding what document types you have and how you use those documents. This includes considering the policies and guidelines (including any industry or company standards you must follow) and deciding if and how they will change your documents.

---

• See “Decide What Standards and Policies You Must Obey,” p. 112

---

Defining your environment is like designing your dream house. You have to plan it before you build it. You have to make sure everything fits together on paper before you try to make it fit with physical building materials. If it doesn’t fit (it’s never perfect at first), the fix is easier to make while it’s still on paper than it is to make once your dream house is under construction.

---

Caution:  
Don’t be too quick to breathe a sigh of relief because you think you’re a small one-person installation. You can still have complex policies and external considerations that will slow down your progress. Defining your environment is crucial for discovering and resolving these conflicts.

For example, your Internet provider can have space restrictions or equipment maintenance schedules that dictate how and where you link structural components of your online documents together. This type of conflit should become evident during the process of defining the environment.

---

When you’ve completed the process of defining your environment, you should know all your different types of documents and what you intend to do with them. If there are any “land mines” that will affect the path you chose, this is the time to map them out. In fact, following the dream house analogy, this is where you identify not only what type of house it is (i.e., Tudor, French Country, Colonial, and so on), but also the potential environmental hazards (frequent flooding, forest fires, mosquitoes, and so on).

For example, what if you’re doing a government contract and you forget that security status, configuration management, and usable on codes (applicable to Illustrated Parts Manuals for the government) all have to be maintained in your documents? You must know these requirements before you start the SGML publishing process. After you define your environment, including defining which military specifications you must follow in your contract, you know the requirements you must build into your documents.

Defining Your Elements

Once you have established which environmental considerations you must accommodate and which document types you will design, you’re ready to begin studying your first document type. A simple one is best to start, like the magazine article sample shown in figure 4.1.

Fig. 4.1  Defining your elements is dismantling your document into its building blocks.

You cut into the first document, pick out the structural components, and lay them to the side, much like a physiology student dissects a lab specimen. But in this case, your document is the first-ever lab specimen, so it’s up to you to define each structural component as you go.

---

• See “The Definition Process,” p. 137

---

During this step, you’ll take each document type and list all its building blocks—its elements, attributes, and entities, only they won’t look like <para>tagged stuff</para> yet. They’ll be a little friendlier looking. See figure 4.1 for an idea of what this process looks like with a sample magazine article.

After dismantling your document, you’ll have a summary of its building blocks. A magazine article could contain the building blocks listed in table 4.1.

Elements for other document types can be collected and listed, as shown in figure 4.2.

Fig. 4.2  Defining your elements is breaking your document types into their respective building blocks.

---

Note:  
Don’t worry about SGML syntax at this stage. Don’t even worry about making it “look” like an SGML element.

At this stage, you can make notes on elements and attributes for DTDs, but you’ll actually create those later (in content modeling).

Just have a clear idea of what you’re going to put in those DTDs later.

---

Relating Elements to Each Other

The next step is determining sequence, hierarchy, and occurrence for each element of your selected document type. The elements in the magazine article example must appear in a certain sequence. For example, the title comes before the subtitle and the byline, and so forth. Also, certain elements may not occur outside of other elements, so they have a hierarchy. (For example, a graphic image could not be found outside of a paragraph. A quote could not be found inside a subtitle.) Some elements might occur only once, like the <TITLE> and <AUTHOR> elements, but there may be many <PARA> and <GRAPHIC> elements. However, for each <GRAPHIC> element, you must have a single <CAPTION> element. These are all examples of relating elements by sequence, hierarchy, and occurrence.

In addition to determining sequence, hierarchy, and occurrence, you can also group common elements together in this step. The magazine article example above is quite simple, but if you have to deal with complicated articles that have tables and math equations, you would need to define many more elements. In such a case, you could collect all table elements together in one group and all math equation elements together in another group. These groups of elements, and any others of your choice, would be very convenient when you design your DTD.