General Ramblings comments edit

I’m generally irritated today and I don’t think it’s any one particular thing, so I can’t say what the root of it is, but I’ll gladly share some of the stuff pissing me off. Granted, more of a cathartic effort for me than a great entry for the readers.

There’s one week left for RSVPs to come back for the wedding and we’ve only gotten about half back. Yeah, folks have a week left, but I think it’s time to start chasing people down. There’s really no margin for folks to just be showing up without having replied. Which means I’m going to have to start getting email reminders out to folks with email and call the rest personally. I’m not sure what the difficulty is with sending a pre-addressed, pre-stamped postcard, but apparently it’s a showstopper for some folks.

I’m concerned that a good friend of mine is becoming a workaholic, possibly entirely out of boredom, as they have become fairly distant in recent times. Not to mention pretty conservative with information about what they’ve been up to. I’m not interested in the gory details of peoples’ lives, but when you get together to talk to someone and it’s a one-way information sharing street unless you ask just the right questions, it becomes a little stilted.

On that same note, I got an instant message from another friend who seems to know a hell of a lot more about what I’m doing than I know about what they’re doing. It’s been a while since I’ve gotten together with this friend, but somehow they are entirely up to speed on a lot of things - things I’ve not posted, emailed, IM’d or talked to them about. That’s a little disconcerting, and I’m not sure how I really feel about it. I’m glad to reconnect with this friend, but I think if my friend wants to know what’s up with me and Jenn… they should ask me and Jenn.

I’m super bored with the latest project at work which involves a hell of a lot of “review this stuff you’ve already done.” And I’m tired of people telling me when I mention how boring it is that, “you have to take the good with the bad” or “business needs require tasks that aren’t as fun sometimes” or whatever. I get it. I mean, I’m doing what needs to be done, right? That doesn’t make it fun, it only justifies the requirement. I’m not debating the requirement. I’m debating my motivational difficulties in completing the task.

Anyway, it’ll get done, I just have this vehement ennui.

Hey, that’s a good band name. “Vehement Ennui.”

Okay, done ranting. Time to get to work.

General Ramblings comments edit

CoconutI went to the store last night to pick up some unsweetened shredded coconut for use in a recipe I plan on trying out. Unfortunately, it looks like the market for unsweetened coconut is somewhere between nil and zero, so they have seven brands of sweetened coconut but not a single unsweetened bag to be seen.

This being the case, I crossed the store to the rarely-visited produce section and picked myself up a fresh coconut. The only way to get unsweetened coconut is to get it right from the source, right?

It’s three bucks for a coconut. Three American dollars! For one coconut! Somehow I think they’re getting me coming and going on that one. But what choice have I got? Three bucks later, I’m out the door and on the way home.

Fast-forward a bit and it’s Travis vs. The Coconut. The coconut, staring up at me from the counter with its three beady eyes, me staring back at it, not really sure how to proceed. I mean, I watch Survivor, I’ve seen folks open coconuts, but it usually involves a large rock and a machete, neither of which I have readily available. Plus, somehow I think that’s going to create a larger mess than I’m willing to clean up. As it stands, that sonofabitch is shedding its shell crap all over my counter.

It crossed my mind that “I know computer stuff, maybe Jenn knows how to open the coconut,” but I was disappointed in that effort - she didn’t really have an idea, either.

Good Housekeeping to the rescue. There are actually two pages on how to deal with coconuts in there. (It sort of reminds me of my mom’s [really] old Joy of Cooking cook book that explains how to prepare squirrel and other crazy shit.)

Here’s what you do: get a hammer and a screwdriver. Yeah, because you have those sitting in the kitchen. Okay, so take the screwdriver and pop two of the eyes of the coconut out. Take that, you stupid coconut! Drain the liquid out of the coconut because it’s freaking nasty and if you need coconut milk the stuff in the can at the store is better. Now bake the coconut at 350°F for 15 minutes. (I think the baking is to dry it out, but it wasn’t dry when I finished baking it.) Finally, take the coconut into the garage and beat the shit out of it with the hammer until you have reasonably sized coconut chunks.

Now comes the hard part. You have to use some sort of cutting utensil to get the coconut meat off of the shell. I found that it was easier to do this with some of the larger pieces of coconut because once you get a large section going, it all comes off in one big piece. Smaller bits are harder to get started. Once you’ve got the thing shelled, use a peeler to remove the hard brown outer skin on the coconut meat. (You would think that removing the shell is enough, but no, there’s like this “shell within a shell” bullshit so there’s still more shell to remove.)

That peeling is actually the hardest part because coconut meat is slippery so you can’t really get a good grip on it while you’re working. Again, larger pieces of coconut were easier to deal with here. Of course, you can’t escape unscathed, and I peeled my left middle finger just a little in the process.

That’s when I decided that if I were on a deserted island, I’d just starve. Cracking and shelling and fucking peeling and everything else really is just a hell of an effort to get a little bit of coconut. I think you’d be better off trying to catch fish with your bare hands or wrestle an alligator or something. They must have some sort of coconut shelling/peeling machine at the coconut factory. This is ridiculous.

The end result of all this is that we now have a shelled, peeled bunch of coconut we can run through the grater tonight and use in the recipe. Let me tell you, that coconut had better be the best damn addition to any recipe ever tasted by a human tongue. I’m gonna be so hella pissed if I just spent all that effort for some mediocre crap.

dotnet, process, build comments edit

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.

Holy crap.

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?

That’s awesome.

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.