Tips and Techniques for Single-sourcing with RoboHelp X5®

By Matthew Ellison


Contents

Click a link below to jump to a particular section; click any "CONTENTS" image following a section heading to jump back here.

Introduction

As its name suggests, RoboHelp has always primarily been a tool for creating online Help—in 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    Link to the article contents

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:

  • If you are generating online Help and printed documentation from the same project, you can create an "Online" conditional build tag to markup up content elements (such as hyperlinks) for exclusion from the printed version. Note that you would not need to use conditional build tags to exclude entire topics from the printed documentation, since it is possible to exclude topics using the print document single-source layout (see Customizing the Structure and Sequence of Printed Documents).
  • If you are supporting a "Professional" and a "Lite" version of a software product, you can create a "Professional" conditional build tag and use it to mark up any content to be excluded from the "Lite" version of the generated output (this is based on the assumption that the "Lite" version of the user assistance will be a pure subset of the "Professional" version).
  • If you have to create customized Help for three different clients, you can create a conditional build tag for each client. You would then mark up any content that was specific to Client A with the "Client_A" conditional build tag.

Conditional build tags are extremely easy to create and apply—when 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

  • When you apply a conditional build tag to an entire topic, you should also apply the conditional build tag to any hyperlinks that target that topic (with the exception of inline hyperlinks that form part of the text of a paragraph). You can easily locate these hyperlinks by dragging the topic into Link View and seeing the topics that link into it on the left-hand side).
  • You can use drag-and-drop to apply conditional build tags. To apply a conditional build tag to entire topics, select the topic(s) in the Topic List and drag the conditional build tag from the Project tab on to the highlighted topic(s).
  • You can overlap conditional build tags. For example, if a piece of content was applicable to Client A and Client B, but not Client C, you would apply both the "Client_A" and "Client_B" conditional build tags.

Conditional Build Expressions    Link to the article contents

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

  • When you have defined more than one conditional build tag, it is usually better to use inclusive conditional build expressions—in other words, expressions that specify the tags you want to include instead of those you want to exclude. For example, if you have three conditional build tags "Client_A", "Client_B", and "Client_C", and you want to include only Client A content, you should use the conditional build expression "Client_A". Ironically, to create this simplest of conditional build expressions, you need to click on the Advanced button in the Define Conditional Build Tag Expression dialog. You can then select the appropriate conditional build tag and use the Add Tag button to create the conditional build expression.
  • Remember that content that is not marked up with any conditional build tag is always included in the output, no matter what the conditional build expression.

Customizing the Structure and Sequence of Printed Documents    Link to the article contents

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

  • When you add new topics during maintenance of your RoboHelp project, remember to add them to the correct location within the structure for the printed document output (in addition to adding them to RoboHelp’s TOC, of course!).

Mapping RoboHelp Styles To Word Styles    Link to the article contents

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 way to create the Word document template is to generate a printed document from your project using the "None – Use the Project’s CSS Styles" option. The resulting document will contain a set of named styles matching the styles used in your RoboHelp project. You can then reformat each of the styles as you want them to be in your printed document output, delete the content of the document, and save it as a document template.
  • Store your document template in the same directory as your other Word templates (such as Normal.dot) and do not select "Yes" when RoboHelp offers to copy the template into your project directory. As a result, you will be able to share the same Word document template between multiple RoboHelp projects.

Eliminating Hyperlinks from Printed Documentation    Link to the article contents

One of RoboHelp’s key strengths is that it offers precise control of the online Help output to the user—the 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:

  • Inline hyperlinks that form part of a paragraph
  • "Stand-alone" hyperlinks (usually located at the end of a topic) that provide a list of related 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.

Customized Single Source Layouts    Link to the article contents

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 layouts—this 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

  • The easiest way to create a new single source layout is usually to create a copy of an existing single source layout. This often saves you having to set most of the options for the new single source layout from scratch. To create a copy of a single-source layout, right-click on the single-source layout and select the Duplicate Layout option.

Batch Generation    Link to the article contents

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:

Batch Generate window

Tip for Working with Batch Generation

  • The Batch Generate dialog tells you whether each of your different outputs is out of date (in other words, whether you have made changes to the project since you last generated the output), and the date on which you last generated the output.

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

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.



up