The plan, (assuming I don’t get sidetracked on a million other things, which is what usually happens) is to do a major overhaul of the mod_rewrite documentation during the hackathon at ApacheCon. Please speak up if you have specific comments or recommendations. So far, the outline is something like this.
1) A couple of years ago, I split the “Rewrite Guide” into basic and advanced. This was ill-advised, and the division was stupid. Now it’s just harder to find stuff. Going to re-merge those, and then try to do a division based on topic, rather than difficulty, since that’s not a particularly useful concept.
2) Rewrite cookbook, divided into categories of, perhaps:
a. redirecting/remapping
b. controlling access
c. when not to use mod_rewrite (aka ‘mod_rewrite is obsolete’)
d. advanced features
3) Scrap the inscrutable examples. Both the guide and the formal docs are littered with examples that either never happen in the real world, or are done better using some of the built-in functionality of other modules like mod_alias and mod_dir. Scrap those examples entirely, rather than continuing to try to make then scrutable.
4) Rewrite Flags documentation. Started this years ago, and never really finished it. Also, needs to be updated to include the new flags that have been added in 2.2 and trunk.
5) General grammatical overhaul, hopefully with help from Noirin, who has better grammar than all the rest of us put together. (Actually, that’s the problem – it was written by all of the rest of us put together, resulting in a mish-mash of styles and voices.)
6) A document about (so-called) S.E.O. uses of mod_rewrite, discussing both the techniques that can be used, and the misinformation that tends to drive the desire to use those techniques. This needs to be handled carefully, because there’s a tendency to simply state that all SEO is snake oil – which much of it is – and ignore the topic entirely. But, folks are going to do this stuff whether or not we approve, and it’s better if they do it well. At least, that’s what I think at this particular moment.
2c, above, is both about stuff that you shouldn’t do with mod_rewrite at all, and also some of the new features in 2.2 and trunk that make mod_rewrite unnecessary.