RoboHelp apparently doesn't support FM text insets or other "referenced content"

[Don Laux]

(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. See
http://forums.adobe.com/message/6088200#6088200
 
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 regular 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 who use those
items 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.
-Don