Product Review

XML's surface-level simplicity hides a deceptively complex beast. At first glance, creating an XML document does not take a lot of effort. Create some tags, ensure they are well-formed, and that's it. Throw in a DTD or Schema and now there are a set of rules against which the document can be validated. There is an innumerable amount of XML documents created in the world today in this manner. And for many scenarios, this is a perfectly reasonable approach.

But XML is so much more than that. Among other things, XML promises and delivers the separation of many concerns. The rules governing the structure of a document may be separated from the document; a document's presentation and formatting information may be independent of its content; and XML documents are not tied to any single platform. These are but a few of the benefits of the technology. However, fully realizing these benefits can become extremely complicated.

Take content and presentation separation as an example. In many ways, XSL Stylesheets achieve this goal. However, they can quickly grow to contain complex and convoluted logic even for relatively simple formats. Achieving the results worthy of professional publications, including image manipulation, cross-references within documents with large volumes of text can be all but impossible. This is where Adobe FrameMaker 7.1 steps in.

FrameMaker is an authoring and publishing solution that brings the benefits of XML to the publishing world. Incorporated into its standard feature set is the ability to author and publish content based on the structured data within an XML document, while maintaining the business rules associated with the content of the document. For the purposes of this review, only the XML components of FrameMaker will be addressed.

Working with Structured Documents
Structured documents are any documents that follow a predetermined hierarchy. Editing structured documents in FrameMaker requires set up of several standard supporting files, a few of which include the following:

• Structured template: Document that defines, in FrameMaker terms, the elements and attributes of a document. This is comparable to a DTD or XML Schema but specifically for FrameMaker.
• XML DTD: Standard DTD associated with an XML document.
• Import and export (read/write) rules: This document provides the translation between XML and FrameMaker. This is loosely analogous to an XSL Stylesheet for transforming XML tags to FrameMaker document elements.
• EDD: The Element Definition Document defines the FrameMaker-specific structural rules and formatting information. In a way, this acts as a secondary XSL Stylesheet for transforming XML tags to FrameMaker document elements.

It is important to note that when editing structured documents in FrameMaker, the author is not working directly with raw XML. Only when the document is exported and transformed according to the import/ export rules is XML actually generated.

Figure 1 shows an example of the structured FrameMaker environment. Pictured is the setup for this article. (Note: In the interest of full disclosure, this article was authored in both MS Word and Adobe FrameMaker. However, it was submitted to the magazine's editors in Word format.) Visible in the left portion of the screen is the EDD for the document. In it appears the FrameMaker element names, the subelements that are valid for each, the cardinality for the occurrence of each, and the relevant text formatting rules. In the middle of the window is the text of this article as it appears after all formatting rules have been applied. The top half of the right side of the image shows the XML hierarchy of the article itself; the raw XML of which is shown in Listing 1. The bottom half acts as a contextual guide listing what elements are available for placement into the document at the current insertion point.

Writing This Article
In working with the tool, it was clear that the majority of the effort of working with XML centers on three main tasks:

1. Setting up the FrameMaker application definition
2. Establishing the read/write rules for the XML document
3. Creating and applying the transformation and formatting rules

An application in Adobe FrameMaker is a series of configuration settings that establish a general environment for working with content. Typical settings include the location and filename of the read/write rules, the location and filename of the document's DTD, the FrameMaker template used for new XML instance documents, and the XML elements that may appear as the DOCTYPE within an XML instance document. FrameMaker ships with several preconfigured applications and supporting files for working with DocBook XML documents, XHTML, XDocBook, and DocBook 2.1.

For the purposes of writing this article, I have created a simple DTD that supports the desired structure. As a result, I've created a new application definition that references the DTD.

The second part of the process is to define the read/write rules for the XML document. Read/write rules act as a kind of XSL Stylesheet to translate the elements of an XML instance document to the elements of FrameMaker. Read/write rules may also be used to define how attributes are assigned to elements. For example, the DTD for this article includes a graphic element for figures. Assigned to it is an attribute that contains the type of image used and the allowable values: JPEG, SVG, GIF, and so forth. FrameMaker presents this attribute to the user in the form of a dialog box with a drop-down menu containing the predefined enumerated attribute values.

Finally, the third part of the process is to create the transformation and formatting rules. This document also acts as a kind of stylesheet. However, it deals with the resulting FrameMaker elements after they have been converted via the read/write rules. In it, all the formatting rules and special handling rules necessary for the document's elements are defined to reach the formatted result. The example created for this article is very simple. As seen in Figure 1, it assigns some basic formatting properties to the article's title, section headings, and body content. Because this rule document is independent of the XML content, any number of variations may be created and applied easily for different results. All of the characteristics available to a FrameMaker element may be accessed in this document. Therefore, it gives users access to the full suite of the tool's standard authoring and publishing capabilities.

Once all of the setup is complete, it is just a matter of entering or importing the content into the appropriate sections of the document. As data is entered, all formatting and structural rules for the presentation of the content are applied, while the integrity of the DTD and read/write rules are checked and maintained on the fly.

Adobe Systems Incorporated
345 Park Avenue
San Jose, California 95110-2704
Tel: 408-536-6000
Fax: 408-537-6000

Summary
Adobe FrameMaker 7.1 provides a powerful set of capabilities for working with XML documents. Although this is a product that is geared to the authoring and publishing audience, its capabilities may be used to bridge into the technical world of XML. It delivers on the promise of separating presentation from content and allows those with expertise in each area to work independently. This is a sophisticated solution for a complex problem.