Advertising Information

Your Ad Here!

 
March 2004
Helpful Tips


Return Home

Contact Gail

How we use RoboHelp® HTML
as a single-source tool for help and printed guides
By Gail Van Landingham

In this article I'll present the details on how we use RoboHelp® HTML for single sourcing at DR systems. See last month's newsletter for my article about our search for a single-source tool.

(For more in-depth instructions, see Online Help in RoboHelp® HTML.)

Note: Our company is using RoboHelp® X.3, and the screenshots and examples in this article are from this version. Currently, Macromedia is selling RoboHelp® X.5, and the dialog boxes are different in this release. But the basic procedures are the same.

Here's what I'll cover in this article:

Before starting

Before starting, we reviewed the requirements for our documentation products and thought about the products we wanted to create:

  • Help. Compiled Microsoft HTML Help

  • Printed guides. One user guide and several smaller guides on specific topics

  • Release-specific output. The current release plus the Beta release

We also learned a few key concepts in RoboHelp HTML:

  • Conditional Build Tags. These tags identify content that needs to be excluded from the output. For example, you can create and apply a tag named "Print" for content that goes only into a printed guide, not into Help.

  • Single source layouts. Each layout is a template that includes output settings and preferences. For our company, our layouts include online Help and several printed guides.

Here's the process we followed.

Creating Conditional Build tags

  1. In the Project tab, right-click Conditional Build Tags.


  2. Select New Conditional Build Tag.


  3. Name the tag. You can select a different color if you don't want to use the default color assigned.


  4. Click OK.

This is the set of Conditional Build Tags that we created:

Figure 1: Create Conditional Build Tags

Applying tags to content within a topic

In this example, we wanted the Related Topics button to appear only in Help, not in the printed guides.

  1. Select the text or graphic. In this case, we selected the Related Topics button.


  2. Right-click and select Apply Conditional Build Tag.



    Figure 2: Apply tag

  3. Select Online. This is the tag we use for content that goes only into Help (not into printed guides).

    After selecting the tag, the Related Topics button is marked with the Online tag. It has blue hatch marks--because we selected blue as the color for the Online tag.



    Figure 3: After tag applied

Applying tags to an entire topic

We also needed to exclude entire topics from an output. For example, we didn't want our Release 6 features (our Beta release) to be included in the Release 5 Online Help and printed guides.

To apply the Release 6 tag to an entire topic:

  1. In the Project tab, select the topic.


  2. Right-click and select Properties from the shortcut menu.


  3. Click the Advanced tab.



    Figure 4: Topic properties


  4. Select the Rel6_only tag.


  5. Click OK.
Creating single-source layouts

For Release 6 Online Help, we started with the HTML Help template that RoboHelp provided.

  1. In the Project tab, double-click Single Source Layouts.



    Figure 5: Single Source Layout - Help


  2. Double-click Microsoft HTML Help. The HTML Help Options dialog box opens.



    Figure 6: HTML Help options

  3. Next to "Conditional Build Expression," click Define. The Define Conditional Build Tag Expression dialog opens.



    Figure 7: Conditional Build Expression

    • Select a tag from the Available tags pane on the left.

    • Click the right arrow to move the tag to the "Exclude from output" pane.

    Because we're creating a help system for Release 6, we excluded:
    • AddTopicLater. The draft topics that are incomplete.

    • Rel5_only. Any text designed for Release 5.

    • Print. Any text designed only for printed guides.

  4. Click OK.


  5. Click Finish to generate Online Help.

Customizing each printed guide

  1. In the Project tab, double-click Single Source Layouts.



    Figure 8: Single Source Layout - print


  2. Double-click Printed Doc--R5 User Guide. The Print Document General dialog box opens.


  3. Click Next.


  4. From the list of available topics, select the chapters and topics for the printed guide.
    • Select a topic or book from the Topics pane on the left.

    • Click the right arrow to move the topic or book to the Chapter layout--into the printed guide.




    Figure 9: Print content


  5. Click Next.


  6. Now map the heading styles used for the HTML topics to the styles used in the Word template.



    Figure 10: Print styles


  7. Click Finish to generate the printed document.

Meeting our goals

Using a single-source tool, we've been able to meet the requirements for our documentation products. We've been able to produce Online Help and multiple printed guides, and maintain two releases of software--all from a single source.

An unexpected reward was hearing my manager say that using a single-source method has meant substantial savings for our company.
Return Home

Feature | Editor's Desk | President's Podium
Helpful Tips | Chapter Meetings|Humor
Mission | Author Bios | Newsletter Staff | San Diego Chapter Council Members