Something’s Fishy with the MySQL Documentation…
If you’re interested in looking at what goes into the MySQL documentation, there’s a new and kind of cool gizmo we’ve just installed that makes browsing the docs sources a breeze. Fisheye lets you browse by project, directory, author, date, and other criteria. It also provides an easy way to get to the complete changelogs, and even provides a customisable changelog RSS feed — for example, this feed has commits for just the NDB API documentation, and this is a feed of (all) my commits to the mysqldoc repository.
The display also features a graph showing how many lines are in a given directory, from which you can see that the MySQL Manual as a whole recently passed the 2-million-line mark. The NDB API docs were up to about 170K, then suddenly dropped off to about 50,000 lines in mid-July. What happened there? Well, that’s when I replaced the Umbrello XMI files containing the sources for all of the class diagrams with tar.gz archives. That’s because I got tired of generating a 250KB commit seemingly every time I changed the signature of one class method. (Now that the NDB API Guide is fairly stable, perhaps I should put the XMI files back?)
Not only is this stuff fun to look at, but I can see where it might be good for my workflow as well, starting with one of my very favourite tasks in the whole world — weekly reports. Until now, I’ve been using Thunderbird and filtering the documentation commit emails… Hmmmm… I wonder if I could just tell my boss to subscribe to the RSS feed now…? In any case, this looks like it could speed up and simplify the process considerably.
Hopefully, it’ll also be helpful to users looking for updates in the docs as well.
In a system that stores only diffs at commit, such as Subversion, switching from text to .gz archive could be significantly worse - wouldn’t text diffs be relatively small in the case you mention?
Hi Toby,
Not in this case. It has to do with how Umbrello works: a very minor change in a class diagram can cause it to rewrite a large portion of the XMI file, which can easily be several MB in size, thus leading to one of those 250KB commits I was grumbling about. Whereas the same file gzipped is only 20-30KB.
And I see that Umbrello now supports something I’ve long thought would be a great idea — working directly with gzipped XMI files. So it looks like the gzips will remain.
Although I’ve had to rename them all with a
.xmi.tgzextension because it doesn’t recognise.xmi.tar.gz. What’s up with that. I wonder?In any case, I hope this answers your question.