Tips and Techniques for Single-sourcing with RoboHelp X5®
Click a link below to jump to a particular section; click any "
As its name suggests, RoboHelp has always primarily been a tool for creating online Helpin its early versions, support for printed output was limited to dumping the content of all the topics into Word, with little opportunity to control the structure and format of the resulting document. And before X3, there was little scope for customizing the output for particular requirements.
However, the trend in the user assistance community toward information reuse over recent years, and competition from a new generation of tools specializing in single-sourcing, has resulted in a number of important refinements to RoboHelp's printed document capability. Successive releases from X3 onwards have also added a number of other features that support single-sourcing, not least of which are conditional build tags that enable you to customize both online and printed outputs.
The quality of the printed document output in RoboHelp X5 now meets the needs of many users, and is quite acceptable for internal review and informal documentation. However, you should be clear that is not of the same high standard of print documentation that you can create directly in print-oriented tools such as FrameMaker® and Word.
Despite the limitations of its printed document output, RoboHelp now offers a rich set of easy-to-use features for delivering multiple customized outputs out of a single project. This article provides some guidelines and tips on using the key single-sourcing features.
Conditional build tags provide the means for marking up either entire topics, or sections of content within topics, so that you have the option of excluding them from the generated output. The ability to do this is a key feature of any single-sourcing tool since it enables you to generate a variety of customized user assistance deliverables from the same source project.
Here are some examples of how you might use conditional build tags:
Conditional build tags are extremely easy to create and applywhen you create a new conditional build tag, you assign a name and a color to it. As you mark up content with the conditional build tag, the content is shaded with the color for that conditional build tag.
Tips for Working with Conditional Build Tags
A conditional build expression is a Boolean expression that determines which conditional build tags are included in the generated output. Usually the conditional build expressions that you will use in RoboHelp are very simple. For example, if you wanted to exclude any topics or content marked up with the "Online" conditional build tag, the expression would be "NOT Online".
RoboHelp makes it very easy to create exclusive expressions like this. Its Define Conditional Build Tag Expression dialog is designed for excluding conditional build tags from the output with a single click.
You can use conditional build expressions when you are previewing individual topics (useful to see how the topic will appear in a specific output) and when you generate the output. When you are generating multiple outputs from a single project, you can define a different conditional build expression for each Single Source Layout (RoboHelp’s name for a specific generated output).
Tips for Working with Conditional Build Expressions
For printed document output only, you can customize the structure (and hence the table of contents) of the output without affecting the TOC in your RoboHelp project. You can also exclude topics entirely from the printed document output. You create the customized structure the first time that you generate the output, and it is stored within the printed document single source layout.
Tip for Structuring Printed Documents
For printed document output only, RoboHelp enables you to map the styles you have used in your RoboHelp project to the styles within a Word document template. This means that you can give your printed document output a completely different look-and-feel to your online Help. Before being able to map your styles, you should create a Word document template outside of RoboHelp. This Word document template will contain a style for each of the different formats that you wish to use in your printed document.
For the style mapping process to work successfully, you must ensure that you have formatted your topics in RoboHelp using only named styles, without using any "inline" or manual formatting. Inline formatting cannot be mapped to a different format within Word, and so will carry over into the print document exactly as is.
Tips for Working with Style Mapping
One of RoboHelp’s key strengths is that it offers precise control of the online Help output to the userthe price to pay for this is the fact that the printed documentation has to be converted from information that has been written and designed with the online medium in mind. As a result, RoboHelp still struggles to compete with the quality of printed documentation of tools that store content in a database and are not rooted to any specific output medium. For example, RoboHelp does not convert hyperlinks to cross-references for printed document output, in the way that AuthorIT, Doc-To-Help®, and Veredus all do. By default, RoboHelp includes all topic hyperlinks in your printed document output, colored blue and underlined, but not implemented as a hyperlink in Word. However, it does remove See Also and Related Topic buttons from the printed document output.
Tips for removing hyperlinks from printed document output
There are two types of hyperlinks within topics:
In the case of the inline hyperlinks, the aim is to remove the blue color and the underline, but to leave the text intact so as to preserve the correct wording and flow of the paragraph. You can do this by removing the unwanted formatting from the "Hyperlink" character style in the Word document template you are using for your print output.
You can remove "stand-alone" hyperlinks by applying a conditional build tag to them, and then excluding that conditional build tag from the print document output. This is a somewhat fiddly and time-consuming process, and it is a pity that RoboHelp does not provide an inbuilt automated way of dealing with such unwanted hyperlinks.
RoboHelp provides a ready-made set of outputs, or single source layouts, for your project. You can customize each of these with a specific conditional build expression and with options applicable to the format (HTML Help, WebHelp, Print Document, etc.) of the single source layout.
You can also create your own new single source layoutsthis enables you, for example, to create multiple HTML Help outputs each of which uses a different conditional build expression to customize the content for a specific audience.
Tip for Creating New Single Source Layouts
If you have multiple single source layouts for a project, it is sometimes useful to be able to generate all (or some of) the outputs in a single operation. You can do this using the batch generation feature. To use batch generation, right-click on the Single Source Layouts folder and select the Batch Generate option. The following window appears:
Tip for Working with Batch Generation
If you'd like to discuss or comment on any of the issues raised in this article, please submit a posting to The Forum on this site.
Matthew Ellison has 18 years experience as a user assistance professional in the software industry. He has been a popular speaker at WritersUA events throughout the world since 1997, and now runs his own independent UK-based training and consulting company specializing in online Help design and technology. Matthew holds a B.Sc. in Electronic Engineering and a Post-Graduate Certificate of Education from Bristol University in the UK. He is also a Certified RoboHelp Instructor.