Output files and so(u)rcery
The difference between a RoboHelp project’s source and output files can be an area of much confusion. This is especially true where users are more used to WinHelp, compiled HTML (CHM) or compressed JavaHelp output. With these output types you have one or two output files to worry about. Web based output however, has many more. Whilst it may seem unnecessary to understand the difference between the output and source files, it is essential in certain instances.
Take the scenario where you are faced with making changes to a legacy project that you have no knowledge of. You have the output but you don’t have the source. It is a common misconception that to recreate a project you just need to import the output files and, hey presto, off you go. Nothing could be further from the truth. In such instances it is always best to explore all avenues to find the source files. Or how about the scenario where you have a WebHelp project that is published to a test area, but which needs to be copied to a company intranet of SharePoint site once testing is complete. You could just republish to another location or manually copy the files, but which files should be copied?
Web based output types (WebHelp, WebHelp Pro, FlashHelp or FlashHelp Pro) output a series of files in a folder structure that largely mirrors the project’s folder structure. However there are some anomalies. For a start you may notice some additional folders. These contain versions of the output uses in different circumstances. The “whdata” folder contains DHTML files used by some older browsers. The “whxdata” folder contains output used in Java applet and DHTML versions on newer browsers. The “whgdata” folder contains pure HTML.
There are also other files likely to unfamiliar to those who haven’t seen them before. These include files related to context sensitive help, framesets, skins, style sheets and all manner of JavaScript files required by various elements of the help. These files are too numerous to list here but are well documented in the RoboHelp help file.
Users with access to web based output files often find there is no .XPJ file with which to open the project. This is a sign that you haven’t got the source. Some even try creating a new project and import the .HTM files they find in the output. If you do this, you are asking for trouble as the .HTM output produced by RoboHelp contains additional code which when imported back into a project causes it to complain loudly. Try creating a new project and importing a few WebHelp output files to see what I mean.
Compiled HTML output, as the description implies, compiles a set of HTML source files into a single deliverable file (.CHM). The file contains all that is required to display and use the file content and as such is, to this day, a natural choice for applications being installed locally on a client PC. Creating a new help file from a CHM however is relatively straightforward. RoboHelp has its own tool called HTML Help Studio that decompiles a CHM file into its constituent parts allowing you to create a new project from them. Just create a directory, select a CHM and point it at the directory and before you know it you have everything you need to proceed.
Before Compiled HTML output there was WinHelp. This uses Microsoft Word as the editor to produce a series of .RTF files from which a .HLP and a .CNT file are generated. The .HLP file is the package for the help and contains the tri-pane view and the topic area. The .CNT file contains the Table of Contents data and must be shipped with the .HLP file and installed in the same directory for the Table of Contents to be displayed. This output type is no longer widely used and cannot be used on Windows Vista or Windows Server 2008 PCs without downloading and installing the WinHlp32.exe, as it is not part of these Windows installs.
JavaHelp comes in two formats; uncompressed and compressed. Uncompressed JavaHelp produced a series of files in a folder structure in a similar fashion to WebHelp or FlashHelp output. Compressed JavaHelp outputs a single .JAR file. This is a bit like a compressed WinZip file and can be displayed in a JavaHelp viewer. As it is a single file, it is the favored method of delivery.
Dislaying CHMs and that default tab
Have you ever double cliked on a CHM file in Windows Explorer, or opened the file from inside RoboHelp, expecting to see the default tab displayed only to find another tab in all its glory? If so, you have you’ve come across one of their idiosyncrasies of CHM files.
There is nothing that can be done to avoid this behavior. The first time you compile the help project, the file opens with the default tab displayed. But move to another tab and it will be displayed each and every time you open it. Even re-compiling the help has no effect. To get the default tab displayed you just have to click on it before you close the CHM.
The last used tab is stored in the user’s HH.DAT file and this has led to speculation that the file could be changed or a script written to override the data file’s content. Alas as any script would have to reside inside the topic, it only apply to the topic pane not the help file viewer as a whole.
The same does not apply to context sensitive help calls to a CHM from an application. If required, your developer should code the API to always open the file at the default tab. For example, if the Table of Contents is the default tab, the following syntax should be used:
HtmlHelp(
GetDesktopWindow(),
“c:\\MyHelpFile.chm::/topic.htm”,
HH_DISPLAY_TOC,
NULL) ;
CHM Files and Security Risks
With the advent of web based help formats, CHM files may not be a widely used as they used to. That said, there are still many that use them. Just search your hard drive and you’ll soon see more than a few. The trouble is that if the posts on the various authoring forums are anything to go by, they can cause problems for some.
Most of the problems are security related, especially after Microsoft Security Update 896358. This update identified that running a CHM file posed a security threat and as such could not be run on a network drive. This is covered in full on Peter Grainge’s website together with the workarounds you can use. Apart from only have CHMs on a local drive that is.
Similar problems can also occur where a CHM has been passed to a third party and installed on a local drive. Users complain that they are unable to see the topic content. Instead they get a message “Navigation to the webpage was cancelled”. This is also a security related issue but is easily solved.
- Right click on the file to display a popup menu.
- Click Properties to display the File Properties dialog.
- Click the Unblock button.
- Click OK.
The Unblock button is displayed if the file has been produced on another PC and is therefore flagged as a potential security risk. Clicking Unblock says you are happy that there is no security risk imposed by the file, therefore make sure you are happy with the content before doing so.
