Description of the process for converting unstructured FrameMaker files to structured FrameMaker files

1. April 23, 2007
Migrating from Unstructured to Structured
FrameMaker Documents
Kevin Chilton
Topic Page
Purpose 11
Benefits 11
Migration Process 14
1.0 Purpose
To combine FrameMaker’s powerful features with structured authoring to create a
sophisticated workflow. Within this new authoring environment, you can automate
formatting, create, edit, and publish XML-based content, and enforce required
document structures.
2.0 Benefits
Creating an XML-based workflow improves the consistency and organization of your
files, enables reuse of content, and can help reduce publishing costs.
2.1 Enforcing consistent organization
In unstructured FrameMaker, a template specifies which formatting components are
available in your files. Along with the template, you provide usage rules. For example,
you might specify that a simple proposal should have the following content sequence:
• Proposal title
• Executive summary
• Project description
• Schedule
• Cost
You cannot enforce this required sequence in an unstructured template. Instead, you
create a style guide, which authors are supposed to read and comply with. To verify that a
particular document follows the rules in the style guide, a human editor must read the
proposal and verify that each section is in the proper order.
11

2. Migrating from Unstructured to Structured FrameMaker Documents
XML technology lets you describe the required organization of the content with
structure rules. A file that follows these rules is valid. and you can use software to
validate your file and verify that it conforms to the rules you’ve established, so that
instead of a human reading the file to check its organization, the software can do the
validation work.
In addition to built-in validation features, structured FrameMaker also provides guided
editing, which supports authors by displaying only the allowed elements as they are
working. This means you can now enforce your document organization through the
template (rather than by human review).
For a proposal document, the structure rule would read as follows:
Title,ExecSummary,ProjectDescription,Cost,Schedule
This rule indicates that a syntax reference section must contain one Title, followed by one
ExecSummary, and so on. You can then specify further structure inside each
element. For example, you can require that the ExecSummary element contains a title and
a paragraph:
Title,Para
A document that omits one of these items, or that uses a different order for the
elements, is not allowed. FrameMaker’s structure view indicates in real-time where
required content is missing, as shown in the following figure.
12

3. April 23, 2007
2.2 Automating and enforcing formatting
In structured FrameMaker, authors do not work with formatting components such as
paragraph and character tags. Instead, they insert elements and element content into their
documents.
Document formatting is applied automatically based on formatting information that is
embedded in the structured template. The structured template is made up of two
components: formatting information and structure definitions. The structure definitions
are stored in an element definition document (EDD), which in turn references
formatting information.
Element formatting is context-sensitive; that is, a single element can appear with
different formatting in different structured positions. A single ListItem element, for
example, can replace half a dozen (or more) paragraph tags.
As you position information in the structure, the context-sensitive formatting is updated
immediately based on the element position.
2.3 Using metadata for versioning
At the document level, metadata provides keywords and other descriptions of a
document. You can also use metadata to identify information that is unique for a
particular version of a deliverable.
This technique lets you use a single set of source documents to deliver highly
customized information for each version. Consider, for example, the problem of
customized software development. If your company customizes its products for each
client, you need a way to identify what information belongs to each client.
Using metadata, you can specify which clients each topic applies to. When you are ready
to deliver the information, you filter based on the metadata to create the appropriate
deliverables.
13

4. Migrating from Unstructured to Structured FrameMaker Documents
2.4 Publishing to multiple output formats
In a structured FrameMaker environment, you can take advantage of FrameMaker’s
powerful print and PDF capabilities, and then generate XML to create other outputs, such
as HTML and online help formats.
You can also continue to use single-sourcing workflows that are based on unstructured
conversion tools.
2.5 Supporting content reuse and exchange with XML
XML lets you move information from one authoring tool to another without losing
information. You can develop information in FrameMaker, save it out to XML, and then
open the XML files in another tool. Perhaps a technical writing group (which uses
FrameMaker) needs to share information with a training group (which uses an
XML-based learning management system). You can use XML to exchange content
between two otherwise incompatible applications.
2.6 Reducing localization cost
When content is localized, the desktop publishing component is a significant part of the
cost. A publishing workflow built on XML and structured authoring lets you automate
much of the publishing effort, so you can greatly reduce the ongoing costs associated
with localization.
2.7 Simplifying database publishing
Instead of connecting directly into a database, you can use XML as an intermediate
format. From the database, you generate an XML file that contains the information you
want to publish. On the FrameMaker side, you set up an import application that
provides formatting information for the XML elements. You then open the XML file in
FrameMaker, and the database information is formatted automatically.
2.8 Complying with required document structures
The ability to enforce structure based on explicit rules improves consistency for any
document. In regulated industries, the ability to verify that the required structures are
being followed is critical.
If an organization is required to comply with specific structures due to government or
industry standards, structured authoring can help ensure that the documents conform.
3.0 Migration Process
To migrate from unstructured to structured documents entails these stages:
• Producing a conversion table from an existing unstructured FrameMaker document
(see “Producing a conversion table from an existing unstructured FrameMaker
document” on page 15).
14

