Known Participant

Question

Not quite the integration I hoped for - or a complicated question

Forum|Forum|18 years ago
April 16, 2008
7 replies
4941 views

Greetings,

I've been using Frame for over 10 years and Robohelp for about 6, on and off, for both of them; plus a lot of Interleaf, and several other DTP, word processing, and imaging/drawing apps... in short, I'm no neophyte in the tools and principles of technical writing.

I'm trying to single-source some related documents (online help, FrameMaker user's guide, and possibly a FrameMaker programming guide). The guides will be printed and delivered electronically, so a primarily-printed output is required.

So my client purchased the TC suite and handed me the assignment for these and several other documents. I've determined that the only shareable content will be procedures and definitions. So what I'd like to do is create source objects and put them in a shared directory. Procedures will consist of a heading and a numbered list, possibly images where appropriate. Definitions will consist of a heading and one or more short paragraphs of body text.

If I were just single-sourcing in FrameMaker, this would be a very simple structure to create and deploy. I would have host documents with their own, native, static content and create shared text references out of the content files mentioned in the last paragraph. All of the structure of the documents would be native to the host document.

However, it seems to share FrameMaker files with RoboHelp, it's a very one-way process, and not very modular. For instance, assume I want to make a topic out of one of my source procedure files. I import the file by reference into RoboHelp, and it appears as a new topic in my help system. That's great, but now I'd like to add a list of related links to the topic, or maybe some other additional blurb of content that I want to appear in the Online Help, but not in the FrameMaker documents. I can't do it. If I make changes to the imported Frame document, I can't later make changes to the Frame source file and update it without losing changes made in the help file.

