Make documentation consistent with new implementation

src/site/markdown/examples/attached-jar.md.vm

@@ -1,6 +1,6 @@
 ---
 title: How to create an additional attached jar artifact from the project
-author: 
+author:
   - Karl Heinz Marbaise
 date: 2014-06-16
 ---
@@ -26,9 +26,12 @@ under the License.
 
 # How to Create an Additional Attached JAR Artifact
 
-Add `<includes>`/`<include>` or `<excludes>`/`<exclude>` in your `pom.xml`. Add a `classifier` as well.
+Add `<includes>`/`<include>` or `<excludes>`/`<exclude>` in your `pom.xml`.
+Add a `classifier` as well.
 
-**Note:** Define the JAR Plugin in a new execution. Otherwise, it replaces the default use of the JAR Plugin. It does not add a second artifact. The `classifier` is also required to create more than one artifact.
+**Note:** Define the JAR Plugin in a new execution.
+Otherwise, it replaces the default use of the JAR Plugin. It does not add a second artifact.
+The `classifier` is also required to create more than one artifact.
 
 ```unknown
 <project>

src/site/markdown/examples/create-test-jar.md.vm

@@ -1,6 +1,6 @@
 ---
 title: How to create a jar with test classes
-author: 
+author:
   - Karl Heinz Marbaise
 date: 2014-06-16
 ---
@@ -26,9 +26,11 @@ under the License.
 
 # How to Create a JAR With Test Classes
 
-When you create a JAR with test classes, you probably want to reuse those classes. There are two ways to do this:
+When you create a JAR with test classes, you probably want to reuse those classes.
+There are two ways to do this:
 
-- Create an attached JAR with the test classes from the current project. This JAR does not include the transitive `test`-scoped dependencies.
+- Create an attached JAR with the test classes from the current project.
+  This JAR does not include the transitive `test`-scoped dependencies.
 - Create a separate project with the test classes.
 
 The easy way
@@ -80,11 +82,18 @@ To reuse this artifact in another project, declare the dependency with `type` se
 </project>
 ```
 
-This configuration generates two JAR files. The first contains the classes from `src/main/java`. The second contains the classes from `src/test/java`. The JAR names follow the schema `artifactId-version.jar` and `artifactId-version-classifier.jar`.
+This configuration generates two JAR files.
+The first contains the classes from `src/main/java`.
+The second contains the classes from `src/test/java`.
+The JAR names follow the schema `artifactId-version.jar` and `artifactId-version-classifier.jar`.
 
-The values of `artifactId` and `version` come from your `pom.xml` file. The default `classifier` is `tests`. You can change it in the [jar goal configuration](../test-jar-mojo.html).
+The values of `artifactId` and `version` come from your `pom.xml` file.
+The default `classifier` is `tests`.
+You can change it in the [jar goal configuration](../test-jar-mojo.html).
 
-**Note:** This solution does not include the transitive `test`-scoped dependencies automatically. Maven resolves only the `compile`-time dependencies. Add all other required `test`-scoped dependencies by hand.
+**Note:** This solution does not include the transitive `test`-scoped dependencies automatically.
+Maven resolves only the `compile`-time dependencies.
+Add all other required `test`-scoped dependencies by hand.
 
 The preferred way
 -----------------
@@ -100,8 +109,10 @@ To let Maven resolve all `test`-scoped transitive dependencies, create a separat
 </project>
 ```
 
-- Move the source files you want to share from `src/test/java` in the original project to `src/main/java` in this project. Move the resources in the same way.
-- Move the required `test`-scoped dependencies from the original project to this project. Remove their `test` scope. The test framework dependency, for example junit, gets the default scope too. Add any project specific dependencies that the code needs.
+- Move the source files you want to share from `src/test/java` in the original project to `src/main/java` in this project.
+  Move the resources in the same way.
+- Move the required `test`-scoped dependencies from the original project to this project. Remove their `test` scope.
+  The test framework dependency, for example junit, gets the default scope too. Add any project specific dependencies that the code needs.
 
 Add this dependency to use the reusable test classes in another project:
 

src/site/markdown/examples/include-exclude.md.vm

@@ -1,6 +1,6 @@
 ---
 title: Howto include/exclude content from a jar archive
-author: 
+author:
   - Karl Heinz Marbaise
 date: 2014-06-16
 ---
@@ -26,7 +26,8 @@ under the License.
 
 # How to Include or Exclude Content from a JAR Artifact
 
-Add `<includes>`/`<include>` or `<excludes>`/`<exclude>` in your `pom.xml`. These elements specify the fileset patterns to include or exclude.
+Add `<includes>`/`<include>` or `<excludes>`/`<exclude>` in your `pom.xml`.
+These elements specify the fileset patterns to include or exclude.
 
 ```unknown
 <project>
