You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by sl...@apache.org on 2026/08/06 13:15:12 UTC
(maven-jar-plugin) 02/02: Port the site documentation from APT to Markdown
This is an automated email from the ASF dual-hosted git repository.
slachiewicz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-jar-plugin.git
commit 6d9645d8d0cff204a138b2b5347f46cc22f8ecaa
Author: Sylwester Lachiewicz <sl...@apache.org>
AuthorDate: Thu Aug 6 14:54:37 2026 +0200
Port the site documentation from APT to Markdown
6 page(s) converted with doxia-converter and then cleaned up by hand:
- <<<code>>> becomes backticks, <<bold>> becomes **bold**, {{{url}text}}
becomes [text](url)
- the ASF license header becomes a single block HTML comment
- a page whose only Velocity reference was ${project.name} is now a plain
.md with the title spelled out
- a page that keeps a reference stays a .vm. Velocity reads ## as a line
comment and would silently swallow every ATX heading below level one, so
subsections use setext underlines and anything deeper is wrapped in
#[[ ... ]]#
- references APT rendered literally are escaped, so they do not resolve
Verified by building the site before and after and comparing every
generated page: the visible text and the link targets are unchanged apart
from <b>/<i> becoming <strong>/<em> and quotes in prose picking up the
Markdown module's typographic substitution.
---
src/site/markdown/examples/attached-jar.md.vm | 56 ++++-----
src/site/markdown/examples/create-test-jar.md.vm | 137 +++++++++------------
src/site/markdown/examples/include-exclude.md.vm | 66 ++++------
.../markdown/examples/manifest-customization.md.vm | 69 ++++-------
src/site/markdown/index.md | 102 ++++++---------
src/site/markdown/usage.md.vm | 128 +++++++------------
6 files changed, 211 insertions(+), 347 deletions(-)
diff --git a/src/site/markdown/examples/attached-jar.md.vm b/src/site/markdown/examples/attached-jar.md.vm
index 6a7826d..6e7ddca 100644
--- a/src/site/markdown/examples/attached-jar.md.vm
+++ b/src/site/markdown/examples/attached-jar.md.vm
@@ -1,42 +1,29 @@
- ------
- How to create an additional attached jar artifact from the project
- ------
- Karl Heinz Marbaise
- ------
- 2014-06-16
- ------
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
- ~~ Licensed to the Apache Software Foundation (ASF) under one
- ~~ or more contributor license agreements. See the NOTICE file
- ~~ distributed with this work for additional information
- ~~ regarding copyright ownership. The ASF licenses this file
- ~~ to you under the Apache License, Version 2.0 (the
- ~~ "License"); you may not use this file except in compliance
- ~~ with the License. You may obtain a copy of the License at
- ~~
- ~~ http://www.apache.org/licenses/LICENSE-2.0
- ~~
- ~~ Unless required by applicable law or agreed to in writing,
- ~~ software distributed under the License is distributed on an
- ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- ~~ KIND, either express or implied. See the License for the
- ~~ specific language governing permissions and limitations
- ~~ under the License.
+http://www.apache.org/licenses/LICENSE-2.0
- ~~ NOTE: For help with the syntax of this file, see:
- ~~ http://maven.apache.org/doxia/references/apt-format.html
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
-How to create an additional attached jar artifact from the project
+# How to create an additional attached jar artifact from the project
- Specify a list of fileset patterns to be included or excluded by adding
- <<<\<includes\>>>>/<<<\<include\>>>> or <<<\<excludes\>>>>/<<<\<exclude\>>>>
- and add a <<<classifier>>> in your <<<pom.xml>>>.
+Specify a list of fileset patterns to be included or excluded by adding `<includes>`/`<include>` or `<excludes>`/`<exclude>` and add a `classifier` in your `pom.xml`.
- <<Note:>> the jar-plugin must be defined in a new execution, otherwise it
- will replace the default use of the jar-plugin instead of adding a second
- artifact. The <<<classifier>>> is also required to create more than one artifact.
+**Note:** the jar-plugin must be defined in a new execution, otherwise it will replace the default use of the jar-plugin instead of adding a second artifact. The `classifier` is also required to create more than one artifact.
-+-----------------+
+```unknown
<project>
...
<build>
@@ -66,5 +53,4 @@ How to create an additional attached jar artifact from the project
</build>
...
</project>
-+-----------------+
-
+```
diff --git a/src/site/markdown/examples/create-test-jar.md.vm b/src/site/markdown/examples/create-test-jar.md.vm
index 2bee6f8..2498b7a 100644
--- a/src/site/markdown/examples/create-test-jar.md.vm
+++ b/src/site/markdown/examples/create-test-jar.md.vm
@@ -1,47 +1,35 @@
- ------
- How to create a jar containing test classes
- ------
- Karl Heinz Marbaise
- ------
- 2014-06-16
- ------
-
- ~~ Licensed to the Apache Software Foundation (ASF) under one
- ~~ or more contributor license agreements. See the NOTICE file
- ~~ distributed with this work for additional information
- ~~ regarding copyright ownership. The ASF licenses this file
- ~~ to you under the Apache License, Version 2.0 (the
- ~~ "License"); you may not use this file except in compliance
- ~~ with the License. You may obtain a copy of the License at
- ~~
- ~~ http://www.apache.org/licenses/LICENSE-2.0
- ~~
- ~~ Unless required by applicable law or agreed to in writing,
- ~~ software distributed under the License is distributed on an
- ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- ~~ KIND, either express or implied. See the License for the
- ~~ specific language governing permissions and limitations
- ~~ under the License.
-
- ~~ NOTE: For help with the syntax of this file, see:
- ~~ http://maven.apache.org/doxia/references/apt-format.html
-
-How to create a jar containing test classes
-
- When you want to create a jar containing <test-classes>, you would probably want to reuse those classes.
- There are two ways to solve this:
-
- * Create an attached jar with the <test-classes> from the current project and loose its transitive <<<test>>>-scoped dependencies.
-
- * Create a separate project with the <test-classes>.
-
- []
-
-* The easy way
-
- You can produce a jar which will include your test classes and resources.
-
-+-----------------+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# How to create a jar containing test classes
+
+When you want to create a jar containing _test-classes_, you would probably want to reuse those classes. There are two ways to solve this:
+
+- Create an attached jar with the _test-classes_ from the current project and loose its transitive `test`-scoped dependencies.
+- Create a separate project with the _test-classes_.
+
+The easy way
+------------
+
+You can produce a jar which will include your test classes and resources.
+
+```unknown
<project>
...
<build>
@@ -64,11 +52,11 @@ How to create a jar containing test classes
</build>
...
</project>
-+-----------------+
+```
- To reuse this artifact in an other project, you must declare this dependency with type test-jar :
+To reuse this artifact in an other project, you must declare this dependency with type test-jar :
-+-----------------+
+```unknown
<project>
...
<dependencies>
@@ -83,45 +71,32 @@ How to create a jar containing test classes
</dependencies>
...
</project>
-+-----------------+
-
- Based on such configuration there will be two jar files generated. The first one contains the
- classes from <<<src/main/java>>> whereas the second one will contain the classes from <<<src/test/java>>>.
- The generated jar files follow the naming schema <<<artifactId-version.jar>>> for the first one and
- <<<artifactId-version-classifier.jar>>> for the second one. The parts <<<artifactId>>>, <<<versions>>>
- will be replaced by the values given within your project <<<pom.xml>>> file. The <<<classifier>>>
- will be set to <<<tests>>> which is a default of the maven-jar-plugin which can be changed if you need by
- {{{../test-jar-mojo.html}using the configuration in the jar goal}}.
-
- <<Note:>> The downside of this solution is that you don't get the transitive <<<test>>>-scoped dependencies automatically.
- Maven only resolves the <<<compile>>>-time dependencies, so you'll have to add all the other required <<<test>>>-scoped dependencies by hand.
-
-* The preferred way
-
- In order to let Maven resolve all <<<test>>>-scoped transitive dependencies you should create a separate project.
-
-+-----------------+
+```
+
+Based on such configuration there will be two jar files generated. The first one contains the classes from `src/main/java` whereas the second one will contain the classes from `src/test/java`. The generated jar files follow the naming schema `artifactId-version.jar` for the first one and `artifactId-version-classifier.jar` for the second one. The parts `artifactId`, `versions` will be replaced by the values given within your project `pom.xml` file. The `classifier` will be set to `tests` [...]
+
+**Note:** The downside of this solution is that you don't get the transitive `test`-scoped dependencies automatically. Maven only resolves the `compile`-time dependencies, so you'll have to add all the other required `test`-scoped dependencies by hand.
+
+The preferred way
+-----------------
+
+In order to let Maven resolve all `test`-scoped transitive dependencies you should create a separate project.
+
+```unknown
<project>
<groupId>groupId</groupId>
<artifactId>artifactId-tests</artifactId>
<version>version</version>
...
</project>
-+-----------------+
-
- * Move the sources files from <<<src/test/java>>> you want to share from
- the original project to the <<<src/main/java>>> of this project.
- The same type of movement counts for the resources as well of course.
-
- * Move the required <<<test>>>-scoped dependencies from the original
- project to this project and remove the scope (i.e. changing it to the <<<compile>>>-scope).
- And yes, that means that the junit dependency (or any other testing
- framework dependency) gets the default scope too. You'll probably need
- to add some project specific dependencies as well to let it all compile again.
-
- Now you have your reusable <test-classes> and you can refer to it as you're used to:
-
-+-----------------+
+```
+
+- Move the sources files from `src/test/java` you want to share from the original project to the `src/main/java` of this project. The same type of movement counts for the resources as well of course.
+- Move the required `test`-scoped dependencies from the original project to this project and remove the scope (i.e. changing it to the `compile`-scope). And yes, that means that the junit dependency (or any other testing framework dependency) gets the default scope too. You'll probably need to add some project specific dependencies as well to let it all compile again.
+
+Now you have your reusable _test-classes_ and you can refer to it as you're used to:
+
+```unknown
<project>
...
<dependencies>
@@ -134,4 +109,4 @@ How to create a jar containing test classes
</dependencies>
...
</project>
-+-----------------+
+```
diff --git a/src/site/markdown/examples/include-exclude.md.vm b/src/site/markdown/examples/include-exclude.md.vm
index 79529c4..eabb6c5 100644
--- a/src/site/markdown/examples/include-exclude.md.vm
+++ b/src/site/markdown/examples/include-exclude.md.vm
@@ -1,38 +1,27 @@
- ------
- Howto include/exclude content from a jar archive
- ------
- Karl Heinz Marbaise
- ------
- 2014-06-16
- ------
-
- ~~ Licensed to the Apache Software Foundation (ASF) under one
- ~~ or more contributor license agreements. See the NOTICE file
- ~~ distributed with this work for additional information
- ~~ regarding copyright ownership. The ASF licenses this file
- ~~ to you under the Apache License, Version 2.0 (the
- ~~ "License"); you may not use this file except in compliance
- ~~ with the License. You may obtain a copy of the License at
- ~~
- ~~ http://www.apache.org/licenses/LICENSE-2.0
- ~~
- ~~ Unless required by applicable law or agreed to in writing,
- ~~ software distributed under the License is distributed on an
- ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- ~~ KIND, either express or implied. See the License for the
- ~~ specific language governing permissions and limitations
- ~~ under the License.
-
- ~~ NOTE: For help with the syntax of this file, see:
- ~~ http://maven.apache.org/doxia/references/apt-format.html
-
-How to include/exclude content from jar artifact
-
- Specify a list of fileset patterns to be included or excluded by adding
- <<<\<includes\>>>>/<<<\<include\>>>> or <<<\<excludes\>>>>/<<<\<exclude\>>>>
- in your <<<pom.xml>>>.
-
-+-----------------+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# How to include/exclude content from jar artifact
+
+Specify a list of fileset patterns to be included or excluded by adding `<includes>`/`<include>` or `<excludes>`/`<exclude>` in your `pom.xml`.
+
+```unknown
<project>
...
<build>
@@ -53,9 +42,6 @@ How to include/exclude content from jar artifact
</build>
...
</project>
-+-----------------+
-
- Note that the patterns need to be relative to the path specified for the plugin's
- <<<classesDirectory>>> parameter.
-
+```
+Note that the patterns need to be relative to the path specified for the plugin's `classesDirectory` parameter.
diff --git a/src/site/markdown/examples/manifest-customization.md.vm b/src/site/markdown/examples/manifest-customization.md.vm
index 9adc206..27a504b 100644
--- a/src/site/markdown/examples/manifest-customization.md.vm
+++ b/src/site/markdown/examples/manifest-customization.md.vm
@@ -1,52 +1,37 @@
- ------
- Manifest customization
- ------
- Dennis Lundberg
- ------
- 2006-07-12
- ------
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
- ~~ Licensed to the Apache Software Foundation (ASF) under one
- ~~ or more contributor license agreements. See the NOTICE file
- ~~ distributed with this work for additional information
- ~~ regarding copyright ownership. The ASF licenses this file
- ~~ to you under the Apache License, Version 2.0 (the
- ~~ "License"); you may not use this file except in compliance
- ~~ with the License. You may obtain a copy of the License at
- ~~
- ~~ http://www.apache.org/licenses/LICENSE-2.0
- ~~
- ~~ Unless required by applicable law or agreed to in writing,
- ~~ software distributed under the License is distributed on an
- ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- ~~ KIND, either express or implied. See the License for the
- ~~ specific language governing permissions and limitations
- ~~ under the License.
+http://www.apache.org/licenses/LICENSE-2.0
- ~~ NOTE: For help with the syntax of this file, see:
- ~~ http://maven.apache.org/doxia/references/apt-format.html
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
-Manifest customization
+# Manifest customization
-* The Default Manifest
+The Default Manifest
+--------------------
- The default contents of the manifest is described in the documentation for
- {{{/shared/maven-archiver/examples/manifest.html}Maven Archiver}}.
+The default contents of the manifest is described in the documentation for [Maven Archiver](/shared/maven-archiver/examples/manifest.html).
- Starting with version 2.1, the maven-jar-plugin uses Maven Archiver ${mavenArchiverVersion}. This
- means that it no longer creates the Specification and Implementation details
- in the manifest by default. If you want them you have to say so explicitly in
- your plugin configuration. This is also is described in the documentation for
- {{{/shared/maven-archiver/examples/manifest.html}Maven Archiver}}.
+Starting with version 2.1, the maven-jar-plugin uses Maven Archiver ${mavenArchiverVersion}. This means that it no longer creates the Specification and Implementation details in the manifest by default. If you want them you have to say so explicitly in your plugin configuration. This is also is described in the documentation for [Maven Archiver](/shared/maven-archiver/examples/manifest.html).
-* Customization the Manifest
+Customization the Manifest
+--------------------------
- The default manifest can be altered with the <<<archive>>> configuration
- element. Below you will find some of the configuration options that are
- available. For more info see the
- {{{/shared/maven-archiver/index.html}Maven Archiver reference}}.
+The default manifest can be altered with the `archive` configuration element. Below you will find some of the configuration options that are available. For more info see the [Maven Archiver reference](/shared/maven-archiver/index.html).
-+-----------------+
+```unknown
<project>
...
<build>
@@ -63,7 +48,7 @@ Manifest customization
</manifest>
<manifestEntries>
<mode>development</mode>
- <url>\${project.url}</url>
+ <url>${esc.d}{project.url}</url>
<key>value</key>
</manifestEntries>
</archive>
@@ -74,4 +59,4 @@ Manifest customization
</build>
...
</project>
-+-----------------+
+```
diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md
index 7cedcd4..493fca2 100644
--- a/src/site/markdown/index.md
+++ b/src/site/markdown/index.md
@@ -1,82 +1,50 @@
- ------
- Introduction
- ------
- Dennis Lundberg
- ------
- 2013-07-22
- ------
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
- ~~ Licensed to the Apache Software Foundation (ASF) under one
- ~~ or more contributor license agreements. See the NOTICE file
- ~~ distributed with this work for additional information
- ~~ regarding copyright ownership. The ASF licenses this file
- ~~ to you under the Apache License, Version 2.0 (the
- ~~ "License"); you may not use this file except in compliance
- ~~ with the License. You may obtain a copy of the License at
- ~~
- ~~ http://www.apache.org/licenses/LICENSE-2.0
- ~~
- ~~ Unless required by applicable law or agreed to in writing,
- ~~ software distributed under the License is distributed on an
- ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- ~~ KIND, either express or implied. See the License for the
- ~~ specific language governing permissions and limitations
- ~~ under the License.
+http://www.apache.org/licenses/LICENSE-2.0
- ~~ NOTE: For help with the syntax of this file, see:
- ~~ http://maven.apache.org/doxia/references/apt-format.html
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
-${project.name}
+# Apache Maven JAR Plugin
+This plugin provides the capability to build jars. To sign jars, use the [Maven Jarsigner Plugin](/plugins/maven-jarsigner-plugin/).
- This plugin provides the capability to build jars.
- To sign jars, use the
- {{{/plugins/maven-jarsigner-plugin/}Maven Jarsigner Plugin}}.
+## Goals Overview
-* Goals Overview
+- [jar:jar](./jar-mojo.html) create a jar file for your project classes inclusive resources.
+- [jar:test-jar](./test-jar-mojo.html) create a jar file for your project test classes .
+## Usage
- * {{{./jar-mojo.html}jar:jar}} create a jar file for your project classes inclusive resources.
+General instructions on how to use the JAR Plugin can be found on the [usage page](./usage.html). Some more specific use cases are described in the examples below.
- * {{{./test-jar-mojo.html}jar:test-jar}} create a jar file for your project test classes .
+In case you still have questions regarding the plugin's usage, please have a look at the [FAQ](./faq.html) and feel free to contact the [user mailing list](./mailing-lists.html). The posts to the mailing list are archived and could already contain the answer to your question as part of an older thread. Hence, it is also worth browsing/searching the [mail archive](./mailing-lists.html).
+If you feel like the plugin is missing a feature or has a defect, you can file a feature request or bug report in our [issue tracker](https://github.com/apache/maven-jar-plugin/issues). When creating a new issue, please provide a comprehensive description of your concern. Especially for fixing bugs it is crucial that the developers can reproduce your problem. For this reason, entire debug logs, POMs, or most preferably little demo projects attached to the issue are very much appreciated. [...]
-* Usage
+## Archiver Configuration
- General instructions on how to use the JAR Plugin can be found on the {{{./usage.html}usage page}}. Some more
- specific use cases are described in the examples below.
+The plugin uses Maven Archiver to handle jar content and manifest configuration.
- In case you still have questions regarding the plugin's usage, please have a look at the {{{./faq.html}FAQ}} and feel
- free to contact the {{{./mailing-lists.html}user mailing list}}. The posts to the mailing list are archived and could
- already contain the answer to your question as part of an older thread. Hence, it is also worth browsing/searching
- the {{{./mailing-lists.html}mail archive}}.
+You can have a look at the [Maven Archiver Documentation](/shared/maven-archiver/) to understand how to setup this.
- If you feel like the plugin is missing a feature or has a defect, you can file a feature request or bug report in our
- {{{https://github.com/apache/maven-jar-plugin/issues}issue tracker}}. When creating a new issue, please provide a comprehensive description of your
- concern. Especially for fixing bugs it is crucial that the developers can reproduce your problem. For this reason,
- entire debug logs, POMs, or most preferably little demo projects attached to the issue are very much appreciated.
- Of course, patches are welcome, too. Contributors can check out the project from our
- {{{./scm.html}source repository}} and will find supplementary information in the
- {{{http://maven.apache.org/guides/development/guide-helping.html}guide to helping with Maven}}.
+You might also want to consult the [Guide to Working with Manifests](/guides/mini/guide-manifest.html).
-* Archiver Configuration
+## Examples
- The plugin uses Maven Archiver to handle jar content and manifest configuration.
+To provide you with better understanding of some usages of the JAR Plugin, you can take a look at the following examples:
- You can have a look at the {{{/shared/maven-archiver/}Maven Archiver Documentation}} to understand how to setup this.
-
- You might also want to consult the {{{/guides/mini/guide-manifest.html}Guide
- to Working with Manifests}}.
-
-* Examples
-
- To provide you with better understanding of some usages of the JAR Plugin,
- you can take a look at the following examples:
-
- * {{{./examples/manifest-customization.html}Manifest Customization}}
-
- * {{{./examples/include-exclude.html}Howto include/exclude Content from a jar archive}}
-
- * {{{./examples/attached-jar.html}How to create an additional attached jar artifact from the project}}
-
- * {{{./examples/create-test-jar.html}How to create a jar containing test classes}}
-
- []
+- [Manifest Customization](./examples/manifest-customization.html)
+- [Howto include/exclude Content from a jar archive](./examples/include-exclude.html)
+- [How to create an additional attached jar artifact from the project](./examples/attached-jar.html)
+- [How to create a jar containing test classes](./examples/create-test-jar.html)
diff --git a/src/site/markdown/usage.md.vm b/src/site/markdown/usage.md.vm
index ee7284b..0329253 100644
--- a/src/site/markdown/usage.md.vm
+++ b/src/site/markdown/usage.md.vm
@@ -1,53 +1,36 @@
- ------
- Usage
- ------
- Jerome Lacoste
- Dennis Lundberg
- Olivier Lamy
- Karl Heinz Marbaise
- ------
- 2016-06-03
- ------
-
- ~~ Licensed to the Apache Software Foundation (ASF) under one
- ~~ or more contributor license agreements. See the NOTICE file
- ~~ distributed with this work for additional information
- ~~ regarding copyright ownership. The ASF licenses this file
- ~~ to you under the Apache License, Version 2.0 (the
- ~~ "License"); you may not use this file except in compliance
- ~~ with the License. You may obtain a copy of the License at
- ~~
- ~~ http://www.apache.org/licenses/LICENSE-2.0
- ~~
- ~~ Unless required by applicable law or agreed to in writing,
- ~~ software distributed under the License is distributed on an
- ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- ~~ KIND, either express or implied. See the License for the
- ~~ specific language governing permissions and limitations
- ~~ under the License.
-
- ~~ NOTE: For help with the syntax of this file, see:
- ~~ http://maven.apache.org/doxia/references/apt-format.html
-
-Usage
-
- Some brief examples on how to use this plugin. If you want to use advanced
- configurations you should have a look at the
- {{{./index.html#Examples}Example section}}.
- documentation for
- {{{/shared/maven-archiver/}Maven Archiver}}.
-
- To handle archiving this version of Maven JAR Plugin uses
- {{{/shared/maven-archiver/index.html}Maven Archiver}} ${mavenArchiverVersion}.
-
- <<Note:>> If you need to sign your JAR files you should use the
- {{{/plugins/maven-jarsigner-plugin/}Maven Jarsigner Plugin}} instead.
-
-* How to build a JAR file
-
- When you want to create a JAR-file with Maven, you first have to create a <<<pom.xml>>>-file with at least the following content:
-
-+----------+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Usage
+
+Some brief examples on how to use this plugin. If you want to use advanced configurations you should have a look at the [Example section](./index.html#Examples). documentation for [Maven Archiver](/shared/maven-archiver/).
+
+To handle archiving this version of Maven JAR Plugin uses [Maven Archiver](/shared/maven-archiver/index.html) ${mavenArchiverVersion}.
+
+**Note:** If you need to sign your JAR files you should use the [Maven Jarsigner Plugin](/plugins/maven-jarsigner-plugin/) instead.
+
+How to build a JAR file
+-----------------------
+
+When you want to create a JAR-file with Maven, you first have to create a `pom.xml`-file with at least the following content:
+
+```unknown
<project>
<modelVersion>4.0.0</modelVersion>
@@ -56,44 +39,25 @@ Usage
<version>1.0-SNAPSHOT</version>
<!-- <packaging>jar</packaging> -->
</project>
-+----------+
-
- Since 'jar' is the default packaging type it is not required to set it in this case.
- Apart from the above you will normally want some real java source files which should be located within
- <<<src/main/java>>>. If you need extra resources on your classpath (for example property files)
- they should be located in <<<src/main/resources>>>.
- Now we can create a JAR-file by using the command below:
+```
+
+Since 'jar' is the default packaging type it is not required to set it in this case. Apart from the above you will normally want some real java source files which should be located within `src/main/java`. If you need extra resources on your classpath (for example property files) they should be located in `src/main/resources`. Now we can create a JAR-file by using the command below:
-+-----------------+
+```unknown
mvn package
-+-----------------+
+```
- The 'package' phase is always responsible for bundling all the files in the artifact, in this case a JAR-file.
+The 'package' phase is always responsible for bundling all the files in the artifact, in this case a JAR-file.
- In your project's <<<target>>> directory you'll see the generated jar file which is named like:
- 'core-1.0-SNAPSHOT.jar'. The resulting 'jar' file contains the compiled java class files as well as
- the files from <<<src/main/resources>>>.
+In your project's `target` directory you'll see the generated jar file which is named like: 'core-1.0-SNAPSHOT.jar'. The resulting 'jar' file contains the compiled java class files as well as the files from `src/main/resources`.
- Usually there is no need to mentioned the 'maven-jar-plugin' explicit cause it's bound to
- the {{{/guides/introduction/introduction-to-the-lifecycle.html}Maven Build Life Cycle}}.
+Usually there is no need to mentioned the 'maven-jar-plugin' explicit cause it's bound to the [Maven Build Life Cycle](/guides/introduction/introduction-to-the-lifecycle.html).
- For full documentation, click {{{./plugin-info.html}here}}.
+For full documentation, click [here](./plugin-info.html).
-* Modular JAR files
+Modular JAR files
+-----------------
- The {{{https://openjdk.java.net/projects/jigsaw/spec/}Java Platform Module System (JPMS)}} introduced
- {{{https://cr.openjdk.java.net/~mr/jigsaw/spec/jar.html}changes in the JAR file specifications}}
- as well - Modular JAR files. Modular JAR files are JAR files with <<<module-info.class>>> file in the root directory
- (or in the versioned area for multi-release JAR files). If the project contains <<<module-info.class>>>
- the resulting JAR will be a Modular JAR without a need for any configuration regardless of the plugin version used.
+The [Java Platform Module System (JPMS)](https://openjdk.java.net/projects/jigsaw/spec/) introduced [changes in the JAR file specifications](https://cr.openjdk.java.net/~mr/jigsaw/spec/jar.html) as well - Modular JAR files. Modular JAR files are JAR files with `module-info.class` file in the root directory (or in the versioned area for multi-release JAR files). If the project contains `module-info.class` the resulting JAR will be a Modular JAR without a need for any configuration regardl [...]
- Starting with version 3.1.2, if the JAR file contains <<<module-info.class>>>, this plugin will update
- the modular descriptor (<<<module-info.class>>>) with additional attributes such as the list of packages included
- and will validate the resulting modular descriptor (for example if all services provided by the module are actually
- included in the JAR file). The most notable additional attribute added is the module main class.
- If the JAR manifest contains <<<Main-Class>>> attribute this plugin will set the module main class to the same value
- (for example how to set it read {{{../../shared/maven-archiver/examples/classpath.html}Make The Jar Executable}}).
- Internally the plugin uses the JDK <<<jar>>> tool so in order to add the additional attributes and to
- verify the modular descriptor Maven should be run with JDK version 9 or newer. If version 8 or earlier is used
- the resulting JAR still will be Modular JAR (as it contains <<<module-info.class>>>) but no additional attributes
- will be added and no validation will be performed.
+Starting with version 3.1.2, if the JAR file contains `module-info.class`, this plugin will update the modular descriptor (`module-info.class`) with additional attributes such as the list of packages included and will validate the resulting modular descriptor (for example if all services provided by the module are actually included in the JAR file). The most notable additional attribute added is the module main class. If the JAR manifest contains `Main-Class` attribute this plugin will s [...]