This is a new topic branching off of http://forums.adobe.com/message/6088200#6088200
(Cross-posted to FrameUsers, Adobe RoboHelp "FrameMaker Integration" forum, and RoboHelp bug report)
What follows are some important limitations regarding FrameMaker books that are linked via TCS 4 to a Robohelp project to produce online Help output (HTML Help, WebHelp, etc.).
After a fair amount of testing and research, it seems that RoboHelp is incompatible with *any* FM text insets or "referenced content" such as Excel spreadsheets. Plus, there may be a serious limitation with cross-references in general that might require you to alter the folder structure of your FM project.
In several text insets in my FM book, I have cross-references to a topic outside of the inset. In FM, the links work and everything updates/generates with no errors. The links work in PDF. But in the HTML Help output from RoboHelp, some (but not all) of the cross references are broken--they look like links, but the cursor does not change to a pointing finger and no jump occurs when you click. Looking at the source HTML, the href command is missing for those particular links.
And although the FM "Heading & Page" cross-refs are set to convert to just <$paratext> in RH, some (but not all) of the broken HTML Help links retain the "on page x" part of the FM style. Again, other cross-refs in the insets convert correctly and are active. Even within the *same inset*, some cross-refs convert correctly, and some don't.
An MVP replied to my inquiry on the RoboHelp/FrameMaker Integration forum at the Adobe Community site, suggesting that I shorten the absolute paths for the target files to 35 characters or less, as he and others on the forum also had some random cross-refs that didn't work, and shortening the path seemed to clear most of them up. I moved my "Documents" and "Images" folders up the tree to one level away from the drive letter. (Grudgingly, I'll admit, as it whacked my longstanding project folder structure.) Unfortunately, this didn't work; after updating in RH and generating HTML Help, the same links were broken. See http://forums.adobe.com/thread/1378783 This seems like another serious limitation that could cause pain if you have an established, "verbose" file/folder-naming conventions. I'm leery of restoring my former folder structure out of the fear of breaking more cross-refs.
So I started digging around more in the forums and Help. Here's what I found:
- Other users found that the mere presence of insets would produce the same symptoms in subsequent cross-references in a FM file. Note that these cross-refs are not in an inset, but in text following an inset. So that seems to negate using insets at all in a FM/RH linked workflow. See http://forums.adobe.com/thread/1137497
- Another user imported an Excel spreadsheet into FM as an object. In FM, when the Excel icon is clicked, Excel opens the spreadsheet. But When linking to FrameMaker from Robohelp to create a Robohelp project, that Excel icon gets pulled into RH as an image without the link to Excel. So it seems like it is more than just text insets that fail.
See http://forums.adobe.com/message/6088014#6088014#6088014
- When I opened the Help for the Conversion Settings dialog box in RoboHelp to try to solve a different cross-ref issue, I noticed the following topic tucked under the "Convert FrameMaker cross-reference formats to RoboHelp styles" topic:
"Content reference
"Text or files that you have inserted into the FrameMaker documents as content references appear as part of the topics where they are referenced. They do not appear as references in the online Help outputs."
It took a while to sink in, because "content reference" is not conventional FM terminology, but this vaguely-worded statement buried deep in the Help seems to be saying that text insets are not supported in HTML Help output or any other online Help output. Apparently this at least includes Excel spreatsheets, too. It's also reasonably possible that it would include Word docs, PDFs, or other items imported as objects. Not sure about that, as no examples of "content references" are given, but other users would probably be interested.
Understand that I'm just trying to share what the problems are, share what I tried, and provide an aggregation of what I learned. This info was not forthcoming or obvious when I was shopping tools. Hopefully this might help someone else with their decision making when selecting tools.
In fact, I'd be overjoyed to be wrong about all of this. Text insets are such a useful feature in a single-source workflow, especially if the software you are documenting uses the same widget in multiple modules, has common UI elements in both client and server dashboards, not to mention all of the re-used boilerplate legal/marketing/licensing text, etc.--the list goes on and on. The "edit once, update many" model is too efficient for the TCS Development team to just overlook. In one of the forum threads, another commenter said he designs around this, avoiding insets. But that saddles you with a potentially big maintenance burden at editing time, and makes it necessary to add some "Comment" conditional reminder: "This text is repeated in x, y, and z. If you edit here, edit there, too." Not fun, and prone to mistakes.
Though there may be workarounds to some of these problems, none are as good as making insets work in RoboHelp.
Is any of this fixed in TCS 5? If so, I'd think it unfair to pay for an upgrade to get the fix.
I'm filing a bug report with Adobe, not a feature request, as these issues involve the core competency of TCS with regard to single sourcing, and require budensome workarounds for stuff that should just work right out of the box.
Thanks.