@@ -52,3 +53,6 @@ Add `<includes>`/`<include>` or `<excludes>`/`<exclude>` in your `pom.xml`. Thes
 ```
 
 The patterns must be relative to the path for the plugin's `classesDirectory` parameter.
+By default, the syntax is the same as Maven 3, where `**` can match any number of directories including zero.
+An alternative syntax can be specified by prefixing the pattern with `glob:`, `regex:` or any other syntax added
+through the service provider mechanism. See `FileSystem.getPathMatcher(String)` in Java NIO for more information.

src/site/markdown/examples/manifest-customization.md.vm

@@ -1,6 +1,6 @@
 ---
 title: Manifest customization
-author: 
+author:
   - Dennis Lundberg
 date: 2006-07-12
 ---
@@ -31,12 +31,16 @@ The Default Manifest
 
 The documentation for [Maven Archiver](/shared/maven-archiver/examples/manifest.html) describes the default contents of the manifest.
 
-Since version 2.1, the Maven JAR Plugin uses Maven Archiver ${mavenArchiverVersion}. It no longer creates the Specification and Implementation details in the manifest by default. To add them, specify them explicitly in your plugin configuration. The documentation for [Maven Archiver](/shared/maven-archiver/examples/manifest.html) describes this as well.
+Since version 2.1, the Maven JAR Plugin no longer creates the Specification and Implementation details in the manifest by default.
+To add them, specify them explicitly in your plugin configuration.
+The documentation for [Maven Archiver](/shared/maven-archiver/examples/manifest.html) describes this as well.
 
 Manifest Customization
 ----------------------
 
-You can alter the default manifest with the `archive` configuration element. The example below shows some of the available configuration options. For more information, see the [Maven Archiver reference](/shared/maven-archiver/index.html).
+You can alter the default manifest with the `archive` configuration element.
+The example below shows some of the available configuration options.
+For more information, see the [Maven Archiver reference](/shared/maven-archiver/index.html).
 
 ```unknown
 <project>

src/site/markdown/index.md

@@ -1,6 +1,6 @@
 ---
 title: Introduction
-author: 
+author:
   - Dennis Lundberg
 date: 2013-07-22
 ---
