¶Documentation sucks
If you ever wonder why so many programs come with nonexistent or lousy documentation, it's because programmers hate to write it, and that's because it takes forever to do so. I decided to start working on an updated help file for VirtualDub today, because the help file I'm currently shipping is quite old and incomplete, and the new capture system is basically undocumented. I started at around 2pm today, it's now 8pm, and I think I'm only about a third through the capture system documentation, to say nothing of processing mode. Bleah.
I also just noticed that I've been listening to nothing but Minami Kurabayashi songs for the past six hours, so maybe it's time to take a break.
Hint regarding VirtualDub's new help file: To display help, VirtualDub has to decompress the VirtualDub.vdhelp file and launch a web browser. This can fail for a variety of reasons, such as a read-only program directory. If you run into problems, you can read the help files by changing the file extension to .zip and extracting the double-layered archive.
The help files are processed through a utility I wrote called Lina, the source of which is in the VirtualDub source archive. It takes source files in psuedo-XML format and transforms them into the output HTML files. The design is somewhat similar to XSLT, with the primary differences being that the stylesheet is the data source, and that result trees are automatically reprocessed for templates. I played around with using XSLT 2.0 stylesheets with Saxon, but got stuck on the latter point — it is surprisingly non-intuitive and difficult in XSLT to get it to reprocess result trees and not have it strip out all container nodes. Lina also strips or compresses whitespace as appropriate, which also turned out to be annoying in XSLT.
I then looked into writing a new version of the preprocessor in C#, called Amelia, in the hope of being able to use cool XPath expressions. I immediately got lost in the maze that is System.Xml when I tried to get it to process HTML entities properly. Seems that to get entity processing you have to use XmlValidatingReader instead of XmlReader, and while passing it a DTD is the fastest way to get it to processing entities, it's a pain to get it to use one without having it download the stupid thing every time from w3.org. Then I tried to stick the DTDs in a resource, where I discovered (a) that the VS.NET 2003 managed resource editor is just the XML editor, and (b) the documentation tells you to compile one of the sample applications for an actual resource editor. At which point I just closed the Solution in disgust.
Many of you are probably wondering why I switched to the goofy double-zip format for help files. The reason is that I couldn't stand using Word and WinHelp anymore. Word itself is pretty aggravating — Microsoft still hasn't solved the backspace-screws-the-whole-paragraph problem — but to compile a WinHelp file you have to export RTF, and RTF transfer between Word and the help compiler isn't that reliable (What You See Is Maybe What You'll Get). Bulleted lists, in particular, tend to get messed up. Eventually I want to switch over to using HTML Help, but I don't have the process set up for that yet and I have a budget for how many things I can break each release.