[WFLY-19178] Rationalize order of 'Subsystem configurations' content …

…in the Admin Guide I also changed the title of each subsystem section to 'XXX Subsystem' for a consistent appearance in the TOC. I dropped 'Configuration' as overly verbose in the TOC. I made a few random tweaks as I looked at the files I touched.
rhusar · Apr 18, 2024 · bed2c2f · bed2c2f
1 parent 399e7fc
commit bed2c2f
Show file tree

Hide file tree

Showing 33 changed files with 78 additions and 80 deletions.
diff --git a/docs/src/main/asciidoc/_admin-guide/Subsystem_configuration.adoc b/docs/src/main/asciidoc/_admin-guide/Subsystem_configuration.adoc
@@ -1,6 +1,6 @@
 [[Subsystem_configuration]]
 = Subsystem configuration
-Subsystem configuration reference
+
 :author: tcerar@redhat.com
 :icons: font
 :source-highlighter: coderay
@@ -17,80 +17,80 @@ endif::[]
 
 ifdef::basebackend-html[toc::[]]
 
-The following chapters will focus on the high level management use cases
+The following chapters will focus on the high level subsystem management use cases
 that are available through the CLI and the web interface. For a detailed
 description of each subsystem configuration property, please consult the
 respective component reference.
 
-Schema Location
 
-TIP: The configuration schemas can found in `$JBOSS_HOME/docs/schema`.
+TIP: The configuration schemas can found in the `$JBOSS_HOME/docs/schema` directory.
 
 :leveloffset: +1
 
-include::subsystem-configuration/EE.adoc[]
+include::subsystem-configuration/Datasources_Agroal.adoc[]
+
+include::subsystem-configuration/Core_Management.adoc[]
 
-include::subsystem-configuration/Naming.adoc[]
 
 include::subsystem-configuration/DataSource.adoc[]
 
-include::subsystem-configuration/Datasources_Agroal.adoc[]
+include::subsystem-configuration/Deployment_Scanner.adoc[]
 
-include::subsystem-configuration/Logging.adoc[]
+include::subsystem-configuration/EE.adoc[]
+
+include::subsystem-configuration/Elytron_OIDC_Client.adoc[]
+
+include::subsystem-configuration/Health.adoc[]
+
+include::subsystem-configuration/Jakarta_Batch.adoc[]
 
 include::subsystem-configuration/Jakarta_Enterprise_Beans_3.adoc[]
 
-include::subsystem-configuration/Undertow.adoc[]
+include::subsystem-configuration/Jakarta_Faces.adoc[]
 
-include::subsystem-configuration/Messaging.adoc[]
+include::subsystem-configuration/Jakarta_MVC.adoc[]
 
-include::subsystem-configuration/Transactions.adoc[]
+include::subsystem-configuration/Jakarta_RESTful_Web_Services.adoc[]
 
-include::subsystem-configuration/Metrics.adoc[]
+include::subsystem-configuration/JMX.adoc[]
 
-include::subsystem-configuration/Micrometer.adoc[]
+include::subsystem-configuration/Logging.adoc[]
 
-include::subsystem-configuration/Observability_Tracing.adoc[]
+include::subsystem-configuration/Messaging.adoc[]
 
-include::subsystem-configuration/Health.adoc[]
+include::subsystem-configuration/Metrics.adoc[]
+
+include::subsystem-configuration/Micrometer.adoc[]
 
 include::subsystem-configuration/MicroProfile_Config_SmallRye.adoc[]
 
+include::subsystem-configuration/MicroProfile_Fault_Tolerance_SmallRye.adoc[]
+
 include::subsystem-configuration/MicroProfile_Health.adoc[]
 
 include::subsystem-configuration/MicroProfile_JWT.adoc[]
 
+include::subsystem-configuration/MicroProfile_LRA.adoc[]
+
 include::subsystem-configuration/MicroProfile_OpenAPI.adoc[]
 
