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.

    

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.

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.

And, lo and behold, version control is now working again in release 6.1.

Thanks Madcap - much appreciated!

Flare has had built-in version control support for some time now - but only for Microsoft's Team Foundation Server and Visual Source Safe. If you use a non-Microsoft version control system you have to make other arrangements.

If you're a CVS or SVN user then, of course, you can just use something like TortoiseCVS or TortoiseSVN from within Windows Explorer. But in the past Madcap have pointed Flare/SVN users in the direction of the SVNSCC plugin produced by PushOK Software as a solution that allows you more or less the same functionality offered to TFS/VSS users, in terms of being able to work with a source control repository directly within Flare.

This worked OK in Flare 5. It wasn't brilliant, it was a little clunky, but it did work, and it provided real benefits. Specifically it made it easier for writers to update the repository and it made it less likely that you'd forget to get the latest version of a file before starting to work on it. Using the plugin has definitely resulted in fewer version conflicts to resolve.

Unfortunately, after installing Flare 6, try and get the latest version of files and you get this:

Unexpected exception: Access violation - KERNEL32.dll

After clicking OK, the Progress dialog box shows an error message like this:

Querying source control server. This could take several minutes.
: D:\Alistair\ITauthor\Flare-demo-project\itauthorflare\: CustomScc:GetLatestVersion - call failed with error code -15 (Nonspecific error.)

The source control operation finished with warnings and/or errors. Press Close when you are done reviewing the messages.

This is really disappointing for a number of reasons:

• I'd obviously prefer us to use the latest version of Flare rather than having to stick on version 5.
• Flare 6 has been out a few weeks now and the forum shows no positive response from Madcap or indication that they're going to fix this. Yes, I know the plugin is third-party software, but Madcap do not provide their own alternative and have, in the past, suggested SVN users use this plugin: I found out about it via Madcap.
• I had to push to get my purchase request for plugin licences signed off and right now that's looking like a bad decision. I don't want to use something else. I don't want to write off that purchase. I won't get another similar purchase signed off next time.
• I generally have a high regard for Madcap, but in this instance I feel they've let me down. Subversion is not some weird, new, little used system. If you have Microsoft blinkers on you might think that, but you'd be wrong. Subversion has been around since 2000, it's the successor to CVS and is used in software companies around the world.

For more tales of Flare/SVN woes go to: http://forums.madcapsoftware.com/search.php and search for pushok.

I've got a MadCap Flare project that I want to publish as open source code for anyone to go and download. It turns out this is extremely easy to do using Google Code. And Google Code has the benefit of allowing you to sync your work with the online source files using SVN (Subversion).

Multiple people can work on the project simultaneously and each time you open the Flare project the SVN plugin for Flare asks you if you want to use the most up-to-date files from the online repository. When you've finished making changes you just commit your changes, straight into Google Code, without having to leave Flare.

Here's how to create a project in Google Code and add a Flare project.

Prerequisites:

• For the initial upload of files into a Google Code project I'm using TortoiseSVN. You can download this from http://tortoisesvn.net/downloads. TortoiseSVN allows you to work with a Subversion repository from the right-click menu of Windows Explorer.
• You will sign into Google Code using a Google account, so you need one of these if you haven't got one already. If you use Gmail you've already got a Google account, so use that.
• You are going to commit files into a publicly viewable repository. Even if you delete a file from the repository, people will still be able to browse previous revisions of the project and view the file. Versioning repository systems like Subversion are designed to keep a historical record of everything that happened to the repository, so there's no easy way to remove all trace of a file that you didn't mean to upload.* So, before adding a project, make sure that you remove any files that you don't want other people to see.

To put a Flare project into Google Code:

1. Go to http://code.google.com/p/support/wiki/GettingStarted and read through the information about project hosting.

2. When you're ready, go to http://code.google.com/hosting/createProject, fill out the simple form and click Create.

   You will now have a Google Code project with one project member: you (or, to be more precise, your Google account).

   You are the project owner. To allow other people to commit changes to the project, you can add more project members from the Administer tab.

3. Click the Profile link (top right of the page).
4. Go to the Settings tab and copy your googlecode.com password.
5. Now go to Windows Explorer and browse to the directory that contains the Flare project you want to add.
6. Within the project directory select and cut the Analyzer and Output directories.

7. Paste the Analyzer and Output directories somewhere outside of the project directories.

   This is to avoid these directories being added to the repository.

8. Do the same to the Project/Reports and Project/Users directories, moving them out of the project for now.

