¶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:
- Entities/DTDs. XML doesn't understand HTML entities, so you need to provide a DTD. If you just enable DTD support and use the validating reader though, the .NET Framework will happily go and download the XHTML DTD from the W3 every single time, without caching. This drove me nuts; not only is it slow and a bit rude, but I can't imagine why this would be desired behavior. I didn't know how to fix this at the time.
- Namespaces. My preprocessor uses elements in a namespace, but didn't actually declare one, so the XSL processor couldn't ever resolve the names, and I didn't know how to set up a resolver.
- Recursion. I had implemented templates such that they could auto-expand within the output of other templates, but stock XSLT doesn't allow this, because input and result node sets are distinct. You'd have to manually call the child templates, which is verbose.
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.