Some updates to start doco.

Signed-off-by: WalkerWatch <ctwalker@gmail.com>

jetty-documentation/src/main/asciidoc/administration/startup/start-jar.adoc

@@ -55,6 +55,7 @@ When executed `start.jar` performs the following actions:
 
 * Loads and parses all INIs found in `${jetty.base}/start.d/*.ini` as command line arguments.
 * Loads and parses `${jetty.base}/start.ini` as command line arguments.
+** Please see link:#start-vs-startd[Start.ini vs. Start.d] for more information on the difference between these.
 * Parses actual command line arguments used to execute `start.jar` itself.
 * Resolves any XML configuration files, modules, and libraries using base vs. home resolution steps:
 1.  Checks whether file exists as relative reference to `${jetty.base}.`
@@ -217,3 +218,18 @@ The time (in seconds) to wait for confirmation that the running Jetty server has
 If not specified, the stopper waits indefinitely for the server to stop.
 +
 If the time specified elapses, without a confirmation of server stop, then the `--stop` command exits with a non-zero return code.
+
+===== Advanced Commands
+
+--lib=<classpath>::
+Add arbitrary classpath entries to the the server classpath.
+
+--include-jetty-dir=<path>::
+Include an extra Jetty directory to use as a source for configuration details.
+This directory behaves similarly to `${jetty.base}` but sits at a layer between `${jetty.base}` and `${jetty.home}`.
+This allows for some complex hierarchies of configuration details.
+
+--download=<http-uri>|<location>::
+If the file does not exist at the given location, download it from the given http URI.
+Note: location is always relative to `${jetty.base}`.
+You might need to escape the slash "\|" to use this on some environments.

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

@@ -18,7 +18,7 @@
 === Managing Jetty Base and Jetty Home
 
 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.
+There should always only be *one* Jetty Home (per version of Jetty), but there can be multiple Jetty Base directories that reference it.
 
 Jetty Base::
   * Also known as the `${jetty.base}` property.
@@ -36,26 +36,22 @@ ____
 [[base-vs-home-resolution]]
 
 Potential configuration is resolved from these 2 directory locations.
+When Jetty starts up in processes configuration from them as follows:
 
-Check Jetty Base::
-  If the referenced configuration exists, relative to the defined Jetty base, use it.
-Check Jetty Home::
-  If the referenced configuration exists, relative to the defined Jetty home, use it.
+Check Jetty Base First::
+  If the referenced configuration exists, relative to the defined Jetty base, it is used.
+Check Jetty Home Second::
+  If the referenced configuration exists, relative to the defined Jetty home, it is used.
 Use java.io.File(String pathname) Logic::
-  Lastly, use the reference as a `java.io.File(String pathname)` reference, following the default resolution rules outlined by that constructor.
+  Lastly, use the reference as a `java.io.File(String pathname)` reference, following the default resolution rules outlined by that constructor. In brief, the reference will be used as-is, be it relative (to current working directory, aka $\{user.dir}) or absolute path, or even network reference (such as on Windows and use of UNC paths).
 
-+
-In brief, the reference will be used as-is, be it relative (to current working directory, aka $\{user.dir}) or absolute path, or even network reference (such as on Windows and use of UNC paths).
-
-For more details on how startup with start.jar works, see link:#execute-start-jar[Using start.jar: Executing]
+For more details on how startup with start.jar works, see link:#executing-startjar[Using start.jar: Executing]
 
 [[demo-base]]
 ==== Demo-Base in the Jetty Distribution
 
 The Jetty Distribution comes with an example `${jetty.base}` which enables the various demonstration webapps and server configurations.
 
-How to use the demo-base directory as a Jetty Base directory.
-
 [source, screen, subs="{sub-order}"]
 ....
 [jetty-distribution-{VERSION}]$ ls -la
@@ -89,31 +85,39 @@ drwxrwxr-x  2 user group   4096 Oct  8 06:54 webapps/
 ...
 ....
 