5. April 23, 2007
• Stucturing an Unstructured Document (see “Stucturing an Unstructured Document”
on page 16).
• Creating an Element Definition Document (EDD) (see “Creating an Element
Definition Document (EDD)” on page 16).
• Testing the EDD (see “Testing Element Definition Document (EDD)” on page 17).
• Applying the EDD to unstructred documents (see “Apply Element Definition
Document (EDD) to Unstructured Documents” on page 18).
You can also add structure to multiple documents or a book file with these methods:
• Adding stucture to multiple documents with a conversion table (see “Adding
Stucture to Multiple Documents” on page 18).
• Importing element definitions into a book (see “Importing Element definitions into
a Book” on page 19).
3.1 Producing a conversion table from an existing unstructured FrameMaker
document
You can set up a conversion table to help end users automate the task of adding structure
to documents. The conversion table uses paragraph and character formats to identify
which document objects to wrap in elements, and element tags to identify which child
elements to wrap in parent elements. A user wraps all of a document’s contents in one
move by applying a structure command to the document and referring to one of your
conversion tables.
To generate an initial conversion table
1 Select File Developer Tools Generate Conversion Table in a document with
objects you want to structure.
2 Select Generate New Conversion Table in the dialog box and click Generate.
The software looks through the flows on body pages in the document and compiles a list
of every object that can be structured. For each object, it gives the object type and the
format tag used in the document (if the object has a format), and maps the object to an
element. The element tag is the same as the format tag, or if the object does not have a
format, the element tag is a default name such as CELL or BODY. If necessary,
FrameMaker removes parentheses and other characters to create an element tag that is
valid.
The initial conversion table gives you a first pass through the document, identifying
objects to wrap in elements. It does not identify child elements to wrap in parent
elements—you need to add those rules to the table yourself.
15

6. Migrating from Unstructured to Structured FrameMaker Documents
Note:
The conversion table only picks up the catalog tags actually embedded in the document,
NOT all those in the catalog.
For more details see Appendix A Conversion Tables for Adding Structure to Documents
in the Structure Application Developer’s Guide.
3.2 Stucturing an Unstructured Document
To structure an unstructured document
1 Open your unstructured document and your conversion table document.
2 Select select File Utilities Structure Current Document.
3 Select the conversion table document from the drop-down list and click Add
Structure
FrameMaker creates a new, untitled, structured document.
Keep refining and testing your conversion rules until you are satisfied with the document
produced.
You can add tags to the conversion rules table by typing them or by scanning additional
documents.
To add tags automatically
1 Make sure that the conversion rules table is open. Open the file that contains
additional formatting components.
2 Select File Structure Tools Generate Conversion Table.
3 Select Update Conversion Table and select your conversion rules document in the
drop-down list.
4 Click Generate.
FrameMaker scans the second sample document and adds additional formatting
components to the end of the conversion rules table.
3.3 Creating an Element Definition Document (EDD)
An element definition document (EDD) contains the structure rules, attribute definitions,
and format rules for all of the elements in a group of FrameMaker documents.
16

7. April 23, 2007
To create an Element Definition Document (EDD) carry out this step:
Select File Developer Tools Export Element Catalog as EDD in your stuctured
file.
FrameMaker opens a new, untitled, EDD document.
For detailed information on creating and EDD see Part II Working with an EDD in the
Structure Application Developer’s Guide.
3.4 Testing Element Definition Document (EDD)
To test the EDD, you import it into a document and then verify that you can create the
structure you expect. At this point, the document will not have any formatting, but you
can verify that the structure is working as expected.
To verify that the structure is working as expected
1 Create a new, blank,document by selecting File New Document, and then click
Portrait.
2 Make sure that the EDD and the new document file are both open.
3 In the new document, select File Import Element Definitions.
4 In the Import from Document drop-down list, select the proposal EDD and click
Import.
5 The Element Definitions are now available by clicking the icon to open the
Element Catalog:
17

8. Migrating from Unstructured to Structured FrameMaker Documents
Note:
The Element catalog lists all the eleements you can use at the current location in the
document.
3.5 Apply Element Definition Document (EDD) to Unstructured Documents
To apply the EDD to an unstructured document
1 Make sure that the EDD and the unstructured document file are both open.
2 In the unstructured document, select File Import Element Definitions.
3 In the Import from Document drop-down list, select the proposal EDD and click
Import.
Note:
Importing element definitions into an unstructured document does not automatically
apply structure. This must be done manually by the author (under research
srickaby@wordmongers.com - articles in Communicator).
3.6 Adding Stucture to Multiple Documents
You can add structure to one or more documents without having to open them by
applying a conversion table. The documents should either be the only contents of a single
folder or all have a filename extension that is unique in a single folder.
To apply a conversion table to a group of documents
1 Open the file with the conversion table.
2 Select File Utilities Structure Documents to open the Conversion Table
Document pop-up menu.
18

9. April 23, 2007
3 Select the file with the conversion table (i.e., current).
4 In the Input Unstructured Files area, specify the location and filename extension of
the documents you are adding structure to.If you need to look for the location, click
Browse and navigate to it.
Note:
The filename extension is optional. You can leave the Suffix text box empty to add
structure to all the documents in the folder.
5 In the Output Structured Files area,specify a location for the structured versions of
the documents. If you need to look for the location, click Browseand navigate to it.
6 To overwrite an existing batch of structured files in the output-folder, select Allow
Existing Files to Be Overwritten.
7 Click Add Structure.
When you open the structured documents, you can import element definitions into them.
3.7 Importing Element definitions into a Book
You can import element definitions into a book file and into any files contained in the
book.The definitions.are stored in the Element Catalog for the book and the other files.
When you import e1ement definitions into a book, FrameMaker replaces any existing
definitions in the book and all its files with the new definitions and re-applies format rules
from the definitions. It also validates the book file.
19

10. Migrating from Unstructured to Structured FrameMaker Documents
To import element definitions into a book
1 Open the book.you want to update and the template, document, or book with the
definitions to import.
2 In the book window, select the files into which you want to import clement
definitions, and select File lmport Element Definitions.
3 Choose the template or document from the Import from Document pop-up menu
which lists all open, saved documents and books.
4 To remove format rule overrides in the files, select While Updating, Remove Format
Overrides.
5 Click Import.
FrameMaker updates the element definitions in the book file and in the files listed in the
Update scroll list.
20