9. Right-click your Flare project directory and choose TortoiseSVN > Import.
   

10. In the Import dialog box, enter the following as the URL of the repository:

    https://<PROJECT-NAME>.googlecode.com/svn/trunk
    

11. When prompted, enter your user name and password.

    These are the user name of your Google Code account (e.g. the bit before the @ symbol in your Gmail address) and the googlecode.com password you copied to the clipboard.

12. Click OK.

    This will now add all of the files/directories to the SVN trunk in Google Code.

    TortoiseSVN displays the progress.
    
    If you have a lot of files in the project this may take some time.

13. When the import finishes, click OK to close the dialog box.
14. Move the Analyzer, Output, Project/Reports and Project/Users directories back within the Flare project directory again.
15. Still in Windows Explorer, in the directory that contains your Flare project directory, right-click anywhere on the background to the main pane of Windows Explorer and choose SVN Checkout.

16. In the Checkout dialog box, enter the URL of the repository:

    https://<PROJECT-NAME>.googlecode.com/svn/trunk

    and the Windows path to the Flare project directory (that is, the directory you just imported into Google Code) as the checkout directory.
    

17. Click OK.

    The files you imported are checked out and marked as under version control.

    A little check mark on the file icon indicates that TortoiseSVN knows they are part of a Subversion repository.
     

18. In your browser, go to the Source tab of your Google Code project.

    For example, http://code.google.com/p/itauthorflare/source/browse/

19. Click trunk and you should see all of the files you uploaded.

    

You can now start Flare and open your project and (if you have the SVN plugin) you will be asked if you want to load the latest version of the files from the SVN repository.

* Note: If you forget about clearing out sensitive files and you discover you've uploaded something you really don't want anyone to see, then you can remove all the revisions within the project - in other words you can empty the project and return it back to its initial state before you imported any files. You do this by resetting the repository.

To do this, go to the Source tab in your Google Code project and click the reset this repository link near the bottom of the page. Be aware that this removes everything from the repository, so you should never do this for a project that has an active community working on it, or a project with any sort of a history because this history will be destroyed by resetting the repository. But if you've just started and then realised there's stuff in there that shouldn't be, then it's a way out of a fix.

Without seeing/hearing the screencasts it's not easy to form an opinion, so I thought I'd let you have a look. Let me know what you think. Are you put off by the ums and ahs, and the little mistakes I correct as I go along, or does it lend authenticity to the demo? Personally, I wouldn't mind seeing a demo like this as part of the user assistance for a product. I think the effects that Camtasia lets you add (zooming in and the rotating cube effect) lend a little polish to make up for the ad hoc presentation style. But it's probably not everybody's cup of tea. What do you think?
 

 
Please note:  When I recorded this it was purely meant for internal use within my company. However, I've had a look at it and I'm confident it doesn't give away any corporate IP. It does, however, reveal (if you look closely) that I had to Google to find a solution to a buzzing microphone shortly before starting the recording!  :-)

