FrameMaker: Structured or Unstructured?

By Alan Houser

Introduction

At the 2004 WritersUA and STC Conferences, structured FrameMaker and XML were among the more popular session topics. There is obviously significant interest in the user assistance community about authoring XML documents with structured FrameMaker. This is not surprising, as many organizations are struggling with the problems of creating and delivering increasing amounts of user assistance in multiple formats, and managing their content in a way that maximizes their capabilities to reuse content across multiple publications.

This article provides an introduction to structured FrameMaker and describes the advantages of using this approach for content development. The article is presented through the following sections:

Overview of FrameMaker and Structured FrameMaker

The World Wide Web Consortium (W3C) finalized the XML Recommendation in February 1998. Since then, we have seen a steady increase in the number of tools and technologies for working with XML. For example, we can use the XML transformation language (XSLT), another W3C standard, for transforming XML documents to other formats, including HTML or XHTML. We can use VoiceXML to send our XML content to voice-driven interfaces. We can extract specific content from our XML documents for publishing to wireless and small-screen devices.

Any organization that wants to author and publish XML documents must choose an XML authoring tool. Adobe FrameMaker, which provides the capability to author, edit, and publish complex XML documents, is one popular choice.

One product, two interfaces

With the release of FrameMaker 7.0 in 2002, Adobe merged two products — the previous FrameMaker product and a product called FrameMaker+SGML — and added support for for creating and editing valid XML documents. FrameMaker is now a single product with two somewhat different authoring interfaces. “Unstructured FrameMaker” refers to the conventional FrameMaker interface. “Structured FrameMaker” refers to the interface for authoring and publishing XML documents in FrameMaker.

Running structured FrameMaker

The first time you invoke FrameMaker, the application prompts you for the interface you wish to run. You may choose “FrameMaker” to launch unstructured FrameMaker, or “structured FrameMaker” to launch the application with the structured interface. FrameMaker retains this setting on your system until or unless you change it.

You can change your FrameMaker interface at any time by invoking the File->Preferences command. The Preferences dialog box includes a pop-up menu for choosing the FrameMaker or structured FrameMaker product interface. If you wish to change your interface (for example, if you have been using FrameMaker and wish to explore structured FrameMaker), you must quit and restart FrameMaker for the change to take effect.

Figure 1. Changing the FrameMaker interface

The Structured FrameMaker interface is a superset of the FrameMaker interface. If you work with both structured and unstructured FrameMaker documents, you can do all of your work in structured FrameMaker. There is no need to toggle back and forth between the two interfaces.

Key differences between structured and unstructured FrameMaker     Link to the article contents

If you are a FrameMaker user, much of the structured FrameMaker interface will be familiar. The table designer, cross-reference dialog, marker dialog, graphics tools, as well as most menus and commands, are nearly identical between FrameMaker and structured FrameMaker. However, there are key differences in the two product interfaces and in the documents that you will create, edit, and publish in each interface.

Your documents: structured or unstructured?

FrameMaker presents a strong template-based authoring paradigm. Authors apply paragraph and character formats as they write. When inserting a table, the author chooses a table format. Even the content and format of cross-references is controlled by a document’s cross-reference formats.

This template-based authoring strategy has many advantages over ad hoc formatting. The format of a document is largely automated, through the definitions of the paragraph, character, and other formats. The overall format of a document is relatively simple to adjust, and template-based documents tend to be significantly easier to maintain than documents that are manually formatted.

These template-based FrameMaker documents may be referred to as unstructured FrameMaker documents, and the authoring interface may be called either FrameMaker, or unstructured FrameMaker. Although structured FrameMaker documents also include the same template format definitions as unstructured documents, a structured FrameMaker document includes another “layer” of information — a set of element definitions.

Elements, not paragraphs

Although much of structured FrameMaker interface will be familiar to users of unstructured FrameMaker, the application presents a somewhat different authoring paradigm. FrameMaker users are familiar with paragraph and character formats (as are authors who use any style-based authoring tool, including Microsoft Word with Word styles). Instead of presenting paragraph formats or styles, structured FrameMaker presents elements to the author. Adobe calls this “structured editing.”

An element is a label for a chunk of content. A chunk may be a paragraph, a section, a table, or an inline element. Even cross-references, tables, and markers are expressed as elements in structured FrameMaker.

Unlike unstructured FrameMaker and other style-based authoring tools, a structured FrameMaker document will have a hierarchy of elements. Many of the element chunks of content are nested within other chunks. For example, a section is likely to contain a section title followed by paragraphs, tables, graphics, lists, and any other content chunks that comprise the section.

