This team blog intends to provide interesting and useful info about Technical Communication Suite, FrameMaker, RoboHelp and related issues in Technical Communication.
Contributors include Mahesh Kumar Gupta, Product Manager - Adobe FrameMaker, Adobe Technical Communication Suite and Ankur Jain - Product Manager, Adobe RoboHelp. There is also an active contribution from members of the product engineering teams.
During the WritersUA conference and more recently, the eLearning Guild conference we showed Adobe RoboHelp Packager for Adobe AIR and in both conferences this was a real hit. Since customers continue to ask how they can create AIR-based information systems, Adobe Senior Product Evangelist, RJ Jacquez, has created a Getting Started Training Video.
RoboHelp Packager is a solution for anyone (not just developers) who wants to build any type of online information systems in Adobe AIR format and not just online help systems. For example in eLearning, the packager can used to create Performance Support Systems, Searchable Knowledge bases, electronic libraries, electronic Catalogs or just a way to package Captivate movies into a single file deliverable (.air); in Technical Communication, the most obvious ones are creating Online Help systems, searchable knowledge bases or just a way to package mechanical 3D models and deliver them as a .air file.
As the title suggests, this article is primarily for people upgrading from RoboHelp X5 or earlier releases. For those of you who are upgrading directly from RoboHelp X5 to Adobe RoboHelp 7, you should not only look at the new features that we implemented in Adobe RoboHelp 7, but should also look at the features that we implemented in Adobe RoboHelp 6.
There is a lot of information on the Adobe.com on the new features implemented in Adobe RoboHelp 7; however, I believe the Reviewer’s Guide is amongst the best document that describes the functionality in a structured manner. You can access and download the Reviewer’s Guide for Adobe RoboHelp 7 from the following web address: http://www.adobe.com/products/robohelp/pdfs/robohelp_7_reviewers_guide.pdf
However, there is little information on Adobe.com on the features that were implemented in the previous release (Adobe RoboHelp 6). Since this product had a very small shelf life, approximately nine months, there is little information about the same on the web too. Hence, I thought it might be useful to share the Reviewer’s Guide for Adobe RoboHelp 6 (Click to DOWNLOAD). When you download, you shall get a zip file that has Demo Assets, Getting Started Guides for Adobe RoboHelp 6 and Adobe RoboHelp Server 6 and the Reviewer’s Guide as Adobe PDF. You shall find Demo Assets useful if you want to follow “Try it” sections in the Reviewer’s Guide.
I hope this blog entry helps you find more reasons to upgrade :)
I have met a number of technical communicators who are interested in excluding some topics from being searched in a RoboHelp published project. Adobe RoboHelp doesn't’t support this natively however, since I see a lot of interest in doing the same, today, I shall describe a procedure that will help you exclude specific topics and even content in a topic from being searched.
Here is what you have to do:
Create a Conditional Build Tag, say “Exclude_from_Search”. I have created a sample Adobe RoboHelp 7 project. You can download (DOWNLOAD NOW) the same and work on it.
Apply this CBT to all the topics in the Project Manager that you want to be excluded from the Search. Here in the sample project, I have applied the CBT to Third_Topic.htm in the project manager.
Apply this CBT to content within a topic that you would want to exclude from Search. In the sample project, I have applied CBT to some text in the Second_Topic.htm
In the SSL, create a special SSL that excludes all the content that is tagged with "Exclude_from_Search” CBT. All you have to do is create a new WebHelp SSL, name it "Exclude from Search" and then click on its Properties and Define Condition Build Expression as “NOT Exclude_from_Search” and then Save the same.
Now generate output for both the WebHelp SSL‘s - "WebHelp" and "Exclude from Search". You can even use the Batch Generate option to do that in a single shot.
Quick test in the WebHelp output:
1) Search for lazy – you shall get hits for Second and Third Topic
Now we need to replace the index generated in the "WebHelp" output with the one that is generated in the "Exclude from Search" output. Follow the steps listed below to do the same:
Now browse to the output folder of the "WebHelp" output. The default location would be “<Project Path>\<Project Name>\!SSL!\WebHelp”
Browse to folder “whxdata” under the WebHelp folder.
Search and delete whf*.* files in this folder.
Copy whf*.* files from the corresponding folder in the Exclude from Search output (“<Project Path>\<Project Name>\!SSL!\Exclude from Search\whxdata”) and place them in this folder (“<Project Path>\<Project Name>\!SSL!\WebHelp\whxdata”).
Please note that you have to delete all files and copy files and not do a replace operation as the number of files might be different.
Quick test in the WebHelp output after patching the index:
1) Search for lazy – No hits
I just hope that you will now be able to exclude content from being searched in RoboHelp published projects using this procedure till we build native support in the product.
You might be aware that, Adobe released an Alpha build of Adobe AIR for Linux a couple of days ago. You can read more about the same and download a build from the Adobe Labs website. We had released RoboHelp Packager for Adobe AIR when this was not available and we claimed that the output (an .air) created using RoboHelp Packager for Adobe AIR will work on Linux when we release Adobe AIR for Linux. I got a number of queries around that claim, but couldn’t substantiate it then. However, I am happy to announce that you can now download and install Adobe AIR for Linux on a Linux machine and then install any output created using RoboHelp Packager for Adobe AIR. The best part is you will be amazed to see that the complete experience including installation is exactly similar on all platforms.
Since Adobe RoboHelp is a Windows only product and many of us might not have access to an Apple Mac machine or a Linux machine, I thought I must share my experience of installing an .air file created using RoboHelp Packager for Adobe AIR on all the three platforms - Win, Mac and Linux.
So what I did was, I picked up the “Customer Care” sample project that we ship with Adobe RoboHelp and packaged its WebHelp output to a .air file and then installed the same on a Microsoft Windows XP machine, an Apple Mac machine and a Linux machine. As you all know an .air file has to be installed. The installation experience was same and the output (Help) looked exactly same on all three platforms. Here are the images – see it for yourself.
Figure 1: Customer Care on Microsoft Windows (Larger Image)
Figure 2: Customer Care on Apple Mac (Larger Image)
Adobe Senior Product Evangelist,
RJ Jácquez, has created three On Demand training videos to help customers get started with Adobe Technical Communication Suite. A large number of customers have been asking us for training material on the Suite. I hope you will find this useful. Please see the details below-
In Part 1, you will learn about leveraging live and interactive 3D models from virtual any CAD/CAM/CAE software in your technical and instructional documents using the Adobe Technical Communication Suite. This training video includes all exercise files needed for you to follow along with the presenter, and experience first-hand how to convert a 3D CAD file into a highly compressed 3D PDF document and how the included 3D Toolkit software allows you to reuse this model in FrameMaker and then generate an interactive and rich PDF document, that you can distribute to anyone using the free Adobe Reader. The video also guides you through the steps on how to further polish your 3D models using 3D materials and by adding animation that shows your end-users how to disassemble the model.
In Part 2, you will learn how to supplement your technical and instructional design documents with engaging Adobe Captivate demonstrations, simulations and quizzes in the Flash format using the Adobe Technical Communication Suite. This training video includes all exercise files needed for you to follow along with the presenter and experience first-hand how to create engaging Captivate demonstrations, simulations and quizzes that can be imported into FrameMaker documents and saved as PDF files, that end-users can playback using the free Adobe Reader. The video also guides you through the steps needed to add a printing poster in FrameMaker and how to generate a single .SWF file from Captivate, which includes the playback bar in the PDF file, as well as other best practices.
In Part 3, you will learn about adding FrameMaker books and documents in RoboHelp as live links and reusing FrameMaker content for creating Online Help systems, Searchable Knowledge bases, Performance Support systems and even Policies and Procedures. Just like the first two, the exercise files are also included in case you want to go over the integration features yourself.
Besides Adobe Technical Communication Suite, there are training videos for Adobe FrameMaker 8 and Adobe RoboHelp 7 available on Help Resource Center. Adobe Certified Trainers (for example, John Daigle is a certified trainer for RoboHelp and Captivate) can help you with formal training, if required. If you are looking for formal training, you can locate Adobe Authorized Trainers in your area from Adobe site.
With Adobe Technical Communication Suite and RoboHelp Packager for Adobe AIR (free download), you can now generate Adobe AIR output when you are authoring documents in FrameMaker. As part of Adobe Techncial Communication Suite, you can add FrameMaker documents and books as live links in RoboHelp and generate WebHelp output from RoboHelp. RoboHelp Packager for Adobe AIR enables you to generate Adobe AIR output from the WebHelp output. Adobe AIR output comes with several advantages - please check out Adobe Labs page for more details.
Generating Online Help for DITA content
If you are authoring in DITA, it is easy to convert the DITAMap file into a FrameMaker book or a FrameMaker document (see DITA menu in FrameMaker 8 below) and generate the HTML help using RoboHelp. If you update your DITA topics later, you can re-generate the FrameMaker document and RoboHelp will allow you to generate Online Help in two clicks (Update and Publish).
Another alternative for publishing DITA content to RoboHelp is to (a) create HTML files through DITA Open toolkit, (b) bring these HTML files in RoboHelp and (c) run publish/generate commands. RoboHelp also supports command line compile and publish. For generating overnight builds, you can run a batch command to download the source files from source control system, compile and publish the output.
Do you have a custom help viewer for cross-platform applications?
Online Help using Adobe AIR is an attractive alternative for cross-platform applications. Over the last month, I met several customers who write custom help viewers to support online help for cross-platform applications. This requires additional cost of creating and maintaining the helpviewer application. Helpviewer is not a simple application, it requires functionality for creating mini-TOC, breadcrumbs, browse sequences, support for skins or templates, support for PDF, SWF and other dynamic content and search functionality for multiple languages. If you are planning to add Web 2.0 features, there is additional effort required to create a commenting infrastructure. With Adobe AIR and RoboHelp Packager for Adobe AIR, you now have an easy out of the box cross-platform option available to you.
FYI- Adobe AIR for Linux (alpha) is now available on Adobe Labs.
You can create custom filenames for topics in RoboHelp, when you add FrameMaker documents to RoboHelp as live link. You don't need to use filename markers in FrameMaker. Since RoboHelp supports conditional tags and imports the text in FrameMaker which has conditional text setting applied, the same workflow can be created using conditional text. This solution relies on the fact that RoboHelp creates topic names based on the text of the style you paginate on.
1. Please add the specific file names (say, FileName1, FileName2, FileName3, FileName4) just before the topic headings in FrameMaker which correspond to these dialog names.
2. Assign a unique style to these names (say, "FrameMakerFileNameStyle").
3. Apply a conditional text to these names in FrameMaker (say, "FileNameTag").
4. Add another style in RoboHelp (say"RoboHelpFileNameStyle").
5. Map the FrameMaker style "FrameMakerFileNameStyle" to RoboHelp style "RoboHelpFileNameStyle". You can map the remaining styles as you had done earlier. No change is required.
6. Select "RoboHelpFileNameStyle" as the style to paginate on (instead of Heading 1 or Heading 2).
7. Also, select to create a TOC based on FrameMaker TOC which uses Heading1 or Heading2 styles in FrameMaker. Note that
filenames are not same as the TOC entries, RoboHelp project explorer will list topics by filename. However, if you have a hierarchical TOC in FrameMaker (using styles Heading1, Heading2, Heading3) etc, RoboHelp will convert the TOC and maintain hierarchy.
8. Select "paratext_no_num" as the option for topic name pattern. This option asks RoboHelp to generate filenames based on the text of the style you paginate on and remove the autonumbering from the text.
Please click on Continue to view the Captivate demo below.
On Import of content in RoboHelp,
1. RoboHelp creates a TOC which mirrors FrameMaker TOC (the additional text is not reflected here)
2. RoboHelp creates filenames based on the text added (for example, FileName1, FileName2, FileName3, FileName4 etc.)
3. RoboHelp shows the custom filenames (FileName1, FileName2, FileName3, FileName4 etc.) as part of each topic with conditional text (FileNameTag) applied.
4. In the SSL, exclude the conditional text "FileNameTag" and generate output. You get your TOC, topics are also displayed fine without the additional text.
Please click on Continue to view the Captivate demo below.
