If you're in the UK and you write create HTML Help (i.e. .chm files) you might have noticed that your Related Topics links display in a big clumsy dialog box instead of a neat little popup.

This is thanks to a stunning piece of incompetence on Microsoft’s part. They managed to break the hhctrl.ocx Active X file that controls the related topics popups. After about version 4.7 of this file, related topics always appear in a dialog box unless the language of your project is set to US English.

The workaround for RoboHelp is to open the .hhp file in a text editor (e.g. UltraEdit) and make sure the Language is set as follows in the [OPTIONS] section of the file:

Language=0x409 English (United States)

The chances are there won’t be a Language setting, in which case just add this. Save the file and, when you next compile the project, the related topics are displayed as popups.

If you've imported your RoboHelp project into Flare, go into Project > Project Settings and make sure the language is set to English (United States), then recompile the .chm file.

If you import an HTML Help project from RoboHelp into Flare you might find that when you compile the .chm file the Search doesn't work. Every time you do a search you get "No topic found".

The fix to the problem is described here. It involves running a batch file that registers a file called itcc.dll. This is Microsoft HTML Help Workshop and, for some reason, you're going to need it to compile the .chm file successfully. Fortunately your end users won't need this DLL, you just need it for creating the .chm file.

Madcap supply the DLL and a batch file to register it. It might seem odd to supply a batch file to register a DLL when it's such an easy thing to do using regsvr32. The reason is that, on Vista with UAC, you won't be able to register it. You can, of course, turn off UAC - but you don't want to do that. What you need to do is right-click the batch file, which will be somewhere such as:

C:\Program Files\MadCap Software\MadCap Flare\Flare.app\Resources\Bin\RegisterItcc.bat

then choose Run As Administrator.

I'd been looking forward to getting source control working in MadCap Flare. This came in as part of version 3 and allows you to do all your standard add/update/commit/remove operations directly within Flare, rather than using a third-party application like WinCVS, TortoiseCVS or TortoiseSVN. Or so they claim.

The truth about Flare version control is that it's been designed for Microsoft Visual Source Safe (VSS) and Microsoft Team Server and, in my experience (my painful experience, believe me!) not much effort has gone into making it work with CVS or Subversion. This is strange because a vast amount of source control around the planet is handled by CVS and Subversion. But maybe if you're a Microsoft house and your developers and in-house documentation team use Microsoft source control then you believe that any other source control is peripheral. I'd strongly argue against that viewpoint.

My source files are in CVS and Subversion. The older ones in CVS, the newer ones in Subversion. To use Subversion with Flare you need a DLL published by PushOK. I won't bother providing a link. I really don't want to drive any traffic their way.

The first sign of trouble with the PushOK software comes right after installing it. A program called the RWMonitor launches and begins to scan your hard disk. This goes on and on, with an animated GIF to make you think something's happening, until you notice the directories processed count has halted:
 
Note the spelling: "Directiores". This is the first clue that you are not dealing with quality software here.

The only way to get rid of this dialog is via Task Manager. I tried running RWMonitor several times. Once it got up to 27000 files, but each time it eventually hung and had to be killed brutally in Task Manager.

I've spent - hang on, make that wasted - most of my day on this, so don't expect a step-by-step guide because I'm sick of it. But here are some impressions.

1. Don't expect the Flare help to help you out much because it's wrong in several places. You've got to try to figure it out yourself.

I tried several approaches:

• Opening a project that's already in SVN and "binding" it within Flare.
• Importing a project that's already in SVN.
• Removing the project from SVN and then trying to add it back in again from within Flare.

All approaches failed. Much of the pain comes from a dialog box called Select SVNURL, module and local path:
 
Have a read of the message in this dialog box:

The clarity of this explanation perfectly matches the functionality of the software.

This dialog box is presented when you are asked for the project name. When you fill it in you have to provide your Subversion user name and password. Despite claiming that it will cache this authentication information, it demands that you enter the details again and again, and again.

Then it shows the following charming little dialog box. Well you can't really call it a dialog box. I haven't clipped this screenshot, this is the whole thing:
 
The Cancel button here is not functional and the image on the right is another animated GIF that pretends something useful is happening.

Occasionally you get to a Subversion Progress dialog box. This sits empty for a couple of minutes, making you think nothing is happening:
 
Eventually, if you're patient, some Subversion activity does show up, but for me this didn't signal success. Instead of checking in the whole project as one job, Flare (or maybe the plugin, but let's blame Flare because this should be integrated anyway) checked in one file at a time. The problem with this is that our Subversion system is set up to check that you have entered a bug tracking reference number for each job. From TortoiseSVN this means you can add one comment and bug reference for a whole stack of files. But within Flare you have to do this for each and every file. I tried holding down the Return key and entering blank comments, but progress was painfully slow and I gave up after the first 20 or so files.

All in all this is a big letdown because I was really looking forward to having source control integrated within Flare.

MadCap really should have written their own integration software as part of Flare. The PushOK software is appalling. It's like the worst freeware - except it's not free. Having bought Flare you have to pay extra to PushOK to get the plugin. Don't do it!

We're going to have to stick to what we've been doing: adding/updating/committing from within Windows Explorer, using TortoiseSVN (which is free and very well designed).

Publishing output from Madcap Flare using the inbuilt FTP functionality seems to be a little flaky. Sometimes it works, sometimes it doesn't.

When it does work it's very slow. I monitored the FTP activity on my server and noticed that for each copy task, Flare appears to be trying to create the directory in which the file lives. If the directory already exists, the FTP connection is terminated, at which point Flare has to connect again and then does a simple copy which works. But the very next task fails for the same reason. And so it goes on: connect, MKDIR attempt, fail, disconnect, connect, copy, MKDIR attempt, fail, disconnect, connect, copy, MKDIR attempt, fail, disconnect ...

The result is a painfully slow process: one file copied for every two connections.

However, if you get a connection this process does, eventually, succeed in copying over your output files. But much of the time, after a long wait, a successful connection and another long wait ... the process fails without copying anything. The error message is:

Problem(s) in background thread: The remote server returned an error: (55) File unavailable (e.g., file not found, no access). [System.Net.WebException]

The problem appears to be that the first file Flare tries to transfer is called something like publish_1BA597E8.txt (where the number changes every time). This file doesn't appear to exist, so I can't get past this hurdle. The log on the server side looks like this:

I should perhaps add that the distance between the desktop machine and the server is approximately a foot and a half, so you might think I could expect a nice, speedy, problem-free transfer. Using command-line FTP from the a Windows command console on the desktop machine I can connect and transfer files with ease.

Not good.

If you are upgrading Madcap Flare from version 3.0 to 3.1 you may come across the following problem. Flare will not let you install 3.1 alongside your 3.0 version.

So if you have 3.0 installed somewhere like:

D:\programs\MadCap Software\MadCap Flare V3

and during the install process you choose to install 3.1 in:

D:\programs\MadCap Software\MadCap Flare V3.1

You will sit through a fairly lengthy installation process, where a blue progress bar creeps forward gradually, taking frequent breaks - like a geriatric walking up a long hill - only to be presented with an error message right at the end saying:

Could not find a part of the path 'D:\programs\MadCap Software\MadCap Flare V3\Flare.app\B3.InstallFlareKit.InstallState'.

The only course of action is to click OK, at which point the old guy creeps back down the hill again.

The solution is that you have to install over the top of the existing 3.0 installation. So if Flare 3.0 is in:

D:\programs\MadCap Software\MadCap Flare V3

you must install 3.1 in:

D:\programs\MadCap Software\MadCap Flare V3