I've been using the microsoft.public.helpauthoring
newsgroup again over the past couple of weeks. It's an incredibly
useful resource, particularly the fact that it allows you to contact
experts like Rob Chandler and Pete Lees, who invariably provide the
answer you're looking for – usually within a day or so.

The trouble with this newsgroup is that you have to know about it.
It's not that easy to find. So here are some ways to get to it.

Using your browser

This is the way I usually read this newsgroup. Browse to:

http://communities.microsoft.com/newsgroups/default.asp?icp=web_publishing_all&slcid=us&newsgroup=microsoft.public.helpauthoring

This provides a nice interface to the newsgroup. The drawbacks with
this method are that you have to type in your name/email every time
you post a comment and you don't see any attachments that people
might post.

[Update: The above link no longer works. Microsoft changed the interface to this newsgroup shortly after I posted this. See posting of 19 May.]

Using a newsreader

My newsreader of choice is Thunderbird. To read microsoft.public.helpauthoring
in Thunderbird, set up a new account for the public news server msnews.microsoft.com.
Once the account is added, click Manage newsgroup subscriptions.
Search for helpauthoring and subscribe to microsoft.public.helpauthoring.

The drawback with this approach is that you don't get any message
threading, you just get a separate entry for each posting –
so it's difficult to read through a set of connected postings. Thunderbird
normally handles threading very nicely. I can only assume it's something
to do with the way msnews.microsoft.com serves up
it's newsgroup output.

However, not all newsreaders suffer from this problem ...

Using Outlook Express

I don't like to suggest you use Outlook Express, but it does
handle message threading for microsoft.public.helpauthoring.

Set it up in more or less the same way described above. Or –
if Outlook Express is your default newsreader – clicking the
following link will set it up for you:

news://msnews.microsoft.com/microsoft.public.helpauthoring

It's quite handy to drag this link to your Bookmarks/Favorites as
a quick way to get to the newsgroup.

Using RSS

You can use the following link to Google Groups to add an RSS feed
to your newsreader (e.g. Thunderbird) or to the Sage add-on for Firefox:

http://groups-beta.google.com/group/microsoft.public.helpauthoring/feed/msgs.xml

However, this also does not provide you with any threading.

Google Groups provides an alternative way to read postings in a
browser. Browse to:

http://groups-beta.google.com/group/microsoft.public.helpauthoring

However, I don't like the way this is set out and I don't find it
easy to use. Also, some replies seem to be missing. On the plus side,
using Google Groups to search the newsgroup does provide a very quick
way of finding information in old postings.

Following on from my previous posting, I've found a smarter way to test context-sensitive help topics, using a Windows batch file. This way involves only one batch file, rather than two (as described previously).

Put the following batch file in your help directory. In my case this directory contains various subdirectories, one for each help project. The one I'm currently working on is called imuser, so this is the default project directory in the batch file, and the help file within this subdirectory is imuser.chm, so again this is the default. Change the two lines near the top of the batch file to change these defaults.

Once in place, all you do is double click the batch file in Windows Explorer, or double-click a shortcut to this batch file on your desktop, or in your Favorites, and a console window opens prompting you for the path, file name and map ID you want to use. You can hit Enter twice if you want to accept the defaults, but you must enter a map ID.

The help file is opened using keyHH.exe, which is a free download from Keyworks Software.

The batch file:

Read the rest of this entry »

If, when you click a link in an HTML Help topic, you get an HTML Help Author Message dialog box, with the message

You need to specify two Item parameters for the Shortcut command.

it is probably because you are using a networked help file.

I have a topic containing the following link, which is meant to open a PDF in a separate browser window:

<object
    classid="clsid:ADB880A6-D8FF-11CF-9377-00AA003B7A11"
    id="OBJECT1" type="application/x-oleobject">
    <param name="Command" value="Shortcut">
    <param name="Text" value="Text:User’s Guide">
    <param name="Font" value="Verdana,8,0,,UNDERLINE">
    <param name="Item1" value=",userguide.pdf,">
</object>

This works fine if everything is on the local machine, but if I try to use it on a network server, it fails with the above message. The reason for this is a security fix in version 1.4 of the HTML Help viewer that prevents the viewer being used to open up files on a remote computer. This was a big security hole in previous versions of the viewer.

For more details, see:
http://helpware.net/htmlhelp/hh_info.htm#hh14

Macromedia chose not to attend the recent WritersUA Conference in Las Vegas. After the lay-off of the RoboHelp development team last year, this non-attendance confirmed the belief of many that Macromedia has decided not to develop RoboHelp any further. It will still be sold and supported - just not actively developed. This puts it in the same becalmed boat as FrameMaker - still afloat, just not going anywhere.

At the time of writing there's an interesting discussion about this on the Macromedia General Discussion forum:
www.macromedia.com/cfusion/webforums/forum/messageview.cfm?catid=447&threadid=979594&forumid=65