-include::subsystem-configuration/MicroProfile_Fault_Tolerance_SmallRye.adoc[]
+include::subsystem-configuration/MicroProfile_Reactive_Messsaging_SmallRye.adoc[]
 
 include::subsystem-configuration/MicroProfile_Reactive_Streams_Operators_SmallRye.adoc[]
 
-include::subsystem-configuration/MicroProfile_Reactive_Messsaging_SmallRye.adoc[]
-
 include::subsystem-configuration/MicroProfile_Telemetry.adoc[]
 
-include::subsystem-configuration/MicroProfile_LRA.adoc[]
+include::subsystem-configuration/Observability_Tracing.adoc[]
 
-include::subsystem-configuration/Web_services.adoc[]
+include::subsystem-configuration/Naming.adoc[]
 
 include::subsystem-configuration/Resource_adapters.adoc[]
 
-include::subsystem-configuration/Jakarta_Batch.adoc[]
-
-include::subsystem-configuration/Jakarta_Faces.adoc[]
-
-include::subsystem-configuration/Jakarta_MVC.adoc[]
-
-include::subsystem-configuration/JMX.adoc[]
-
-include::subsystem-configuration/Deployment_Scanner.adoc[]
-
-include::subsystem-configuration/Core_Management.adoc[]
+include::subsystem-configuration/Transactions.adoc[]
 
-include::subsystem-configuration/Jakarta_RESTful_Web_Services.adoc[]
+include::subsystem-configuration/Undertow.adoc[]
 
-include::subsystem-configuration/Elytron_OIDC_Client.adoc[]
+include::subsystem-configuration/Web_services.adoc[]
 
 include::subsystem-configuration/Simple_configuration_subsystems.adoc[]
 

diff --git a/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/Core_Management.adoc b/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/Core_Management.adoc
@@ -1,5 +1,5 @@
 [[Core_Management]]
-= Core Management Subsystem Configuration
+= Core Management Subsystem
 
 ifdef::env-github[]
 :tip-caption: :bulb:
@@ -9,7 +9,7 @@ ifdef::env-github[]
 :warning-caption: :warning:
 endif::[]
 
-The core management subsystem is composed services used to manage the
+The core management subsystem is composed of services used to manage the
 server or monitor its status. +
 The core management subsystem configuration may be used to:
 

diff --git a/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/DataSource.adoc b/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/DataSource.adoc
@@ -1,5 +1,5 @@
 [[DataSource]]
-= DataSource configuration
+= DataSource Subsystem
 
 ifdef::env-github[]
 :tip-caption: :bulb:

diff --git a/.../src/main/asciidoc/_admin-guide/subsystem-configuration/Datasources_Agroal.adoc b/.../src/main/asciidoc/_admin-guide/subsystem-configuration/Datasources_Agroal.adoc
@@ -1,5 +1,5 @@
 [[agroal]]
-= Agroal configuration
+= Agroal Subsystem
 
 ifdef::env-github[]
 :tip-caption: :bulb:

diff --git a/.../src/main/asciidoc/_admin-guide/subsystem-configuration/Deployment_Scanner.adoc b/.../src/main/asciidoc/_admin-guide/subsystem-configuration/Deployment_Scanner.adoc
@@ -1,5 +1,5 @@
 [[Deployment_Scanner]]
-= Deployment Scanner configuration
+= Deployment Scanner Subsystem
 
 ifdef::env-github[]
 :tip-caption: :bulb:

diff --git a/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/EE.adoc b/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/EE.adoc
@@ -1,5 +1,5 @@
 [[EE]]
-= EE Subsystem Configuration
+= EE Subsystem
 :leveloffset: +1
 
 ifdef::env-github[]
@@ -10,19 +10,19 @@ ifdef::env-github[]
 :warning-caption: :warning:
 endif::[]
 
-The EE subsystem provides common functionality in the Jakarta EE platform,
+The `ee` subsystem provides common functionality in the Jakarta EE platform,
 such as the EE Concurrency Utilities (JSR 236) and `@Resource`
 injection. The subsystem is also responsible for managing the lifecycle
 of Jakarta EE application's deployments, that is, `.ear` files and configuration of global directories to share common libraries across all deployed applications.
 