Alternative larger format video  (you'll need to wait a little while for it to download, but the picture quality is better).

In this example, all the new button does is change the h1 heading style, giving it an orange background, but you could have buttons to completely change the whole look and feel of your WebHelp – to give readers some variety – or you could add a button that darkens the window and display a lightbox-style popup containing a video of you juggling cats. You might have more useful applications for this functionality, but you get the picture: the functionality is there for you to use however you want. The trick is how you add a button and then how you make that button call a JavaScript function. After that the rest is down to your own JavaScript/jQuery skills. 

So, the following assumes that each topic page in your WebHelp calls a JavaScript file where you keep all the cool, dynamic stuff you want to do when a reader clicks around in your help files. For example, I have a JavaScript file called MyWebHelp.js that uses a lot of jQuery to do stuff, so the head element of each HTML page in my help projects contains the following:

<script type="text/javascript" src="Resources/JavaScript/jquery-1.3.2.min.js"></script>
<script type="text/javascript" src="Resources/JavaScript/MyWebHelp.js"></script>
        

To add a function button to the WebHelp toolbar
    

1. Create an image to serve as the toolbar button and save it as a .gif file.

   If you want the button to change on hover, or when clicked, then you can create 2 additional images for these states.

   These are the 3 images I used in this example:

        

2. In your JavaScript file add a function that you want to call when the toolbar button is clicked. For example, this function (using jQuery) adds an orange background to the h1 heading on the page (pretty useless, I know, but it illustrates the point):

   function makeHeadingOrange() { 
       $('h1').css('background-color','orange');
   }

3. From the Project Organizer in Flare, open the skin you want to modify.
4. Click the Styles tab.
5. Select Toolbar Item.
6. Right-click Toolbar Item and choose Add Class.
7. In the New Style dialog box, enter a name for your button class (for example, makeHeadingOrange).

   

8. Click OK.
9. Expand the Toolbar Item list and select your new class.
10. In the Basic properties for the class, click in the value column for Icon (this will currently be displaying “not set” as its value).
11. Click [Browse for image…] and find the button image you created.

    Notes:
    - When you specify an image it becomes part of the binary project data. The image file itself is not saved as a resource, like your screenshots, so you can only choose one of the existing images that have been absorbed into the project file, or incorporate a new image by browsing for it.
    - The images in this list are not sorted into alphabetical order. New images are simply added to the bottom of the list.

    

12. Choose images for the PressedIcon and HoverIcon properties (you can use the same image for all three states if you want).
13. Add a tooltip – for example, Make main heading orange.
14. In the Type properties for this class set ControlType to Button.
15. Set Onclick to the name of the function you want to call – in my example it’s makeHeadingOrange().

    

16. Click the WebHelp Toolbar tab.

    Your new button class is now shown in the Available list.

17. Move the button class into the Selected list and position as required using the up/down arrows.

    

18. In the section “Custom Javascript to include in Toolbar page”, click Edit.
19. Paste the following into the Toolbar JavaScript dialog box:

    function makeHeadingOrange() {
          parent.frames['body'].makeHeadingOrange();
    } 

    

    This creates a function called makeHeadingOrange which, when called, in turn calls another function called makeHeadingOrange. This second function is the one you added to your main JavaScript file in step 2 of this process. You could call them by different names if you wanted – but I think it’s clearer to call them the same thing. This second function is in a JavaScript file that’s referenced in your topic files and it isn’t directly accessible from the toolbar frame, so the first function (the one you added in Flare) is used to call it from within the context of the frame named “body”. The “body” frame in Flare WebHelp is the main frame within which the help topics are displayed. You could locate the code for the second JavaScript function within the topic HTML itself, but it’s going to be far easier if this function resides in a JavaScript file that you reference in the head of your topic pages.

    You can include as many custom Javascript functions as you want, listed one after the other in this dialog box. When the project is compiled, the text in this box becomes a file called Toolbar.js in the Data/<skin name>/ directory of your WebHelp output.

    So, if you want to, you can have lots of buttons, each calling a different function in your main JavaScript file (via the functions in the Toolbar.js file).

20. Click OK to close the Toolbar JavaScript dialog box.
21. Save your changes.
22. Build the WebHelp target output and test the results.

    Hovering over the button:
     

    Clicking the button:
     

Your problem may be that the Flare database for your project has got messed up in some way. The symptoms of this are that you can be typing in the editor but no characters are showing up, then, after you wait a few seconds they appear, so you go on typing, but then things slow up again.

Flare uses a Microsoft SQL Server database to keep track of the interconnections between topics. This helps prevent you screwing things up when you delete a topic – because Flare will ask you what you want to do about all the references to that topic and will convert all the hyperlinks to normal text, if that’s what you want to do.

To repair a messed up database:

1. Save your work.
2. Close the project and Flare.
3. In Windows Explorer, go to the Analyzer subdirectory for the project.

   

4. Delete the files in this directory.
5. Restart Flare and load the project.

   Flare will rebuild the database. This will take a few minutes, depending on the size of the project – during which time you’ll see lots of activity in Flare’s status bar – but once it’s done you should have a nice speedy Flare again.

The other things you can do to speed up Flare a little are:

• Disable phrase collecting (choose Tools > Options > Analyzer and remove the selection from the check box). This turns off the phrase suggestions that you see in the Intellisense popups (if you have that turned on). If you don’t use this, turn it off.
• Turn off Intellisense all together (choose Edit > Intellisense and remove the selection of Enable Intellisense). Personally, I found this feature annoying rather than useful, so I prefer to have it turned off anyway. 

And with formatting and styling it’s pretty much the same story. By using CSS, you have a high degree of control over the look and feel of your output. For example, I’m working on a WebHelp system right now and it’s been fairly straightforward to get most of the output looking more or less how I want it to look. The simple things like changing the background colours, the fonts, the icons, and so on are easily done from within the Flare application. And there are other things you can achieve by using Javascript to inject a CSS file dynamically on page load, if you want to override things in the Flare stylesheets that are injected into your output files at build time.

However, I’m painfully reminded, working with Flare again today, that one of the reasons I’m not 100% of a Flare fan is that Madcap fell short of making the styling of output 100% configurable via stylesheets.

Things like the Related Topics popups rely on Javascript, triggered by an onClick event, to add elements to the topic. This is perfectly standard, but whoever coded this decided in their wisdom to embed style information directly into those HTML elements, rather than giving everything a class name and controlling the styles from a stylesheet. In the hierarchical system that is CSS, nothing gets to overrule styles applied directly within the style attribute of an element in the HTML, so if the coder coded:

color="black"

then you you can have any colour you want, as long as it’s black – that is, you don’t get to modify the colour in your stylesheet to something more subtle, you’re stuck with the coder’s idea of what looks best for your output.

So my particular example today was that I was trying to beautify the Related Topics popup a little. Here’s what it looks like out of the box:

And I managed to modify most of it. But I just couldn’t get at that close button. It’s added directly by the Javascript. If it was in a Madcap CSS file – for example, as the background image on a div – then I could have overridden it with my own close button. But in the end I thought: sod it, if I can’t replace it I’ll just remove it. So here’s what I ended up with:

I know I’m biased, but I think it’s a big improvement. A little close button would have been nice, but I think most users know, or will quickly work out, that clicking away from the popup box makes it go away.

To style this up I used the following Javascript to add an override CSS file, which allows me to get at some of those hard-to-read Madcap styles:

$(document).ready(function(){
    ...
    //Append a link to the CSS file
    var newCSSlink=document.createElement('link');
    newCSSlink.setAttribute("href","Resources/StyleSheets/MCstylesOverrider.css");
    newCSSlink.setAttribute("rel","stylesheet");
    newCSSlink.setAttribute("type", "text/css");
    headElement = document.getElementsByTagName("head")[0];
    headElement.appendChild(newCSSlink);
    ...
});

This first line of the above code gives away that I’m using jQuery as an easy way to select and modify elements in the HTML. This just requires an extra Javascript file reference in the head of each page. If you use Javascript and you’re not familiar with jQuery, I’d strongly advise you have a look at it now!

Within my MCstylesOverrider.css file, the bit of CSS that removes the div containing the close button is:

div.MCKLinkBody div
{
    display: none;
}

Flare presents you with the old 80:20 rule. To get to a state where you’d be happy with the styling and behaviour of everything, you’d spend 20% of your time and effort getting 80% there, and then you’d spend the remaining 80% of the time finishing things off. For us pernickety perfectionists, Madcap could have made life a whole lot easier by making everything accessible and easy to change.

Message to software developers: when it comes to look and feel, less of the hard coding – please!

I’m currently working on tidying up a migration of RoboHelp into Flare. I’ve got to say immediately that Flare does an excellent job of migrating RoboHelp projects – but only if you’ve only used RoboHelp from within it’s GUI and never gone and tinkered with the HTML or added your own Javascript.

Huh! What are the chances of that?

Any help project from a few years ago that was built in RoboHelp will definitely and certainly have some tweaking and augmenting to it – or it will look like rubbish and be clunky and unsophisticated. Things might be different in the current version of RoboHelp, I don’t know, I don’t have it – but previous versions of RoboHelp had some serious shortcomings that forced you into a bit of roll-your-own behaviour just in order to get things looking and working the way you wanted.

The trouble is, once you do a migration into Flare, none of this is handled for you. I’m not complaining about that. The guys at Madcap have no way of knowing what extra goodness you layered on top of your plain old RoboHelp projects. And fortunately, most of the time, Flare just leaves any stuff you added by hand. That way you can do what I’ve been doing over the past few days: you can run some crafty regex search/replaces to go and convert those things into something that’ll work in Flare.

Unfortunately though, the philosophy of “if you don’t understand it, don’t touch it” hasn’t been extended to the TOC processing. The TOCs in the projects I’ve been migrating use anchor names at the end of topic file names, to pass a value to a redirect file, which then sends the browser off to display the appropriate page. Why would you want to do that then, I hear you ask. Well it’s a nice little Rob Chandler trick that allows you to decide which entry in the TOC gets highlighted where there are multiple TOC refs to the same topic. If you don’t use this method, the TOC will always jump to the first reference to the topic.

After some laborious debugging I’ve discovered that, at build time, Flare is taking my TOC file, seeing references such as redirect.file#sometopic and stripping off the anchor. So, within the generated .chm the reference is just redirect.file, which results in no redirection happening because the Javascript never finds out where to redirect to.

Flare does the same with query strings, like redirect.file?param=value. Annoying! Very annoying! It’s like when you were a kid and your mother tidied up your bedroom and chucked out your favourite comic. “Well it was lying on the floor. How was I to know it was important?”

So I’ve been having a dig around on Madcap’s forums and I came across a really interesting discussion (starting in November 2006 and, currently, ending in December last year). This centres around Madcap’s in-your-face branding of their .NET Help Viewer. It had the following problems:

• A big Madcap splash screen that was displayed every time you started up the help,
• Madcap branding on the title bar of the Viewer – rather than the name of the help project.
• Madcap branding in the Help menu called from within the Viewer.

There is much lively discussion in the string of messages. One contributor makes the point that there is no earthly point in Madcap promoting themselves in a Help system that is not going anywhere near anyone who would ever buy, or be remotely interested in, Flare or any other technical authoring application. Another contributor makes the point that I’m sure I would face: customers running a mission-critical IT system do not want to see a big, jokey splash screen suddenly appearing. It reeks of malware! Even the name “Madcap” would set teeth grinding if it appeared in the applications my company produces.

Finally, bowing to the weight and vehemence of the postings, Madcap gets around to providing a way of disabling the splash screen – but no word on configuring the title bar text and icon. As for the help menu, I think there’s a workaround.

One of the interesting things, reading through this, was the exasperation evident in the postings. People really, really wanted to use this product but were unable to because Madcap couldn’t go that extra mile (or 100 yards) for them. And the change from vitriol to delight and gratitude when Madcap staff contributed to the discussion with some positive news was quite touching, although it did seem a bit like: “Thank you for making it possible for us to use your product!”

http://madcapsoftware.com/assets/FlareWhatsNewGuide.pdf

If you just want a quick idea of what's new, here are some screenshots I've nicked off Madcap's (newly redesigned) Web site. Click to view full size:

Note: The copyright of these screenshots belongs to Madcap Software. I didn't ask their permission to use these, but I'm guessing they won't mind me disseminating their marketing material.

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.

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.

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).

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.

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

