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.
Sounds great! I'm glad someone is actually taking the initiative to do it.
Yeah, those docs really need a lot of work, but I think part of the reason why they haven't been updated in so long is that they're "good enough" for 95% of people to figure out how to do the (relatively) simple things that 95% of people need to do (e.g. pass URL "directories" to a PHP script as GET arguments). Of course, the 5% who want to do something slightly out of the ordinary are usually left banging their heads in frustration before going to #apache.
Part of the reason for the bit-rot is the changing audience of the documentation. Back when mod_rewrite (and the Guide) was written, Apache configuration was pretty much limited to experienced techies. Today, more and more people are setting up personal web servers -- more and more people who aren't already familiar with server configuration and regular expressions, and who aren't used to reading the entirety of 20-screen man pages to figure out every last option. These people are smart and can follow an example, but don't have the inclination to read a huge document, nor the experience to figure out some of the things that are obvious/intuitive to technical folks.
So my suggestion for re-working the documentation would be to have two different sections: one aimed at the 95%, and one aimed at the 5%. The 95% section should be relatively short, and should be the first thing anybody would come to if they were looking for mod_rewrite documentation.
WTF? 1997? That late? :(