-The EE subsystem configuration may be used to:
+The `ee` subsystem configuration may be used to:
 
 * customise the deployment of Jakarta EE applications
 * create EE Concurrency Utilities instances
-* define the default bindings
+* define the spec-mandated default JNDI bindings for services that must be made available via JNDI to applications.
 
-The subsystem name is ee and this document covers EE subsystem version
-`5.0`, which XML namespace within WildFly XML configurations is
+This document covers EE subsystem version
+`5.0`, whose XML namespace within WildFly XML configurations is
 `urn:jboss:domain:ee:5.0`. The path for the subsystem's XML schema,
 within WildFly's distribution, is `docs/schema/jboss-as-ee_5_0.xsd`.
 

diff --git a/...src/main/asciidoc/_admin-guide/subsystem-configuration/Elytron_OIDC_Client.adoc b/...src/main/asciidoc/_admin-guide/subsystem-configuration/Elytron_OIDC_Client.adoc
@@ -1,5 +1,5 @@
 [[Elytron_OIDC_Client]]
-= Elytron OpenID Connect Client Subsystem Configuration
+= Elytron OpenID Connect Client Subsystem
 
 ifdef::env-github[]
 :tip-caption: :bulb:

diff --git a/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/Health.adoc b/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/Health.adoc
@@ -1,5 +1,5 @@
 [[Health]]
-= Health Subsystem Configuration
+= Health Subsystem
 
 ifdef::env-github[]
 :tip-caption: :bulb:

diff --git a/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/JMX.adoc b/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/JMX.adoc
@@ -1,5 +1,5 @@
 [[JMX]]
-= JMX subsystem configuration
+= JMX Subsystem
 
 ifdef::env-github[]
 :tip-caption: :bulb:

diff --git a/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/Jakarta_Batch.adoc b/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/Jakarta_Batch.adoc
@@ -1,5 +1,5 @@
 [[Jakarta_Batch]]
-= Jakarta Batch Subsystem Configuration
+= Jakarta Batch Subsystem
 
 ifdef::env-github[]
 :tip-caption: :bulb:
@@ -13,7 +13,7 @@ endif::[]
 
 The batch subsystem is used to configure an environment for running
 batch applications. http://wildfly.org[WildFly] uses
-https://github.com/jberet/jsr352[JBeret] for it's batch implementation.
+https://github.com/jberet/jsr352[JBeret] for its Jakarta Batch implementation.
 Specific information about JBeret can be found in the
 http://jberet.gitbooks.io/jberet-user-guide/content/[user guide]. The
 resource path, in <<CLI_Recipes,CLI notation>>, for the subsystem

diff --git a/...n/asciidoc/_admin-guide/subsystem-configuration/Jakarta_Enterprise_Beans_3.adoc b/...n/asciidoc/_admin-guide/subsystem-configuration/Jakarta_Enterprise_Beans_3.adoc
@@ -1,5 +1,5 @@
 [[EJB3]]
-= EJB3 subsystem configuration guide
+= Jakarta Enterprise Beans Subsystem
 
 ifdef::env-github[]
 :tip-caption: :bulb:
@@ -9,11 +9,11 @@ ifdef::env-github[]
 :warning-caption: :warning:
 endif::[]
 
-This page lists the options that are available for configuring the EJB
+The `ejb3` subsystem provides support for Jakarta Enterprise Beans. This page lists the options that are available for configuring the `ejb3`
 subsystem.
 
 A complete example of the config is shown below, with a full explanation
-of each
+of each item.
 
 [source,xml,options="nowrap"]
 ----

diff --git a/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/Jakarta_Faces.adoc b/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/Jakarta_Faces.adoc
@@ -1,7 +1,7 @@
 :module-url: https://raw.githubusercontent.com/wildfly/wildfly/main/jsf/multi-jsf-installer/src/main/resources
 
 [[Jakarta_Faces]]
