A little tip for users of Madcap Flare who find that things are getting very … very … very … s – l – o – w …

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. 

After several months away from Madcap Flare, coming back to work on it again, I’m reminded that one of the reasons I like this technical authoring tool is that it uses standard XHTML. So, if you’re using Flare to produce online help, you can modify your pages just like you could any Web page. So, for example, because I don’t like Flare’s default (text-only) glossary popups, I’ve replaced those with my own variety that allow text formatting and images, and can be dragged around the screen. And because I don’t have the budget for Madcap’s Feedback Server, I’ve hooked our help system up to a MySQL database, using AJAX and PHP, to give some of the same functionality. All good stuff and it’s great to have the freedom to do that kind of customisation.

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!

Don’t you just hate it when software tries to be helpful but just gets in the way?

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?”

Due to the lack of any response to my question on the Content Wrangler forum (http://thecontentwrangler.ning.com/forum/topics/how-can-i-deliver-serverbased – see also my previous post), I’ve been digging around trying to find out more about Madcap’s .NET Help. This isn’t easy as Madcap have not published much documentation for it (although there is an SDK that presumably tells developers what they need to know – but doesn’t help me, as a technical author).

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!”

Wondering what's changed in Flare? Madcap have published a 70-page guide to what's new:

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.