Madcap Flare has a pretty good built-in text editor for editing topic files in text-only format. I use this all the time. But sometimes it’s handy to be able to open a topic file in an external editor of your choice so that you can use the various features of that tool. My text editor of choice is Notepad++.

Until now, when I right-clicked a topic file in Flare’s Content Explorer and chose Open With, all I got, apart from the internal text editor and the internal browser, was a choice of either Firefox or Notepad (the simple Microsoft text editor):

I wanted to see Notepad++ in there. You might want to see Dreamweaver or something else. So here’s how to add programs to that menu.

Note: This procedure involves editing the Windows Registry. You need to treat the Registry with caution. Don’t go any further if you’re at all concerned about tweaking your Registry settings. You will also need to have an Administrator account. The following procedure worked for me today, using Windows 7. However, I provide no guarantees it will work for you.

1. First, check whether Windows knows where to find the executable file.

   To do this, enter run in the search box in the Start menu and press Enter.

   In the Run dialog box, enter the name of the executable file (e.g. notepad++.exe) and click OK.

   If the application starts it means Windows knows where this application lives. This reduces the number of steps in this procedure. If Windows does not find the application, but you know it’s installed, the process is a bit more complex and you should read ahead through the rest of the instructions before deciding whether you really want to proceed.

2. Start the Registry Editor.

   To do this, enter regedit in the search box in the Start menu and press Enter.

   If you have Windows UAC enabled (which you should have if you know what’s good for you), you’ll be asked to confirm that you want to allow the Registry Editor to make changes to your computer. Click Yes.

3. Expand the following sections of the Registry:

   HKEY_CLASSES_ROOT > .htm

4. Right-click the .htm folder and choose Export.

   Exporting a Registry key creates a file that you can double-click later, if things go wrong, to reinstate that part of the Registry.

5. Give the .reg file a suitable name (preferably something that tells you which part of the Registry it’s for and the date it was created) and save it somewhere appropriate.
6. Expand .htm > OpenWithList.
7. Right-click the OpenWithList folder and choose New > Key.  

   

