Converting FrameMaker content to DITA (brief)

FrameMaker 8 includes DITA support, and works well for creating new content.  Converting existing FrameMaker content poses a few challenges.  One of these challenges, converting FrameMaker cross references to Structured FrameMaker cross reference elements, is addressed herein.

 It is important for you to know that if the FrameMaker conversion table isn't "just so" the cross references may be broken in the structured document created. It takes some doing to actually convert a FrameMaker document to structure and NOT break the links! Conversion tables sometimes aren't even enough when they are done right. So, you could end up stuck with Marker "crud" in process instructions and broken cross reference elements throughout their docs by not properly converting the cross-ref markers. For example, if you convert to an fm-xref element, FrameMaker exports to a DITA xref but may not have appropriate attribute values.  The xref element might say:

<li><xref href = "#" type = "fm:headingpage">Building Templates on page 4</xref>Building Templates on page 4</li>

The corresponding item (concept) being referred to may have innappropriate marker info and the id attribute):

<concept id = "buildtpls"><title><?FM MARKER [Cross-Ref] 38999: Heading1: Building Templates?>Building Templates</title>...

The concept/task/concept/reference "id" attribute value needs to be in the xref element's "href" attribute to fix the broken links. The marker process instruction needs to be blown away.

Result after you fix the files:

<li><xref href = "filename.ext#buildtpls" ></li>

<concept id = "buildtpls"><title>Building Templates</title>...


You can minimize conversion/output issues by doing several things, including:

  • In your conversion table, the Cross-Ref markers need to be converted to an element that can be searched/deleted after conversion. 
  • Ensure that your id and href are connected, and ensure your cross references are not between a cross reference element and a paragraph (instead of an element).
  • You can work around some attribute issues by tweaking the DITA EDD before conversion, to get the id (for one example) to be Id (capital i).  Otherwise, you'll find yourself manually moving Id values to id and deleting the Id attribute Frame adds by default.

Once content is converted, note that just about any problem with the code can be fixed by using FrameScript or FrameSLT to modify the Structured FrameMaker document. Once fixed, you can validate it within FrameMaker using your own DITA-based application or the Adobe DITA application built into FrameMaker 8. Once validated, your output (DITA XML) should be just fine.

If you have any questions, or need some assistance setting up your conversion table properly, feel free to ping me. Focus Areas: BPEL | DITA | ebXML | IDtrust | OpenDocument | SAML | UBL | UDDI
OASIS sites: OASIS | Cover Pages | | AMQP | CGM Open | eGov | Emergency | IDtrust | LegalXML | Open CSA | OSLC | WS-I