Getting started with Structured Applications

Learn how to get started with Structured Applications, the significance of formatting in the Structured Application

In unstructured FrameMaker, setting up an authoring environment requires only a template file. The template file defines the formats and the styles and a style guide defines how to work correctly with the template. In Structured FrameMaker, you require more than just a Structured Template.

To establish a basic structured authoring environment in FrameMaker, you require an EDD or a DTD. You can create custom EDDs and DTDs or use off-the-shelf EDDs and DTDs. Additionally, you need to link the element definitions with formatting information. You can link elements in the EDD to formatting in three ways:

Formatting template: You can assign formatting based on the various tags (paragraph styles, character styles, and so on) in a template. If you already have a formatting template, you can reuse information in that template.
Format change lists: You can create named formatting definitions in the EDD. The format change lists let you provide partial formatting specifications and inherit the rest from a few base paragraph styles. You can reuse format change lists for related elements.
Embedded formatting: You can specify formatting by writing the formatting into each element definition.

After you create the EDD and the formatting, you combine the two components to create a single Structured Template. To create the Structured Template, you open the formatting template and import element definitions (File > Import > Element Definitions) from the EDD. The resulting file is your Structured Template.

Apart from the EDD and the Structured Template, you also need:

read/write rules: The read/write rules control translation from FrameMaker structure to XML and back. Specifically, read/write rules help manage table translation and other complex formatting.
Structured Application: The Structured Application lists all of the component files in your structure implementation and provides configuration information. For example, you can use the Structured Application to specify whether and how to export conditional text tagging.

Structured Templates

All FrameMaker Structured Applications require a Structured Template. Structured FrameMaker templates contain definitions of all the elements that can be used in the document as well as the document’s page layout and formatting.

Structured Templates are like unstructured templates with the most obvious difference being the Elements catalog.

The Elements catalog displays the element definitions defined in the EDD. To create a structured document as a first step, you import the definitions from either an EDD or a DTD. The element definitions in an EDD or DTD are populated in the Elements catalog. You use the Elements catalog to insert valid elements in your document and build a structure that complies with the rules in the EDD.

Content analysis

The term content analysis describes a process in which you review existing documents to understand how they are designed and what implicit structure they contain. Begin your analysis by making a list of the documents your organization produces. Your list might include user guides, reference guides, white papers, tutorials, training manuals, and online help. Make a list of the major components for each document type. For each component, list whether the item is required, optional, and how often it occurs in that document. The following table shows a high-level analysis for a book:

Component	Requirement	Occurrence
Front matter	Mandatory	1
Table of contents	Mandatory	1
Preface	Optional	0 or 1
Chapter	Mandatory	2 or more
Appendix	Optional	0 or more
Glossary	Optional	0 or 1
Index	Mandatory	1

For major components, such as lessons (for training manuals) or chapters (for books), work your way down the document hierarchy into smaller and smaller chunks, until you reach the bottom level of the hierarchy.

You must do a content analysis for every document type you want to create in your structured environment. Once you have developed a content model for each document, you can look for opportunities to refine the model and reuse names. For example, suppose that a Help deliverable consists of topics and the chapters in a book also consist of topics. If you create a Topic element that is usable for both printed and online materials, you can minimize the number of elements in your structure definition and perhaps reuse information in both output formats.

Printed Topic	Online Topic	Combined Topic
Topic	Topic	Topic
Title	Title	Title
Para	Para	Para
Steps	Steps	Steps
Can contain Para, List, Table, Graphic, Note	Can contain Para, List, Table	Can contain Para, List, Table, Graphic, Note
	RelatedTopics	RelatedTopics

It’s unlikely that your documents are perfectly consistent. You need to decide whether to create a structure that is loose (allowing many variations) or strict (very few variations are permitted). You will have problems at both ends of the spectrum:

A very loose structure is quite complex, and can be difficult to maintain because so many variations are permitted.
A very strict structure may disallow element combinations that are needed.

It’s very difficult to find the right balance between these two extremes. One approach is to allow variations only where they add value.

Note: A similar problem occurs when creating unstructured FrameMaker templates. You want to minimize the number of tags that must be maintained while providing all of the tags that are needed to create your content.

Once the analysis is complete, you can decide whether to use an existing structure or to build your own. Numerous XML implementations are available; DocBook and the Darwin Information Typing Architecture (DITA) are specifications used for technical documentation. Standard structures are also defined for military documents (mil-specs or mil-standards), aircraft maintenance manuals, and others. The following table describes some of the factors that influence whether you will use a standard specification or build your own structure.

Use a standard	Build your own
You are required to deliver content that follows the standard. For example, many U.S. military contractors are required to deliver documentation that follows a published standard	You want to create a structure that matches your content analysis precisely.
Your content requirements closely match an existing structure. You only need to make minimal changes to the standard structure.	Your content analysis indicates that your information does not match existing structures very well.
You do not want to spend a significant amount of time building a structure, and you are willing to change the organization of your content to fit it into an existing structure.	The structure needs to match the content precisely. A longer implementation period is an acceptable cost to ensure you can build exactly what you need
You do not have the technical expertise or resources available to build your own structure.	You have resources available, whether in-house or as consultants, who can build the structure.

Elements

The basic building blocks of structured documents are elements. Elements represent pieces of a document's content (its text, graphics, and so on) and together make up the document's structure. Elements can be simple elements or complex elements.

A simple element in XML contains just text. A complex element can have attributes and can:

be empty.
contain other elements.
contain only text.
contain both elements and text.

Elements can have values within a specified range of valid values.

All structured documents in FrameMaker use elements. Each element has a name, such as <section>, <title>, or <p>. The elements that are available are determined by the document element definitions.

Attributes

Attributes supply additional information about an element. For example, the DTD designer for a manual could use an attribute called version for its book element to allow the user to specify a book’s revision status. In FrameMaker, the attributes for an element are a part of the definition of the element itself. In XML or SGML, the attributes of an element occur separately in an attribute definition list declaration (ATTLIST) in the DTD.

Attributes can have a default value or a fixed value. Attributes can also be either mandatory or optional. For example, if you have a topic element, the topic ID could be a mandatory attribute for topics being cross-referenced. You can also have value ranges for attributes or enumerate the legal values for an attribute.

Element rules

Following seven rules control how the elements are used in terms of their sequence, number of occurrences, and group.

All: Indicates that child elements can appear in any sequence but must appear at least once.
Choice: Indicates one or the other child element can occur.
Sequence: Indicates the order in which the child elements appear.
minOccurs: Indicates the minimum number of times a child element can occur.
maxOccurs: Indicates the maximum number of times a child element can occur.
Element Groups: Elements can be grouped under a group declaration.
Attribute Groups: Attributes can be grouped under an attributeGroup declaration.

XML schema

An XML schema defines the legal building blocks of an XML document. Unlike the EDD, DTDs and schema files do not provide formatting information.

XML schemas define the following:

List of elements that can appear in a document
Attributes that can appear in a document for an element
Hierarchy of elements—which elements can appear as child elements
Sequence of child elements
Number of child elements
The data types for elements as well as attributes
Default and fixed values for elements and attributes

XML namespace

XML namespaces allow the same document to contain XML elements and attributes taken from different vocabularies, without naming collisions.

Opening or importing a schema

You can import an XML document that references a schema file, and you can specify a schema file in your Structured Application to use for validating a document upon export to XML.

To specify a schema file for use in exporting to XML, modify the structapps.fm file. The element schema, a child of the <XMLApplication> element, specifies the schema file path for export.