Matt Sullivan returns as a guest blogger to share technical details on integrating FrameMaker and RoboHelp in order to publish to multiple output formats. Matt covered many of the principles shared below in a recent webinar; you may view the recording by clicking on it’s title: Exploring TCS Integration Sess 2: FrameMaker > RoboHelp Integration.
Integrating FrameMaker and RoboHelp
I’ve been using Adobe FrameMaker for over 19 years to produce books. Its long document publishing features are 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 non-Adobe 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
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:
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
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
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.
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.
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.
About our Guest Blogger:
Matt Sullivan is an Adobe Certified Instructor and Adobe Certified Expert in ten different Adobe publishing and e-learning applications, including everything in the Technical Communication Suite 4. He teaches online and in-person classes as well as helping companies improve their publishing workflow. Matt spent years setting up electronic prepress departments for commercial printers prior to the start of his training career. After that, Matt ran his own Adobe Authorized Training Centers (GRAFIX Training, in southern California), managed the training arm of roundpeg, Inc., and co-wrote the definitive FrameMaker 11 reference book, Publishing Fundamentals: Unstructured FrameMaker 11. He has represented Adobe in countless conferences, trained FrameMaker support personnel, presented webinars, and assisted in Adobe pre- and post-sale engagements. To learn more about Matt, and what he does, you can perform a web search on his social media id, mattrsullivan.
/* Style Definitions */
mso-padding-alt:0in 5.4pt 0in 5.4pt;
font-family:”Times New Roman”,”serif”;}