Current version

v1.10.4 (stable)

Navigation

Main page
Archived news
Downloads
Documentation
   Capture
   Compiling
   Processing
   Crashes
Features
Filters
Plugin SDK
Knowledge base
Contact info
 
Other projects
   Altirra

Archives

Blog Archive

Making help files

Want to know why programs aren't well documented? It's because writing documentation sucks, and people don't want to do it. And even when someone does, it doesn't necessarily mean they're good at it, or that they'll keep doing it.

I'm currently using Microsoft Compiled HTML Help as my help format for programs, and I like it. It's way better than the old Rich Text Format (RTF) method of WinHelp, from which I still have nightmares about strikethrough and double underlines, and that slightly scary uses-System-font hotspot editor. What I like most about HTML Help is that it uses HTML, but bundles everything into one file with compression, and puts a desktop-app interface on it, avoiding a messy set of loose HTML files or a crappy browser-based interface. The build process is also surprisingly easy, too: you just take a set of HTML pages and feed it to the compiler, along with project and TOC files. The compiler just takes all of the HTML pages and bundles them up.

For VirtualDub, I use a home-grown HTML template preprocessor that evolved from the one I use to generate my web site. It was born out of my frustration with XSLT, which at the time was just transitioning from draft to final, and wasn't very well documented or debuggable. At one point I tried porting my preprocessor to .NET/C# and real XML/XSLT, but got screwed by three issues:

Thus, I abandoned the idea at the time. For Altirra, though, I decided to try again as I'd learned enough about XSL to actually use it, and I'd hit upon a new idea. Previously, in order to preview the help file, I had to either (a) build the CHM file and load it in the HTML Help viewer, or (b) run the preprocessor and view it in a browser. Both of these workflows suck. The new idea was to use a processing instruction to invoke client-side XSLT in the web browser, and just preview the source .xml file that way. The processor would then just invoke a standalone XSLT engine to generate the intermediate files for the HTML compiler.

After trying this for a bit, I have to say that I really like it. I use CSS a lot more than templating now, so the lack of easy recursion isn't a problem anymore. I can preview the result a lot faster and I can debug the stylesheet in Visual Studio if necessary. (Nothing like adding a template and having all elements in the output vanish.) The main downside is that with XSLT I can't generate multiple pages and TOC entries off of a table like I could before, but that wasn't necessarily a good idea anyway (the interface XML doc files for the VirtualDub Plugin SDK are a big unwieldy mess). On the other hand, XSL has sorting and keying abilities that my preprocessor didn't have, and XPath is a lot more powerful than the simple paths I had before.

The one problem I had remaining after I had everything working apparently well, is that I had written the new preprocessor in C#, in order to use .NET's XML and XSLT engines. That wouldn't be so bad except that everything else I write in native C++, and I try to avoid having mixed solutions to avoid screwing over the Visual Studio Express editions. Even the help files themselves use C++ projects in order to invoke a makefile. What I ended up doing is hack-porting the C# code to C++/CLI so that everything could stay all-C++-projects. I feel a bit dirty, but the program's only a couple of hundred lines, and it works.

Comments

This blog was originally open for comments when this entry was first posted, but was later closed and then removed due to spam and after a migration away from the original blog software. Unfortunately, it would have been a lot of work to reformat the comments to republish them. The author thanks everyone who posted comments and added to the discussion.