Merge pull request #1012 from WalkerWatch/issues/modlisting

Issue #984 documentation updates.

jetty-documentation/src/main/asciidoc/administration/sessions/chapter.adoc

@@ -29,7 +29,6 @@ include::session-configuration-jdbc.adoc[]
 include::session-configuration-mongodb.adoc[]
 include::session-configuration-infinispan.adoc[]
 include::session-configuration-gcloud.adoc[]
-include::session-configuration-gcloud-module.adoc[]
 //include::setting-session-characteristics.adoc[]
 //include::using-persistent-sessions.adoc[]
 //include::session-clustering-jdbc.adoc[]

jetty-documentation/src/main/asciidoc/administration/startup/screen-list-logging-modules.adoc

@@ -0,0 +1,92 @@
+//  ========================================================================
+//  Copyright (c) 1995-2016 Mort Bay Consulting Pty. Ltd.
+//  ========================================================================
+//  All rights reserved. This program and the accompanying materials
+//  are made available under the terms of the Eclipse Public License v1.0
+//  and Apache License v2.0 which accompanies this distribution.
+//
+//      The Eclipse Public License is available at
+//      http://www.eclipse.org/legal/epl-v10.html
+//
+//      The Apache License v2.0 is available at
+//      http://www.opensource.org/licenses/apache2.0.php
+//
+//  You may elect to redistribute this code under either of these licenses.
+//  ========================================================================
+
+[source, screen, subs="{sub-order}"]
+....
+[mybase]$ java -jar ../start.jar --list-modules=logging,-internal
+
+Available Modules:
+==================
+tags: [logging, -internal]
+
+Modules for tag 'logging':
+--------------------------
+
+     Module: console-capture
+           : Redirects JVMs console stderr and stdout to a log file,
+           : including output from Jetty's default StdErrLog logging.
+       Tags: logging
+        LIB: resources/
+        XML: etc/console-capture.xml
+
+     Module: logging-jcl [logging]
+           : Configure jetty logging to use Java Commons Logging (jcl)
+           : SLF4J is used as the core logging mechanism.
+       Tags: logging
+     Depend: jcl-impl, slf4j-jcl
+        JVM: -Dorg.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.Slf4jLog
+
+     Module: logging-jetty [logging]
+           : Configure jetty logging mechanism.
+           : Provides a ${jetty.base}/resources/jetty-logging.properties.
+       Tags: logging
+     Depend: console-capture, resources
+
+     Module: logging-jul [logging]
+           : Configure jetty logging to use Java Util Logging (jul)
+           : SLF4J is used as the core logging mechanism.
+       Tags: logging
+     Depend: jul-impl, slf4j-jul
+        JVM: -Dorg.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.Slf4jLog
+
+     Module: logging-log4j [logging]
+           : Configure jetty logging to use Log4j Logging
+           : SLF4J is used as the core logging mechanism.
+       Tags: logging
+     Depend: log4j-impl, slf4j-log4j
+        JVM: -Dorg.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.Slf4jLog
+
+     Module: logging-log4j2 [logging]
+           : Configure jetty logging to use log4j version 2
+           : SLF4J is used as the core logging mechanism.
+       Tags: logging
+     Depend: slf4j-log4j2, log4j2-impl
+        JVM: -Dorg.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.Slf4jLog
+
+     Module: logging-logback [logging]
+           : Configure jetty logging to use Logback Logging.
+           : SLF4J is used as the core logging mechanism.
+       Tags: logging
+     Depend: logback-impl, slf4j-logback
+        JVM: -Dorg.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.Slf4jLog
+
+     Module: logging-slf4j [logging]
+           : Configure jetty logging to use slf4j.
+           : Any slf4j-impl implementation is used
+       Tags: logging
+     Depend: slf4j-api, slf4j-impl
+        JVM: -Dorg.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.Slf4jLog
+
+Modules for tag 'requestlog':
+-----------------------------
+
+     Module: logback-access [requestlog]
+           : Enables logback request log.
+       Tags: requestlog, logging, logback
+     Depend: server, logback-core, resources
+        LIB: lib/logback/logback-access-${logback.version}.jar
+        XML: etc/jetty-logback-access.xml
+....

jetty-documentation/src/main/asciidoc/administration/startup/startup-modules.adoc

@@ -17,16 +17,15 @@
 [[startup-modules]]
 === Managing Startup Modules
 
-Jetty 9.1 a new Module system replacing the previous `start.config` + `OPTIONS` techniques from past Jetty Distributions.
-
 The standard Jetty Distribution ships with several modules defined in `${jetty.home}/modules/`.
