mod_rewrite is one of the most amazing modules that comes with the Apache web server. Written by Ralf Engelschall, and granted to the ASF in 1997, it allows for arbitrarily complex URL manipulation which are not possible with the other URL mapping modules.

Unfortunately, the documentation that came along with it has been almost entirely untouched since then. And, commonly held beliefs notwithstanding, bits do rot. The documentation contains examples that are incorrect, mostly due to changes in the abilities of the module, and of the web server itself. It contains examples that are irrelevant, such as the rules for mapping NCSA server-side imagemaps to mod_imap imagemaps. I suspect that most web users today have not heard of either one of those things, nor would they know why they’d want to convert one to the other.

Also, the once enormously useful Rewrite Guide, rather than being maintained and updated, has just been added to over the years, until it is impossible to find anything in it. And, once having found it, you’re never quite sure if it’s accurate, as evidenced by my struggles of a few days ago.

However, this is far more than just a rant. I’ve actually been working on this, and should have something to show for my work in the next day or two. I’ve rearranged a bunch of the documentation, splitting it into introductory material, recipe-type material, and advanced technical stuff that nobody will ever actually read. And then there’s the standard module reference manual, like every other manual has. We’ve been discussing doing this, on the docs mailing list, for at least 2 years, but nobody ever really wanted to actually start doing it. Because it’s a bit of a daunting task. But I’m hoping that my caffeine-induced initial attempts over the last couple nights will result in some folks working on small parts of it until it’s genuinely useful.

I started working on the Rewrite Cookbook a few months ago, but that never really got off the ground. I still like the idea, but it didn’t have enough starter material to really draw an editing audience. I’ll probably do some more on that once I’ve finishes this work. We’ll see. I also am not interested in the Rewrite Guide growing into a 100-entry monstrosity that’s impossible to use, so perhaps the Rewrite Cookbook will be a helpful supplement.