Elements may have one or more attributes, which allow authors to associate additional information with elements. The elements and attributes provide metadata — additional information about the document, which is generally not included in the printed rendition. This information can be invaluable for processing documents for other output devices or for managing documents via content management systems.

Overview of the structured FrameMaker authoring and publishing environment     Link to the article contents

This section presents a tour of the structured FrameMaker interface. Here we discuss the main interface components that are unique to structured FrameMaker — the structure view, element catalog, attribute editor, and validation dialog box.

Document window, element catalog, and structure view

The following screen shot shows the main components of the structured FrameMaker authoring interface — the document window, which displays a WYSIWYG rendition of the current document, the structure view, which displays a representation of the document’s structure, and the element catalog, which allows the author to select appropriate elements to insert during the editing process.

Figure 2. Structured FrameMaker authoring interface

Element catalog

The element catalog is analogous to the unstructured FrameMaker paragraph and character catalogs. While editing, the author selects appropriate elements from the element catalog. The element catalog is context-sensitive — the element catalog will display legal elements at the current cursor position. In the example element catalog, the elements Feature, InfoBlock, Note, or Para are legal at the author’s current cursor position.

 :

Figure 3. Structured FrameMaker element catalog

Structure view

The structure view shows a hierarchical view of the elements that comprise a document, as well as the attributes. The structure view also provides an active editing interface. Authors can select any element (and all of its content) by clicking on the element bubble. Authors can add content, remove content, or re-arrange content through the structure view.

Figure 4. FrameMaker structure view interface

Attribute editor

Element names provide labels for chunks of a structured or XML document. Attributes provide the ability to attach additional property information to elements. For example, a “Section” element may have an attribute named “status,” which is set to either “Draft” or “Final.” A “Topic” element may have an attribute that specifies the product(s) for which the topic applies, or the user level for whom the topic is appropriate. These attributes and their values are used by both content management systems and XML publishing applications for selecting appropriate chunks from a repository of XML content.

The following screen shot shows the structured FrameMaker attribute editor.

Figure 5. FrameMaker attribute editor with the structure view

Validation tool

If you are responsible for FrameMaker documents that are produced by multiple writers, you know how vexing format overrides can be. Alas, there is no way, without writing or buying a commercial plug-in, to automatically identify format overrides in a FrameMaker document.

In a structured FrameMaker document, the structure is comprised of elements and attributes, instead of paragraph and character formats. Alas, there is a way to verify that the original author conformed to your expected structure. You do this by using the Validate command.

Running the Validate command is similar to running a spelling checker. FrameMaker steps you through each validity error in the document, reports the error, and allows you to fix it. After all validity errors are fixed, FrameMaker reports that the document is valid.

Figure 6. Validation tool

Overview of the support files and migration effort     Link to the article contents

All XML authoring tools require a substantial amount of configuration, and FrameMaker is no exception. As a rule-of-thumb, I advise that creating and maintaining the support files for structured FrameMaker is easily double the effort required to create and maintain an unstructured FrameMaker template. Be aware that this amount of configuration is not unique to FrameMaker. If you encounter an XML authoring tool that claims to require little or no configuration, it’s likely that the XML produced by the tool will be severely constrained in some way.

Configuration files

If you are working with XML documents, you will need a Document Type Definition (DTD). The primary purpose of the XML DTD is to define the element names, the valid content for each element, and any legal attributes that each element may have. An XML document that conforms to a DTD is a valid XML document.

The FrameMaker Element Definition Document (EDD) is similar to a DTD, but adds formatting information for any elements that contain text (some elements may contain only child elements). Because of their similarity, you can automatically create a FrameMaker EDD from a DTD, or vice-versa.

Just as in unstructured FrameMaker, page layout is controlled by a FrameMaker template. The template may define paragraph and character formats. If so, these will be referenced and used by the EDD to format elements, and won’t be used by authors.

The structured application

When you open an XML document, FrameMaker parses the document, validates it against a DTD, then formats the document depending on the template and EDD. The DTD, EDD, and template, as well as a few other minor support files, together comprise a structured application.

Because of FrameMaker’s strong style-based authoring paradigm, you can easily change the format of an unstructured FrameMaker document by importing a FrameMaker template that defines different formatting properties, or even a different page layout. Structured FrameMaker is no different — you can change the page layout of a structured FrameMaker document by importing a different template, or you can import a different EDD that defines different formats for your elements. Many organizations define multiple structured applications to render XML documents in different formats, or to work with XML documents that conform to different DTDs.

Migrating legacy documents