The functionality I would really like (and if it's there, I cannot see it), is the ability to import a frame file as a text inset into RoboHelp exactly the way it is done in FrameMaker. That way if I have a boiler-plate paragraph shared definition that is only part of a topic, I can just insert it at the cursor's location and have a live link to the Frame source file for updating when needed.

Alternately, if FrameMaker could import an HTML file by reference, I could author my definitions and procedures in RoboHelp, then pull in the HTML files into FrameMaker just like I can do with Word document (or for that matter an imported graphic). There doesn't seem to be any reason why we couldn't go both ways. 95 percent of the functionality is already there, so I suppose it wouldn't be hard to go the next step. The same goes for the HTML snippets, which are a cool idea, but again, not compatible with FrameMaker: if FrameMaker could import an .hts file by reference, those handy snippets could appear in both Frame and RoboHelp files and be auto-updated easily.

As it is, I don't see any way to take advantage of all of this integrated functionality. The philosophy behind the design of the integrated RH/FM packages seems to be that I can create a Frame Book and turn it into a RoboHelp Help system, which would really make for a crappy, and fairly pointless help system that looks like a printed document. I can already generate a PDF out of FrameMaker that is technically usable online. What I really want is to be able to use much of the same content but put it online help system that looks and feels like an online help system.

Sorry I'm a long way into my head and not sure if any of this will make sense to others or not. I've been playing with single-sourcing in a lot of applications, so my way of thinking about it is kind of abstract and hard to follow without example.

Does anyone have any light to shed or anything else to share about single-sourcing methodology with the new package? Hopefully, I'm just missing something and what I want to do is doable.

Thanks in advance.

Tom

FrameMaker integration

This topic has been closed for replies.

Tom.HAuthor

Known Participant

Jain,

Thanks for the suggestion. I haven't touched a frameset since my early homepage authoring days. Since your post, I've been playing around with the idea, and it just might work. It could be a pain to setup the whole system, but I can use one of the frames in the frameset to pull in the imported FrameMaker .fm file.

I'll keep you all posted.

Tom

Tom.HAuthor

Known Participant

All,

Another loose end I might as well tie up as long as I'm here.

I regret to report that everything I tried from my own bank of ideas and from the ideas of others in this forum ultimately failed to produce the result I was looking for (or even a close enough). The numerous shortcomings of the Frame-to-RH single-sourcing engine ultimately overcame my will to keep coming up with workarounds. I was using a Frameset model for quite some time, and it almost worked... almost. I have a long s***... er laundry list of things that could have been done better, some of which I've described in earlier threads.

But anyway, here is what I ended up doing instead:

1. Copied all of my FrameMaker content into RH as new topics.

2. Threw away all FrameMaker source content and all remnants of the Frame stuff imported by reference.

3. Created two single-sourse layouts, one was WebHelp, the other a printed document.

4. Conditioned out of the print document layout:

a. The CSH topics from the webhelp

b. Any and all content that made reference to the online help.

c. The "Related Topics," which were manually created hyperlinks at the bottom of each webhelp topic.

5. Conditioned out of the WebHelp output layout some printed-document-only content.

6. Output the WebHelp according to a typical process.

7. Created a Word template with all of my FrameMaker styles defined in it (same exact names).

8. Mapped the RoboHelp styles to Word Document styles (Except for Heading 1, etc. which apparently absolutely have to keep those names).

9. Generate the Printed (Word) doc.

10. Used Word's capabilities to do global search and replace for niggling formatting issues.

11. Created a FrameMaker book with a front matter, TOC, body chapter, and back page. The book has my typical printed document catalogs in it.

12. Copy and paste the entire reformatted Word document into the FrameMaker body chapter (not linked, just copied).

13. Used FrameMaker tools to make any final tweaks to the Frame version. A particular hassle was I had to change the anchored frame properties for every screen capture because they come into FrameMaker as floating anchored frames that end up in bad locations (I always use "below current line" and a figure title that goes above.

14. Generated the FrameMaker TOC.

15. Published the FrameMaker book to PDF for distribution online and P.O.D.

An obvious problem is that there is no live link between the printed doc and the online help. The whole process is a one-way process. When I need a new printed User's guide, I have to re-output the printed doc, paste it into the word template, tweak it, copy it into the FrameMaker book, tweak it, then I'm done. Fortunately, I have it down to a pretty smooth process that takes about 30 minutes.

The final result, I can create a FrameMaker-quality (with appropriate company template) printed document from an online help project in less than an hour. If I had to do another new book rather than this same project, it would take a little longer because I'd have to create a new Frame book and monkey with the front and back matter, etc., but overall it isn't that hard to do.

It's nowhere near the solution I was looking for, but it works.

I hope this description is helpful to some of you struggling with this kind of issue.

(I know TC Suite 2 will probably eliminate the Word step, making it that much easier, but I don't have that yet.)

Cheers,

Tom

Jeff_Coatsworth

Community Expert

Hi Tom,

I've been trying to follow what you're trying to accomplish in this thread & having a great deal of difficulty.

Why all this back & forth stuff to Word & FrameMaker from RoboHelp?

I thought that the whole idea of single sourcing is that you do ALL of your writing in Frame; creating separate books for print & online versions out of the common .fm documents that make up the components of each. You say there's only about 30% common material between the two - fine! Use text insets for that stuff and author away. It's a one-way street from FM to RH.

When it's time to publish - suck the online FM book into RH and print your PDF from FM for the printed material. What's the big deal? There's no need to screw around stripping "printed" references out of the topics in RH - they're already gone because they never existed in the FM doc in the first place, right? I think your mistake is trying to print PDF's out of RH - it's not a very good tool for that compared to FM IMHO.

I don't know, maybe I've just misunderstood what you're trying to accomplish.

Jeff

JainVivek

Inspiring

Tom

Have you explored FrameSets in RoboHelp? You can add multiple topics in a FrameSet. Since you maintain your HTML content in a table structure, will FrameSets help?

Tom.HAuthor

Known Participant

Michael,

Thanks, you make some interesting points worth considering. I'm going to have to do a little more thinking on it and maybe a little experimenting to see if I can author the help system in Frame (making use of the content-sharing available exclusively in Frame with the other two documents), then pull the whole system into RoboHelp.

Tom

Tom.HAuthor

Known Participant

Arnis,

Thanks for your input. You're right about my aims. Using just FrameMaker, it is quite possible to do topic-based authoring with text insets, conditional text, and variables. I've seen and created very dynamic product that way. I was hoping that the TC suite would extend FrameMaker's existing functionality into RoboHelp, but it stopped a little short. It was worth a try to see if anyone discovered something other than I did in playing with the new suite. I did see the RoboHelp snippets (and I read the article you linked for me) and I think they're a great idea for developing help systems. Too bad they didn't make FrameMaker able to import an HTML (and/or .hts) file as a text inset: map the HTML tags to Frame paragraphs, etc. That might have been another fairly streamlined way to share content between the two applications.

I don't really have the option of bringing in other development tools, so it sounds like I'm stuck doing things the old way with the new package.

Tom

Newsgroup_User

Inspiring

mrtomh,

IT sounds like you're really aiming to do topic-based authoring as in
a DITA documentation model. This way you assemble all of your discrete
topics using map files (kind of similar to FM's book-building) to get
the final piece. The publisher route for creating the actual
deliverable would be a bit different though - you'd probably have to
use the DITA Open Toolkit (OT) to create the help files.
Alternatively, you could possibly create a Book file in FM from the
specific map and then publish that through RoboHelp (haven't heard of
anybody doing that though).

Regardless of the route, with the current set of tools, it's going to
be convoluted.

RoboHelp does utilize "snippets" which are similar in concept to FM's
text insets. Unfortunately, you can't link these to FM files to
maintain a dynamic single-sourcing workflow. There's an Adobe devnet
article on these at
http://www.adobe.com/devnet/robohelp/articles/snippets.html that might
be of interest.

Tom.HAuthor

Known Participant

Thanks Arnis and Jain for your replies. I'm familiar with context sensitivity and the role it plays in the FM/RH integration, but even with it, I'm still only part way to where I'd like to be.

I'm not trying to write a whole FrameMaker book and then single-source it into a help system. The printed guides and the help system might only share about 30 percent of the same content between them. But I would like the shared content to be single-sourced.

So let's say I have a descriptive paragraph that I want to use in the OLH and the Print docs. So I author it in FrameMaker as a separate document and import it into my two printed documents by reference, within the larger context of those two books. But in the OLH version, I want that one paragraph, along with its heading, to be either

• part of a bigger topic
• a separate topic with some related links at the bottom, or
• (better yet) inserted into a table cell because all of my OLH topics are a two-column table with related links in the right column and body text in the left column.

I can't really do any of these. If I import the frame file by reference, it wants to be a whole topic. Any subsequent changes I make to that topic will force me to either break the ability to update with changes from the source document or accept that any changes to the Frame source document will destroy the changes made in RoboHelp.

If I put a list of cross-references in the Frame topic, then condition them for the OLH only, those could turn into my related links, but it will only work if the targets of the cross-references were inside of the same Frame book to begin with (I can't create a reference from within Frame to a RoboHelp topic that was natively created in RH.

On the other hand, if RoboHelp could just import a Framemaker document by reference as a text inset, the same way as Frame does it, it would be perfect. I could add material within the topic before or after the inset, then still update the inset whenever I made changes to the source.

Again, maybe I'm just missing something, but it doesn't seem like there's any reasonable way for me to do what I need to do with any single-sourcing.

mrtomh

Michael_Müller-Hillebrand-basb

Inspiring

quote:

Originally posted by: mrtomh@yahoo.com
I'm not trying to write a whole FrameMaker book and then single-source it into a help system. The printed guides and the help system might only share about 30 percent of the same content between them. But I would like the shared content to be single-sourced.

Tom,

although at the first look your reasons are understandable, IMO your way would really make issues more complicated. Trying to integrate and mix content from two different sources is always more difficult (and error-prone). It is easier for writers to work with a single editor for all content, it is easier to exchange content. For instance, if some sections you originally thought would be in the help file only, suddenly are supposed to be available in the printed documents as well?

I always found it easier to write in a 'printable' environment which by design can handle all the special issues involved when creating 'books' (like pagination control). When pushing such content through a conversion engine to HTML it is easy to throw away the special things that are only needed for print output. The other direction is not as easy; it is very difficult to automatically add good pagination.

Also with FrameMaker you can easily set up two (or more) books which share a certain amount of common sections.

If the percentage of common content is really low, you might want to look at other editors, but I would alway advise to work from a well-defined, single source format with one editor.

- Michael Müller-Hillebrand

Newsgroup_User

Inspiring

As I understand it, the TCS uses RoboHelp as the (help) publisher in a
single-sourcing workflow from FM. If you use conditional text in the
FM documents, the conditions get passed to RH and can be activated (on
or off) as required. You still do all of your maintenance and writing
at the FM end in this scenario.

JainVivek

Inspiring

As Arnis mentioned, you can use conditional text in FrameMaker to add Help specific content in FrameMaker. Since both FrameMaker and RoboHelp support conditional text, allow you to filter content and RoboHelp imports content with conditional text settings intact, this works.

You can also edit a part of content (a topic) in RoboHelp and preserve the changes in that topic while you update the remaining content from FrameMaker.

Sign up

To post, reply, or follow discussions, please sign in with your Adobe ID.

Sign in to Adobe Community

To post, reply, or follow discussions, please sign in with your Adobe ID.

Scanning file for viruses.

This file cannot be downloaded