Setting up basic FrameMaker and RoboHelp integration

I’ve been using Adobe FrameMaker for over 29 years to produce books. Its long document publishing features re solid, predictable, and (in my opinion) the best answer for producing technical documentation.

When Adobe created the initial Technical Communication Suite (currently at TCS 4) they asked me to get more involved with all of the products, specifically to work with the FrameMaker to RoboHelp workflow. I jumped at the chance, because the only other options I knew of involved substantial setup, markers, and an overall developer mentality. While powerful, as a tech comm specialist, that wasn’t what I was looking for. Not for me, and not for my clients.

Note: The following techniques may also apply to FrameMaker files and books which are imported into RoboHelp projects. The emphasis is on linking because of the subsequent ability to produce top notch PDF from FrameMaker, in addition to the many outputs available via RoboHelp.

This article assumes you have:

• FrameMaker 11 and RoboHelp 10 installed as part of the Technical Communication Suite 4. These products should have all available patches applied
• Knowledge of FrameMaker, including authoring and formatting content and books, TOC, and Index
• Set FrameMaker preferences (Edit > Preferences > Alerts) to not suppress missing resource messages
• A working FrameMaker book which allows:
  • all files to open without dialogs requiring user interaction (missing fonts, graphics, unresolved cross-references, etc.)
  • updating of the book file without a book error log or similar messages

Helpful skills include:

• Knowledge of RoboHelp
• Familiarity with CSS

You can find the sample files used here in the FrameMaker install directory as shown in this screenshot:

 

Creating the RoboHelp output project

In RoboHelp, choose File > New Project…

Note that the location of the project is within the FrameMaker book directory we’ll be using. Since you will likely have a different RoboHelp project for each FrameMaker book file, this gives you an easy way to find your project and your output.

In the resulting RoboHelp project file, the Project Manager has 2 views:

• what I cal the Globe View ( )
• what I call the Goggles View ( )

In these examples, I’ll be working with the Goggles View ( ), as I find the presentation of the project materials more intuitive using this view.

Linking the FrameMaker book file

In the Project Manager, right-click on HTML Files (Topics) and select Link > FrameMaker Document

Select the appropriate FrameMaker .book or .fm file. I typically use a .book file,

The file will quickly scan the FrameMaker content, giving you references to the files. At this point, you haven’t processed your Fm content into Rh topics. (If your Project Manager looks slightly different, see the Globe/Goggles discussion above.)Note that the imported document doesn’t reference the generated files (in this case, TOC and IX) 

Using the FrameMaker TOC, IX, and Glossary

Right-click on the book file and select Properties On the Content Settings tab, select the generated files you’d like to process (in this case, the TOC and IX) and give them unique names for use in RoboHelp. From this point on, whenever you update your Fm content in Rh, these files will reprocess the generated content along with the rest of the content in the FrameMaker book. We’ll come back to these files later in the Single Source Layout (SSL) section.

Updating content for the first time

In the Rh project manager, right-click on the FrameMaker book file and choose Generate or Update All. 

After the first time, your choices will be Update or Update All.

Setting up initial mappings

Although you can use the formatting applied to your Fm content to format your Rh output, you may find that the results are difficult to manage, and that the code is a bit “heavy.”

To create a more manageable process, you can define the formatting of your help and online output within RoboHelp using (by default) the RHStyleMapping.css file.

Accessing the mappings

In RoboHelp, select File > Project Settings… > FrameMaker Document > Edit Map the content of your Fm book to improve the control over your online formatting and the overall quality of the HTML you’ll use to create online help, eBooks, and any other Rh output formats. In this example, I’ve mapped my main content paragraph style, Body, to the BodyLevel1 entry in RHStyleMapping.css. If your window doesn’t show the FrameMaker styles, see Updating Content for the first time earlier in the post.

Avoid mapping to [Source]

The default mapping of [Source] to all formats will attempt to write a formatting definition (written to additional temporary .css files) based upon the existing FrameMaker properties. Print is not Online, so I strongly encourage you to avoid using this option. The [Source] option will result in HTML code that uses the class=”FM_(FrameMaker formatting style name) attribute. Not only is is difficult to set appropriate web formatting options from the FrameMaker files, this code is lengthy, and will often include inline formatting which is best avoided in your output.

For more information on specifics of mapping content, see http://mattrsullivan.com, or search for framemaker to robohelp integration mattrsullivan in your search engine.

Controlling body copy

Body copy and indents to the body copy can be controlled using the supplied BodyLevel1 to BodyLevel3 css styles.

Mapping topic titles

Chapter titles and section titles which will be split into their own topic should be mapped to Heading 1.

Controlling topic splits

Topic-based output is most effective when topics are short. The easiest way to control topic breaks is by using the Pagination (Split into topics based on this style) option. Map styles with this option to the Heading 1 css style.

Controlling lists

Convert Fm numbered and bulleted lists into corresponding Rh lists by selecting the appropriate BodyLevel1-3 based on the level of the list nesting (initial lists should map to BodyLevel1, and nested second level lists should map to the BodyLevel2 style). In addition, set the Autonumber option to Convert Autonumber to HTML List. You can also choose to convert to RH List instead of HTML List, if you are more comfortable working with RH Lists. RoboHelp Lists are not controllable via the .css file.

Controlling other autonumbers

Chapters, figures, tables and Warnings/Notes/Cautions are all examples of autonumbering from FrameMaker that may not be appropriate in your online output. For these numbering strings, you can choose either to Ignore Autonumber, or to Convert Autonumber to Text.

Mapping character styles, table styles, and cross-references

Map other styles to css styles as with the paragraph tags. If an appropriate style doesn’t exist, then add one to the RHStyleMapping.css file using the Rh css editor, or other css editor.

Knowledge of .css, while not mandatory, is extremely helpful in defining web and other electronic output.

Other mapping options

Conditional text, image conversion and context sensitive help are all available options with the conversion. For more on these topics, see the FrameMaker Integration forum.

Creating output from RoboHelp

RoboHelp has quite robust output options, far beyond the scope of this article. However, here are some tips for generating a basic WebHelp output from your linked FrameMaker content.

WebHelp SSL settings

In the Single Source Layouts panel, double-click on the WebHelp SSL. In the Content Categories > Content <Default> section, select the FM TOC and FM IX options we defined when setting up our linked project. Also be sure to indicate an appropriate Default Topic for your project. Click on Save and Generate to finish your processing and select View to open the project in a browser. If you get a security warning, don’t worry about it…it is a temporary notice posted by your browser. Your users will not see this message when accessing content via the network or web. To eliminate the warning, choose the Add Mark of the Web option in the Navigation properties.

Conclusion

RoboHelp provides a smooth road to nearly any electronic output format you require, including HTML5, EPUB, and Kindle. It is what I used to produce the EPUB versions of both the FrameMaker 11 Reviewer’s Guide, and my Publishing Fundamentals : Unstructured FrameMaker 11 book.

For more detail on Fm to RH integration, and TCS integration in general, see the Adobe OnDemand Webinars page, the FrameMaker Integration forum, and mattrsullivan.com