Before starting a conversion it is important to analyze, clean up, and possibly rewrite and retag the content so it “fits” better into the DITA model. It is best to do as much cleanup before rather than after conversion.
It’s easy to say “rewrite and retag to fit the DITA model,” while actually doing that can be quite time consuming. However, it really is best to take as much time as you can to do this work before converting to DITA. Doing this work post-conversion will be even more difficult and time consuming.
You’ll need to do the following:
Clean up inconsistently or improperly tagged content. Any formatting overrides assigned to text or paragraphs will be lost in the conversion.
If this formatting is important to preserve, you must make sure that each unique “style” is defined as a character or paragraph tag. This is frequently a problem with text ranges that have been bolded or italicized with the “B” or “I” buttons.
The FM2DITA Tag Cleanup command is designed to help with character tagging inconsistencies.
The FM2DITA Untag Boundary Spaces command ensures that all spaces between tagged text ranges have no character tag applied. XML whitespace normalization rules will typically cause leading and trailing whitespace in an element to be removed, so if an inline element starts or ends with whitespace, that will often be lost in a conversion.
Clean up inconsistent use of conditional tagging.
It is difficult to transfer conditional tagging to DITA’s filtering attributes. First, for this to map properly, the start/end points of a condition must align with the start/end tag of the corresponding element. Because this unlikely to work well for inline tagging (even if you are able to align the start/endpoints), you’ll end up with less than ideal DITA content, so it is best to assume that all conditional tagging should be applied at the paragraph level.
The FM2DITA Condition to Attribute command transfers conditions that exist at the start of a paragraph to the corresponding element(s). By default the condition names are assigned to the element’s product attribute, but you can specify a different default and can define specific mapping of condition to attribute names.
The FM2DITA Rename Conditions command can be used before conversion to globally rename conditions if the current condition names are not appropriate to be used as attribute values going forward.
The FM2DITA Show All Conditions command will show all conditions in the book or file. It is always best to show all conditions in all files before performing a conversion.
Rewrite your content so it’s consistent and fits into the parts of the DITA model you plan to use.
If you want your topics to include a short description (the DITA <shortdesc> element), make sure every heading that defines a new topic is followed by a paragraph to be used as the short description.
To increase the possibility for topic reuse, it’s suggested that you reduce the number of inline cross-references. If possible, consider moving all of your cross-references into relationship tables; conversion time is an ideal time to make that move.
Retag the paragraph styles so that the content in the various topics is clearly and unambiguously identified. It’s better to have too many paragraph tags than too few.
If you are converting from chapter-based FM files into multiple topic types, you’ll likely need to develop a tagging scheme with new style names that allow you to mark sections of content as belonging to specific sections within each DITA topic model. This is particularly important for the task model, which contains multiple sections with similar types of content; the only way for the conversion table to distinguish between a “prereq” or “context” paragraph is through the paragraph tag name.
The FM2DITA Retag Paras command can be used to assign prefixes to existing paragraph tag names within certain sections. This command can make multiple passes on the content to build up tag names which create unique, section-based tag groups, that allow a conversion table to create properly structured DITA topics.
Similarly, the FM2DITA Retag Tables in Paras command will assign prefixes to table format names within certain paragraph tags. This can help to ensure that tables get wrapped in the proper elements.
A brief note about Index marker conversion:
If your content contains Index markers (converted to fm-indexterm elements while in FM), the export API client associated with the structured application imported into the files in Task 3, is responsible for converting from FrameMaker marker syntax to the corresponding DITA markup. If those Index markers define “See” and/or “See also” entries, the conversion to the proper DITA elements is dependent on the text in those markers matching up with the syntax expected by the API client. If you’re using DITA-FMx, make sure that the character tags used to format the entry match those in the Index Options dialog (in DITA Options). If you’re using another export API client, you should do some testing to make sure the Index markers will convert as expected. (Or just assume that you’ll fix them in a post-conversion pass.)
Once your files have been properly cleaned up and tagged, you’re ready to start the conversion process.