Redirecting documentation | Notes In The Margin

I just spent an inordinately long time trying to get a simple documentation redirect working.

This was suggested to me by the recent discussion on PHP, where it was noted that http://php.net/foo takes you directly to the documentation on the function foo. Which is, of course, a really cool feature.

So, I decided that the Apache docs need that too. But while this would be really easy to do with, say, php, or perhaps a mod_perl handler, I wanted to do it with stuff that comes with Apache. mod_rewrite seemed like the obvious choice.

There are, however, a number of obstacles. mod_rewrite is, to put it nicely, documented in a user-hostile manner. Particularly in a beginner hostile manner.

I had already decided that I needed to use RewriteMap, because I have a large number of URLs that I want to redirect, and I want that list to be easily updateable. So, using a simple Perl script, I generated a starter map file from the XML documentation source:

#!/usr/bin/perl
use XML::Simple;

foreach my $file(@ARGV) {
    my $doc = XMLin($file);
    
    my $mod = $file;
    $mod =~ s/^.*mod_//;
    $mod =~ s/.xml$//;
    
    my $directives = $doc->{directivesynopsis};
    foreach my $d (keys(%$directives)) {
        next unless $d;
        print "$d http://httpd.apache.org/docs-2.0/mod/mod_$mod.html#$dn"
    }   
}

Running this script:

xml2rewritemap mod_rewrite.xml

generated a starter rewrite map. A single line of this file looks simply like:

RewriteMap http://httpd.apache.org/docs-2.0/mod/mod_rewrite.html#RewriteMap

So far, so good. If this works, it’s a simple matter to generate a map for the entire documentation tree, since it’s all in XML.

Then, in httpd.conf, I put the following:

RewriteEngine On
RewriteMap directive2url txt:/www/vhosts/drbacchus/fajita/scripts/rewritemap.txt

RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^/([^/]*)$ ${directive2url:$1} [NC,R]

So that creates the mapping function “directive2url”, pointing at the rewritemap file I generated. And then it runs that function on any URL which generated a 404. (Yes, that’s slightly over-simplifying.)

And it almost works. Going to http://fajita.drbacchus.com/RewriteMap *almost* redirects you to the desired location. Unfortunately, the # gets converted to a %23, which, in turn, generates a 404.

Well, after a bit of rooting around, it turns out that this exact problem is covered in the RewriteGuide (Look for “extended redirection”) and that it’s actually by design. Hrmph. Well, I may end up doing this without mod_rewrite. But it will be very disappointing. Perhaps I should agitate for a DoNotEscape flag for RewriteRule so that stuff like this isn’t such a pain.

Or maybe there already is one, and I’m just missing it because the mod_rewrite documentation is written for people who have already read the code. *sigh*.

The Margin Is Too Narrow