Documentia Inc

In my latest project, I’ve been reacquainting myself with the joys of Adobe RoboHelp and Framemaker to produce some online help. Please see my previous post about RoboHelp that I’ve updated to include RoboHelp 11.

I’ve been using RoboHelp for years, all the way back to the days when it was owned by BlueSky and it worked with Microsoft Word. Nowadays, the thought of using Word to write technical documentation makes me want to re-evaluate my life choices.

We’ve decided to go with the subscription model with Adobe, which means we get the latest and greatest versions as they are released. Sounds good on paper, but it’s lead to more than a few headaches. The Adobe community has been pretty good to suggest workarounds and we’re making progress.

For this post, I’m keeping track of a couple of tips and tricks that I’ve encountered in this journey. It’s mostly to act as a reminder, but I’m hoping it’ll help others.

Bug #1 — File Associations

At first, I had FM2015 installed, but I then upgraded to FM2017. To my surprise, Windows (7) did not update the file association to FM2017. I had to go into \Control Panel\All Control Panel Items\Default Programs\Set Associations\ to ensure that the associations had been made correctly.

Bug #2 — RoboHelp 2017 gets Nostalgic

If you are linking Frame files as your source files, RH2017 will attempt to access Framemaker when importing or updating these files. However, if you do not have FM2017 currently running, RH2017 will attempt to launch FM2015 automatically, which can lead to an error if 1) you do not have FM2015 on your system, or 2) your Frame file are in 2017 format.

The solution is that you need to ensure that the File Associations are correct (see Bug #1) and that you must launch FM2017 BEFORE launching RH2017 and they must be running at the same time.

Respecting the Conditional Text Rules

If your source files use a bunch of Conditional Text tags, you will need to be able to hide the Conditional Text that does not apply to the output your are trying to generate.

For example, if your source documents have content for ABC, DEF, and GHI products, to generate the content for DEF, you need to hide the ABC and GHI content.

Once you import your Frame files to your project, you need to indicate which Conditional Text needs to be hidden and which needs to be displayed.

To prepare the Output to respect the Conditional Text rules, follow these steps:

1. In your RoboHelp project, select Output > Outputs(SSL). The Outputs(SSL) pod appears.
2. Select the output type you want to use, right-click it, and select Properties. The Settings dialog box appears.
3. Open Content Categories > Content<Default>, look for the Conditional Build Expression panel, and click Define. The Define Conditional Build Tag Expression dialog box appears.
4. Select the Conditional Text tags you want to display (in the Available tags list) and move the ones you don’t want to the Exclude from output list.
5. When prompted, provide a name for this type of Conditional Text output.
6. Either click Save to save these changes, or click Save and Generate to save your choice and generate the output immediately.

Defining the Default Topic

The first topic that appears in the online help when you launch it is defined in the Output model (ex: Webhelp Pro).

Note: If you want to pick a topic other than the one you created when you started the project, make sure you generate all the pages for your project first.

To select the default topic, follow these steps:

1. Select Output > Open > Outputs(SSL).
2. Right-click the output model you wish to use and select Properties.
3. Open Content Categories and select Content<Default>.
4. For the Default Topic field, click Select and pick the topic you want to use.
5. Save or Save and Generate.

Hypertext Links Don’t Convert

I had a Book file with chapters in Frame that I would convert to HTML5. Everything was converting over nicely, except the hypertext links to external website (like the company website or an FTP site). The text appears in the traditional blue link color, but there’s no link there to click.

In Framemaker, I highlighted the text and insert a Hypertext marker (message URL http://www.documentia.ca). When I save this as PDF, the hypertext is live and works great. When I convert it to WebHelp, the text appears in blue, but there is no link.

When I looked at the page source of the converted HTML5 (where the hyperlink was dead), I noticed there was a span marker called FM_urllink, but no hyperlink. So on a hunch, I removed the character style in Framemaker and kept the marker (Hypertext: message URL http://www.documentia.ca). I updated the Frame file, regenerated the page, and voila! The link works!

There’s something about applying a character style on the text that has the Marker that hides the hyperlink in the converted HTML5 page.

Now while the link still works in PDF, this means that links in PDF cannot be highlighted with a Character style. For now, the work-around I can see is to use Conditional Text to mark one link as Print only and another as HTML only.

Mapping Styles from Framemaker Source Files

In this project, I wanted to have an increased left/right margin for the Body text (including Bullets, Steps, Step Ghost, Bullet Ghost, etc). I really didn’t want the text to go rampaging from one edge to the other, especially if the browser went full-screen.

To make this process easier, you need to open the Project Settings > Import tab, enable the Apply Framemaker Template option, and select a chapter from your Framemaker document that has all the styles you use in the book. This will allow you to make changes to the output styles across the whole project.

Then use the Edit Conversion button to make your changes.

To prevent having to regenerate the project every time to check the layout changes, select a topic from the Project Manager that has the styles you are changing, right-click it, and select View.

Once you are satisfied with your changes, regenerate the output and verify that everything has worked out.