-= Jakarta Faces Configuration
+= Jakarta Faces Subsystem
 
 Jakarta Faces configuration is handled by the `jsf` subsystem. The `jsf` subsystem
 allows multiple Jakarta Faces implementations to be installed on the same WildFly server. In particular, any

diff --git a/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/Jakarta_MVC.adoc b/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/Jakarta_MVC.adoc
@@ -1,5 +1,5 @@
 [[Jakarta_MVC]]
-= Jakarta MVC Subsystem Configuration
+= Jakarta MVC Subsystem
 
 ifdef::env-github[]
 :tip-caption: :bulb:

diff --git a/...asciidoc/_admin-guide/subsystem-configuration/Jakarta_RESTful_Web_Services.adoc b/...asciidoc/_admin-guide/subsystem-configuration/Jakarta_RESTful_Web_Services.adoc
@@ -1,5 +1,5 @@
 [[JAXRS]]
-== JAXRS Subsystem Configuration
+== Jakarta RESTful Web Services Subsystem
 
 ifdef::env-github[]
 :tip-caption: :bulb:

diff --git a/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/Logging.adoc b/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/Logging.adoc
@@ -1,5 +1,5 @@
 [[Logging]]
-= Logging Configuration
+= Logging Subsystem
 
 ifdef::env-github[]
 :tip-caption: :bulb:
@@ -9,12 +9,10 @@ ifdef::env-github[]
 :warning-caption: :warning:
 endif::[]
 
-[abstract]
-
 The overall server logging configuration is represented by the logging
 subsystem. It consists of four notable parts: `handler` configurations,
