Merge pull request #4807 from joewiz/controller-config-docs

Improve controller-config inline comments

exist-jetty-config/src/main/resources/webapp/WEB-INF/controller-config.xml

@@ -1,10 +1,9 @@
-
 <!--
   ++ Base configuration for eXist's URL rewriting. This file defines
   ++ all basic path mappings. A path can be mapped to a servlet or
   ++ the root of a directory or collection hierarchy.
-  
-  $Id$
+  ++
+  ++ The order of elements within this configuration file is significant.
 -->
 <configuration xmlns="http://exist.sourceforge.net/NS/exist" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://exist.sourceforge.net/NS/exist file:../../schema/controller-config.xsd">
@@ -24,28 +23,30 @@
   <!-- RESTXQ -->
   <forward pattern="/restxq/" servlet="RestXqServlet"/>
 
-  <!-- scale images on the fly and cache the output. -->
+  <!-- Scale images on the fly and cache the output. -->
   <!-- 
   <forward pattern="/images" servlet="ScaleImageJAI"/>
   -->
 
   <!-- The JMX status servlet used to monitor the db -->
   <forward pattern="/status" servlet="JMXServlet"/>
 
-  <!-- 
-    ++ Default configuration: main web application is served from the
-    ++ webapp directory. 
-  -->
+  <!-- HTTP requests to /apps are mapped onto the database path /db/apps -->
   <root pattern="/apps" path="xmldb:exist:///db/apps"/>
 
+  <!--
+    ++ The default fallback web application is served from the
+    ++ /etc/webapp directory on the filesystem. 
+  -->
+
+  <root pattern=".*" path="/"/>
+
   <!-- 
     ++ To redirect requests based on the server name (i.e. www.example.com)
-  	++ to a specific collection within the database, comment out the following
+  	++ to a specific collection within the database, comment out the previous
   	++ root line and uncomment the block below with the server-name
   	++ attribute.
     -->
-  <root pattern=".*" path="/"/>
-
 
   <!-- 
     <root server-name="site1.example.com" pattern="/*" path="xmldb:exist:///db/org/site1/"/>
@@ -56,18 +57,20 @@
     -->
 
   <!-- 
-      ++ The following configuration assumes that the main webapp
-      ++ is stored in the database. However, the contents of the /webapp directory
-      ++ should still be accessible with a /fs prefix in the path.
+      ++ The following alternative configuration assumes that the main webapp
+      ++ is stored in the database. However, the contents of the /etc/webapp directory
+      ++ will still be accessible with a /fs prefix in the path.
+  -->
+  <!--
+    <root pattern="/fs" path="/"/>
+    <root pattern=".*" path="xmldb:exist:///db/www"/>
   -->
-  <!--root pattern="/fs" path="/"/>
-    <root pattern=".*" path="xmldb:exist:///db/www"/-->
 
   <!--
-      ++ Order is important here: the forward rule for XQuery resources has 
-      ++ to be last in this document, otherwise all XQuery files would be immediately 
-      ++ forwarded to the XQueryServlet without ever going through any of the
-      ++ controllers.
+      ++ Order is important. The following forward rule for XQuery resources has 
+      ++ to be last in this document. Otherwise, all XQuery files would be immediately 
+      ++ forwarded to the XQueryServlet without ever going through controllers.
   -->
   <forward pattern=".*\.(xq|xql|xqy|xquery)$" servlet="XQueryServlet"/>
+
 </configuration>