@@ -35,15 +35,28 @@ This plugin builds JAR files. To sign JAR files, use the [Maven Jarsigner Plugin
 
 ## Usage
 
-General instructions for the JAR Plugin are on the [usage page](./usage.html). The examples below describe more specific use cases.
+General instructions for the JAR Plugin are on the [usage page](./usage.html).
+The examples below describe more specific use cases.
 
-If you have questions about the plugin, see the [FAQ](./faq.html) or contact the [user mailing list](./mailing-lists.html). The mailing list stores all posts in an archive. An older thread can contain the answer to your question. You can search the [mail archive](./mailing-lists.html) for the answer.
+If you have questions about the plugin, see the [FAQ](./faq.html) or contact the [user mailing list](./mailing-lists.html).
+The mailing list stores all posts in an archive.
+An older thread can contain the answer to your question.
+You can search the [mail archive](./mailing-lists.html) for the answer.
 
-If the plugin is missing a feature or has a defect, file a feature request or bug report in the [issue tracker](https://github.com/apache/maven-jar-plugin/issues). When you create a new issue, describe your concern in detail. The developers must reproduce the problem to fix a bug. Attach entire debug logs, POMs, or small demo projects to the issue. Patches are welcome. Contributors can check out the project from the [source repository](./scm.html) and find supplementary information in the [guide to helping with Maven](https://maven.apache.org/guides/development/guide-helping.html).
+If the plugin is missing a feature or has a defect,
+file a feature request or bug report in the [issue tracker](https://github.com/apache/maven-jar-plugin/issues).
+When you create a new issue, describe your concern in detail.
+The developers must reproduce the problem to fix a bug.
+Attach entire debug logs, POMs, or small demo projects to the issue. Patches are welcome.
+Contributors can check out the project from the [source repository](./scm.html) and find supplementary information
+in the [guide to helping with Maven](https://maven.apache.org/guides/development/guide-helping.html).
 
 ## Archiver Configuration
 
-The plugin uses Maven Archiver to handle JAR content and manifest configuration. See the [Maven Archiver Documentation](/shared/maven-archiver/) to learn how to set it up. You can also see the [Guide to Working with Manifests](/guides/mini/guide-manifest.html).
+The plugin uses the JDK `jar` tool internally to create and verify the JAR file.
+The plugin uses Maven Archiver to handle manifest configuration.
+See the [Maven Archiver Documentation](/shared/maven-archiver/) to learn how to set it up.
+You can also see the [Guide to Working with Manifests](/guides/mini/guide-manifest.html).
 
 ## Examples
 

src/site/markdown/usage.md.vm

@@ -1,6 +1,6 @@
 ---
 title: Usage
-author: 
+author:
   - Jerome Lacoste
   - Dennis Lundberg
   - Olivier Lamy
@@ -29,11 +29,15 @@ under the License.
 
 # Usage
 
-The examples below show how to use this plugin. For advanced configurations, see the [Example section](./index.html#Examples). See the documentation for [Maven Archiver](/shared/maven-archiver/).
+The examples below show how to use this plugin.
+For advanced configurations, see the [Example section](./index.html#Examples).
+See the documentation for [Maven Archiver](/shared/maven-archiver/).
 
-This version of the Maven JAR Plugin uses [Maven Archiver](/shared/maven-archiver/index.html) ${mavenArchiverVersion} to handle archive creation.
+The plugin uses the JDK `jar` tool internally to create and verify the JAR file.
+This version of the Maven JAR Plugin uses [Maven Archiver](/shared/maven-archiver/index.html) ${mavenArchiverVersion}
+to handle manifest configuration.
 
-**Note:** If you need to sign your JAR files, use the [Maven Jarsigner Plugin](/plugins/maven-jarsigner-plugin/) instead.
+**Note:** If you need to sign your JAR files, use the [Maven Jarsigner Plugin](/plugins/maven-jarsigner-plugin/).
 
 How to build a JAR file
 -----------------------
@@ -43,7 +47,7 @@ To create a JAR file with Maven, create a `pom.xml` file with at least the follo
 ```xml
 <project>
   <modelVersion>4.0.0</modelVersion>
-  
+
   <groupId>com.mycompany.project</groupId>
   <artifactId>core</artifactId>
   <version>1.0-SNAPSHOT</version>
@@ -63,21 +67,26 @@ mvn package
 
 The `package` phase bundles all the files into the artifact. In this case, the artifact is a JAR file.
 
-The generated JAR file is in the `target` directory. Its name is `core-1.0-SNAPSHOT.jar`. The JAR file contains the compiled Java class files and the files from `src/main/resources`.
+The generated JAR file is in the `target` directory. Its name is `core-1.0-SNAPSHOT.jar`.
+The JAR file contains the compiled Java class files and the files from `src/main/resources`.
 
-Usually you do not need to declare the `maven-jar-plugin` in your `pom.xml`. The plugin is bound to the [Maven Build Life Cycle](/guides/introduction/introduction-to-the-lifecycle.html).
+Usually you do not need to declare the `maven-jar-plugin` in your `pom.xml`.
+The plugin is bound to the [Maven Build Life Cycle](/guides/introduction/introduction-to-the-lifecycle.html).
 
 For full documentation, see [plugin-info](./plugin-info.html).
 
 Modular JAR files
 -----------------
 
-The [Java Platform Module System (JPMS)](https://openjdk.java.net/projects/jigsaw/spec/) introduced Modular JAR files in the [JAR file specifications](https://cr.openjdk.java.net/~mr/jigsaw/spec/jar.html). A Modular JAR file contains a `module-info.class` file in the root directory. For multi-release JAR files, the file is in the versioned area. If the project contains `module-info.class`, the final JAR is a modular JAR. This happens without any configuration and regardless of the plugin version.
-
-Since version 3.1.2, this plugin updates the modular descriptor when the JAR contains `module-info.class`. The plugin adds additional attributes, such as the list of included packages. It verifies the modular descriptor. It also verifies that all services provided by the module are in the JAR file. The most notable added attribute is the module main class.
-
-If the JAR manifest contains the `Main-Class` attribute, this plugin sets the module main class to the same value. For an example, see [Make The Jar Executable](../../shared/maven-archiver/examples/classpath.html).
+The [Java Module System](https://openjdk.java.net/projects/jigsaw/spec/) introduced
+Modular JAR files in the [JAR file specifications](https://cr.openjdk.java.net/~mr/jigsaw/spec/jar.html).
+A Modular JAR file contains a `module-info.class` file in the root directory.
+For multi-release JAR files, the file can be in the versioned area.
+If the project contains `module-info.class`, the final JAR is a modular JAR.
+This happens without any configuration and regardless of the plugin version.
 
-The plugin uses the JDK `jar` tool internally to add the additional attributes and to verify the modular descriptor. This requires JDK version 9 or newer.
+Since version 4.0.0-beta-2, this plugin can verify the JAR file with a `validate` option.
+The checks depend on the JDK tool and can include a verification of `module-info.class`.
 
-If you use JDK version 8 or earlier, the JAR is still a modular JAR. The JAR contains `module-info.class`. The plugin adds no additional attributes and performs no validation.
+If the JAR manifest contains the `Main-Class` attribute, this plugin sets the module main class to the same value.
+For an example, see [Make The Jar Executable](../../shared/maven-archiver/examples/classpath.html).