From d36dc20475e4f0d98d7a4ea9bbd1343da49a45d9 Mon Sep 17 00:00:00 2001
From: Joe Wicentowski <joewiz@gmail.com>
Date: Sat, 18 Mar 2023 18:34:59 -0400
Subject: [PATCH] Improvements controller-config inline comments

---
 .../webapp/WEB-INF/controller-config.xml      | 43 ++++++++++---------
 1 file changed, 23 insertions(+), 20 deletions(-)

diff --git a/exist-jetty-config/src/main/resources/webapp/WEB-INF/controller-config.xml b/exist-jetty-config/src/main/resources/webapp/WEB-INF/controller-config.xml
index f9c55940160..4bb83a9f548 100644
--- a/exist-jetty-config/src/main/resources/webapp/WEB-INF/controller-config.xml
+++ b/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,7 +23,7 @@
   <!-- 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"/>
   -->
@@ -32,20 +31,22 @@
   <!-- 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>