minor refactor: expand slightly

subprojects/groovy-servlet/src/spec/doc/servlet-userguide.adoc

@@ -21,15 +21,25 @@
 
 = Servlet support
 
-You can write (Java) Servlets in Groovy (called Groovlets).
+The `groovy-servlet` module supports the following features:
+
+* A `GroovyServlet` class let you use Groovy scripts as Servlets (called _Groovylets_).
+* A `TemplateServlet` class which supports running Groovy's template engines to generate servlet content. A typical use case is to write Groovy Server Pages (GSPs) which are similar to Java Server Pages (JSPs) but embed Groovy code
+rather than Java code.
+* An `AbstractHttpServlet` class for defining traditional Servlets.
+* Helper classes like `ServletBinding` and `ServletCategory` which let you access some of the features offered by the `groovy-servlet` module in additional contexts.
+
+From Groovy 5, `groovy-servlet` supports Jakarta EE Servlet specifications. Javax EE servlet specifications are supported in version before Groovy 5 or with Groovy 5 by using the `javax` classifier when specifying your dependency.
 
-There is also a `GroovyServlet`.
+== Groovlets
+
+You can write (Java) Servlets in Groovy (called Groovlets).
 
-This feature will automatically compile your .groovy source files, turn them into bytecode, load the Class and cache it until you change the source file.
+This is supported by the `GroovyServlet` class. It will automatically compile your `.groovy` source files, turn them into bytecode, load the Class and cache it until you change the source file.
 
 Here's a simple example to show you the kind of things you can do from a Groovlet.
 
-Notice the use of implicit variables to access the session, output and request. Also notice that this is more like a script as it does not have a class wrapper.
+Notice the use of implicit variables to access the `session`, `output` and `request`. Also notice that this is more like a script as the code isn't wrapped with a class definition.
 
 [source,groovy]
 ----
@@ -65,11 +75,11 @@ The following variables are ready for use in Groovlets:
 1. The session variable is only set, if there was already a session object. See the `if (session == null)` checks in the examples above.
 2. These variables cannot be re-assigned inside a `Groovlet`. They are bound on first access, allowing to e.g. calling methods on the `response` object before using `out`.
 
-== Setting up groovlets
+== Setting up Groovlets
 
-Add the following to your `web.xml`:
+The traditional configuration approach for declaring new servlets is to add them to your Servlet engine configuration, e.g. you might add the following to your `web.xml`:
 [source,xml]
---------------------------------------------------------------------------------------------------
+------------------------------------------------------------------------------
 <servlet>
     <servlet-name>Groovy</servlet-name>
     <servlet-class>groovy.servlet.GroovyServlet</servlet-class>
@@ -79,16 +89,32 @@ Add the following to your `web.xml`:
     <servlet-name>Groovy</servlet-name>
     <url-pattern>*.groovy</url-pattern>
 </servlet-mapping>
---------------------------------------------------------------------------------------------------
+------------------------------------------------------------------------------
 
 Then put the required groovy jar files into `WEB-INF/lib`.
 
 Now put the .groovy files in, say, the root directory (i.e. where you would put your html files). The `GroovyServlet` takes care of compiling the .groovy files.
 
-So for example using tomcat you could edit `tomcat/conf/server.xml` like this:
+So for example using https://tomcat.apache.org/[Apache Tomcat] you could edit `tomcat/conf/server.xml` like this:
 [source,xml]
---------------------------------------------------------------------------------------------------
-<Context path="/groovy" docBase="c:/groovy-servlet"/>
---------------------------------------------------------------------------------------------------
+------------------------------------------------------------------------------
+<Context path="/groovy" docBase="/path_to_servlet_base"/>
+------------------------------------------------------------------------------
 
 Then access it with http://localhost:8080/groovy/hello.groovy
+
+Some Servlet engines let you define Servlets programmatically, e.g. here is how you might use https://jetty.org/[Jetty] with Groovlets enabled:
+
+[source,groovy]
+----
+import groovy.servlet.GroovyServlet
+import org.eclipse.jetty.server.Server
+import org.eclipse.jetty.ee9.servlet.ServletContextHandler
+
+var server = new Server(8080)
+var handler = new ServletContextHandler(server, '/', ServletContextHandler.SESSIONS)
+handler.baseResourceAsString = 'path_to_servlet_base'
+handler.addServlet(GroovyServlet, '*.groovy')
+server.start()
+server.join()
+----