Soltys Family Home | Internet Resources For Technical Communicators | Articles | Core Dump


EDD Maintenance Techniques

by Lynne A. Price

Note: This article was assembled from several posts by Lynne to the Framers mailing list.

Introduction
Using Variables
Using Conditional Text
Working with a Metatemplate
Working with Text Insets

Introduction

FrameMaker and FrameMaker+SGML are separate but related products. In FrameMaker, the user model of a document is a sequence of paragraphs, with a paragraph format assigned to each. While FrameMaker+SGML structured documents still consist of tagged paragraphs, users have a different model. The document consists of a hierarchy of elements, each consisting of text and/or other elements: books consist of chapters, chapters begin with titles followed by sections, sections have paragraphs, lists, tables, and figures, lists have list items, paragraphs and list items contain text interspersed with emphasized phrases, part numbers, and so on. There is no universal set of element types: different document types use different elements and permit different arrangements of elements. Formatting is automatic-the software assigns paragraph or character formats or properties to elements based on the context in which they occur.

For example, the writer doesn't have to remember which heading format to use for section titles at different levels. FrameMaker+SGML might be configured to use Heading1 for titles of first-level sections, Heading2 for titles of second-level sections and so on. If the writer rearranges a document by, say, grouping two previously first-level sections into subsections of a new first-level section, he doesn't need to retag the section titles. FrameMaker+SGML recognizes the new context and reformats them automatically. By the way, it is pretty easy to wrap a new section around the existing sections-there is no need for the writer to find the beginning and end of the original sections to select them.

An Element Definition Document or EDD is a FrameMaker+SGML structured document that defines the element types that are used for a particular project, the contexts in which an element is permitted, and the formatting that pertains in each context.

Using Variables

Using a variable in the EDD, just like a variable in any other FM document, eliminates the possibility of typos in some occurrences of a repeated string and also allows all occurrences to be changed by editing a single definition.

When I use variables in an EDD (or in an SGML application file), I usually use a character format to distinguish them from surrounding text. For example, I've been working on one project in which the same EDD is used sometimes for technical documentation and sometimes for training material. The primary division of a book is called Chapter in technical documentation and Module in training material, so I use a variable named Chapter that is defined to be

<Variable>Chapter 

when I'm working with technical documentation. When I'm working with training material, I import variable definitions from another file into the EDD. The second file defines the Chapter variable to be

<Variable>Module 

In the EDD character format Variable is defined to set the color to red.

Using Conditional Text

I also use numerous text insets. I use conditional text to make the text insets visible by defining a condition with condition indicators to set the desired appearance. I then do a global Find/Change searching for text insets and changing by pasting to apply the condition. I never hide this condition; I use it only for formatting. In this way, without using format overrides, I have a visual clue about which parts of my EDD are text insets.

Conditional text is a good tool for something that occurs just once. The element tags occur several times in the EDD. To make the distinction with conditional text, I'd need to retype the element tags and assign the condition tags with each occurrence. There is a risk that I could make a mistake in any of these repetitions. Furthermore, if I make any changes, I'd have to make them repeatedly.

Working with a Metatemplate

In my metatemplate (template for EDDs), instead of making Element valid at the highest level, I define a new element called SGMLFragment. I define SGMLFragment with the general rule <ANY> and define it to be valid at the highest level. FM+SGML treats the element tag SGMLFragment differently than other element tags. In particular, elements with this tag are unwrapped when they are the highest-level element in a text inset. Thus, an SGMLFragment can consist of a sequence of attribute definitions or several format rules.

If an attribute is used by several element types, I can define it in an SGMLFragment and include that fragment as a text inset in multiple element definitions. I can then change the default value or make the attribute hidden for all element types just by editing the fragment in one place. Because SGMLFragment is unwrapped, an element definition can include both attribute definitions from text insets and those entered directly.

If I'm working on one EDD, I often define the SGMLFragments in reference flows in the EDD, so the entire structure is maintained in one file. Of course, if several EDDs share the same text insets, I put them in a separate file.

You can modify the metatemplate to support multiple highest-level elements. You can also define additional documentation elements (for example., notes, tables, and lists as well as Paras) and change the formatting. Feel free to look at the metatemplate I use. It's at http://www.txstruct.com/MetaTemplate (case is significant). This directory contains the files:

MetaEDD.edd has comments that enumerate the various changes I've made to Adobe's original metatemplate.

Working with Text Insets

While the following comments refer to the use of text insets in EDDs, they conclude by describing some bugs in FM+SGML 6.0 that are relevant to the use of FM text insets in all structured documents.

At last year's FrameUsers conference, I described a tool for maintaining a set of related EDDs. A key point was using text insets for fragments of an EDD that occur multiple times. For example, numerous elements may share one or more attribute definitions or one or more format rules. Placing these definitions in text insets allows editing one copy to affect all instances, and ensures there are no inadvertent differences. Like all structured flows, a structured flow used as a text inset must have a highest-level element. This element can be any element defined in the metatemplate (i.e., in the template used by EDDs). For such flows to be valid, though, the original Adobe metatemplate must be modified to make those elements that are used as highest-level elements of text insets to be valid at the highest level.

An alternative is to define a new element, which might be called TextInset, with the general rule <ANY> to be used as the highest level element of text insets. This approach has the advantage that a TextInset element can have multiple children and hence allows a text inset to define more than one attribute or more than one format rule. The approach has disadvantages also. The metatemplate must be modified to allow the TextInset element. And an FDK client is needed to unwrap the TextInset elements before element definitions from the EDD can be imported into a template.

However the TextInset element should not be needed. FM+SGML automatically unwraps an element named SGMLFragment when that element is the highest-level element of a text inset. Thus, it should be possible to use SGMLFragment just as I have been using TextInset with no need to write an FDK client to unwrap it. Furthermore, since the SGMLFragment element will not appear in the main EDD, its metatemplate does not need to account for the use of SGMLFragment.

Unfortunately, FM+SGML does not seem to handle SGMLFragment correctly. Both 5.5.6 and 6.0 correctly unwrap SGMLFragment at the highest-level of a text inset when the SGMLFragment has only one child; when it has multiple children, though, SGMLFragment is simply replaced with NoName. Furthermore, FM+SGML 6.0 has a tendency to crash when such text insets are updated.

 

Back to top


Soltys Family Home | Internet Resources For Technical Communicators | Articles | Core Dump