Current version

v1.10.4 (stable)

Navigation

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

Search

Archives

01 Dec - 31 Dec 2013
01 Oct - 31 Oct 2013
01 Aug - 31 Aug 2013
01 May - 31 May 2013
01 Mar - 31 Mar 2013
01 Feb - 29 Feb 2013
01 Dec - 31 Dec 2012
01 Nov - 30 Nov 2012
01 Oct - 31 Oct 2012
01 Sep - 30 Sep 2012
01 Aug - 31 Aug 2012
01 June - 30 June 2012
01 May - 31 May 2012
01 Apr - 30 Apr 2012
01 Dec - 31 Dec 2011
01 Nov - 30 Nov 2011
01 Oct - 31 Oct 2011
01 Sep - 30 Sep 2011
01 Aug - 31 Aug 2011
01 Jul - 31 Jul 2011
01 June - 30 June 2011
01 May - 31 May 2011
01 Apr - 30 Apr 2011
01 Mar - 31 Mar 2011
01 Feb - 29 Feb 2011
01 Jan - 31 Jan 2011
01 Dec - 31 Dec 2010
01 Nov - 30 Nov 2010
01 Oct - 31 Oct 2010
01 Sep - 30 Sep 2010
01 Aug - 31 Aug 2010
01 Jul - 31 Jul 2010
01 June - 30 June 2010
01 May - 31 May 2010
01 Apr - 30 Apr 2010
01 Mar - 31 Mar 2010
01 Feb - 29 Feb 2010
01 Jan - 31 Jan 2010
01 Dec - 31 Dec 2009
01 Nov - 30 Nov 2009
01 Oct - 31 Oct 2009
01 Sep - 30 Sep 2009
01 Aug - 31 Aug 2009
01 Jul - 31 Jul 2009
01 June - 30 June 2009
01 May - 31 May 2009
01 Apr - 30 Apr 2009
01 Mar - 31 Mar 2009
01 Feb - 29 Feb 2009
01 Jan - 31 Jan 2009
01 Dec - 31 Dec 2008
01 Nov - 30 Nov 2008
01 Oct - 31 Oct 2008
01 Sep - 30 Sep 2008
01 Aug - 31 Aug 2008
01 Jul - 31 Jul 2008
01 June - 30 June 2008
01 May - 31 May 2008
01 Apr - 30 Apr 2008
01 Mar - 31 Mar 2008
01 Feb - 29 Feb 2008
01 Jan - 31 Jan 2008
01 Dec - 31 Dec 2007
01 Nov - 30 Nov 2007
01 Oct - 31 Oct 2007
01 Sep - 30 Sep 2007
01 Aug - 31 Aug 2007
01 Jul - 31 Jul 2007
01 June - 30 June 2007
01 May - 31 May 2007
01 Apr - 30 Apr 2007
01 Mar - 31 Mar 2007
01 Feb - 29 Feb 2007
01 Jan - 31 Jan 2007
01 Dec - 31 Dec 2006
01 Nov - 30 Nov 2006
01 Oct - 31 Oct 2006
01 Sep - 30 Sep 2006
01 Aug - 31 Aug 2006
01 Jul - 31 Jul 2006
01 June - 30 June 2006
01 May - 31 May 2006
01 Apr - 30 Apr 2006
01 Mar - 31 Mar 2006
01 Feb - 29 Feb 2006
01 Jan - 31 Jan 2006
01 Dec - 31 Dec 2005
01 Nov - 30 Nov 2005
01 Oct - 31 Oct 2005
01 Sep - 30 Sep 2005
01 Aug - 31 Aug 2005
01 Jul - 31 Jul 2005
01 June - 30 June 2005
01 May - 31 May 2005
01 Apr - 30 Apr 2005
01 Mar - 31 Mar 2005
01 Feb - 29 Feb 2005
01 Jan - 31 Jan 2005
01 Dec - 31 Dec 2004
01 Nov - 30 Nov 2004
01 Oct - 31 Oct 2004
01 Sep - 30 Sep 2004
01 Aug - 31 Aug 2004

Stuff

Powered by Pivot  
XML: RSS feed 
XML: Atom feed 

§ 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

Comments posted:


If you love documentation, come work in aerospace lol.

evropej - 25 10 10 - 06:07


"What I ended up doing is hack-porting the C# code to C++/CLI so that everything could stay all-C++-projects. "
Hopefully, you have used /clr:safe for this one.

Yuhong Bao - 28 10 10 - 03:55


Why? What does it matter?

Phaeron - 28 10 10 - 06:14

Comment form


Please keep comments on-topic for this entry. If you have unrelated comments about VirtualDub, the forum is a better place to post them.
Name:  
Remember personal info?

Email (Optional):
Your email address is only revealed to the blog owner and is not shown to the public.
URL (Optional):
Comment: /

An authentication dialog may appear when you click Post Comment. Simply type in "post" as the user and "now" as the password. I have had to do this to stop automated comment spam.



Small print: All html tags except <b> and <i> will be removed from your comment. You can make links by just typing the url or mail-address.