It’s a brand new blog(s)!

You may notice that something seems different around here. Today I migrated my blog from that crusty old Typo to the shiny new Mephisto! Most things are working well, but excuse the dust.

You might also notice that the Rubygame posts have vanished mysteriously! Well, in fact, they have been moved to…the new Rubygame blog!

I’ve been sitting on the domain name for a while now, but I was never sure what to do with it. But then I figured, “Hey, let’s put all the Rubygame news on that domain, and use for my other projects and personal stuff!” Evenutally, I’m also going to set up a copy of the documentation and downloads on, as well.

And it gets cooler: both blogs are running from the same Mephisto instance, using its multi-site feature! Pretty slick.

But wait, there’s more! Within the next day, everything will be using Mongrel, so it’ll load nice and fast.

Good news all around! … well, except for the old RSS and Rubygame post links not working.

P.S. I’ve tried to keep all the article URLs the same, with moderate success. Unfortunately, the old RSS feed link doesn’t work anymore. But that’s the way the cookie crumbles, I guess. Maybe I can set up a redirect to fix that. I’m also trying to get monthly archives listen in the sidebar, etc. etc. Also, the domain change for the Rubygame posts means that links to them at this domain will fail. Blech. I’ll see if I can set up redirects for that, too.

Update: I found a redirect solution on BlogFish. Hurray! Sorry for flooding your RSS readers, though.

P.P.S. You might be wondering what happened to my plans to use Radiant, since I was hacking on the Radiant-Comments extension earlier this week. Radiant is a really cool platform, but the extensions just aren’t solid enough for me to set up a proper blog without a lot of work. Maybe some day, I’ll switch this blog over to Radiant (and break the RSS feed again ;-) ) but in the meantime I needed a working setup, and Mephisto provided that with a minimum of fuss.

Testing the Git Waters

Apparently, Git is the new hotness, and Github is liquid hotness concentrate, with pulp. Or, so I hear. Rails monkeys seem to like it, anyway. ;)

You can blame Piotr for bringing it to my attention, and then radiant-comments for giving me an excuse to dip my foot in.

I did some browsing online, and it seemed pretty neat (yay for branching), but I wasn’t quite grokking the process. Luckily, I had some old PeepCode credits lying around, so I took a look at their Git tutorial screencast. The three main things I got out of the screencast were:

  1. Learned about the ‘tree’ utility for *nix. (Huh, never knew about that one before! Handy.)
  2. Got a better handle on how you do stuff with Git. Branching, fetching, rolling over and playing dead, etc. (Arf arf.)
  3. Learned that you can work on Subversion repositories using Git!

For now, I’m just getting my feet wet by hacking on the comments extension for Radiant CMS. Once I get the hang of it, I might try using git-svn to work on Rubygame in its Subversion repo. And maybe, just maybe, if that works out well, I’ll consider migrating Rubygame’s repo to Git / Github. Maybe.

By the way, did you know that Rubygame has almost 1000 commits in its Subversion repository, dating back to December 4, 2004? (Hrmm, 1000 commits sounds more impressive when it’s not spread out over 3½ years. How does 325 commits since Rubygame 2.2.0, December 19, 2007, sound? Sounds like progress to me.)

Anyway, it’s at revision 995 right now. I’ll probably do some sort of commemorative post when I commit #1000. Y’know, because I’m all sentimental, and stuff.

RDoc C parser needs improvement

I don’t think I’ve mentioned here how frustrating RDoc’s C parser can be. It’s almost up there with SDL_mixer on the headache-o-meter, I swear.

I’ll admit, the idea of automatically generating documentation from the code structure and comments in the source code is neat. And RDoc does a pretty good job of figuring out the structure of Ruby code. It’s pretty smart at that, and it can figure out which class is located under which module, and which class in the parent of which subclass, and which mixin is included in which class, etc.

But it’s not so great at figuring that stuff out in the code for extensions written in C, like Rubygame.

Partly that’s because it’s a harder task to tease the meaning out of the C code. It’s also partly because the C parser doesn’t have as many users (and thus fewer eyes for looking, and fewer hands for patching).

Whatever the reason, the C parser is a lot less polished than its Ruby-parsing counterpart. It’s able to handle simple things decently: defining a module, defining a class, defining methods under that class, etc. But for more complex scenarios, it fails.

And it’s fine that it can’t figure out complicated stuff on its own. It wouldn’t be reasonable to expect RDoc to handle every strange scenario perfectly. The problem I have is that there’s very little you can do to help RDoc generate the correct documentation, except trying to avoid situations that it doesn’t understand. (Designing code around the deficiencies of the documentation program? It’s insane, but I have to admit I’ve done it in several places in Rubygame in the past.)

What I’d really like to do, is give meaningful hints to RDoc, to help it understand what’s going on. For example, consider this C code, which I’ve recently written in the Surface class to make it include the NamedResource mixin:

rb_include_module( cSurface,
  rb_const_get(mRubygame, rb_intern("NamedResource")) );

RDoc’s parser will not have a clue what’s going on here, and that’s understandable. But if there was a way to tell RDoc, “Hey, the Surface class includes Rubygame::NamedResource”, it wouldn’t need to figure out what the code means. I’d have more control over the documentation that’s generated, and the output would be more meaningful and useful to the reader. Everybody would be shiny and happy.

Unfortunately, I don’t think I have the time to learn RDoc’s inner workings well enough to patch it to do such a thing. (Heck, I don’t even have as much time to dedicate to Rubygame as I’d like.)

So my options right now are:

  1. Jump through some hoops and pretend to define the NamedResource module again in a place that RDoc will remember it in this scope.
  2. Write the module inclusion code in Ruby (and thus split my class definition across two files in two different languages).
  3. Write a dummy sourcefile in Ruby with the documentation (this is what Chipmunk does).
  4. Just put a note in the class documentation for Surface, mentioning that it includes the module.

I started using #1 years ago to make RDoc to correctly place all the classes inside the Rubygame module. But since it’s not as important that RDoc know about the relationship between Surface and NamedResource, I’ll probably end up using #4.

Besides the deficiencies in the C parser, there are some other things about RDoc (and automated documentation extraction in general) which displease me, but I’ve already wasted enough time ranting for one day. ;)