Conversion workflow

Creating a Conversion Table from an unstructured Document

To begin the conversion process, select an unstructured document that is representative of your typical content. Ideally, this document should contain examples of all of the formatting styles that would occur in your documents. These tags should be shown in logical sequences (as they would occur in documents), so a formatting template that shows examples of each paragraph style in alphabetical order is not a good example document.

In the following example, an unstructured document with several paragraphs tagged with multiple paragraph styles is given. This document will be converted to DITA with a Conversion Table.

Figure 1. Example of an unstructured FrameMaker document tagged with paragraph styles

1. Open an unstructured document with a similar content and formatting structure shown in the illustration above.

2. Import element definitions from the DITA 1.3 EDD into the example document.

3. Choose Structure > Utilities > Generate Conversion Table. The Generate Conversion Table dialog opens:

   Figure 2. Generate Conversion Table dialog
   
   

   Choose Generate New Conversion Table, then click Generate.

   FrameMaker scans the document and creates a list of the formatting components that occur in this document. Tags that are defined in the formatting catalogs but not used in the document are not included in the list.

   FrameMaker creates a new document with a Conversion Table. A Conversion Table can look like this:

   Note: FrameMaker assumes that the name of a formatting component will be the same as the name of the structure element.

   Wrap this object or objects	In this element	With this qualifier
   P:Title	Title
   P:Heading1	Heading1
   P:Heading2	Heading2
   P:Body	Body

4. To test the Conversion Table, switch to your unstructured document again.

   Choose Structure > Utilities > Structure Current Document. Select the conversion rules table document in the drop-down list, and then click Add Structure.

   
   
   

   FrameMaker creates a new, untitled, structured document with the following flat structure which is not DITA compatible yet. As neither the elements nor the hierarchical structure are DITA comliant and as there is no Root Element set, all elements are marked in red.

   Figure 3. Converting an unstructured FrameMaker document to structured FrameMaker document
   
   

5. Modify the Conversion Table to match the elements used by DITA:

   • Map all heading paragraphs that are tagged in the unstructured FrameMaker document with the paragraph styles “Title”, “Heading1”, “Heading2” into a title element. To change this mapping, change the second column (“In this element”) to read title for all heading styles.

   • Map all paragraphs with the paragraph style “Body” to the p element. To change this mapping, change the second column (“In this element”) to read p instead of Body.

   The modified table now looks like this:

   Wrap this object or objects	In this element	With this qualifier
   P:Title	title
   P:Heading1	title
   P:Heading2	title
   P:Body	p

   To test the conversion rules table, switch to your unstructured document again. Choose Structure > Utilities > Structure Current Document. Select the conversion rules table document in the drop-down list, and then click Add Structure.

   Running this Conversion Table on the unstructured document will give the following flat structure. The elements are valid now, but the structure is not valid yet and no root element is set.

   Figure 4. Converting an unstructured FrameMaker document to structured FrameMaker document – Step 1
   
   

6. To add additional DITA compliant structural hierarchy wrap groups of elements into parent elements:

   • Wrap all p elements (E:p*) into a body element.

   • Wrap all title elements with qualifier H2 (E:title[H2]) followed by or many of the new body elements into a new topic element and mark this new topic element with qualifier L2 (to remember it as “Level 2”).

     In the unstructured document, this was the “section” beginning with a Heading2 style paragraph.

     To be able to distinguish between the three title elements during during the conversion for later wrapping into parent elements, we add the (temporary) qualifiers T, H1, and H2.

   The modified table now looks like this:

   Wrap this object or objects	In this element	With this qualifier
   P:Title	title	T
   P:Heading1	title	H1
   P:Heading2	title	H2
   P:Body	p
   E:p*	body
   E:title[H2], body	topic	L2

   To test the conversion rules table, switch to your unstructured document again. Choose Structure > Utilities > Structure Current Document. Select the conversion rules table document in the drop-down list, and then click Add Structure.

   Running this Conversion Table on the unstructured document will give the following hierachical structure. The elements are valid now, but the structure is not valid yet and no root element is set.

   Figure 5. Converting an unstructured FrameMaker document to structured FrameMaker document – Step 2
   
   

7. Add additional entries to the Converstion Table to create more structural hierarchy and create the root element topic:

   • Wrap all title elements with qualifier H1 (E:title[H1]) followed by an optional (?) body element, followed by zero or more (*) topic[L2] elements into a new parent topic element.

     In the unstructured document, this was the “section” beginning with a Heading1 style paragraph plus paragraphs and/or the Heading2 sections.

   • Wrap the top title element (E:title[T]) followed by one or many topic elements into a root topic element.

   Our modified table now looks like this:

   Wrap this object or objects	In this element	With this qualifier
   P:Title	title	T
   P:Heading1	title	H1
   P:Heading2	title	H2
   P:Body	p
   E:p*	body
   E:title[H2], body	topic	L2
   E:title[H1], body?, topic[L2]*	topic	L2
   E:title[T], topic*	topic

   Running the this Conversion Table on the example document will give this final topic structure:

   Figure 6. Converting an unstructured FrameMaker document to structured FrameMaker document – Step 2
   
   

Save the newly generated document as a structured FrameMaker document (*.fm) or as an XML document (*.xml).

Updating an existing Conversion Table with new rules

1. Make sure that the Conversion Table document is open. Open the file that contains additional formatting components.

2. Choose Structure > Utilities > Generate Conversion Table. The Generate Conversion Table dialog opens:

   
   
   

   Select Update Conversion Table and select your Conversion Table document in the drop-down list.

3. Click Generate. FrameMaker scans the second sample document and adds additional formatting components to the end of the conversion rules table.

4. Refine the added rules as required and save the updated conversion table.