[maven-site] 01/01: Clarify language around exclusions

[el...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

elharo pushed a commit to branch elharo-patch-6
in repository https://gitbox.apache.org/repos/asf/maven-site.git

commit a7a077e97a90ea31ff45f4c5216cd9518f9524e9
Author: Elliotte Rusty Harold <el...@users.noreply.github.com>
AuthorDate: Sun Nov 13 09:43:49 2022 -0500

    Clarify language around exclusions
    
    @michael-o
---
 content/apt/pom.apt.vm | 25 +++++++++++++++----------
 1 file changed, 15 insertions(+), 10 deletions(-)

diff --git a/content/apt/pom.apt.vm b/content/apt/pom.apt.vm
index c05265fc..42665ddb 100644
--- a/content/apt/pom.apt.vm
+++ b/content/apt/pom.apt.vm
@@ -567,10 +567,13 @@ Display parameters as parsed by Maven (in canonical form and as a list of tokens
 
 *** {Exclusions}
 
-  Exclusions tell Maven not to include the
-  specified project that is a dependency of this dependency (in other words, its transitive
-  dependency). For example, the <<<maven-embedder>>> requires <<<maven-core>>>, and we do not
-  wish to use it or its dependencies, then we would add it as an <<<exclusion>>>.
+  It is sometimes useful to limit  a dependency's transitive dependencies. A dependency may have incorrectly
+  specified scopes, or dependencies that conflict with other dependencies in your project. Exclusions tell Maven not to include a
+  specified artifact in the classpath even if it is a dependency of one or more of this project's dependencies.
+  (a transitive dependency). For example, the <<<maven-embedder>>> depends on <<<maven-core>>>.
+  Suppose we want to depend on maven-embedder but we do not want to include maven-core 
+  or its dependencies in our classpath. Then we add it as an <<<exclusion>>> when we declare the 
+  dependency on maven-embedder:
 
 +-----------------------------+
 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -580,7 +583,7 @@ Display parameters as parsed by Maven (in canonical form and as a list of tokens
     <dependency>
       <groupId>org.apache.maven</groupId>
       <artifactId>maven-embedder</artifactId>
-      <version>2.0</version>
+      <version>3.8.6</version>
       <exclusions>
         <exclusion>
           <groupId>org.apache.maven</groupId>
@@ -594,9 +597,11 @@ Display parameters as parsed by Maven (in canonical form and as a list of tokens
 </project>
 +-----------------------------+
 
-  It is also sometimes useful to clip a dependency's transitive dependencies. A dependency may have incorrectly
-  specified scopes, or dependencies that conflict with other dependencies in your project. Using wildcard excludes makes it easy to exclude all a dependency's
-  transitive dependencies. In the case below you may be working with the maven-embedder and you want to manage
+  This only removes the path to maven-core from this one dependency. If maven-core appears as
+  a direct or transitive dependency elsewhere in the POM, it can still be added to the classpath.
+
+  Using a wildcard excludes makes it easy to exclude all a dependency's
+  all transitive dependencies. In the case below you may be working with the maven-embedder and you want to manage
   the dependencies you use yourself, so you clip all the transitive dependencies:
 
 +-----------------------------+
@@ -607,7 +612,7 @@ Display parameters as parsed by Maven (in canonical form and as a list of tokens
     <dependency>
       <groupId>org.apache.maven</groupId>
       <artifactId>maven-embedder</artifactId>
-      <version>3.1.0</version>
+      <version>3.8.6</version>
       <exclusions>
         <exclusion>
           <groupId>*</groupId>
@@ -624,7 +629,7 @@ Display parameters as parsed by Maven (in canonical form and as a list of tokens
   * <<exclusions>>:
   Exclusions contain one or more <<<exclusion>>> elements, each containing a <<<groupId>>> and
   <<<artifactId>>> denoting a dependency to exclude. Unlike <<<optional>>>, which may or may not
-  be installed and used, <<<exclusions>>> actively remove themselves from the dependency tree.
+  be installed and used, <<<exclusions>>> actively remove artifacts from the dependency tree.
 
 ** {Inheritance}