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.
SHARE
The Technical Writer’s “Killer App”
Everyone with an opinion talks about the “killer app” that if you didn’t have use of would cause untold stress and difficulty. The sort of application that prevents lots of sleepless nights and cold sweats by solving a difficult problem with an easy solution. In my days as a Psion PDA user it was the macro shareware that allowed you to mimic the Windows Start button to gain quick and easy access to the installed application, user folders and shortcuts and other macros you had created. It was all there with a single tap with the pen. Poetry in motion!
In the world of technical writing, the competition for that one killer application is close. Macro Express is right up there with its ability to (amongst other things) capture keystrokes and save them in a macro. So is DotColor for converting any on-screen color into a hex or RGB value. But for me, a find and replace tool just pips these to the title.
RoboHelp has a built in utility, available in the Tools pod, called Multi-File Find and Replace. This simple to use tool does a pretty good stab at the job in hand but has limitations. For a start it only searches .HTM and .TXT files. Additionally it works by searching the HTML, or XHTML/XML in the case of RoboHelp 8, and has difficulty with text strings spread across multiple lines. Anyone who has seen the HTML/XHTML/XML inside a file created in RoboHelp will soon realise just how big a problem this can be. For a really powerful tool, it is best to look elsewhere.
Two find and replace tools utilised by many Technical Writers are FAR, a shareware application written by Rob Chandler, and BK ReplacEm, a freeware utility developed by Bill Klein. Both fall into the category of “killer apps” with their ability to perform complicated searches (e.g. starting with, ending with, containing, not containing) across all file types. For me, FAR gets my vote as it can also be used as a help authoring tool and can be used to test and solve issues with projects created in RoboHelp. Only you can decide if it will work for you.
SHARE
Backwards compatibility of new RoboHelp versions
With any new software release the thorny issue of backwards compatibility comes to the fore. And why shouldn’t it. After all you’ve spent a lot of money on the new version and you want to ensure you get the best return on your investment.
With RoboHelp things are straightforward. From RoboHelp 7 onwards, a project created in a previous version can be easily converted to the new version. You can’t open a project created in RoboHelp 7 in an earlier version because of the rewritten HTML (or XHTML with RoboHelp 8). However despite the new code, projects work virtually seamlessly in the new version. In summary once you have upgraded a project from a previous version you cannot open the project in that version; only the new version. For this reason it is highly recommended that you take a copy of your project before upgrading.
With RoboHelp Server (formally called RoboEngine) things are similar, if a little more complicated. RoboHelp Server is the product that allows you to publish WebHelp Pro output (not to be confused with WebHelp output) to a server where the software resides. As a result, data is gathered of how users access the help, what they look for and all sorts of other useful stuff about your help files. With the additional expense of purchasing the RoboHelp Server license in addition to the RoboHelp license, ensuring you get what you need is paramount.
So what is acceptable?
- Help generated using RoboHelp 8 must use RoboHelp Server 8.
- Help generated using RoboHelp 7 can use either RoboHelp Server 7 or RoboHelp Server 8 provided you have the RoboHelp 7.0.3 patch installed.
What if you have WebHelp Pro output generated in a version before RoboHelp 7? The good news is that should you have RoboHelp Server 7, you can use it to publish WebHelp Pro output generated not only in RoboHelp 7 but also RoboHelp 6 and RoboHelp X5. If you have RoboHelp Server 8 you can publish WebHelp Pro output generated in RoboHelp 7 provided you have the 7.0.3 patch installed.
SHARE
WYSIWYG v HTML
The arrival of RoboHelp 7 saw the underlying code completely rewritten. Out went the dreaded KADOV tags and other messy looking HTML. RoboHelp 8 takes things one step further with the arrival of XTHML (Extensible Hypertext Markup Language) topic files and project files in XML.
What this all means is that the underlying code in RoboHelp is well written making it much easier to read and follow. The code also contains closed tags, no overlapping tags, properly quoted attributes with explicit values and no proprietary attributes.
But why does this matter. RoboHelp has a WYSIWYG and this is the default editor of choice for most documentation professionals. That’s true and that is what makes RoboHelp one of the quickest and easiest tools to learn. If you can use Word, you can create a topic in RoboHelp with little instruction. So if you only intend creating topics in RoboHelp with little interaction with outside products, then you will rarely, if ever, need to go over to the dark side.
But say you want to push the boundaries of what the WYSIWYG can do. Perhaps add a redirect topic or a simple piece of JavaScript to add a Print button. Maybe you are just curious of what is happening in your name under the hood. It is easy to find out. Recent versions offer the “HTML” tab on each topic whilst older versions used the optimistically named “Truecode” tab. Whatever your reason for wanting to get more adventurous, a whole new world of opportunity opens up.
This is a real bonus for those of us who have to look under the hood is that it increases productivity. It should also encourage those of you who don’t know HTML, XHTML or XML to look at it as it appears far less scary.
SHARE
The "My Documents" folder. The scourge of Technical Authors.
The My Documents folder prevalent in the Windows OS is a great idea. Its purpose is to be the default repository for storing all those files that you need on a regular basis. What is more, the OS automatically directs you by default to the folder from just about everywhere. Open up Windows Explorer or save a file in Microsoft Office and the default location is your My Documents folder.
So far that’s OK. Things started to get a little sticky when application developers decided it would be a good idea to create sub-directories inside your My Documents directory to house all the files you create using it. RoboHelp (from version 7), Paint Shop Pro, and FAR are just three applications I use frequently that by default insist on creating these folders. So, is this a problem?
Well, RoboHelp is well known in authoring circles to have issues when run over a network because of the MS Access database at the core of each project. In a corporate environment you are bound to have networks. Such networks are easily identifiable by their network drive. See a drive letter of W:\ or T:\ and you know what you are dealing with. But what about your My Documents folder. That’s local, right? Chances are you are wrong! It is common for Network Administrators to map your My Documents folder and your desktop to the network to enable you to logon at any networked PC and to access your data. Rick Stone describes this very well on one of his RoboWizard Monthly Scrys.
But networks are only one half of the problem. Occasionally the RoboHelp forums see posts where users have issues with compiling, generating output, or some other problem. There appears to be no logical reason for the error. That is until you look at the error thrown out. The file path for the project normally looks something like this:
C:\Documents and Settings\Username\My Documents\My RoboHelp Projects\Some Very Long RoboHelp Project Name\!SSL!\Printed Documentation\!chm_tmp_folder_0\A Very Long RoboHelp Project Name.hhp
Wow! Including the spaces that is nearly 190 characters. Best practice suggests the following:
- Keep directory names and filenames as short as possible whilst keeping them meaningful. This may be easier for people like me who remember the days when Windows 3.1 limited you to eight character file and folder names. Boy that made you think long and hard about naming conventions.
- With RoboHelp, or indeed any application that defaults to adding files to your My Documents folder, create a folder off your C: drive. I use a folder with the path C:\RHSource with subfolders for each of my projects. You can always copy the folder to the network later.
- Change the output folder of your Single Source Layout to a folder somewhere other than the default \!SSL!\Single Source Layout Name folder. For example create a folder called Output inside your project directory.
Follow these tips and you end up with something like the path below. A significant improvement and you won’t loose any sleep or hair as a result as the long path name issue will be a thing of the past.
C:\RHSource\Project Name\Output\!chm_tmp_folder_0\Project Name.hhp
SHARE
