Ugly MadCap Flare errors

MadCap Flare is a pretty good application most of the time, but it does crash and it does, now and again, give you some very ugly errors. Programmers, it seems, always forget to capture internal error messages and add something that actually results in a useful error message being shown in the GUI.

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.