The trouble is that the application pack makes DITA possible, but it doesn't make it a realistic option for most folk because you still need to do a lot of work before you can actually get to the stage where you can hope to produce professional quality documentation with it. If you're like me you just don't have the time to dedicate to this. However, there are efforts to bring this to you and reduce the amount of setup work you need to do before you can start using DITA to produce documentation in FrameMaker.

One such effort  is DITA-FMx. I haven't  tried it out yet, but you can download it for free from here:    

http://www.leximation.com/dita-fmx/

Check out the  online help here:

http://docs.leximation.com/dita-fmx/0.01/  

It's probably worth a look, but I'm still kind of hanging on for Madcap to get their act together on DITA. Flare seems like an obvious tool to use with DITA, but it wasn't in the recently released DITA 3.0 and I haven't heard any firm plans for when it's going to get added. Adobe have stolen a march on Madcap here, but I suspect Madcap's DITA effort will be worth waiting for - so I'm holding back spending time doing DITA in FrameMaker until I see what Madcap come up with, or until I get fed up waiting.

"Object reference not set to an instance of an object."

There appears to be no solution to this problem as yet. See:

http://forums.madcapsoftware.com/viewtopic.php?t=1947&start=0&sid=91025ee508cf1c1cb4e32fc0d17b4628

This error happened to me just now. After restarting Flare I was able to complete the compile, but when I clicked to view the output Flare froze. I then went to the output in Windows Explorer and double-clicked the index.html file to have a look at the output in Firefox. At this point Explorer froze on an egg timer. Even after killing and restarting the explorer process in Task Manager, Explorer does not respond and doesn't let me into the Start menu.

