Getting the TOC you want from FrameMaker for RoboHelp Output

Already have a TOC in RoboHelp, and just looking for the new troubleshooting tip I discovered? Then read the spoiler alert that follows.

Spoiler Alert

While I’ve written on using FrameMaker TOCs for linked RoboHelp projects before, I recently came across a client project where the TOC was behaving badly. The source of the behavior  was a bit tough to track down because while the TOC worked well (enough) in FrameMaker, the left margin (which is different than the first line margin) was set incorrectly. This caused (within the RoboHelp TOC) an unfortunate nesting of appendix titles within the final chapter title of the FrameMaker book.

Long Form outline

If you haven’t yet linked your FrameMaker book to the RoboHelp project, here are some tips from the RoboHelp help system for doing so: Link a FrameMaker book or DITAMAP into RoboHelp project

You can also see Checklist for FrameMaker to RoboHelp Crashes, a previous blog post I wrote on the details of ensuring a clean connection ‘tween Fm and Rh projects.

Here’s the “long version” of how to get the proper conversion of the TOC, from start to finish!

Set your RoboHelp project to create a TOC based on the FrameMaker book TOC

Right-click on the linked FrameMaker book file, and select Properties

 

Then select the Content Settings tab and select the Convert FrameMaker Table of Contents option. Add an identifying label in the Create new associated TOC field. When finished, click OK.

Update your linked FrameMaker files

Right-click on your FrameMaker book file and choose Update > Update All

Set your Single Source Layouts to use the TOC generated from FrameMaker

Identify your new TOC in each Single Source Layout you need. (You may only have one SSL) First, edit the Properties of the SSL

 

From the Content section, point to the FrameMaker-generated TOC you specified earlier

 

Now that the connections are made, let’s look at what you can expect.

How RoboHelp interprets the FrameMaker TOC

The trick here is to understand how the Fm TOC is analyzed during conversion.

Here’s the explanation from the RoboHelp 8 Help system…I believe it’s the same scenario for Rh11, but found this one via Google first…:

At some level, this translates to the following:

RoboHelp looks at the left indent, the size of the text, and formatting attributes of the text when determining hierarchy in the TOC. As noted above, RoboHelp considers the left margin, not the first line margin when considering nesting. Also, the left margin is the primary consideration, so changes in size and emphasis don’t matter much unless the left margin is the same for two different paragraph styles.

Problem: When the first line margin  is set as needed, but the left margin is not set to address multiple line TOC entries, you may get undesired results.

Solution: Set the left margin for each FrameMaker TOC paragraph tag approximately +.25″ to account for multiple line TOC entries, and follow this pattern for all TOC entries on the FrameMaker reference page.

Pro Tip #1: If you find there are multiple TOC reference pages (when viewing the Reference Pages, I use Ctrl+g to see the list pages in the drop-down menu) then delete the unnecessary page. FrameMaker will only use the first TOC page it finds, but 2 TOC definitions are bound to cause confusion down the road.

Pro Tip #2: Delete any unused or duplicated lines in the TOC. Entries for unused TOC  paragraph styles make the TOC harder to decipher. Duplicated entries (like 2 paragraphs with the Heading1TOC tag) will not only confuse the issue, but may also impede your ability to properly convert the content.

For more on FrameMaker TOC’s see my FrameMaker 11 book, Publishing Fundamentals: Unstructured FrameMaker 11. If you’re interested in an EPUB version, please contact me directly, as I’ll be handling sales of the EPUB after July 2014.