Task 1: Preconversion Cleanup

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:

A brief note about Index marker conversion:

Once your files have been properly cleaned up and tagged, you’re ready to start the conversion process.

  1. Create a folder named conversion where the conversion process will be performed. Create source and out folders within the conversion folder.
    • These folder names can be anything that makes sense for your workflow.
  2. Copy the source FrameMaker and any auxiliary files (graphics, etc) to the source folder.
    • Only references to files that are converted at the same time will be resolved. If you have references to other books, those will need to be fixed in a post-conversion pass.
    • If you are converting multiple FM files and there is no book file, create one. This isn’t required, but it’s easier to run the automation commands on a book rather than each file individually.
  3. Create and set up an fm2dita.ini file for this project. This INI file should be created in the conversion folder.
    • When an FM2DITA command is run on any FM or BOOK file, the current folder is checked for an fm2dita.ini file. If that file is not found, the parent folders are scanned (allowing you to maintain just one INI file per project). If that file is not found, the default fm2dita.ini file (in the Pubs-Tools folder) is used.
  4. Open the book file.
  5. Delete any frontmatter, backmatter, and other generated or non-content files.
    • The only files that should remain in the book are “content” files. The conversion table is typically not set up to support cover pages or other frontmatter and backmatter.
  6. Open all files in the book.
    • This isn’t required, but can simplify problems that are caused by missing graphics or unresolved references. If you don’t open the files, the FM2DITA commands will open each file, then save it before closing.
    • Place focus on the book, press Shift and click File > Open All Files in Book
  7. Convert any text insets to text.
    • If any exist, locate each inset, double-click, select Convert to text, repeat. The FM2DITA conversion process is currently not set up to support text insets (although this may be supported in the future).
  8. Perform any necessary preconversion processing.
    • If you are using any of the FM2DITA preconversion tools, make sure that the fm2dita.ini file has been set up properly and copied to the source folder.
  9. Resolve all cross-references.
    • Any unresolved references will not be resolved in the XML files.
    • With focus on the book, use the Edit > Update References command.
    • Also make sure all graphics are “found”. You can convert with missing graphics, but it’ll likely interrupt the conversion process at various points.
  10. Confirm that all user variables, cross-reference formats, table formats, and styles are included in the conversion table.
    • Place focus on book, choose Pubs-Tools > FM2DITA > Catalog Report
    • Compare the results to previous catalog reports. If new objects or styles exist, add them to the conversion table.
  11. Save and optionally close all files in the book.
    • Place focus on book, press Shift and click File > Save All Files in Book
    • Place focus on book, press Shift and click File > Close All Files in Book
  12. Optionally save the source folder to a new name (source-1?) to make it easier to roll back to this point in case something goes wrong.