Image tooltips in PDFs
PDF Settings in the Printed Documentation single source layout
One of the big advantages of the latest version of RoboHelp is its closer integration with other Adobe products. It was promised after their takeover of Macromedia and now it has been delivered. Of course with any new software version there are bound to be problems. One such problem appeared today on the Adobe RoboHelp Forums which had us scratching our collective heads.
The problem was thus. You have your project which includes images with tooltips which display a short piece of text for the user. All appears OK except that when you generate a PDF, a hover of the mouse over one of these images displays not the tooltip but the drive location of the original image. Weird! The good news is that the text displayed is “alternative text” which is harmless as a user can not gain access to your drive. At worst they would have an idea of your project’s folder structure. It is all a bit annoying though.
So thanks go to JoeO3443 and Rick Stone for doing some research and coming up with a solution to prevent these tool tips from occurring. RoboHelp has an option in the Printed Documentation single source layout called Enable Accessibility and Reflow with Tagged PDF. The option is available from the PDF Settings button in the single source layout properties. Ensure it is ticked and all your troubles will be resolved. See it’s easy once you know how!
The perils of Context Sensitive Help
RoboHelp Map File Dialog
I remember the first time I had to produce Context Sensitive Help. I inherited three help files produced by the MD, each with their own map and alias file. He had heard of the concept of context sensitive help but had little idea how to implement it. This is a common scenario for Technical Authors. So he went to the Lead Developer who did his research and cam up with the solution. It was implemented and it worked…..to a point.
Context Sensitive Help is one of those areas of a Technical Author’s job that causes a lot of confusion. It involves participation from both the Technical Author and the Developer and as we all know, communication in the corporate environment is fraught with danger; even for technical communicators. The map and alias files are produced by the Technical Author and passed to the Developer to code the API call from the application. This step is essential if you are to avoid confusion later on and incorrect help being called by the application. As such it is always beneficial to talk to the Developer even before you write the help to ensure that your requirements for the help file meet theirs. I have often come across scenarios where they don’t and the earliest you know about these the better.
One case I came across saw a change being made which introduced a series of new dialogs each of which had a Help button. The idea was that the user clicked on the button to see the context sensitive help topic. “No problem”, I thought until I spoke to the Developer. My initial thoughts were a separate topic for each dialog with a mapid for each. That mapid could be used by the Developer to call the relevant topic. Trouble was that each of the “new” dialogs were in fact the same dialog as far as the application code was concerned. They just employed some sort of variable in the code to rename the dialog and display different fields in it. This meant that the application could only use one mapid. Needless to say this meant a rethink about how we implemented the help solution.
The process of creating a map and alias file is not easy the first time. It requires a fair bit of thought and concentration but once you get your head around the logic it is straightforward. All the major help authoring tools have a tool/wizard to help you although not all of them are intuitive. As a RoboHelp user for many years, it’s context sensitive help dialog has problems. First of all, it is small and if you have long file names or topicids it can be difficult to use. Secondly it is not all that clear to a first time user what to do.
The steps in creating context sensitive help are:
- Create a topic id: A topic id is created inside a map file and has a map number assigned to it which is used by the application to call the help. Each Topic id takes the following form in the map file:
#define TOPICID xxxx
(where TOPICID is the name of the Topic Id and xxxx is the map number) - Assign the topic id to a topic: This creates the alias file and links the topic to the map number. This takes the following form in the alias file:
<alias name=”TOPICID” link=”topicname.htm”>
</alias>
(where TOPICID is the name of the Topic Id and topicname.htm is the file name of the topic)
As previously stated, the RoboHelp dialog is not all that intuitive. It is for this reason that I find it easier to manually edit the map and alias files. If you want to follow suit, backup the files, open them in notepad and edit away. Map files have a .h or .hh file extension and there can be one or more files per help file. Alias files have an .ali file extension but there is only one alias file per project. It is important therefore not to use the same map number between different map files. RoboHelp allows you the option of setting a prefix to a mapid (e.g. an abbreviation of map file name) to avoid this scenario and it is highly recommended you do so. First time users may find it better to use the HAT’s dialog but after awhile you will see the advantage of my approach.
RoboHelp ExtendScript Support
Imagine the scenario. You have a RoboHelp project developed in English. All is working well until one day your Sales team sells a contract to a Spanish customer and one of the conditions of sale is the help files have to be translated. You don’t have a Spanish speaker on site so you employ a translation agency. The trouble is the agency charges by the word so you have to work out how many words are in your project.
This type of query pops up occasionally on the RoboHelp forums and the only real answer was to ouptut to a Word file using the Printed Documentation single source layout and using Word’s inbuilt word count feature. This was a solution but one that required use of an additional application.
All of this has changed with the arrival of the latest RoboHelp version which includes ExtendScript Toolkit support. This allows you to write your own scripts using the toolkit to perform functions that extend the RoboHelp functionality outside the box in which it arrived. What is more, the toolkit includes seven scripts:
- EclipseHelp- Converts WebHelp output to EclipseHelp output.
- Link Converter – Converts an anchor link href target across all the files in a RoboHelp project (e.g. www.adobe.com to www.adobe.com/support/) across all the Help files in a project.
- SaveAsProjecTemplate- Saves a RoboHelp project as a template for creating similar RoboHelp projects.
- UDV Converter with UI – Converts a keyword into a user-defined variable and change its value across all files in a project. Enter a keyword, a user-defined variable name, and its value.
- UDV Converter - Converts a keyword into a user-defined variable and change its value across all the files in a project.
- Word Count – Gets a word count for an opened RoboHelp project. It provides a word count by topic and by project.
The King is dead. Long live the King.
Remember a few years ago when the good old RoboHelp people at Macromedia left pretty much en masse and started Madcap Software? The doom merchants were many and vocal. They waxed lyrical about the demise of RoboHelp as an effective help authoring solution as if overnight a good product became a bad one.
Since then Madcap have produced their own HAT called Flare. It was shamelessly marketed at former RoboHelp users with big fat financial inducements to get us to sign up. Many did, but a sizable number remained loyal to the recognized leader in its field. Rumours of RoboHelp being sunset did not originate from inside Adobe when they bought Macromedia and despite all the pessimism they began work on a new release.
RoboHelp 6 was a stepping stone to bigger and better things. It didn’t really set the world alight but it did make Adobe’s intention clear. It shouted from the roof tops that Adobe had a future for RoboHelp. It did not see FrameMaker as an alternative. In fact it thought other products in its suite would compliment each other. This was logical if you think about it as Adobe has PDF, FrameMaker, Captivate and RoboHelp all of which can be used to generate content.
The big leap forward in my opinion was RoboHelp 7 – not to be confused with the earlier RoboHelp version 7 which was released sometime in the previous millenniumwhen WinHelp was a huge step forward and DITA was unheard of. RoboHelp 7 saw a complete redesign of the interface and many new features, reusable snippets and user variables being two of the sexiest, as well as real signs that the product was being integrated with other Adobe applications like Captivate and FrameMaker. It also saw RoboScreenCapture, an old screen capture application from the e-Help days being fully integrated. I was a happy fella.
Then came the Technical Communication Suite 1 which gave you RoboHelp 7, Framemaker 8, Captivate 3 and Acrobat in one box. Everything you could possibly need to produce professional documentation. Rejoice and be glad!
Sales rose, but we wanted more. We told Adobe that whilst we really did like what we were seeing, there was so much more that could be achieved. Adobe staff attended conferences, they went on tours around world and listen to what us authors had to say. The result is RoboHelp 8 and the Technical Communication Suite 2. Believe you me this will make a huge difference to your workflow. Download a trial now.
