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.
The year 2007 has been an exciting one and as I look forward to 2008, it promises to be even better. We had 6 product releases in 2007 - Adobe RoboHelp 6 in January, Acrobat 3D ver 8 in May, Adobe Captivate 3 and Adobe FrameMaker 8 in July, Adobe RoboHelp 7 and Adobe Technical Communication Suite in October. The launch of Adobe Technical Communication Suite is a major milestone for us. It brings together the best in class applications and provides an end-to-end solution to all technical communication needs. It is heartening to see the response to the Suite. It is way beyond my expectation! Thank you.
During the last two years, we have expanded our engineering teams for FrameMaker and Captivate and created a new team for RoboHelp. Overall, we have a larger and may I say more experienced and skilled engineering team than anyone else in the business. Both customers and industry experts have acknowledged the impact we have made in the year 2007. FrameMaker 8 has been rated as the biggest release in a decade and we have received similar comments for RoboHelp 7. Captivate 3 surprised everyone with the features it delivered in short period of time. Acrobat 3D continues to create new milestones in innovation - enabling new workflows which no one thought were possible.
Lastly, a big thank you for hundreds of comments, suggestions and personal e-mails we have received. We started this team blog in January 2007. It's almost a year now and I must say that it has been a rewarding experience. Your feedback is valuable and I look forward to continuing this dialog.
1. Importing the TOC and the Index - RoboHelp supports multiple TOCs, Index and Glossary. When you add a FrameMaker book as live link in RoboHelp, you can create a new TOC and a new Index to import the FrameMaker TOC and Index entries. This enables you to manage FrameMaker content separately inside RoboHelp. As a next step, you can add TOC and Index as placeholder in the master project TOC and Index respectively. You should also properly format the TOC in FrameMaker before you import the content in RoboHelp. To remove Auto Numbering from appearing in the TOC entries, please select "Ignore Auto number" during style mapping for those styles which are used to create TOC in FrameMaker. For Index entries, you should use Index Markers in FrameMaker.
2. Defining Content Sensitive Help -For defining context sensitive help, please
choose any custom marker and apply it at the beginning of the paragraphs in the FrameMaker source files.
3. Print and Help Specific Content - You may want to use conditional text to clearly identify the online and print specific content in FrameMaker. In both FrameMaker and RoboHelp, you can define a conditional expression to filter print and online specific content. For example, if you want to use two different image size in Print and Online Help, you may want to include both of them in FrameMaker and apply conditional text to identify which one is for print and help.
4. Style Mapping - RoboHelp enables you to map styles from FrameMaker to RoboHelp. You can map FrameMaker paragraph and character styles to RoboHelp styles, which will automatically reformat your FrameMaker content for publication in RoboHelp. In addition, you can also specify new definitions for FrameMaker cross-reference formats (e.g., to remove page numbers from cross-references in RoboHelp output). If you are using styles to control spacing between text and images, you may chose "Ignore output" for these styles during the mapping. If you want to pass through content in RoboHelp with a user defined tag, you can specify that as project settings in RoboHelp.
You can export and import the style mapping file in RoboHelp and re-use it across projects.
Update (April 16, 2008)-
You can however create dynamic HTML effects like mouse over through style definitions in RoboHelp. For drop down and expanding hotspots, you may want to check-out a workaround posted on Adobe RoboHelp forums (Category- FrameMaker Integration) .
5. Converting Auto Numbering to HTML lists - You can convert auto numbering styles to HTML lists. This is generally preferred if the FrameMaker document does not include complex numbering e.g., multilevel section numbering 1.1.(a).
You can also select specific styles in FrameMaker for which Auto numbering should be ignored. For example, if you have auto numbering defined for FrameMaker styles SectionName and you don't want sections to be converted to HTML lists, please select "Ignore Auto Number" for the style SectionName.
Update - If convert autonumbers to HTML list is selected, please "ignore autonumbering" for FrameMaker styles which are used in the FrameMaker TOC. This is important when you are importing the TOC as defined in FrameMaker. In sequence of processing, autonumbers are converted to HTML lists before RoboHelp generates the TOC.
6. Images - If you have equations or images in FrameMaker, please make sure they are part of an Anchored Frame. RoboHelp can convert the images (including equations) in FrameMaker to PNG, GIF, BMP or JPG and you can define the default format which RoboHelp should use to convert the images from FrameMaker. If you are using PNG, GIF, BMP or JPG in FrameMaker, these formats will be retained and only other formats like TIFF will be changed to the default selected by you. This setting is available in RoboHelp at Tools-> Options -> FrameMaker Documents.
8. Updating RoboHelp Content when FrameMaker document changes - You can update the RoboHelp content with a click of a button when FrameMaker content changes. RoboHelp also provides visual indication if the content is out of synchronization with FrameMaker document.
9. Preserving Content Changes in RoboHelp - To
handle special situations which may require the RoboHelp content to be out of sync from FrameMaker documents either for short duration or for small set of topics, you can preserve content changes in RoboHelp for linked FrameMaker Books.
Adobe RoboHelp 7 has one of the most innovative and powerful feature of single sourcing, support for hierarchical TOC and hierarchical Index. When you bring content from several sources in RoboHelp, RoboHelp enables you to add that content in a specific folder. For example, for a FrameMaker book, RoboHelp creates a master folder at the book level and sub-folders each representing the Chapters in the book.
By enabling multiple TOC, Index and Glossary, RoboHelp allows to manage your content in a separate space. When you update the content in FrameMaker document, the TOC and Index for the linked FrameMaker books are automatically updated.
In RoboHelp 7, you can now add a TOC inside a TOC as a placeholder enabling a hierarchical structure for TOC. Similarly, you can now add an Index inside an Index as placeholder enabling a hierarchical structure for Indices. This is a really powerful functionality for single sourcing.
You can also include 3D models in a Knowledge base and Online Help. As part of Adobe Technical Communication Suite, you get Acrobat 3D and RoboHelp. Acrobat 3D enables you to capture 3D models from several CAD applications and convert the 3D model to a PDF. And you can include the PDF file containing the 3D model as a baggage file in RoboHelp. RoboHelp enables you to publish the PDF along with Online Help or a Knowledge Base.
Please notice the TOC entry in RoboHelp refers to the baggage file.
The FlashHelp output of this simple projects contains the PDF which can be accessed as part of a Knowledge Base and Online Help. Please click on the button to start the Adobe Captivate demo below.
With single sourcing workflow from FrameMaker to RoboHelp for HTML publishing and powerful content aggregation functionality available in RoboHelp, this opens up a whole new world of possibilities. Do explore more and share your experiences.
Though, I had mentioned in my previous post that I would be talking about Translation Workflows, but then I realized that I need to first talk about a new Single Sourcing feature that we have built in Adobe RoboHelp 7 - Multiple TOCs, Indexes and Glossaries.
Now using RoboHelp 7, you can define multiple TOCs, Indexes and Glossaries in a single project. But why would you want to have multiple TOCs in a single project? You can do that for different audiences of the same project - say Standard user and Advanced users or for different output types – say print and Web output or Help for two different flavors of a Project – Basic, Standard, and Professional or for supporting different languages say – English, French, German and Japanese. For achieving single souring in true sense, you need to have multiple TOCs, Indexes and Glossaries.
Since there can be multiple TOCs, Indexes and Glossaries in a single RoboHelp project, we need a mechanism to manage the same. And for this very reason, there is a change in the way TOCs are handled in RoboHelp 7. We have moved all the management to Project Manager. So in case you want to define a new TOC or edit an existing TOC or delete a TOC, you will have to go to the Project Manager and access Multiple Table of Contents folder. Indexes and Glossaries are also managed through Project Manager.
Apart from this, as you are already aware, Adobe RoboHelp 7 supports Multiple Document Interface (MDI), so it allows you to open up multiple TOCs and work across them – copy paste items from one TOC to another etc. This is how the multiple TOCs look like when you open them up in RoboHelp 7.
One important thing to note is that there is a default TOC in every project. The Default as the name signifies is the TOC used when you do not specify a TOC while generating a SSL. You have the ability to use any of the defined TOCs when you generate a SSL.
As you see in the above snapshot, most of the times there is a big overlap in the TOCs. As you see in the snapshot above, there are two TOCs – one for Customer Care executives and one for Mortgage Specialist executives. Since, the knowledge bases for the Mortgage Specialist executives is always a super set of the knowledge base for basic Customer Care executives (As depicted in the snapshot above), if you make a change in the Customer Care TOC, you will be forced to redo the changes in the Mortgage Specialist TOC. RoboHelp 7 provides a yet another Single Sourcing featuring called Place Holder TOC in the new TOC Editor. To achieve single sourcing what we can do is remove the first three folders in the Mortgage Specialist TOC (the ones that correspond to Customer Care TOC) and instead add a TOC Place Holder for Customer Care TOC as shown in the snapshot below.
Now when you generate a SSL using the Mortgage Specialist TOC, the Customer Care TOC Place Holder will get replaced by the actual contents of TOC at the time of generation. You can view TOC Place Holder as a kind of a reference to another TOC that will be picked at the time to final generation.
I hope I made some sense in the above explanation. We can also use TOC Place Holder for aggregating content defined across multiple TOCs. Let’s discuss how we can achieve the same. Suppose there are two authors working on the same Knowledge base – one is responsible for general Customer Care Knowledge base, however the other one is concerned just about the stuff that relates to Mortgage Specialist executives. The goal is t to generate a single master knowledge base which will contain all the topics defined in the RoboHelp project.
To achieve this, what we can do is, ask the first author to work on the Default TOC, i.e. Customer Care and ask the other author to define a new TOC, say Mortgage Specialist. However, this time we will ask him to just add the Mortgage Specialist related stuff to this TOC. Probably the TOC’s will look something like this:
Now for aggregating the two TOCs, you can either define a third TOC with two Place Holders (one for Customer Care and the other one for Mortgage Specialist) or you can add a Place Holder in Customer Care TOC that references to the Mortgage Specialist. The first approach is generally useful when you have a number of TOC Place Holders. So we shall follow the second approach in the demo below:
All the above examples are shown using the Customer Care Sample Project that we ship with Adobe RoboHelp 7. Index and Glossary have similar features and are implemented in the same fashion in Adobe RoboHelp 7. It’s now your turn to start playing with these Single Sourcing features and to see how best you can make use of the same in your real life projects.
I know I have exceeded the limit that an ideal blog post should be but it would be incomplete if I do not mention that RoboHelp 7 also allows you to add User Defined Variables in TOC entries and lets usage of Conditional Build Tags to TOC items (Books, topics etc). All these features put together result in most powerful Single Sourcing capabilities that no other HAT provides at this moment.
So to summarize:
Create as many multiple TOCs, Indexes and Glossaries as you like. They can be given unique names to help manage them.
Copy/Paste editing works across multiple TOC/Index/Glossary.
Aggregate multiple TOCs, Indexes using the Place Holder feature.
Use User Defined Variables while defining the TOC items.
Apply Conditional Build tags on TOC items.
At time of publishing, your custom TOC/Index/Glossary can be chosen on the fly.
Translation workflows are enhanced because you can have a separate TOC/Index/Glossary for each language.
RoboSource Control integration is enabled.
You guessed it correctly, we are now set to talk about Translation Workflows and I shall do that in my next post.
Adobe Technical Communication Suite enables a single sourcing workflow from FrameMaker to RoboHelp for HTML publishing. While it is ideal to maintain all the content in FrameMaker, there are special situations which may require the RoboHelp content to be out of sync from FrameMaker documents either for short duration or for small set of topics. These special situations can relate to project deadlines or project requirements which make the process of maintaining a single source difficult.
Adobe RoboHelp 7, as part of Adobe Technical Communication Suite, provides a new and really powerful functionality of managing this Out of Synchronization behavior. First, it provides a visual indicator the moment there is a change in RoboHelp content for a Linked FrameMaker document. Second, it allows you to select a set of topics which you want to preserve when the content is updated again. Since you can manage this at HTML topic level, you can control this at a granular level. Lastly, you can also delete topics and not regenerate these topics during the next update.
Here is a Captivate demo of this feature (Update - I am adding a "Click to Start" button on the demos - Thanks Rick for your suggestion). Do share your comments and suggestions with me.
In my previous post, I showed how a style can be edited in RoboHelp by editing the style sheet fmstyles.css. After you edit the style, the change is preserved on further updates in RoboHelp for changes in the linked FrameMaker book. In the attached Captivate demo (Update- I have added a "Click to Start" button to the demo), I show how you can create or edit a style in fmstyles.css, map it to a FrameMaker style (which was previously mapped to "Source") and update the content in RoboHelp.
Note - When you make the change in fmstyles.css or style mapping, always use "Force Update" to update the linked content.