-As you can see above, you are executing the demo-base configuration using the Jetty base concepts.
-
-If you want to see what the Jetty base looks like without executing Jetty, you can simply list the configuration
+If you want to see what the Jetty base looks like without executing Jetty, you can simply list the configuration by using the `--list-config` command.
 
 [source, screen, subs="{sub-order}"]
 ....
-[my-base]$ java -jar $JETTY_HOME/start.jar --list-config
+[demo-base]$ java -jar $JETTY_HOME/start.jar --list-config
 
 Java Environment:
 -----------------
  java.home=/usr/lib/jvm/jdk-7u21-x64/jre
- java.vm.vendor=Oracle Corporation
- java.vm.version=23.21-b01
- java.vm.name=Java HotSpot(TM) 64-Bit Server VM
- java.vm.info=mixed mode
- java.runtime.name=Java(TM) SE Runtime Environment
- java.runtime.version=1.7.0_21-b11
- java.io.tmpdir=/tmp
+ java.vm.vendor = Oracle Corporation
+ java.vm.version = 25.92-b14
+ java.vm.name = Java HotSpot(TM) 64-Bit Server VM
+ java.vm.info = mixed mode
+ java.runtime.name = Java(TM) SE Runtime Environment
+ java.runtime.version = 1.8.0_92-b14
+ java.io.tmpdir = /var/folders/h6/yb_lbnnn11g0y1jjlvqg631h0000gn/T/
+ user.dir = /home/user/jetty-distribution-{VERSION}
+ user.language = en
+ user.country = US
 
 Jetty Environment:
 -----------------
  jetty.home=/home/user/jetty-distribution-{VERSION}
+ jetty.tag.version = master
  jetty.base=/home/user/jetty-distribution-{VERSION}/demo-base
  jetty.version={VERSION}
 
+ Config Search Order:
+ --------------------
+  <command-line>
+  ${jetty.base} -> /home/user/jetty-distribution-9.4.1.v20170120/demo-base
+  ${jetty.home} -> /home/user/Desktop/jetty-distribution-9.4.1.v20170120
+
 JVM Arguments:
 --------------
  (no jvm args specified)
@@ -194,20 +198,22 @@ Note: order presented here is how they would appear on the classpath.
 Jetty Active XMLs:
 ------------------
  ${jetty.home}/etc/jetty.xml
- ${jetty.home}/etc/jetty-http.xml
- ${jetty.home}/etc/jetty-jaas.xml
- ${jetty.home}/etc/jetty-rewrite.xml
- ${jetty.home}/etc/jetty-ssl.xml
- ${jetty.home}/etc/jetty-https.xml
+ ${jetty.home}/etc/jetty-webapp.xml
  ${jetty.home}/etc/jetty-plus.xml
  ${jetty.home}/etc/jetty-annotations.xml
  ${jetty.home}/etc/jetty-deploy.xml
+ ${jetty.home}/etc/jetty-http.xml
+ ${jetty.home}/etc/jetty-ssl.xml
+ ${jetty.home}/etc/jetty-ssl-context.xml
+ ${jetty.home}/etc/jetty-https.xml
+ ${jetty.home}/etc/jetty-jaas.xml
+ ${jetty.home}/etc/jetty-rewrite.xml
  ${jetty.base}/etc/demo-rewrite-rules.xml
  ${jetty.base}/etc/test-realm.xml
 ....
 
-This demonstrates the powerful `--list-config` command line option and how you can use it to see what the configuration will look like when starting Jetty.
-From the Java environment, to the system properties, to the classpath, and finally the Active Jetty IoC XML used to build up the Jetty server configuration.
+The `--list-config` command line option displays what the configuration will look like when starting Jetty.
+This includes information on the Java environment to the system properties, the classpath and the Active Jetty IoC XML used to build up the Jetty server configuration.
 
 Of note, is that the output will make it known where the configuration elements came from, be it in either in `${jetty.home}` or `${jetty.base}`.