Updates to Intro, Chapter 5 and ResourceHandler example for #687.

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

examples/embedded/src/main/java/org/eclipse/jetty/embedded/SplitFileServer.java

@@ -55,20 +55,22 @@ public class SplitFileServer
         // our jetty maven testing utilities to get the proper resource
         // directory, you needn't use these, you simply need to supply the paths
         // you are looking to serve content from.
+        ResourceHandler rh0 = new ResourceHandler();
+
         ContextHandler context0 = new ContextHandler();
         context0.setContextPath("/");
-        ResourceHandler rh0 = new ResourceHandler();
         File dir0 = MavenTestingUtils.getTestResourceDir("dir0");
-        rh0.setBaseResource(Resource.newResource(dir0));
+        context0.setBaseResource(Resource.newResource(dir0));
         context0.setHandler(rh0);
 
         // Rinse and repeat the previous item, only specifying a different
         // resource base.
+        ResourceHandler rh1 = new ResourceHandler();
+
         ContextHandler context1 = new ContextHandler();
         context1.setContextPath("/");
-        ResourceHandler rh1 = new ResourceHandler();
         File dir1 = MavenTestingUtils.getTestResourceDir("dir1");
-        rh1.setBaseResource(Resource.newResource(dir1));
+        context1.setBaseResource(Resource.newResource(dir1));
         context1.setHandler(rh1);
 
         // Create a ContextHandlerCollection and set the context handlers to it.

jetty-documentation/src/main/asciidoc/administration/extras/resource-handler.adoc

@@ -32,7 +32,7 @@ This handler will serve static content and handle If-Modified-Since headers and
 
 ____
 [IMPORTANT]
-There is no caching done with this handler so if you are looking for a more featureful way of serving static content look to the xred:default-servlet[].
+There is no caching done with this handler, so if you are looking for a more fully featured way of serving static content look to the xref:default-servlet[].
 ____
 
 ____
@@ -43,7 +43,7 @@ ____
 ==== Improving the Look and Feel
 
 The resource handler has a default stylesheet which you can change by calling `setStyleSheet(String location)` with the location of a file on the system that it can locate through the resource loading system.
-The default css is called jetty-dir.css and is located in the jetty-util package, pulled as a classpath resource from the jetty-util jar when requested through the ResourceHandler.
+The default css is called `jetty-dir.css` and is located in the `jetty-util` package, pulled as a classpath resource from the `jetty-util` jar when requested through the `ResourceHandler`.
 
 ==== Embedded Example
 

jetty-documentation/src/main/asciidoc/administration/part.adoc

@@ -13,6 +13,7 @@
 //
 //  You may elect to redistribute this code under either of these licenses.
 //  ========================================================================
+[[jetty-admin-guide]]
 
 = Jetty Administration Guide
 

jetty-documentation/src/main/asciidoc/configuring/contexts/configuring-virtual-hosts.adoc

@@ -18,14 +18,14 @@
 === Configuring Virtual Hosts
 
 A virtual host is an alternative name, registered in DNS, for an IP address such that multiple domain names will resolve to the same IP of a shared server instance.
-If the content to be served to the aliases names  is link:#different-virtual-hosts-different-contexts[different], then a virtual host needs to be configured for each deployed link:{JDURL}/org/eclipse/jetty/server/handler/ContextHandler.html[context] to indicate which names a context will respond to.
+If the content to be served to the aliases names is link:#different-virtual-hosts-different-contexts[different], then a virtual host needs to be configured for each deployed link:{JDURL}/org/eclipse/jetty/server/handler/ContextHandler.html[context] to indicate which names a context will respond to.
 
 Virtual hosts are set on a link:{JDURL}/org/eclipse/jetty/server/handler/ContextHandler.html[context] by calling the link:{JDURL}/org/eclipse/jetty/server/handler/ContextHandler.html#setVirtualHosts-java.lang.String:A-[`setVirtualHosts`] or link:{JDURL}/org/eclipse/jetty/server/handler/ContextHandler.html#addVirtualHosts-java.lang.String:A-[`addVirtualHost`] method which can be done in several ways:
 
 * Using a link:#deployable-descriptor-file[context XML] file in the webapps directory (see the example in link:{SRCDIR}/tests/test-webapps/test-jetty-webapp/src/main/config/demo-base/webapps/test.xml[test.xml] in the Jetty distribution).