-`logger`, the `root logger` declarations (aka log categories) and
-logging profiles. Each logger does reference a handler (or set of
+`logger` and the `root logger` declarations (aka log categories) and
+logging profiles. Each logger references a handler (or set of
 handlers). Each handler declares the log format and output:
 
 [source,xml,options="nowrap"]

diff --git a/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/Messaging.adoc b/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/Messaging.adoc
@@ -1,5 +1,5 @@
 [[Messaging]]
-= Messaging configuration
+= Messaging Subsystem
 
 ifdef::env-github[]
 :tip-caption: :bulb:
@@ -9,7 +9,7 @@ ifdef::env-github[]
 :warning-caption: :warning:
 endif::[]
 
-The Jakarta Messaging server configuration is done through the _messaging-activemq_
+Support for an embedded messaging broker or integration with a remote broker, including support for the Jakarta Messaging specification, is done through the _messaging-activemq_
 subsystem. In this chapter we are going outline the frequently used
 configuration options. For a more detailed explanation please consult
 the Artemis user guide (See "Component Reference").

diff --git a/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/Metrics.adoc b/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/Metrics.adoc
@@ -1,5 +1,5 @@
 [[MicroProfile_Metrics_SmallRye]]
-= Metrics Subsystem Configuration
+= Metrics Subsystem
 
 ifdef::env-github[]
 :tip-caption: :bulb:

diff --git a/...asciidoc/_admin-guide/subsystem-configuration/MicroProfile_Config_SmallRye.adoc b/...asciidoc/_admin-guide/subsystem-configuration/MicroProfile_Config_SmallRye.adoc
@@ -1,5 +1,5 @@
 [[MicroProfile_Config_SmallRye]]
-= MicroProfile Config Subsystem Configuration
+= MicroProfile Config Subsystem
 
 ifdef::env-github[]
 :tip-caption: :bulb:

diff --git a/...src/main/asciidoc/_admin-guide/subsystem-configuration/MicroProfile_Health.adoc b/...src/main/asciidoc/_admin-guide/subsystem-configuration/MicroProfile_Health.adoc
@@ -1,5 +1,5 @@
 [[MicroProfile_Health_SmallRye]]
-= MicroProfile Health Subsystem Configuration
+= MicroProfile Health Subsystem
 
 ifdef::env-github[]
 :tip-caption: :bulb:

diff --git a/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/MicroProfile_JWT.adoc b/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/MicroProfile_JWT.adoc
@@ -1,5 +1,5 @@
 [[MicroProfile_JWT_SmallRye]]
-= MicroProfile JWT Subsystem Configuration
+= MicroProfile JWT Subsystem
 
 ifdef::env-github[]
 :tip-caption: :bulb:

diff --git a/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/MicroProfile_LRA.adoc b/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/MicroProfile_LRA.adoc
@@ -1,5 +1,5 @@
 [[MicroProfile_LRA]]
-= MicroProfile LRA Subsystems Configuration
+= MicroProfile LRA Subsystems
 ----
 :narayana-version: 6.0.0.Final
 :eclipse-mp-lra-api-version: 2.0

diff --git a/...rc/main/asciidoc/_admin-guide/subsystem-configuration/MicroProfile_OpenAPI.adoc b/...rc/main/asciidoc/_admin-guide/subsystem-configuration/MicroProfile_OpenAPI.adoc
@@ -1,5 +1,5 @@
 [[MicroProfile_OpenAPI_SmallRye]]
-= MicroProfile OpenAPI Subsystem Configuration
+= MicroProfile OpenAPI Subsystem
 
 ifdef::env-github[]
 :tip-caption: :bulb:

diff --git a/...in-guide/subsystem-configuration/MicroProfile_Reactive_Messsaging_SmallRye.adoc b/...in-guide/subsystem-configuration/MicroProfile_Reactive_Messsaging_SmallRye.adoc
@@ -1,5 +1,5 @@
 [[MicroProfile_Reactive_Messaging_SmallRye]]
-= MicroProfile Reactive Messaging Subsystem Configuration
+= MicroProfile Reactive Messaging Subsystem
 ----
 :smallrye-reactive-messaging-version:       4.5.0
 :smallrye-reactive-messaging-tag:           {smallrye-reactive-messaging-version}

diff --git a/...e/subsystem-configuration/MicroProfile_Reactive_Streams_Operators_SmallRye.adoc b/...e/subsystem-configuration/MicroProfile_Reactive_Streams_Operators_SmallRye.adoc
@@ -1,5 +1,5 @@
 [[MicroProfile_Reactive_Streams_Operators_SmallRye]]
-= MicroProfile Reactive Streams Operators Subsystem Configuration
+= MicroProfile Reactive Streams Operators Subsystem
 
 ifdef::env-github[]
 :tip-caption: :bulb:

diff --git a/.../main/asciidoc/_admin-guide/subsystem-configuration/MicroProfile_Telemetry.adoc b/.../main/asciidoc/_admin-guide/subsystem-configuration/MicroProfile_Telemetry.adoc
@@ -1,5 +1,5 @@
 [[MicroProfile_Telemetry]]
-= MicroProfile Telemetry Subsystem Configuration
+= MicroProfile Telemetry Subsystem
 
 Support for https://microprofile.io/project/eclipse/microprofile-telemetry[MicroProfile Telemetry] is provided by the _microprofile-telemetry_ subsystem.
 

diff --git a/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/Micrometer.adoc b/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/Micrometer.adoc
@@ -1,5 +1,5 @@
 [[Micrometer_Metrics]]
-= Micrometer Metrics Subsystem Configuration
+= Micrometer Metrics Subsystem
 
 ifdef::env-github[]
 :tip-caption: :bulb:

diff --git a/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/Naming.adoc b/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/Naming.adoc
@@ -1,5 +1,5 @@
 [[Naming]]
-= Naming Subsystem Configuration
+= Naming Subsystem
 
 ifdef::env-github[]
 :tip-caption: :bulb:
@@ -10,7 +10,7 @@ ifdef::env-github[]
 endif::[]
 
 The Naming subsystem provides the JNDI implementation on WildFly, and
-its configuration allows to:
+its configuration allows you to:
 
 * bind entries in global JNDI namespaces
 * turn off/on the remote JNDI interface