To go in the /rewrite section of the docs, as rewritemap.html, this will be referenced from the documentation for RewriteMap, and provide examples of the various ways to use it, replacing the somewhat confusing stuff that's there now with actual functional examples.

Sections will include:

For a description of the syntax, see Apache manual

Problem:

We want to map

www.example.com --> /home/www/htdocs/hosts/www/
   the hostname www may be omitted from now on
www.sub1.example.com --> /home/www/htdocs/hosts/sub1/
www.sub2.sub1.example.com --> /home/www/htdocs/hosts/sub1/sub2/
www.sub3.sub2.sub1.example.com --> /home/www/htdocs/hosts/sub1/sub2/sub3/
etc.

Recipe:

RewriteEngine on
RewriteMap sub prg:/physical/path/to/rwmap.pl
RewriteLock  /var/lock/map.sub.lock
RewriteCond %{HTTP_HOST} ^(www\.)?([a-z.-]+)\.example\.com
RewriteRule ^/(.*) /home/www/htdocs/hosts/${sub:%2}$1 [L]

rwmap.pl:

#!/usr/bin/perl

$| = 1;

while(<STDIN>)
{
chomp($_);
my @lables = split(/\./);
@lables = reverse @lables;
foreach my $label (@lables) {
	$path .= $label . "/";
	}
print $path . "\n";
}

Note: The trouble with this recipe is that it could be better done with mod_vhost_alias. It would be great if we could get a stock of RewriteMap examples that are actually the right way to do the thing being discussed.