From 42eb0a9e88a668c29aab75712c90003c2868518c Mon Sep 17 00:00:00 2001
From: Eli Barzilay <eli@barzilay.org>
Date: Tue, 8 Feb 2011 11:48:37 -0500
Subject: [PATCH] Improve the apache rewrite instructions.

Specifically, mention the `NE' flag and point at the apache "current"
version of the page.
---
 .../web-server/scribblings/server-faq.scrbl   | 39 ++++++++++++-------
 1 file changed, 25 insertions(+), 14 deletions(-)

diff --git a/collects/web-server/scribblings/server-faq.scrbl b/collects/web-server/scribblings/server-faq.scrbl
index 153e5b8cd5..0b71be07fa 100644
--- a/collects/web-server/scribblings/server-faq.scrbl
+++ b/collects/web-server/scribblings/server-faq.scrbl
@@ -6,37 +6,48 @@
 
 @section{How do I use Apache with the Racket Web Server?}
 
-You may want to put Apache in front of your Racket Web Server application. 
-Apache can rewrite and proxy requests for a private (or public) Racket Web Server:
+You may want to put Apache in front of your Racket Web Server
+application.  Apache can rewrite and proxy requests for a private (or
+public) Racket Web Server:
 
 @verbatim{
-RewriteRule ^(.*)$ http://localhost:8080/$1 [P]
+  RewriteEngine on
+  RewriteRule ^(.*)$ http://localhost:8080/$1 [P,NE]
 }
 
-The first argument to @exec{RewriteRule} is a match pattern. The second is how to rewrite the URL.
-The @exec{[P]} flag instructs Apache to proxy the request. If you do not include this, Apache will
-return an HTTP Redirect response and the client should make a second request.
+The first argument to @exec{RewriteRule} is a match pattern. The second
+is how to rewrite the URL.  The bracketed part contains flags that
+specify the type of rewrite, in this case the @litchar{P} flag instructs
+Apache to proxy the request.  (If you do not include this, Apache will
+return an HTTP Redirect response and the client will make a second
+request to @litchar{localhost:8080} which will not work on a different
+machine.)  In addition, the @litchar{NE} flag is needed to avoid
+escaping parts of the URL --- without it, a @litchar{;} is escaped as
+@litchar{%3B} which will break the proxied request.
 
-See Apache's documentation for more details on @link["http://httpd.apache.org/docs/2.0/mod/mod_rewrite.html#rewriterule"]{RewriteRule}.
+See Apache's documentation for more details on
+@link["http://httpd.apache.org/docs/current/mod/mod_rewrite.html#rewriterule"]{RewriteRule}.
 
 @section{Can the server create a PID file?}
 
-The server has no option for this, but you can add it very easily. There's two techniques.
+The server has no option for this, but you can add it very
+easily. There's two techniques.
 
 First, if you use a UNIX platform, in your shell startup script you can use
 @verbatim{
-echo $$ > PID
-exec run-web-server
+  echo $$ > PID
+  exec run-web-server
 }
 
-Using @exec{exec} will reuse the same process, and therefore, the PID file will be accurate.
+Using @exec{exec} will reuse the same process, and therefore, the PID
+file will be accurate.
 
 Second, if you want to make your own Racket start-up script, you can write:
 @(require (for-label mzlib/os))
 @racketblock[
-(require mzlib/os)
-(with-output-to-file _your-pid-file (lambda () (write (getpid))))
-(_start-server)
+  (require mzlib/os)
+  (with-output-to-file _your-pid-file (lambda () (write (getpid))))
+  (_start-server)
 ]
 
 @section[#:tag "faq:https"]{How do I set up the server to use HTTPS?}