Document how PATH_INFO/SCRIPT_NAME rewriting works

lib/Plack/App/URLMap.pm

@@ -103,8 +103,9 @@ Plack::App::URLMap - Map multiple apps in different paths
 
 Plack::App::URLMap is a PSGI application that can dispatch multiple
 applications based on URL path and hostnames (a.k.a "virtual hosting")
-and takes care of rewriting C<SCRIPT_NAME> and C<PATH_INFO>. This
-module is inspired by Rack::URLMap.
+and takes care of rewriting C<SCRIPT_NAME> and C<PATH_INFO> (See
+L</"HOW THIS WORKS"> for details). This module is inspired by
+Rack::URLMap.
 
 =head1 METHODS
 
@@ -127,7 +128,8 @@ Mapping URL with host names is also possible, and in that case the URL
 mapping works like a virtual host.
 
 Mappings will nest.  If $app is already mapped to C</baz> it will
-match a request for C</foo/baz> but not C</foo>.
+match a request for C</foo/baz> but not C</foo>. See L</"HOW THIS
+WORKS"> for more details.
 
 =item mount
 
@@ -150,6 +152,34 @@ You can set the environment variable C<PLACK_URLMAP_DEBUG> to see how
 this application matches with the incoming request host names and
 paths.
 
+=head1 HOW THIS WORKS
+
+This application works by I<fixing> C>SCRIPT_NAME> and C<PATH_INFO>
+before dispatching the incoming request to the relocated
+applications.
+
+So if you have a Wiki application that takes C</index> and C</page/*>
+and makes a PSGI application C<$wiki_app> out of it, using one of
+supported web frameworks, you can put the whole application under
+C</wiki> by:
+
+  # MyWikiApp looks at PATH_INFO and handles /index and /page/*
+  my $wiki_app = sub { MyWikiApp->run(@_) };
+  
+  use Plack::App::URLMap;
+  my $app = Plack::App::URLMap->new;
+  $app->mount("/wiki" => $wiki_app);
+
+When a request comes in with C<PATH_INFO> set to C</wiki/page/foo>,
+the URLMap application C<$app> strips the C</wiki> part from
+C<PATH_INFO> and B<appends> that to C<SCRIPT_NAME>.
+
+That way, if the C<$app> is mounted under the root
+(i.e. C<SCRIPT_NAME> is C<"">) with standalone web servers like
+L<Starman>, C<SCRIPT_NAME> is now locally set to C</wiki> and
+C<PATH_INFO> is changed to C</page/foo> when C<$wiki_app> is being
+called.
+
 =head1 AUTHOR
 
 Tatsuhiko Miyagawa