8. Change the default name (New Key #1) to the next name of the executable file. In my case, for Notepad++ this was:

   notepad++.exe

9. Now do exactly the same thing for HKEY_CLASSES_ROOT > .html 

   Remember to export the key before you make any changes.

   If there is no OpenWithList key within .html just go ahead and add one.

10. If Windows found the application in step 1, you can close the Registry Editor, start Flare and check that there’s a new Open with option.

    

    Note: Changes to the Registry are applied immediately. There’s no File > Save menu item and you don’t need to apply your changes. However, you do need to close and restart Flare, if it was already running, before the application is displayed in the Open with submenu.

    If everything went okay, go back and archive or delete the .reg file you exported from the Windows Registry. It’s generally best not to leave .reg files lying around in case you accidentally run them at a later date and overwrite any Registry changes that were made since you created the export file.

11. If Windows doesn’t know where to find your application, you need to tell it. You do this with some more Registry tweaking.

    Warning: The following worked for me but I need to stress here: all messing around in the Windows Registry has a risk. I accept no responsibility for anything that might occur after you edit your Registry. Do not do this unless: you are confident you know what you’re doing in the Registry, you’ve exported any Registry keys before you make any changes, and you’re not going to hold me in any way responsible for any badness that happens after you’ve done this. You have been warned!

    So, having said that, imagine you have a program called qwoop that you want to use to edit Flare topic files. The path to the executable is D:\Alistairs Imaginary Software\Qwoop\qwoop.exe but entering just qwoop in the Run dialog box doesn’t start the application. 

12. Go to HKEY_CLASSES_ROOT > Applications
13. Within Applications, create the following hierarchy of keys (replacing qwoop with your own application’s name):

    qwoop.exe > shell > open > command 

    

    Of these, only command has any data.

14. Double-click the Default string entry in the command key and enter the path to the .exe file (in quotation marks if the path has spaces in it), followed by “%1” – this passes the name of the file you want to edit to the application for it to open.

    

15. Click OK.

    You should have something like this in the Registry Editor:

    

    Assuming you entered qwoop.exe as the name of the key within .htm > OpenWithList and .html > OpenWithList, in the first part of this procedure, Windows now knows what to do with this, because the new keys under Applications tell it where to find qwoop.exe.

16. Close the Registry Editor, start Flare and check that there’s a new Open with option.

    

A recurring problem with generating Microsoft HTML Help output is that, if you don’t have the correct DLLs registered, then you can encounter issues. A common issue is not getting any search results. You open the CHM file, click the Search tab, enter a word that you know is in the help file, but all you get back is:

Almost certainly the issue here is that itcc.dll is not registered. This must be registered on the PC on which the CHM file is compiled. After the CHM has been built, registering itcc.dll has no effect on the existing CHM – the Search tab still won’t work. You need to register itcc.dll and then rebuild the HTML Help output.

I’ve just run across this problem with Madcap Flare 6.1, but this is not a Flare problem. itcc.dll is Microsoft’s HTML Help Workshop, an old, old Microsoft DLL that Flare uses when compiling the CHM file. If this DLL wasn’t registered successfully by the Flare installer, or if it gets unregistered (which seems to happen now and again for no apparent reason), then you need to register it manually.

To register itcc.dll in Windows Vista or Windows 7:

1. In the search box at the bottom of the Windows start menu, type cmd.
2. In the result list, right-click cmd.exe and choose Run as administrator.

   Note: This is important. If you have Windows UAC enabled (you should!), then you won’t be able to register the DLL unless you do so as an administrator (even if you’re logged on as a user with administrator privileges).

3. In the command console window, type: regsvr32 itcc.dll and press Enter.

   A message is displayed confirming that the DLL was registered successfully.

   

4. Restart Flare and rebuild the CHM output.

Related post: Fixing Search in Flare HTML Help.

Rewritten post: Thanks to Janet Swisher for helping me avoid misleading folks with this.

In this post I describe how (with the help of jQuery’s $.ajax() function) to use the existence of a file on the server as a switch to determine behaviour in the browser.

Case study

In my case, the problem I had was that I use Madcap Flare to generate WebHelp output, and sometimes I want to build a customer version of the WebHelp and other times I want to build an internal version that has issue reporting functionality turned on. This adds little icons to the page that call some PHP for reporting, listing or searching for issues for the current page in the help system.

The issue reporting functionality is governed by a Javascript file, and I want to use a Flare condition to turn that functionality on or off. Flare can’t condition lines within a Javascript file to be included or not included in the output, but you can use Flare conditions to determine which files end up in the output. So I wanted a little bit of Javascript that said: if a particular file exists on the server turn on the issue reporting functionality, otherwise leave it turned off.

As with so many things Javascript, jQuery makes this easy.

Code

Here’s the jQuery code. Obviously you can replace the alert statements with something more useful.

$.ajax({
    url:'/somedirectory/onyourserver/filetofind.html', 
    type:'HEAD',
    error:
        function(){
            alert("ERROR: File not found. \n:-(");
        },
    success:
        function(){
            alert("Nice one! File found. \n8-)");
        }
});

Note: The file isn’t important. It’s purely being used as a switch. The file I use as the switch is actually the barest of bare-bones HTML files that is valid XHTML (which Flare demands). The type:'HEAD' statement in the code tells browsers just to request the HTTP response header for the file, not the contents of the file. However, as this is not supported on all browsers, you should only use this method if you know that the file being used as the switch is either empty of very small.

Try it out

To try this out, go to:
http://jsbin.com/avalo4/2/edit

Click Preview to see the output. You should see the “File found” message.

Click Code, change the file name in the Javascript and click Preview again and this time (assuming the file doesn’t exist on the jsbin.com Web site) you’ll get the error message.

If you’re checking in several files in Madcap Flare (e.g. File > Source Control > Project > Check In All) and you get the error:

The given key was not present in the dictionary.

Then try checking files in individually, or in smaller batches, from the Pending Check-Ins panel.

It worked for me!

The context menu for a span in Flare 5

Madcap Flare 6.1 has been out for a while now and, if you haven't already, you really should upgrade to it if you're a Flare user – and if you're a tech writer and you're not using Flare to produce online help then do yourself a favour and go and take a look at it.

Release 6.1 is confirmation that Flare is the best documentation creation tool out there. In particular, for me, this release is important because it allows you to use Subversion (SVN) from within Flare, which was broken in 6.0.

However ...

Isn't it annoying when a new release of a software application removes something that you'd got used to using in previous releases? In Flare 6.1 – for no discernable reason – you can no longer change the attributes of a span by clicking on the "span" marker. We use the Name attribute of a span with a certain class to create a link to our own home-grown glossary popups. This worked great in previous releases, as follows:

• Select a word or phrase
• Choose span.glossPop from the Styles list
• Click "span" > Name
• Add the appropriate glossary reference

In 6.1 you can't do this any more. Now, just to increase your click count, you have to get to the Manage Named Elements dialog box from the Format menu.

Okay, so there's a workaround. But why remove something that was useful and we'd got used to using? Is it a bug or is there some sort of rationale to this change? I'll raise a Support call and report back.

But in my view more clicks to achieve the same result is never a good thing.