I feel a reboot coming on!

The reboot didn't fix the problem. By working backwards I discovered it was a problem with invalid XHTML. One of my topic files had an extra </div> closing tag.

You'd imagine that a little bit of error trapping could have reported an error such as "Invalid XML in topicfile.html." Instead, the last topic in the compiler output had nothing to do with the problem.

My advice if you get this problem is to sort all topic by date modified and then go through, one by one, opening each of them in the XML editor. If one of them fails to open, open it instead in a text editor and track down what's wrong with the XHTML that's causing Flare problems.

Paragraphs should never be hyphenated unless they are justified. Hyphenating text that's aligned left looks daft. So the result is that you have to sort out this problem in the FrameMaker files produced by Flare before you can output to PDF. A tedious process, but here's the best way to do it. The same tip applies to any change you want to make to each and every format in a FrameMaker file:

1. Open the FrameMaker file.
2. Choose Format > Paragraph > Designer.
3. In the Paragraph Designer dialog box, click the Commands button.
4. Choose Set Window to As Is.
5. Now make the format change you want to make. In our case, click the Advanced tab and clear the Hyphenate check box.
6. Click the Commands button again.
7. This time choose Global Update Options.
8. In the Global Update Options dialog box, choose whether you want to apply changes from multiple tabs in the Paragraph Designer dialog box, or just the currently displayed tab. In our case, we've only made one change so it doesn't matter which of these options you choose.
9. In the Update Paragraph Formats section, choose All Paragraphs and Catalog Entries.
10. Click Update.
11. Save the document.