At first it seems odd that Macromedia should spend $65M on aquiring eHelp and then decide not to continue development on eHelp's flagship product. However, probably shouldn't be too surprising. The future of technical documentation is XML-based and many technical authors are looking for tools that will support the creation and maintenance of MAML-based documents. Whatever the eventual successor to FrameMaker and RoboHelp turns out to be (perhaps something from Madcap, perhaps something from ArborText, perhaps something Macromedia have up their sleeves) it will need to be built around MAML, and almost certainly (though perhaps as a by-product rather than a main aim) make DocBook authoring much simpler than it is right now.

I was back on the microsoft.public.helpauthoring newsgroup* yesterday, getting help with some HTML Help problems I was having. During the course of a couple of discussions, Pete Lees reminded me about Rick Stone's useful set of Tips and Tricks, which he has collected into an HTML Help project. You can download a zip file containing the .chm files at:

www.robowizard.com/RoboWizard/NewProject.htm#Downloads/Tips_and_Tricks.htm

There's a lot of good stuff in there, including the fact that you can dig around in the behind the scenes data of a RoboHelp project by opening the .mpj file in Access. I hadn't realised that this file is a database containing a set of tables - one for each of the different parts of a help project (Windows, Merge Files, etc.).

I found another useful tip on Rick Stone's website. It's a fairly obvious idea - but then those are sometimes the best ones. Imagine you want to include in your help system a link to a large user manual in PDF form. When the user clicks the link you want the PDF to open up in a new browser window. Nothing difficult here, but the problem is that on slow machines this can take a while. The user clicks the link and thinks it's broken because nothing happens straight away.

To prevent this confusion you need to display an intermediate page saying something like "Please wait. The User Guide will be displayed shortly." To do this, make the link go to a page containing this message, and in the head of this intermediate page but the following meta tag:

<meta http-equiv=refresh content="1;URL=LargeUserGuide.pdf">

This tells the browser to start loading the PDF after one second (you'll probably want to change this to 0). All being well the message will remain on the screen while the PDF loads. When it loads it will do so in the same browser window. The effect is that the user gets some immediate feedback.

You can do the same thing by pointing all such links to a single redirection page containing JavaScript that works out which page to redirect you to. The good thing about this is that you only need to maintain one redirection page. The JavaScript section contains details of all the destinations, and you tell the JavaScript where to redirect to by including a code word in the URL of the page, in the form of an anchor reference. For example, if the redirection page is called redirection.file, you might call it with the URL redirection.file#UserGuidePDF. The script has another URL mapped to the code UserGuidePDF. Here's an example of the redirection page:

View whole page

1:  <html>
2:  <head>
3:
4:  <title>Redirection page</title>
5:
6:  <!-- This file is used to get display a "please wait..." message
7:           while the browser loads another file.  -->
8:
9:  <script language ="Javascript">
10: <!--
11: var Code = window.location.hash.substring(1);
12: var URL= "" ;
13:
14: if (Code == "UserGuidePDF") URL="PDFs/UserGuide.pdf" ;
15: else if (Code == "AdminGuidePDF") URL="PDFs/UserGuide.pdf" ;
16: else if (Code == "WordDoc") URL="Don't%20use%20spaces%20in%20file%20names.doc" ;
17: else if (Code == "SpreadSheet") URL="spreadsheet.xls" ;
18:
19: if (Code == "")
20: window.location.replace("homepage.html");
21:
22: if (URL != "")
23: window.location.replace(URL);
24: else if (Code != "")
25: alert("Error in redirect.file\n\n" +
26: "No URL has been specified for the anchor: \"" + Code + "\"");
27: //-->
28: </script>
29:
30: </head>
31:
32: <body>         33: <p>Please wait. The page you requested will be displayed shortly.</p>
34: </body>
35:
36: </html>

One of three things happens when you load this page:

1) If you call it with one of the anchors it knows about (e.g. redirect.file#UserGuidePDF), it displays the "please wait" message.
2) If you call it with an anchor it doesn't recognise, it displays an alert box, with an appropriate error message.
3) If you call it with no anchor, it redirects you to a default page.

Thanks to Rob Chandler (The Helpware Group website: http://helpware.net/htmlhelp/how_to_merge_ctx2.htm) for details of how to do this type of redirection.

Notes:
1) This is intended for HTML Help, so it only works in IE. However, with a bit of tweaking you could get it to work in other browsers.

2) I've called this file redirection.file rather than redirection.html so that it doesn't get parsed for a full-text search in the help file. I don't want it showing up in the HTML Help Viewer's search results if the user searches for "wait".
3) Thanks to Jean-Claude Manoli for his wonderful online code formatter (www.manoli.net/csharpformat), which I used to produce the nicely coloured/formatted HTML code you see above.

-----
*You can get to the microsoft.public.helpauthoring newsgroup at:
http://communities.microsoft.com/newsgroups/default.asp?icp=web_publishing_all&slcid=us&newsgroup=microsoft.public.helpauthoring

-----