Best Practices for Single Sourcing from FrameMaker to RoboHelp for Publishing Online Help and Knowledge Bases

RoboHelp,FrameMaker,Technical Communication Suite,Knowledge base software,HAT,Single Sourcing

While responding to one of the comments, I realized the need for summarizing the best practices for single sourcing content from FrameMaker to RoboHelp. We have several posts on this workflow, which is now available as part of Adobe Technical Communication Suite.

1. Importing the TOC and the Index – RoboHelp supports multiple TOCs, Index and Glossary. When you add a FrameMaker book as live link in RoboHelp, you can create a new TOC and a new Index to import the FrameMaker TOC and Index entries. This enables you to manage FrameMaker content separately inside RoboHelp. As a next step, you can add TOC and Index as placeholder in the master project TOC and Index respectively. You should also properly format the TOC in FrameMaker before you import the content in RoboHelp. To remove Auto Numbering from appearing in the TOC entries, please select “Ignore Auto number” during style mapping for those styles which are used to create TOC in FrameMaker. For Index entries, you should use Index Markers in FrameMaker.

Defining Content Sensitive Help -For defining context sensitive help, please
choose any custom marker and apply it at the beginning of the paragraphs in the FrameMaker source files.

Update (April 16, 2008) – Please apply RoboHelp patch 7.0.1. Also, for generating custom filenames for topics in RoboHelp, please see this workaround based on conditional text settings in FrameMaker.

3. Print and Help Specific Content – You may want to use conditional text to clearly identify the online and print specific content in FrameMaker. In both FrameMaker and RoboHelp, you can define a conditional expression to filter print and online specific content. For example, if you want to use two different image size in Print and Online Help, you may want to include both of them in FrameMaker and apply conditional text to identify which one is for print and help.

4. Style Mapping – RoboHelp enables you to map styles from FrameMaker to RoboHelp. You can map FrameMaker paragraph and character styles to RoboHelp styles, which will automatically reformat your FrameMaker content for publication in RoboHelp. In addition, you can also specify new definitions for FrameMaker cross-reference formats (e.g., to remove page numbers from cross-references in RoboHelp output). If you are using styles to control spacing between text and images, you may chose “Ignore output” for these styles during the mapping. If you want to pass through content in RoboHelp with a user defined tag, you can specify that as project settings in RoboHelp.

You can export and import the style mapping file in RoboHelp and re-use it across projects.

Update (April 16, 2008)-
You can however create dynamic HTML effects like mouse over through style definitions in RoboHelp. For drop down and expanding hotspots, you may want to check-out a workaround posted on Adobe RoboHelp forums (Category- FrameMaker Integration) .

Converting Auto Numbering to HTML lists You can convert auto numbering styles to HTML lists. This is generally preferred if the FrameMaker document does not include complex numbering e.g., multilevel section numbering 1.1.(a).
You can also select specific styles in FrameMaker for which Auto numbering should be ignored. For example, if you have auto numbering defined for FrameMaker styles SectionName and you don’t want sections to be converted to HTML lists, please select “Ignore Auto Number” for the style SectionName.

Update – If convert autonumbers to HTML list is selected, please “ignore autonumbering” for FrameMaker styles which are used in the FrameMaker TOC. This is important when you are importing the TOC as defined in FrameMaker. In sequence of processing, autonumbers are converted to HTML lists before RoboHelp generates the TOC.

6. Images – If you have equations or images in FrameMaker, please make sure they are part of an Anchored Frame. RoboHelp can convert the images (including equations) in FrameMaker to PNG, GIF, BMP or JPG and you can define the default format which RoboHelp should use to convert the images from FrameMaker. If you are using PNG, GIF, BMP or JPG in FrameMaker, these formats will be retained and only other formats like TIFF will be changed to the default selected by you. This setting is available in RoboHelp at Tools-> Options -> FrameMaker Documents.

Updating Styles for Linked FrameMaker Books – RoboHelp allows you to edit style information and other project specific settings. You can change the styles either by changing the style sheet in RoboHelp – fmstyles.css or changing the style mapping.

Updating RoboHelp Content when FrameMaker document changes – You can update the RoboHelp content with a click of a button when FrameMaker content changes. RoboHelp also provides visual indication if the content is out of synchronization with FrameMaker document.

9. Preserving Content Changes in RoboHelp – To
handle special situations which may require the RoboHelp content to be out of sync from FrameMaker documents either for short duration or for small set of topics, you can preserve content changes in RoboHelp for linked FrameMaker Books.

Additional links– Adobe User Forum for FrameMaker and RoboHelp Integration, Video training on FrameMaker and RoboHelp Integration

Please let me know if you want more details on this workflow. I will try to keep this post updated as we go forward.

pageTracker._initData();