-* Using a `WEB-INF/jetty-web.xml` file (deprecated).
 * Creating a link:#deployment-architecture[custom deployer] with a binding to configure virtual hosts for all contexts found in the same `webapps` directory.
 * Calling the link:{JDURL}/org/eclipse/jetty/server/handler/ContextHandler.html#setVirtualHosts-java.lang.String:A-[API] directly on an link:#advanced-embedding[embedded] usage.
+* Using a `WEB-INF/jetty-web.xml` file (now deprecated).
 
 [[configuring-a-virtual-host]]
 ==== Virtual Host Names
@@ -48,7 +48,7 @@ www.√integral.com::
 ==== Example Virtual Host Configuration
 
 Virtual hosts can be used with any context that is a subclass of link:{JDURL}/org/eclipse/jetty/server/handler/ContextHandler.html[ContextHandler].
-Lets look at an example where we configure a web application -represented by the link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[WebAppContext] class - with virtual hosts. 
+Lets look at an example where we configure a web application - represented by the link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[WebAppContext] class - with virtual hosts.
 You supply a list of IP addresses and names at which the web application is reachable, such as the following:
 
 * `333.444.555.666`
@@ -96,7 +96,7 @@ For example, suppose your imaginary machine has these DNS names:
 
 Suppose also you have 2 webapps, one called `blah.war` that you would like served from the `*.blah.*` names, and one called `other.war` that you want served only from the `*.other.*` names.
 
-Using the method of preparing link:#deployable-descriptor-files[contextXML] files, one for each webapp yields the following:
+Using the method of preparing link:#deployable-descriptor-file[contextXML] files, one for each webapp yields the following:
 
 For `blah` webapp:
 

jetty-documentation/src/main/asciidoc/configuring/contexts/custom-error-pages.adoc

@@ -70,7 +70,7 @@ javax.servlet.error.status_code::
 ==== Configuring error pages context files
 
 You can use context IoC XML files to configure the default error page mappings with more flexibility than is available with `web.xml`, specifically with the support of error code ranges.
-Context files are normally located in `${jetty.home}/webapps/` (see `DeployerManager` for more details) and an example of more flexible error page mapping is below:
+Context files are normally located in `${jetty.base}/webapps/` (see `DeployerManager` for more details) and an example of more flexible error page mapping is below:
 
 [source, xml, subs="{sub-order}"]
 ----
