ITauthor

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

In this interview, from Channel 9, April Reagan (a Program Manager at Microsoft) talks about the up-coming Microsoft Help 3. This client-side help system will be used first in the MSDN Library within Visual Studio 2010, but will be made available for other software companies to use.

Note: I found the first half of the video the most interesting. After that the interview moves onto other things and only returns to help towards the end. Unfortunately there’s not a whole lot of detail about how the new help system will differ from good old HTML Help. There’s no demo, for instance. Still it’s interesting that Microsoft are still investing in the idea of client-side help.

Note: This video belongs to Dan Fernandez and Channel 9.
If you're having problems viewing the above video, try the orignal video on Channel 9,
or view it in Windows Media Player.

I posted the following question on the Content Wrangler forum yesterday, but returning to it today I notice that most of the other posts to the forum get zero responses, so I’m going to repeat this appeal for ideas here, and I’ll try and think of other places I might pose the question.

I'm hoping for some advice on a way to provide server-based online help. The trouble is it can't be Web-based. Does anyone know of something out there that would solve this problem?

We've got a client/server software application that needs user assistance. It can't be traditional client-side HTML Help because this leaves help files on the PC, which not good for us because of the confidential nature of parts of the IT system. For a similar reason (plus some technical reasons) it can't be Web help.

What I'm looking for is a help viewer that will be launched from within a client application but which will fetch it's help topics from the same secure server used by other parts of the application. The help viewer can be located on the client side, but the help topics must be pulled down from the server.

I have had a look at Adobe AIR Help, but this seems to download files to the client and leave them there for use next time, which is no good for our purposes. I have also had a look at Madcap Flare's .NET Help, but I think this is also client-side, plus Madcap supplies very little information about .NET Help which worries me because I'd rather not migrate to a system/method that is poorly documented (unlike HTML Help or Webhelp output from Flare, which is well documented).

So I'm looking for ideas. Am I missing something obvious? Can anyone suggest a solution? Please post a comment below.

This is an old tip (see Viewing dynamic HTML in a .chm topic from March 2004) but worth knowing.

Suppose you have some JavaScript in a help topic that alters the HTML of the page - for example, it might do some transformations onLoad, or it might be doing AJAX-type stuff in response to input from the user). To debug the JavaScript you need to be able to check the HTML to make sure the transformations are occurring as designed. Right-clicking and choosing View Source is no good because you only see the original HTML saved in the file, before any transformations happened.

To see the dynamically generated HTML as it is right now:

1. Copy the following:
   
   javascript:window.open("").document.open("text/plain", "").write(document.documentElement.outerHTML);
2. Right-click the title bar of the HTML Help Viewer.
3. Choose Jump to URL.
   
   
4. In the Jump to URL dialog box, paste the text you copied in step 1.
   
    
   
   The HTML is displayed in a new Internet Explorer window.

If you have a large HTML Help system, it can take a few minutes to compile.

Say you make a change to a topic and you just want to check quickly that it'll work correctly within the compiled help. For example, the topic might reference a JavaScript file that only works in the context of the Help Viewer, so if you just open the topic in a browser the page doesn't look and/or behave like it does within the help system. So you need to check it in the help system, but you don't want to recompile the help system.

The solution is simple. Just open the existing .chm file, right-click the title bar and choose Jump to URL.

In the Jump to URL dialog box, enter the path to the file you want to test:
 

Click OK.

The topic is displayed in the Help Viewer just as if you compiled it in there.