rework documentation

src/site/apt/index.apt.vm

@@ -25,15 +25,16 @@
 
 ${project.name}
 
-  The Toolchains Plugins enables sharing configuration across plugins,
+  The Toolchains Plugins enables sharing configuration about tools across plugins,
   for example to make sure the plugins like compiler, surefire, javadoc, webstart etc. all use the same JDK for execution independently from JRE used to run Maven itself.
+
   Similarly to the maven-enforcer-plugin, it allows you to control environmental constraints in the build.
 
 * Goals Overview
 
   The Toolchains plugin has one goal:
 
-  * {{{./toolchain-mojo.html}toolchains:toolchain}} selects a toolchain based on configured requirements and stores it in build context for later retrieval by other plugins.
+  * {{{./toolchain-mojo.html}toolchains:toolchain}} selects a toolchain based on configured build requirements and stores it in build context for later retrieval by other plugins.
 
 * Usage
 

src/site/apt/toolchains/jdk.apt.vm

@@ -26,21 +26,19 @@
 JDK Toolchain
 
 
-* Toolchain Identification
+* Toolchain Description
 
   The toolchain type id for JDK is "<<<jdk>>>".
 
-  Predefined identification tokens, for requirement matching, are:
+  Predefined <<<\<provides\>>>> identification tokens, for requirement matching in plugin configuration, are:
 
-  * "<<<version>>>" marks the version of the JDK. This can be either a single version or a version range.
+    * "<<<version>>>" marks the version of the JDK in <<<toolchain.xml>>>. In plugin's selection, this can be either a single version or a version range.
 
-  * Other tokens are accepted, but only exact matches are supported.
+    * Other tokens are accepted, but only exact matches are supported.
 
-  []
+    []
 
-* Toolchain Configuration
-
-  There is only one configuration element named "<<<jdkHome>>>". It designates the root directory
+  There is only one <<<toolchains.xml>>> <<<\<configuration\>>>> element named "<<<jdkHome>>>". It designates the root directory
   of a JDK installation.
 
 * Sample <<<toolchains.xml>>> setup
@@ -63,14 +61,15 @@ JDK Toolchain
 +---+
 
   This defines a toolchain with version 11, vendor "temurin", and purpose "for_mevenide".
+
   A project can request this toolchain by specifying the type "jdk" and the version "11".
-  It can also use a version range that includes 11 like [8, 17]. It can also ask for the
+  It can also use a version range that includes 11 like <<<[8, 17]>>>. It can also ask for the
   vendor temurin, with or without version, or the purpose "for_mevenide".
 
 
 * Toolchains Plugin Configuration
 
-  A project specifies a toolchain in the configuraiton of the maven-toolchains-plugin like so:
+  A project specifies a toolchain in the configuration of the maven-toolchains-plugin like so:
 
 +---+
 <project>
@@ -117,7 +116,7 @@ JDK Toolchain
         </configuration>
 +---+
 
-  Aside from version, the definitions are opaque strings. Maven looks in toolchains.xml
+  Aside from version, the definitions are opaque strings. Maven looks in <<<toolchains.xml>>>
   for a toolchain that provides version=="1.8" and vendor=="temurin". It does not know or care
   what these strings mean. It does not, for instance, concern itself with whether the jdkHome configured
   by the toolchain that satisfies version=="1.8" and vendor=="temurin" is JDK 8 from the Temurin project,

src/site/apt/usage.apt.vm

@@ -30,16 +30,17 @@ Usage
 
 * What is a toolchain?
 
-  A Toolchain is an object that Maven plugins can use to retrieve preconfigured
+  A {{{/ref/current/maven-core/apidocs/org/apache/maven/toolchain/Toolchain.html}Toolchain}} is an object that Maven plugins can use to retrieve preconfigured
   tools (including location and other information).
 
   Maven Toolchains Plugin can read which toolchains are available on the user's
   computer (as configured in <<<toolchains.xml>>>) and match them against the
   toolchain requirements of the project (as configured in <<<pom.xml>>>). If a
-  match is found, the toolchain is made available to other, toolchain aware,
-  Maven plugins in the build. A list of which plugins are toolchain aware can be
-  found in
-  {{{http://maven.apache.org/guides/mini/guide-using-toolchains.html}this guide}}.
+  match is found, the toolchain is made available to other, <toolchain aware>,
+  Maven plugins in the build.
+
+  A list of which plugins are <toolchain aware> can be found in the
+  {{{/guides/mini/guide-using-toolchains.html}Guide to Using Toolchains}}.
 
   With the <<<jdk>>> toolchain, for example, instead of being stuck with the JDK
   used to run Maven, all plugins can use the same other JDK instance without
@@ -50,10 +51,10 @@ Usage
 
   This goal is bound by default to the <<<validate>>> lifecycle phase, the
   first phase in the lifecycle. This is necessary so that all the plugins that
-  are bound to later lifecycle phases are made aware of the available
-  toolchains.
+  are bound to later lifecycle phases are made aware of the selected
+  toolchain(s).
 
-  That being said, you still need to configure the plugin in your <<<pom.xml>>>.
+  That being said, you still need to configure the plugin in your <<<pom.xml>>> to select expected toolchain(s).
   In order for it to execute, you need to add an execution for it, like this:
 
 +---+
@@ -66,6 +67,11 @@ Usage
         <version>${project.version}</version>
         <configuration>
           <!-- Configure your toolchain requirements here -->
+          <toolchain-type>
+            <param>expected value</param>
+            ...
+          </toolchain-type>
+          ...
         </configuration>
         <executions>
           <execution>
@@ -80,8 +86,24 @@ Usage
 </project>
 +---+
 
-  You can read more about which standard toolchains are available
-  {{{./toolchains/index.html}here}}.
+  You can read more about which standard toolchains are available {{{./toolchains/index.html}here}}.
+
+* The <<<toolchains.xml>>> Descriptor
+
+  Toolchains available on the building machine are described in <<<~/.m2/toolchains.xml>>>:
+
+  * toolchain <<<\<type\>>>>,
+
+  * <<<\<provides\>>>> elements to describe toolchain characteristics that can later be matched from plugin, when
+  multiple toolchains for one <<<type>>> are available,
+
+  * <<<\<configuration\>>>> elements to configure access the toolchain.
+
+  []
+
+  See {{{/ref/current/maven-core/toolchains.html}Toolchains Descriptor}} for details on its structure.
+
+  You can read more about which elements standard toolchains propose {{{./toolchains/index.html}here}}.
 
 * Generic Plugin configuration information
 

src/site/site.xml

@@ -19,9 +19,9 @@ specific language governing permissions and limitations
 under the License.
 -->
 
-<project xmlns="http://maven.apache.org/DECORATION/1.4.0"
+<project xmlns="http://maven.apache.org/DECORATION/1.8.1"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-  xsi:schemaLocation="http://maven.apache.org/DECORATION/1.4.0 https://maven.apache.org/xsd/decoration-1.4.0.xsd">
+  xsi:schemaLocation="http://maven.apache.org/DECORATION/1.8.1 https://maven.apache.org/xsd/decoration-1.8.1.xsd">
   <body>
     <menu name="Overview">
       <item name="Introduction" href="index.html"/>
@@ -36,5 +36,9 @@ under the License.
       <item name="License" href="https://www.apache.org/licenses/"/>
       <item name="Download" href="download.html"/>
     </menu>
+    <menu name="See Also">
+      <item name="Guide to Using Toolchains" href="/guides/mini/guide-using-toolchains.html"/>
+      <item name="Toolchains Descriptor" href="/ref/current/maven-core/toolchains.html"/>
+    </menu>
   </body>
 </project>