Search icon Looking for something?

Using RoboHelp to Single-Source Help and Manuals
2004, Q1 (June 20, 2007)
By Robert P. Mohr

If you find yourself in a situation where you have to produce online help and a user manual for the same software application, RoboHelp may be the answer. For years, RoboHelp has allowed you to generate Word (.doc) files directly from help topics, but the output was not very good and many hours of formatting time were needed to tweak the output into something that looked like a real manual. Luckily for us RoboHelp has undergone a change for the better. Starting with versions X4.0 and later, RoboHelp’s ability to generate a well-formatted Word document has improved.

I know what you’re thinking: "But you can’t just take online content, push it out to a Word document and expect it to be a satisfactory manual. Online help and paper manuals aren’t written the same way." I agree. That’s why I employ another feature of RoboHelp’s called Conditional Build Tags. These are very similar to FrameMaker’s conditional text tags. By default, RoboHelp X4.0 starts you off with two conditional build tags: Print and Online. So, all you do to control what you want to see — or not see, and print — or not print, is apply the correct conditional build tag to whatever content that you feel is necessary for the online version and the printed version of your content.

Here is a very simple example of a typical "about" topic that shows build tags applied to parts of the title text that will accommodate an online version and a printed version of the same topic:

The light colored hash represents the Online tag and the darker hash the Print tag. When viewed online with the Print tag excluded, the topic looks like this:

The Printed version, with the Online tag excluded, like this (except it will be on paper):

Conditional build tags can be applied to text, graphics, and tables within a help topic. They can also be applied to topics themselves to prevent them from appearing in the help system’s table of contents. You also can apply more than one tag to the same item, and you can create as many conditional build tags as you want. When it is time to generate the output, you simply tell RoboHelp which build tags to exclude from the output.

The types of output are defined with RoboHelp’s Single Source Layouts function. It is here that you determine the properties of the online and printed versions that are output. One of those properties is which build tag(s) to exclude. Here is an example of a dialog box that shows the Print tag is to be excluded from WebHelp (HTML) output:

As for the printed output, there are several more options available than just build tags:
  • You can generate separate Word document files (subdocuments linked to a Master), or you can generate a single document file.
  • You can embed all graphics within the document files or create links to them, in which case all graphics are collected into a subfolder under the document folder.
  • You can start each topic on a new page.
  • You can include all topics using the same structure as the help’s table of contents and maintain the HTML heading levels, or you can change the order of the topics as well as exclude topics entirely.
  • You can "map" (character and paragraph) styles from the style sheet used in the help project to styles in RoboHelp’s default Word template, or you can map to the styles you’ve created in a custom Word template of your choice.

By default, RoboHelp’s document output includes a title page, table of contents, header and footer, and pages that are set up for doublesided printing. If your help system includes an index and glossary, they will also be included in the document.

So there you have it. With RoboHelp’s Conditional Build Tags and flexible Single Source Layouts, you really can have your singlesource cake and eat it too.

Robert Mohr is a senior STC member and the author of The Elements of Word. He can be reached at rpmohr at writemohr dot com. End of article.

More articles like this...
Comments powered by Disqus.