Merge pull request #1212 from WalkerWatch/issues/jbossupdate

Clarfying Jetty Home v Base

jetty-documentation/src/main/asciidoc/administration/startup/startup-base-vs-home.adoc

@@ -17,7 +17,8 @@
 [[startup-base-and-home]]
 === Managing Jetty Base and Jetty Home
 
-Starting with Jetty 9.1, it is possible to maintain a separation between the binary installation of the standalone Jetty (known as `${jetty.home}`), and the customizations for your specific environment (known as `${jetty.base}`).
+Instead of managing multiple Jetty implementations out of several different distribution locations, it is possible to maintain a separation between the binary installation of the standalone Jetty (known as `${jetty.home}`), and the customizations for your specific environment(s) (known as `${jetty.base}`).
+There should always only be one Jetty Home, but there can be multiple Jetty Base directories that references.
 
 Jetty Base::
   * Also known as the `${jetty.base}` property.
@@ -26,6 +27,14 @@ Jetty Home::
   * Also known as the `${jetty.home}` property.
   * This is the location for the Jetty distribution binaries, default XML IoC configurations, and default module definitions.
 
+____
+[IMPORTANT]
+Jetty Home should always be treated as a standard of truth.
+All configuration modifications, changes and additions should be made in the appropriate Jetty Base directory.
+____
+
+[[base-vs-home-resolution]]
+
 Potential configuration is resolved from these 2 directory locations.
 
 Check Jetty Base::
@@ -241,8 +250,8 @@ jetty.dump.stop=false
 --module=annotations
 ....
 
-The `${jetty.base}/start.ini` is the main startup configuration entry point for Jetty.
-In this example you will see that we are enabling a few modules for Jetty, specifying some properties, and also referencing some Jetty IoC XML files (namely the `etc/demo-rewrite-rules.xml` and `etc/test-realm.xml` files)
+In this example, `${jetty.base}/start.ini` is the main startup configuration entry point for Jetty.
+You will see that we are enabling a few modules for Jetty, specifying some properties, and also referencing some Jetty IoC XML files (namely the `etc/demo-rewrite-rules.xml` and `etc/test-realm.xml` files)
 
 When Jetty's `start.jar` resolves the entries in the `start.ini`, it will follow the link:#base-vs-home-resolution[resolution rules above].
 

jetty-documentation/src/main/asciidoc/configuring/security/jetty-home-and-jetty-base.adoc

@@ -18,9 +18,9 @@
 === Using the $\{jetty.home} and $\{jetty.base} Concepts to Configure
 Security
 
-Jetty 9.1 introduced `${jetty.base}` and `${jetty.home}`.
+Jetty implementations are structured around the idea of `${jetty.base}` and `${jetty.home}` directories.
 
-* `${jetty.home}` is the directory location for the jetty distribution (the binaries).
+* `${jetty.home}` is the directory location for the Jetty distribution (the binaries) should not be modified.
 * `${jetty.base}` is the directory location for your customizations to the distribution.
 
 This separation:

jetty-documentation/src/main/asciidoc/quick-start/getting-started/jetty-running.adoc

@@ -105,6 +105,12 @@ jetty.home::
 jetty.base::
   The property that defines the location of a specific instance of a jetty server, its configuration, logs and web applications (typically start.ini, start.d, logs and webapps)
 
+____
+[IMPORTANT]
+Your Jetty Home directory should be treated as a standard of truth and remain unmodified or changed.
+Changes or additions to your configuration should take place in the Jetty Base directory.
+____
+
 The `jetty.home` and `jetty.base` properties may be explicitly set on the command line, or they can be inferred from the environment if used with commands like:
 
 [source, screen, subs="{sub-order}"]