That's it. Hyphenation is removed from all formats in the document.

You can now use this document as a template for the other document. To do this:

1. In the book window, select all chapter documents.
2. Choose File > Import > Formats.
3. In the Import from Document field, choose the document you just modified.
4. Select all of the check boxes in the Import Formats dialog box.
5. Click Import.

"One or more previously generated files are open in Adobe Framemaker"

but FrameMaker isn't running, the problem is almost certainly that FrameMaker exited without cleaning up one or more of its lock files.

The solution is to go to the output directory and delete any files with the extension .lck.

Alternatively, just wipe the entire contents of your output directory and regenerate the output from Flare.

To workaround a lot of this madness I think I'm going to have to take the FrameMaker files, save them as MIF files (which are text versions of binary FrameMaker files), run a whole batch of search/replaces on these files and then pull the resulting MIF files back into FrameMaker and do the final tidy up, reformatting work prior to outputting to PDF.

All of this is extremely depressing when you consider that you should be able to go straight from Flare to FrameMaker, apply a template, and output to PDF, without ever having to do anything more than click a few buttons in Flare. I think that's what's known as a pipe dream. Come on MadCap! Make it happen! Or at least make it possible.

Anyhow, MIF seems to be the only way to do this, since the FrameMaker output from Flare isn't a structured document, meaning you can't process it with XSL in FrameMaker.

Here's some details on MIF:

http://www.stc-siliconvalley.org/newsletter/2002_1...

And here's a link to an evaluation download for Mif2Go - an application that allows you to output a whole bookful of files to MIF from within FrameMaker:

http://www.omsys.com/dcl/download.htm

After writing this post I realised that I was taking the wrong approach to outputting from Flare to FrameMaker. The reason the a elements were indistinguishable was because all of my topics contain the following references:

Case in point. I've been working on a WebHelp system and, now that I've got a decent amount of content in there, I decided to spend some time sorting out the printed output, which goes through FrameMaker.

Digression

This has been a very disappointing experience because MadCap have come up with a very weak solution to printed output via FrameMaker. What we've got is something that reeks of being thrown together in a rush and hasn't been thought out properly. Yes, you get your text coming through into FrameMaker in something that looks like it could be workable with some templating work. But when you start to work with it you realise that it creates paragraph formats for most, but not all styles within Flare. Here, there and everywhere styling is accomplished by using format exceptions. The result is that there is no easy, automatic way to adjust much of the styling. For example, if you have paragraphs within a list, Flare indents them, but this is done as an exception to the p format, so if you want to change the indent from the huge one you get from Flare ... well, let me know if you know how to do that easily.

Back to ugly errors

Anyway, after a couple of dreary days in which my illusion that Flare was a viable single-source solution have been shattered, I went back to WebHelp and now when I try to build the project I get:

Nice, very nice. Really helpful. Thanks MadCap.

Commence the debugging ...

Thanks to Subversion I was able to establish that the problem was due to a topic I'd recently edited. I'd changed a couple of style references, so who knows what Flare didn't like about it, but by I was able to identify the problem file as follows:

1) Back up my most recent version of the project.

2) Using the Subversion (a CVS-like versioning system) I reverted to the last good copy of the files from the SVN repository.

3) By putting back all the more recent non-HTML files from my backup of the project, I established that I could build the WebHelp OK, which meant the problem was with a topic file.

4) I copied back batches of files and building the WebHelp, gradually getting back to the most recently changed files until the project stopped building again.

5) I quickly pin-pointed one particular HTML file that caused the error shown above.