@@ -80,7 +80,7 @@ Context files are normally located in `${jetty.home}/webapps/` (see `DeployerMan
 <Configure class="org.eclipse.jetty.webapp.WebAppContext">
   <Set name="contextPath">/test</Set>
   <Set name="war">
-    <SystemProperty name="jetty.home" default="."/>/webapps/test
+    <SystemProperty name="jetty.base" default="."/>/webapps/test
   </Set>
 
   <!-- by Code -->
@@ -146,7 +146,7 @@ For example:
 ----
 
 An `ErrorHandler` instance may be set on the entire server by setting it as a dependent bean on the Server instance.
-This can be done by calling `Server.addBean(Object)` via embedded code or in `jetty.xml` IoC XML like:
+This can be done by calling `Server.addBean(Object)` via embedded code or in `jetty.xml` IoC XML:
 
 [source, xml, subs="{sub-order}"]
 ----

jetty-documentation/src/main/asciidoc/configuring/contexts/serving-webapp-from-particular-port.adoc

@@ -25,15 +25,27 @@ However, if contexts need to share resources (eg data sources, authentication),
 ==== Creating Multiple Server Instances
 
 Creating multiple server instances is a straight forward process that includes embedding Jetty code by creating multiples instances of the Server class and configuring them as needed.
-This is also easy to achieve if you are configuring your servers in XML. 
+This is also easy to achieve if you are configuring Jetty servers via XML.
 The `id` field in the Configure element of `jetty.xml` files is used to identify the instance that the configuration applies to, so to run two instances of the Server, you can copy the `jetty.xml`, jetty-http.xml and other jetty configuration files used and change the "Server" id to a new name.
 This can be done in the same style and layout as the existing `jetty.xml` files or the multiple XML files may be combined to a single file.
 
 When creating new configurations for alternative server:
 
-* Change all `id="Server"` to the new server name: `<Configure id="OtherServer" class="org.eclipse.jetty.server.Server">`
+* Change all `id="Server"` to the new server name:
-* For all connectors for the new server change the `refid` in the server argument: `<Arg name="server"><Ref refid="OtherServer" /></Arg>`
+
-* Make sure that any references to properties like `jetty.http.port` are either renamed or replaced with absolute values
+[source, xml, subs="{sub-order}"]
+----
+<Configure id="OtherServer" class="org.eclipse.jetty.server.Server">
+----
+
+* For all connectors for the new server change the `refid` in the server argument:
+
+[source, xml, subs="{sub-order}"]
+----
+<Arg name="server"><Ref refid="OtherServer" /></Arg>
+----
+
+* Make sure that any references to properties like `jetty.http.port` are either renamed or replaced with absolute values.
 * Make sure that any deployers `AppProviders` refer to a different "webapps" directory so that a different set of applications are deployed.
 
 [[jetty-otherserver.xml]]

jetty-documentation/src/main/asciidoc/configuring/contexts/setting-form-size.adoc

@@ -57,4 +57,4 @@ Set an attribute on the Server instance for which you want to modify the maximum
 ==== For All Apps in the JVM
 
 Use the system property `org.eclipse.jetty.server.Request.maxFormContentSize`.
-This can be set on the command line or in the `start.ini` file.
+This can be set on the command line or in the `start.ini` or `start.d\server.ini` file.

jetty-documentation/src/main/asciidoc/configuring/contexts/temporary-directories.adoc

@@ -77,8 +77,8 @@ context.setAttribute("org.eclipse.jetty.webapp.basetempdir", "/tmp/foo");
 
 There are several ways to use a particular directory as the temporary directory:
 
-*Call WebAppContext.setTempDirectory(String dir)*
+====== Call WebAppContext.setTempDirectory(String dir)
-Like before this can be accomplished with an xml file or directly in code. Here's an example of setting the temp directory in xml:
+As before this can be accomplished with an xml file or directly in code. Here's an example of setting the temp directory in xml:
 
 [source, xml, subs="{sub-order}"]
 ----
@@ -101,7 +101,7 @@ context.setWar("foo.war");
 context.setTempDirectory(new File("/some/dir/foo"));
 ----
 
-*Set the `javax.servlet.context.tempdir` context attribute*
+====== Set the javax.servlet.context.tempdir context attribute
 You should set this context attribute with the name of directory you want to use as the temp directory. Again, you can do this in xml:
 
 [source, xml, subs="{sub-order}"]
@@ -129,27 +129,27 @@ context.setWar("foo.war");
 context.setAttribute("javax.servlet.context.tempdir", "/some/dir/foo");
 ----
 
-Once a temporary directory has been created by either of these methods, a File instance for it is set as the value of the `javax.servlet.context.tempdir` attribute of the web application.
+Once a temporary directory has been created by either of these methods, a file instance for it is set as the value of the `javax.servlet.context.tempdir` attribute of the web application.
 
 ____
 [NOTE]
 Be wary of setting an explicit temp directory if you are likely to change the jars in WEB-INF/lib between redeployments.
-There is a JVM bug concerning caching of jar contents: http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4774421
+There is a JVM bug concerning link:http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4774421[caching of jar contents.]
 ____
 
 ==== The "work" directory
 
-Mostly for backward compatibility, from jetty-9.1.1 onwards, it is be possible to create a directory named "work" in the `$\{jetty.base}` directory.
+Mostly for backward compatibility, from Jetty 9.1.1 onwards, it is possible to create a directory named "work" in the `$\{jetty.base}` directory.
-If such a directory is found, it is assumed you want to use it as the parent directory for all of the temporary directories of the webapps in that `$\{jetty.base}`.
+If such a directory is found, it is assumed you want to use it as the parent directory for all of the temporary directories of the webapps in `$\{jetty.base}`.
-Moreover, as has historically been the case, these temp directories inside the work directory are not cleaned up when jetty exists (or more correctly speaking, the `temp` directory corresponding to a context is not cleaned up when that context stops).
+Moreover, as has historically been the case, these temp directories inside the work directory are not cleaned up when Jetty exits (or more correctly speaking, the `temp` directory corresponding to a context is not cleaned up when that context stops).
 
 When a work directory is used, the algorithm for generating the name of the context-specific temp directories omits the random digit string.
 This ensures the name of the directory remains consistent across context restarts.
 
 ==== Persisting the temp directory
 
-Sometimes you may find it useful to keep the contents of the temporary directory between restarts of the web application.
+Sometimes it is useful to keep the contents of the temporary directory between restarts of the web application.
-By default, Jetty will _not_ persist the temp directory.
+By default, Jetty will *not* persist the temp directory.
 To configure Jetty to keep it, use link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[WebAppContext.setPersistTempDirectory(true)].
 
 ____

jetty-documentation/src/main/asciidoc/configuring/part.adoc

@@ -13,6 +13,7 @@
 //
 //  You may elect to redistribute this code under either of these licenses.
 //  ========================================================================
+[[jetty-config-guide]]
 
 = Jetty Configuration Guide
 

jetty-documentation/src/main/asciidoc/development/part.adoc

@@ -13,6 +13,7 @@
 //
 //  You may elect to redistribute this code under either of these licenses.
 //  ========================================================================
+[[jetty-dev-guide]]
 
 = Jetty Development Guide
 

jetty-documentation/src/main/asciidoc/quick-start/introduction/what-is-jetty.adoc

@@ -19,10 +19,27 @@
 
 Jetty is an open-source project providing an HTTP server, HTTP client, and javax.servlet container.
 
-This guide is in two parts.
+This guide is broken up in to five parts:
 
-* The first part emphasizes beginning to use Jetty. It provides information about downloading Jetty, changing things like the port Jetty runs on, adjusting logging levels, and configuring many of the most common servlet container features such as JNDI, JMX, and session management.
+* The link:#quick-start[first section] emphasizes beginning to use Jetty.
-* The second part describes advanced uses of Jetty, providing in depth coverage of specific features like our highly scalable async client, proxy servlet configuration, the Jetty Maven plugin, and using Jetty as an embedded server. The advanced section includes tutorials, howtos, videos, and reference materials.
+It provides information about what Jetty is and where you can download it, and where to find Jetty in repositories like Central Maven.
+It also provides a Quick Start guide on how to get Jetty up and running as well as an overview of how and what to configure in Jetty.
+
+* The link:#jetty-config-guide[second section] of the guide deals with configuring Jetty at a more granular level.
+It explains how to use Jetty to deploy web applications, configure contexts and connects, and how to implement SSL and other security measures.
+
+* Administration of Jetty is the focus of the link:#jetty-admin-guide[third section] of the guide.
+From server startup to session management, logging, HTTP/2 support and Jetty optimization, these chapters will help administrators get the most out of their Jetty server instances.
+This section also covers configuring many of the most common servlet container features such as JNDI and JMX.
+
+* Aimed at advanced users of Jetty, the link:#jetty-dev-guide[fourth section] of the guide focuses on Jetty development.
+A large portion of this section is focused on using Jetty as an embedded server in existing applications.
+It contains several examples and how-to guides for making the most out of the Jetty framework.
+This section also includes a guide on using the Jetty Maven plugin as well as information on debugging Jetty.
+
+* The link:#jetty-ref-guide[final section] of the guide is a reference section.
+Included there are guides on Jetty architecture and Jetty XML syntax, alternate distributions of Jetty and even troubleshooting of common issues.
+There is also a chapter on getting involved in the Jetty community including information on how to contribute code and how to find help.
 
 Feedback is always welcome!
 Additionally, if you are interested in how to contribute to the open source project there is a link:#community[section on that as well!]

jetty-documentation/src/main/asciidoc/quick-start/part.adoc

@@ -13,6 +13,7 @@
 //
 //  You may elect to redistribute this code under either of these licenses.
 //  ========================================================================
+[[quick-start]]
 
 = Getting Started With Jetty
 

jetty-documentation/src/main/asciidoc/reference/part.adoc

@@ -13,6 +13,7 @@
 //
 //  You may elect to redistribute this code under either of these licenses.
 //  ========================================================================
+[[jetty-ref-guide]]
 
 = Jetty Reference Guide