Interesting article about a couple of lesser known features of XML doc comments - multi-line comments and easier support for referencing generics.
I’ve finally taken some time and looked at Sandcastle, the new Microsoft alternative to API documentation rendering. Now that I’ve used it, I’ve decided that either Microsoft is jumping the gun on releasing this thing as any nature of “Community Technology Preview” or Microsoft just generally hates people who need to compile documentation.
“But why,” you might ask, “would you say something like that?”
You, the asker of such a question, have obviously not used Microsoft help compilers.
First Microsoft gave us HTML Help Workshop. If you haven’t used HTML Help Workshop, save yourself the trouble. It sucks. It’s the epitome of late 90’s UI design that basically gives you no indication of what to do or how to do it. RTFM, you loser. You are not smart enough to start up HTML Help Workshop and go.
But HTML Help Workshop is what we’ve got and that’s about where it stayed. It comes with the HTML Help Compiler, which basically crunches all of your HTML help documents into one file that can be distributed - a CHM file. The HTML Help Compiler is actually the important part of the workshop package and is generally the only piece that any normal human can take advantage of.
The problem then becomes figuring out what all the pieces are to get the compiler to run. You’ve got your project file, your index file, your table of contents file, your HTML files that actually contain the body of your help… it’s clunky.
Enter products like RoboHelp that make the process simpler for the standard documentation person. Docs get written, the clunkiness of the process gets abstracted away, and out the back end comes the CHM. Magic! The world forgets about HTML Help Workshop and uses products that work.
Fast forward a bit and along comes along .NET, with its fancy inline XML documentation comments. A stroke of genius, really - you can write your API doc along with the code it corresponds to and automatically create an XML document with that API documentation that can be transformed however you like.
For a very short period of time (relatively speaking), we were back to clunky, but before you know it, lickety-split, we have NDoc rescuing us. Not only that, but NDoc extends on the basic set of XML tags (sort of the way Netscape and IE “extended” HTML and ended up helping to shape the standard) to encompass common elements that get documented.
Anyone who is anyone uses NDoc. Seriously. We all use it, we all love it, it’s the de facto standard for generated API documentation. The really cool thing is that not only is it simple to use by itself, but it’s integrated into NAnt, so it can be automated in the build. It’s The Way and The Light.
So we’re in the Age of Not Clunky and chugging along great…
…until Microsoft trots up and chucks this… thing… out there called “Sandcastle” that they apparently use to render their own internal documentation. The community seems to want to latch onto this thing, but the truth of the matter is: it sucks. And you know why? We’re back to clunky. It’s just as difficult to use as HTML Help Workshop. Microsoft hasn’t made a single step forward on the path to easy help generation, they just keep throwing half-baked tools at it.
For the record, I’m using the August 2006 CTP of Sandcastle as the basis for my statements. I’ve got some test classes that I have for CR_Documentor that I use to see if CR_Documentor renders the preview the way NDoc does. Today I got the Sandcastle docs building for my test classes so I could get started on the Sandcastle renderer in CR_Documentor.
I mean, seriously.
First, it takes 12 steps to render a CHM out of Sandcastle, each step involving running a different command-line tool to transform this XML into that XML or compile this HTML into that CHM or whatever. In fact, the last line is a call to the HTML Help Compiler previously mentioned, so don’t forget to have that installed.
Okay, so that’s not horrible, and it can be automated, but one would think that the automation scripts would be part of the CTP. Unfortunately, not so much. The community has rallied and there are now upwards of ten different GUIs and scripts and tools to automate this thing, most of which will become obsolete when (if) we get something decent out of the Sandcastle team.
Let’s ignore the bajillion step process for a moment, though. Let’s instead look at the documentation they provided to help us get going and… what? What’s that you say? No documentation provided?
Okay, so bajillion-step-process and
distinct-lack-of-any-sort-of-formal-documentation aside, what’s really
eating me here is the lack of out-of-the-box support for tags we NDoc
users all sort of consider standard. For example, the
<see langword="null" /> sorts of things that are strewn throughout
documentation but are blatantly missing from Sandcastle.
I found a forum on this very issue and the recommendation from the Sandcastle team thus far is to modify the “main_sandcastle.xsl” file to add custom support for the tags.
Commonly used tags as a “custom extension” is a patently unacceptable solution. It’s sort of like someone saying, “Yeah, we just came out with this new VCR, but only tapes from Maxell will play in it. In some cases you’ll luck out, but in most cases you will probably have to do some extra work to fix the VCR so it’ll play the rest of your tapes.”
I’ve posted to the forum that I think they should support more
out-of-the-box tags rather than sticking to the small subset that appear
in the MSDN documentation. We’ll see what comes of it. Right now I can’t
even get all of the standard tags to render right. For example, good
luck getting a
<list /> to render (which is one of the tags they
actually list in the MSDN documentation as supported). I sure haven’t
succeeded. Sort of puts a damper on the CR_Documentor emulation since I
have no idea where they’re actually going to end up.
I guess I’m just irritated that such a big stir has been made over this thing and it’s not all that great. I can write a set of utilities to do something and make it super cumbersome and not support common stuff, too, but somehow I don’t think I’m going to get the level of community adoption we’re seeing here. It’s like they released an alpha level product and they maybe should have waited until it was at least beta before issuing a preview.
Maybe they should have a comprehensive list of what’s done and what they plan to do and let us all see that so we can go, “Oh, hey, they might not support such-and-such now, but they will soon” or, “They think this feature’s done, but it sure doesn’t work for me.” As it stands… it’s just frustration.
I really do wish them well on it, but I think for now, I’ll be sticking with NDoc.
I’ve been lamenting the fact that JHymn can’t deal with the latest iTunes DRM. So much so that I haven’t upgraded to iTunes 6 and have consequently been having odd crashes whenever I search the iTunes store. (Why remove the DRM? Because it locks me into only playing the songs I bought through iTunes - for example, the iPod support on Xbox 360 won’t let you play protected songs, and I think I should be able to play the stuff I bought wherever I want.)
Seems there’s potentially a new sheriff in town: myFairTunes6 v0.2b
Might have to get Stu to give this a go. (It’s his turn to be the guinea pig.)
The premise of the movie is that Nicolas Cage is a cop who witnesses a traumatic accident. While he’s taking some time off to get his head straight, he gets a letter from an old girlfriend (played by Kate Beahan) asking him to come to this isolated commune she lives on called Summersisle because she needs help finding her daughter. When he gets there, he finds that there are all nature of weird things going on and its up to him to figure out what the real story is.
I thought it was OK. I wasn’t blown away or anything, and I guessed the twist at the end with about half an hour to spare. I also had an issue with Beahan’s mouth the whole time - her lips are sort of weird (too large? misshapen?) and I had a difficult time concentrating on what she was saying when her mouth was moving. There was also this odd disconnect between the accident that Cage witnesses at the beginning of the movie and his arrival on the island. What relevance did that have? Was it just a mechanism to get him into convalescence so he would be receptive to getting the letter? A plot convenience? I’m still figuring that out.
That said, I’ve seen some pretty sucky movies lately, so I can’t really bag on this one too bad. I think it’d be a decent rental, but you might not want to pay full price for it at the theater.
Interesting item I didn’t know - it’s a remake of a 1973 movie. Kind of makes me want to see the original to see if it’s any better. It’s got almost double the ratings as the remake, so maybe it’s doubly good.