Any organization that migrates to a structured or XML authoring tool faces the problem of converting legacy documents. This task may be substantial or it may be relatively easy. You may be able to automate much of this task, but it virtually always requires some amount of manual effort.

FrameMaker provides a mechanism called a conversion table to automate much of the task of legacy document conversion. The conversion table maps unstructured FrameMaker paragraph and character formats to elements, and allows you to automatically nest groups of elements. If your legacy documents were created using a style-based authoring tool (typically FrameMaker or Word) and your authors have used those styles consistently, you may be able to automate 80%-90% of the conversion process. If your legacy documents include a significant amount of manual or ad-hoc formatting, the conversion will be substantially more tedious.

Publishing from structured FrameMaker

With third-party products such as WebWorks Publisher Professional and RoboHelp for FrameMaker, you can map your FrameMaker styles to formats that are appropriate for online delivery, such as HTML, WinHelp, Microsoft HTML Help, and JavaHelp.

Organizations that use structured FrameMaker have even greater capabilities for generating other output formats from the XML created by structured FrameMaker. You can transform XML created from any authoring tool to any output format using the W3C-standard XML transformation language, XSLT. XSLT provides powerful capabilities to select, sort, and manipulate XML documents based on the document metadata. For example, an XSLT transformation can create a hierarchical navigation structure for traversing a large set of XML documents.

A new plug-in for structured FrameMaker, called FrameSLT, allows you to apply XSLT-like transformations to structured FrameMaker documents without saving the document as XML. FrameSLT is offered by West Street Consulting (www.weststreetconsulting.com).

Key factors for choosing structured or unstructured FrameMaker     Link to the article contents

Is FrameMaker right for you? How about structured FrameMaker? Any tool selection should be driven by your organization’s requirements, and how well the tool meets those requirements. This section provides some requirements that you might consider when choosing FrameMaker or structured FrameMaker.

Why should I consider FrameMaker?

Adobe FrameMaker is a rich application with many capabilities. The following is not a complete list of capabilities, but are some of the key requirements that Adobe FrameMaker meets. You might consider unstructured FrameMaker if:

  • Your primary information delivery format is print or PDF (printed or delivered online).
  • You need support for single-source publishing, for multiple related documents and/or multiple output formats.
  • Your documents include complex tables, graphics, cross-references, and complex numbering.
  • Your documents tend to be large and are difficult to maintain (due to system crashes and file corruption) in other authoring applications.
  • You need to create multiple documents with identical formatting (for example, a documentation set for a complex product).

Why should I consider structured FrameMaker?

Structured FrameMaker offers all of the capabilities of unstructured FrameMaker. In addition, it meets the following additional business requirements:

  • You need to create XML but want to work in a familiar authoring environment without dealing with the minutiae of XML syntax.
  • You need to enforce a consistent structure within and across documents.
  • You need a guided editing interface to support authors in creating valid structured and/or XML documents.
  • You need to create valid XML documents because of your publishing requirements, customer requirements, or content management needs.
  • You need to publish print or PDF documents from XML source files.

Learning More

The current release of FrameMaker, version 7.1, began shipping in January 2004, and is supported in Microsoft Windows and Sun Solaris platforms. A 30-day fully-functional trial version of FrameMaker 7.1 is available from http://www.adobe.com/products/framemaker. FrameMaker 7.1 includes an online tutorial called the XML Cookbook, which steps you through the process of setting up a structured FrameMaker application and editing structured documents.

Conclusion

XML-based publishing can substantially improve an organization’s capabilities for delivering its user assistance in multiple formats to multiple devices, and to manage that content for reuse. Although substantial effort is required for any XML publishing project, the return on investment can also be substantial. For organizations seeking to create and edit content in XML, structured FrameMaker is a capable authoring tool, that has the added advantage of being familiar to many technical writers. Structured FrameMaker’s guided editing and validating capabilities can even provide benefits to organizations that aren’t immediately migrating to XML, but wish to improve the consistency between documents in content and structure.

    Link to the article contents

Alan Houser

Alan Houser is president of Group Wellesley, a firm that provides consulting, training, and application development services to support single-source publishing, electronic publishing, and XML-based publishing. Alan is an Adobe Certified Instructor in FrameMaker and Acrobat, and provides training and consulting for clients across the United States. Alan is an internationally-recognized expert in FrameMaker and XML-based publishing, and is a regular conference speaker. He holds a B.S. in electrical engineering and an M.A. in professional writing from Carnegie Mellon University. Houser is co-author of XML Weekend Crash Course, published in 2001 by John Wiley and Sons.


up