+These modules allow flexibility for implementations and make configuration a much more plug-and-play set up.
 
 What a Jetty Startup Module Defines:
 
 A Module Name::
 The name of the module is the keyword used by the `--module=<name>` command line argument to activate/enable modules, and also find dependent modules.
 The filename of the module defines its name (eg: server.mod becomes the module named "server").
-List of Dependant Modules::
+List of Dependent Modules::
 All modules can declare that they depend on other modules with the `[depend]` section.
 The list of dependencies is used to transitively resolve other modules that are deemed to be required based on the modules that you activate.
 The order of modules defined in the graph of active modules is used to determine various execution order for configuration, such as Jetty IoC XML configurations, and to resolve conflicting property declarations.
@@ -42,6 +41,14 @@ List of Jetty IoC XML Configurations::
 The execution order of the Jetty IoC XML configurations is determined by the graph of active module dependencies resolved via the `[depend]` sections.
 If the default XML is not sufficient to satisfy your needs, you can override this XML by making your own in the `${jetty.base}/etc/` directory, with the same name.
 The resolution steps for Jetty Base and Jetty Home will ensure that your copy from `${jetty.base}` will be picked up over the default one in `${jetty.home}`.
+List of Module Tags::
+For ease of sorting, modules can be assigned tags.
+When using the `--list-modules` command, modules will be groups by the first tag that exists in this section.
+Modules can also be listed specifically by these tags using `--list-modules=<tag name>` on the command line.
+Ini Variables::
+The `[ini]` section is used to add or change server parameters at startup.
+The `[ini]` section can also include a the path of a file or several files which should be made available to the server only.
+This is helpful when you want to control what jars are available to deployed webapps.
 Jetty INI Template::
 Each module can optionally declare a startup ini template that is used to insert/append/inject sample configuration elements into the `start.ini` or `start.d/*.ini` files when using the `--add-to-start=<name>` command line argument in `start.jar`.
 Commonly used to present some of the parameterized property options from the Jetty IoC XML configuration files also referenced in the same module.
@@ -56,8 +63,7 @@ Download File;;
 Currently, the `<url>` must be a `http://` scheme URL (please link:#bugs[let us know] if you need more schemes supported).
 The `<pathname>` portion follows the link:#base-vs-home-resolution[Jetty Base and Jetty Home path resolution rules].
 Example: `http://repo.corp.com/maven/corp-security-policy-1.0.jar:lib/corp-security-policy.jar`
-    This will check for the existence of `lib/corp-security-policy.jar`, and if it doesn't exist, it will download the jar file from
+This will check for the existence of `lib/corp-security-policy.jar`, and if it doesn't exist, it will download the jar file from `http://repo.corp.com/maven/corp-security-policy-1.0.jar`
-    `http://repo.corp.com/maven/corp-security-policy-1.0.jar`
 
 [[enabling-modules]]
 ==== Enabling Modules
@@ -241,11 +247,33 @@ Deleting the ini file associated with module is another option, but may not be p
 
 To see which modules are __available__, use the `--list-modules` command line argument.
 This command will also show you which modules are __enabled__.
-Here's an example:
+Modules are sorted by the value in the `[tags]` section of the associated `.mod` file.
+If there are multiple entries in the `[tags]` section, it sorts by the first tag in the list.
+
+____
+[NOTE]
+By default, the `--list-modules` command line argument shows all modules that do not include `internal` in the `[tags]` section of the associated `.mod` file.
+If you would like to see *all* modules, use `--list-modules=*`
+____
+
+Here's an example of the `--list-modules` command:
 
 include::screen-list-modules.adoc[]
 
-Since being introduced in Jetty 9.1 the modules provided in the Jetty distribution has expanded greatly.
+===== Searching Modules
-Below is a graphical representation of the standard modules and their dependencies.
 
-image:images/modules-9.3-simplified.png[image,width=768]
+Since the introduction of the module system, many new modules have been added.
+As a result, looking at the module list as a whole can be somewhat overwhelming.
+To narrow down which modules you would like to choose from, you can search by values listed under the `[tags]` section.
+Note that when you search this way, all modules that include your criteria in it's `[tags]` section, including internal modules, will be shown.
+To filter out internal modules when searching a specific module tag, simply add `-internal` to the command line.
+For example, if you wanted to look at only the logging modules (excluding the internal implementation modules), you would use `--list-modules=logging,-internal`.
+
+include::screen-list-logging-modules.adoc[]
+
+// Since being introduced in Jetty 9.1 the modules provided in the Jetty distribution has expanded greatly.
+// Below is a graphical representation of the standard modules and their dependencies.
+//
+// TODO - Update modules image for 9.4 / 10?
+//
+// image:images/modules-9.3-simplified.png[image,width=768]