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-site.git
commit c61f169da8c9f947518ebd810975f8af9ea46e23 Author: Sylwester Lachiewicz <[email protected]> AuthorDate: Sat Feb 18 21:35:07 2023 +0100 Revert "[MNGSITE-507] [DOXIA-692] Improve conversion results" This reverts commit 45492f24ab507b20750769901c777ea00979c4a5. --- .../maven-2.x/maven-2.1-architectural-goals.md | 2 +- content/markdown/developers/compatibility-plan.md | 6 +- content/markdown/developers/conventions/code.md | 16 ++--- content/markdown/developers/conventions/git.md | 2 +- content/markdown/developers/dependency-policies.md | 2 +- content/markdown/developers/index.md | 2 +- .../release/maven-project-release-procedure.md | 18 +++--- .../markdown/developers/release/pmc-gpg-keys.md | 2 +- .../markdown/developers/retirement-plan-plugins.md | 6 +- .../deploy-component-reference-documentation.md | 4 +- content/markdown/faq-unoffical.md | 2 +- .../guides/development/guide-committer-school.md | 14 ++--- .../development/guide-documentation-style.md | 4 +- .../guides/development/guide-maven-development.md | 2 +- .../development/guide-plugin-documentation.md | 32 +++++----- .../guide-testing-development-plugins.md | 2 +- .../guides/development/guide-testing-releases.md | 24 ++++---- content/markdown/guides/getting-started/index.md | 12 ++-- .../introduction-to-dependency-mechanism.md | 4 +- ...uction-to-optional-and-excludes-dependencies.md | 6 +- .../guides/introduction/introduction-to-plugins.md | 2 +- .../introduction/introduction-to-profiles.md | 72 +++++++++++----------- .../introduction/introduction-to-the-lifecycle.md | 10 +-- .../guides/introduction/introduction-to-the-pom.md | 6 +- .../guides/mini/guide-configuring-maven.md | 10 +-- .../guides/mini/guide-configuring-plugins.md | 64 +++++++++---------- .../guides/mini/guide-creating-archetypes.md | 6 +- .../guides/mini/guide-default-execution-ids.md | 2 +- .../markdown/guides/mini/guide-http-settings.md | 18 +++--- .../guide-large-scale-centralized-deployments.md | 8 +-- .../guides/mini/guide-maven-classloading.md | 4 +- .../markdown/guides/mini/guide-mirror-settings.md | 16 ++--- .../markdown/guides/mini/guide-multiple-modules.md | 2 +- content/markdown/guides/mini/guide-proxies.md | 2 +- content/markdown/guides/mini/guide-releasing.md | 2 +- content/markdown/guides/mini/guide-relocation.md | 4 +- .../guides/mini/guide-reproducible-builds.md | 6 +- content/markdown/guides/mini/guide-site.md | 10 +-- .../markdown/guides/mini/guide-using-extensions.md | 2 +- .../markdown/guides/mini/guide-using-toolchains.md | 4 +- .../markdown/guides/mini/guide-wagon-providers.md | 10 +-- .../guides/plugin/guide-java-plugin-development.md | 4 +- .../plugin/guide-java-report-plugin-development.md | 4 +- content/markdown/maven-jsr330.md | 16 ++--- content/markdown/maven-logging.md | 2 +- content/markdown/plugin-developers/common-bugs.md | 14 ++--- .../cookbook/plexus-plugin-upgrade.md | 2 +- .../plugin-developers/plugin-documenting.md | 2 +- .../markdown/plugin-developers/plugin-testing.md | 4 +- content/markdown/plugins/index.md | 4 +- content/markdown/plugins/localization.md | 8 +-- content/markdown/repository/central-index.md | 2 +- content/markdown/settings.md | 2 +- 53 files changed, 243 insertions(+), 243 deletions(-) diff --git a/content/markdown/archives/maven-2.x/maven-2.1-architectural-goals.md b/content/markdown/archives/maven-2.x/maven-2.1-architectural-goals.md index 7c73f05e..0f0bba15 100644 --- a/content/markdown/archives/maven-2.x/maven-2.1-architectural-goals.md +++ b/content/markdown/archives/maven-2.x/maven-2.1-architectural-goals.md @@ -71,7 +71,7 @@ About this specific issue (MNG-3012): The best solution is to only share java., There's one more solution to consider; using ASM to rewrite plugins as they're loaded. We could add code modifiers that workaround incompatibilities by detecting usage patterns, like (Xpp3Dom) plugin.getConfiguration(). An example could be to modify the code to wrap Xpp3DomParser.parse( new StringReader( String.valueOf( /plugin.getConfiguration()/ ) ) ) around the call. This is even more of a hack though. Perhaps a mojo that scans for plugin incompatibilities using ASM is more feasible [...] -So the basic problem we're up against is that there can be core api changes between major versions that pose incompatibilities for plugins written against an older version. The simplest solution would be to let plugins specify the maven versions they work against (which is partly present: `<requires><mavenVersion>2.0.6</mavenVersion></requires>`. If this field supports a versionrange, or we'd default the version interpretation above to mean [2.0.6,2.1), we can detect plugins that won't r [...] +So the basic problem we're up against is that there can be core api changes between major versions that pose incompatibilities for plugins written against an older version. The simplest solution would be to let plugins specify the maven versions they work against (which is partly present: <requires><mavenVersion>2.0.6</mavenVersion></requires>. If this field supports a versionrange, or we'd default the version interpretation above to mean [2.0.6,2.1), we can detect plugins that won't run [...] h3. Strategies for ensuring backward compatibility diff --git a/content/markdown/developers/compatibility-plan.md b/content/markdown/developers/compatibility-plan.md index 37d42df5..61d372f1 100644 --- a/content/markdown/developers/compatibility-plan.md +++ b/content/markdown/developers/compatibility-plan.md @@ -47,11 +47,11 @@ under the License. - - Until 2012, Maven 2.2.1 + Java 5 prerequisites, with plugins versions in 2.x + - Until 2012, Maven 2.2.1 \+ Java 5 prerequisites, with plugins versions in 2.x - - Since 2012, Maven 3.0 + Java 7 prerequisites, with plugins in 3.x.y + - Since 2012, Maven 3.0 \+ Java 7 prerequisites, with plugins in 3.x.y - - Since June 2020, Maven Plugin API used by plugins >= 3.1.0 + Java 8 prerequisites [Technical details](https://s.apache.org/MVN-PLUGIN-MIGRATION-3.1) + - Since June 2020, Maven Plugin API used by plugins \>\= 3.1.0 \+ Java 8 prerequisites [Technical details](https://s.apache.org/MVN-PLUGIN-MIGRATION-3.1) diff --git a/content/markdown/developers/conventions/code.md b/content/markdown/developers/conventions/code.md index 0e2a3ec6..729dd2d7 100644 --- a/content/markdown/developers/conventions/code.md +++ b/content/markdown/developers/conventions/code.md @@ -27,7 +27,7 @@ under the License. As the formatting is automatically enforced or even applied with [spotless-maven-plugin](https://github.com/diffplug/spotless/tree/main/plugin-maven) for all projects using [Maven Project Parent POM 38 or newer](/pom/maven/index.html) developers usually don't need to care and the following sections are just for informational purposes. - Optionally you can still import the code style formatter for your IDE from [shared-resources](https://gitbox.apache.org/repos/asf?p=maven-shared-resources.git;a=tree;f=src/main/resources/config;hb=HEAD) + Optionally you can still import the code style formatter for your IDE from [shared-resources](https://gitbox.apache.org/repos/asf?p\=maven-shared-resources.git;a\=tree;f\=src/main/resources/config;hb\=HEAD) - [Generic Code Style And Convention](Generic_Code_Style_And_Convention) @@ -134,7 +134,7 @@ under the License. all imports in each group should be sorted alphabetically. - To ensure a package import order consistent with the layout described above, download `[maven-eclipse-importorder.txt](https://gitbox.apache.org/repos/asf?p=maven-shared-resources.git;a=blob_plain;f=src/main/resources/config/maven-eclipse-importorder.txt;hb=HEAD)`, select _Window \> Preferences_ and navigate to _Java \> Code Style \> Organize Imports_. Click on _Import..._ and select the downloaded file to change the import order. + To ensure a package import order consistent with the layout described above, download `[maven-eclipse-importorder.txt](https://gitbox.apache.org/repos/asf?p\=maven-shared-resources.git;a\=blob_plain;f\=src/main/resources/config/maven-eclipse-importorder.txt;hb\=HEAD)`, select _Window \> Preferences_ and navigate to _Java \> Code Style \> Organize Imports_. Click on _Import..._ and select the downloaded file to change the import order. @@ -262,11 +262,11 @@ under the License. - 1 The `<project>` element is always on one line. + 1 The \<project/\> element is always on one line. - 1 The blocks are voluntary separated by a new line to improve the readiness. + 1 The blocks are voluntary separated by a new line to improve the readingness. - 1 The dependencies in `<dependencies>` and `<dependencyManagement>` tags have no specific ordering. Developers are free to choose the ordering, but grouping dependencies by topics (like groupId i.e. `org.apache.maven`) is a good practice. + 1 The dependencies in \<dependencies/\> and \<dependencyManagement/\> tags have no specific ordering. Developers are free to choose the ordering, but grouping dependencies by topics (like groupId i.e. `org.apache.maven`) is a good practice. @@ -277,9 +277,9 @@ under the License. - - **Metadata**: Always specify metadata in the `<properties>` tag. + - **Metadata**: Always specify metadata in the \<properties/\> tag. - - **Sections**: Always use a new line with indentation for `<section>` tags. + - **Sections**: Always use a new line with indentation for \<section/\> tags. @@ -290,7 +290,7 @@ under the License. - - **FAQ**: Always use a new line with indentation for `<faq>` tags. + - **FAQ**: Always use a new line with indentation for \<faq/\> tags. <!-- * {APT} Do we need any specific APT style/convention? --> diff --git a/content/markdown/developers/conventions/git.md b/content/markdown/developers/conventions/git.md index de40447b..c12e309a 100644 --- a/content/markdown/developers/conventions/git.md +++ b/content/markdown/developers/conventions/git.md @@ -33,7 +33,7 @@ under the License. #### For contributors who are not committers - Apache git repositories are at _git://git.apache.org_. However, the ASF uses clones on github.com to make it easier for people to contribute changes via pull requests. + Apache git repositories are at _ \<\<git://git.apache.org_\>\>. However, the ASF uses clones on github.com to make it easier for people to contribute changes via pull requests. To contribute to a Maven component that is maintained in git, please follow these steps: diff --git a/content/markdown/developers/dependency-policies.md b/content/markdown/developers/dependency-policies.md index 064a45ff..270982d1 100644 --- a/content/markdown/developers/dependency-policies.md +++ b/content/markdown/developers/dependency-policies.md @@ -30,7 +30,7 @@ under the License. This page describes the policies around the use of dependencies by the Apache Maven Developers in the process of developing Apache Maven itself. - This page does not apply to projects hosted outside of the Apache Maven project. In order to remove all doubt, this page only applies to code which has a Github URL that starts with `https://github.com/apache/maven` or a Gitbox URL starting with `https://gitbox.apache.org/repos/asf?p=maven` + This page does not apply to projects hosted outside of the Apache Maven project. In order to remove all doubt, this page only applies to code which has a Github URL that starts with `https://github.com/apache/maven` or a Gitbox URL starting with `https://gitbox.apache.org/repos/asf?p\=maven` If you have stumbled across this page and you are working on code that does not have a Github URL starting with `https://github.com/apache/maven` then this page does not apply to you. diff --git a/content/markdown/developers/index.md b/content/markdown/developers/index.md index 32526fe3..d90d75b7 100644 --- a/content/markdown/developers/index.md +++ b/content/markdown/developers/index.md @@ -69,7 +69,7 @@ under the License. - [Maven Plugins and Components Compatibility Plan](./compatibility-plan.html) - - [Maven Proposals/Backlog](https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=5964567) + - [Maven Proposals/Backlog](https://cwiki.apache.org/confluence/pages/viewpage.action?pageId\=5964567) diff --git a/content/markdown/developers/release/maven-project-release-procedure.md b/content/markdown/developers/release/maven-project-release-procedure.md index 8709bbc2..0e66306a 100644 --- a/content/markdown/developers/release/maven-project-release-procedure.md +++ b/content/markdown/developers/release/maven-project-release-procedure.md @@ -35,11 +35,11 @@ under the License. - you have a recent Git client installed and on your shell's path. - - you have JDK 8 installed and on your shell's path to build Maven 3.7.0+. Details about minimum JDK version to build an appropriate version can be found here: [https://maven.apache.org/docs/history.html](/docs/history.html) + - you have JDK 8 installed and on your shell's path to build Maven 3.7.0\+. Details about minimum JDK version to build an appropriate version can be found here: [https://maven.apache.org/docs/history.html](/docs/history.html) - - if you receive an OutOfMemoryError during the build, make sure to have set the environment variable `MAVEN_OPTS=-Xmx512m` + - if you receive an OutOfMemoryError during the build, make sure to have set the environment variable `MAVEN_OPTS\=-Xmx512m` - - you must use Maven 3.3.9+. + - you must use Maven 3.3.9\+. - follow Apache environment configuration steps outlined at: [Publishing Maven Artifacts](https://www.apache.org/dev/publishing-maven-artifacts.html#dev-env). @@ -133,7 +133,7 @@ Vote open for at least 72 hours. To get the list of issues left in JIRA, browse to the plugin's or component's JIRA page, and from the _Preset Filters_ on the right, use the link for _Outstanding_ issues. - The vote is open for at least 72 hours means, that you need to wait at least 72 hours before proceeding. This gives others time to test your release and check that everything is good. If you have received after that not enough +1 votes to reach the quorum, this doesn't mean, the vote failed. It just takes a bit longer. + The vote is open for at least 72 hours means, that you need to wait at least 72 hours before proceeding. This gives others time to test your release and check that everything is good. If you have received after that not enough \+1 votes to reach the quorum, this doesn't mean, the vote failed. It just takes a bit longer. @@ -209,18 +209,18 @@ The vote has been canceled. - drop your staging repository as described in [Drop a repository](https://www.apache.org/dev/publishing-maven-artifacts.html) - - create new version for next round `Y.Z+1` + - create new version for next round `Y.Z\+1` - - assign issues from version `Y.Z` also to version `Y.Z+1` + - assign issues from version `Y.Z` also to version `Y.Z\+1` - mark the `Y.Z` version as **archived** - - report found issues and assign them to version `Y.Z+1` + - report found issues and assign them to version `Y.Z\+1` - fix found issues - Start the process for version `Y.Z+1` from the beginning. + Start the process for version `Y.Z\+1` from the beginning. @@ -287,7 +287,7 @@ wagon/wagon-2.2-source-release.zip.sha512 1 Update the version tracking in JIRA - In the relevant project, go to Administration, then Versions. Mark the `Y.Z` version as 'released'. Create version `Y.Z+1`, if that hasn't already been done. You may also archive any deprecated releases (milestones or alphas) at this time. + In the relevant project, go to Administration, then Versions. Mark the `Y.Z` version as 'released'. Create version `Y.Z\+1`, if that hasn't already been done. You may also archive any deprecated releases (milestones or alphas) at this time. diff --git a/content/markdown/developers/release/pmc-gpg-keys.md b/content/markdown/developers/release/pmc-gpg-keys.md index a235cdf2..4d7d3351 100644 --- a/content/markdown/developers/release/pmc-gpg-keys.md +++ b/content/markdown/developers/release/pmc-gpg-keys.md @@ -129,7 +129,7 @@ sig 07DDB702 2006-10-10 Vincent Siveton <[email protected]> -## mQGiBEUrnAsRBACQDiYGc1IQmkENLO9iznBg8otGPEbzqQozT5tsip5mB30f6Mc/ uuLxJkLdna7Ul3goIXDtCeLJq38gHvruNtVNR6S+juJFkd5sLEH8UJ18PbKuo/9I KGlzjtCYUUDC48czRr0efhqd54NH8ydNdpaZ76NGPPYfpXtk7kKgH/nPiwCgxozK IG2frMuWIvdFafbqdAl7y/sD/1Csf0r9jtHEeXOuyhm8jCGrSwzLbHUGKPUQP37P ajECHoWp6HnvHEEEpgVl+UjfZvrcVhzUoP+3r5HAugqERfkzK8AWc7qjIRjf64kU sjvto31G2KYz17Y8K9y4LkRkUspu8uw903pKnW/QELg4vvPVaEYpVVIdS6+cUreu V0hOA/4tW7T/GpzSbQmjvnIRQ7GVHbQeXsANwrS6NmGYIxafN9P9dfHV+eUieTu6 rvMP9coOhTYyEKZksrXw2MmXx5SzgxsXT0 [...] +## mQGiBEUrnAsRBACQDiYGc1IQmkENLO9iznBg8otGPEbzqQozT5tsip5mB30f6Mc/ uuLxJkLdna7Ul3goIXDtCeLJq38gHvruNtVNR6S\+juJFkd5sLEH8UJ18PbKuo/9I KGlzjtCYUUDC48czRr0efhqd54NH8ydNdpaZ76NGPPYfpXtk7kKgH/nPiwCgxozK IG2frMuWIvdFafbqdAl7y/sD/1Csf0r9jtHEeXOuyhm8jCGrSwzLbHUGKPUQP37P ajECHoWp6HnvHEEEpgVl\+UjfZvrcVhzUoP\+3r5HAugqERfkzK8AWc7qjIRjf64kU sjvto31G2KYz17Y8K9y4LkRkUspu8uw903pKnW/QELg4vvPVaEYpVVIdS6\+cUreu V0hOA/4tW7T/GpzSbQmjvnIRQ7GVHbQeXsANwrS6NmGYIxafN9P9dfHV\+eUieTu6 rvMP9coOhTYyEKZksrXw2MmXx5Szg [...] You need to append this result to [https://svn.apache.org/repos/asf/maven/project/KEYS](https://svn.apache.org/repos/asf/maven/project/KEYS). diff --git a/content/markdown/developers/retirement-plan-plugins.md b/content/markdown/developers/retirement-plan-plugins.md index 77bbec25..c0cdd1b0 100644 --- a/content/markdown/developers/retirement-plan-plugins.md +++ b/content/markdown/developers/retirement-plan-plugins.md @@ -118,13 +118,13 @@ but has moved to the <Organization> <Project> project. ``` - 1 Add " (RETIRED)" at the end of `<project> <name>` in the plugin's `pom.xml`. This will show up on every page of the generated site. + 1 Add " (RETIRED)" at the end of `\<project\>`/`\<name\>` in the plugin's `pom.xml`. This will show up on every page of the generated site. 1 Go ahead with [the standard release process](./release/maven-project-release-procedure.html), making sure that you follow the exceptions mentioned above regarding the site deployment. 1 When updating the plugins page, move Maven Foo Plugin to under the "Retired" heading. Remove the SVN and JIRA links and add the date of retirement. - 1 When updating the version in JIRA, do not add Y.Z+1 and make sure you remove any future versions. + 1 When updating the version in JIRA, do not add Y.Z\+1 and make sure you remove any future versions. @@ -134,7 +134,7 @@ but has moved to the <Organization> <Project> project. 1 Remove the `.Jenkinsfile` from all branches. This will remove the project from https://builds.apache.org/job/maven-box/ - 1 Ask INFRA for archive git repos (gitbox + github) + 1 Ask INFRA for archive git repos (gitbox \+ github) 1 Republish documentation, postfix project name with (RETIRED) diff --git a/content/markdown/developers/website/deploy-component-reference-documentation.md b/content/markdown/developers/website/deploy-component-reference-documentation.md index 91c20a34..bd735ded 100644 --- a/content/markdown/developers/website/deploy-component-reference-documentation.md +++ b/content/markdown/developers/website/deploy-component-reference-documentation.md @@ -27,7 +27,7 @@ under the License. This document gives step-by-step instructions for deploying Maven components reference documentation inside the Maven [https://maven.apache.org/](/) website. - See [Maven website introduction](./index.html) for instructions on the whole website publication (main site content + components). + See [Maven website introduction](./index.html) for instructions on the whole website publication (main site content \+ components). @@ -95,7 +95,7 @@ mvn scm-publish:publish-scm - **Notice**: content is in fact published to [/components/](/components/) directory, and symbolic links declared in `resources/\*\*/components.links` in main site source are used by Ant to create a reference from `/xxx` (= what we want to be user-visible) to `/components/xxx` (what what is checked out). + **Notice**: content is in fact published to [/components/](/components/) directory, and symbolic links declared in `resources/\*\*/components.links` in main site source are used by Ant to create a reference from `/xxx` (\= what we want to be user-visible) to `/components/xxx` (what what is checked out). diff --git a/content/markdown/faq-unoffical.md b/content/markdown/faq-unoffical.md index b4d3f0bd..2ca5e6a5 100644 --- a/content/markdown/faq-unoffical.md +++ b/content/markdown/faq-unoffical.md @@ -1880,7 +1880,7 @@ To store stuff that is not in ibiblio. An example of this is your own stuff. ### Whenever a file is modified in a maven project how is the SNAPSHOT jar updated in the remote repository? -Using mvn deploy, after inserting proper `<distributionManagement>` section into your POM +Using mvn deploy, after inserting proper <distributionManagement/> section into your POM ### Is maven 'deploy' goal and actually copying of a dependency or artifact jar to remote repository same? diff --git a/content/markdown/guides/development/guide-committer-school.md b/content/markdown/guides/development/guide-committer-school.md index 507f92dd..b7cc4072 100644 --- a/content/markdown/guides/development/guide-committer-school.md +++ b/content/markdown/guides/development/guide-committer-school.md @@ -70,19 +70,19 @@ password - 1 I look at the actual diff, if there is a whole lot of formatting changes irrelevant to the issue being fixed => **Patch is no good, ask on JIRA for a clean patch** + 1 I look at the actual diff, if there is a whole lot of formatting changes irrelevant to the issue being fixed \=\> **Patch is no good, ask on JIRA for a clean patch** - 1 I look at the list of files in the diff, if there are no tests => **Patch is no good, ask on JIRA for test cases** + 1 I look at the list of files in the diff, if there are no tests \=\> **Patch is no good, ask on JIRA for test cases** - 1 I look at the issue and if the issue requires documentation be updated and there is no documentation changes in the patch => **Patch is no good, ask on JIRA for documentation changes in the patch** + 1 I look at the issue and if the issue requires documentation be updated and there is no documentation changes in the patch \=\> **Patch is no good, ask on JIRA for documentation changes in the patch** - 1 I take a clean checkout of the source that the patch applies to and try to apply the patch... if it does not apply clean => **Patch is no good, ask on JIRA for an updated patch** + 1 I take a clean checkout of the source that the patch applies to and try to apply the patch... if it does not apply clean \=\> **Patch is no good, ask on JIRA for an updated patch** - 1 I revert the src/main and run the tests. If the tests all pass, then there are no test cases to catch the bug => **Patch is no good, ask on JIRA for proper tests** + 1 I revert the src/main and run the tests. If the tests all pass, then there are no test cases to catch the bug \=\> **Patch is no good, ask on JIRA for proper tests** - 1 I revert src and run the tests. If any tests fail, then there is something wrong with the existing code => **If I have time I might try and fix the issue, otherwise I just move on** + 1 I revert src and run the tests. If any tests fail, then there is something wrong with the existing code \=\> **If I have time I might try and fix the issue, otherwise I just move on** - 1 I apply the patch a second time and run the tests. If the tests all pass => **Patch is good, I commit the patch and mark the JIRA as resolved** + 1 I apply the patch a second time and run the tests. If the tests all pass \=\> **Patch is good, I commit the patch and mark the JIRA as resolved** So there you have it, my guide to writing good patches... now the next step is getting your patches noticed... diff --git a/content/markdown/guides/development/guide-documentation-style.md b/content/markdown/guides/development/guide-documentation-style.md index 8d83b9b6..0b3deb72 100644 --- a/content/markdown/guides/development/guide-documentation-style.md +++ b/content/markdown/guides/development/guide-documentation-style.md @@ -69,7 +69,7 @@ under the License. - [W3C Quality Web Tips](http://www.w3.org/QA/Tips/iso-date) - - [ISO-8601](http://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=26780) + - [ISO-8601](http://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber\=26780) - [Wikipedia](http://en.wikipedia.org/wiki/ISO_8601) @@ -109,7 +109,7 @@ under the License. </project> ``` - As you can see above the `<distributionManagement>` element is indented once (=2 spaces), the `<site>` element is indented twice (=4 spaces), and the `<id>` is indented three times (=6 spaces). + As you can see above the `\<distributionManagement\>` element is indented once (\=2 spaces), the `\<site\>` element is indented twice (\=4 spaces), and the `\<id\>` is indented three times (\=6 spaces). diff --git a/content/markdown/guides/development/guide-maven-development.md b/content/markdown/guides/development/guide-maven-development.md index 0411186b..a216fe7f 100644 --- a/content/markdown/guides/development/guide-maven-development.md +++ b/content/markdown/guides/development/guide-maven-development.md @@ -74,7 +74,7 @@ under the License. - If this was a new piece of work without a JIRA issue, create a JIRA issue for it now. - - Name the branch after the issue number; the branch name would start with `<jira-project-id>-<ticket-id>`. + - Name the branch after the issue number; the branch name would start with `\<jira-project-id\>-\<ticket-id\>`. - Push your branch with the commit(s) to your fork. diff --git a/content/markdown/guides/development/guide-plugin-documentation.md b/content/markdown/guides/development/guide-plugin-documentation.md index 24d4b3d3..d7706458 100644 --- a/content/markdown/guides/development/guide-plugin-documentation.md +++ b/content/markdown/guides/development/guide-plugin-documentation.md @@ -68,15 +68,15 @@ mvn site - - `<modelVersion>` - POM model version, currently 4.0.0 + - `\<modelVersion\>` - POM model version, currently 4.0.0 - - `<groupId>` - the package name + - `\<groupId\>` - the package name - - `<artifactId>` - artifact name + - `\<artifactId\>` - artifact name - - `<packaging>` - type of artifact produced by the POM + - `\<packaging\>` - type of artifact produced by the POM - - `<version>` - the plugin version + - `\<version\>` - the plugin version @@ -87,15 +87,15 @@ mvn site - - `<name>` - plugin's name, _Maven NNN Plugin_ for plugins hosted at the Maven project or _NNN Maven Plugin_ for all others + - `\<name\>` - plugin's name, _Maven NNN Plugin_ for plugins hosted at the Maven project or _NNN Maven Plugin_ for all others - - `<description>` - project description, an overview of what the plugin can do + - `\<description\>` - project description, an overview of what the plugin can do - - `<url>` - the site of the plugin, normally _maven.apache.org_ or _org.mojohaus_ + - `\<url\>` - the site of the plugin, normally _maven.apache.org_ or _org.mojohaus_ - - `<prerequisites>` - the minimum version of Maven required to use this plugin + - `\<prerequisites\>` - the minimum version of Maven required to use this plugin - - `<issueManagement>` - describes the system used for reporting problems and modification requests + - `\<issueManagement\>` - describes the system used for reporting problems and modification requests ``` <project> @@ -109,9 +109,9 @@ mvn site ``` - - `<inceptionYear>` - year the plugin was first created + - `\<inceptionYear\>` - year the plugin was first created - - `<mailingLists>` - lists where other users or the developers can be contacted for help and discussions + - `\<mailingLists\>` - lists where other users or the developers can be contacted for help and discussions ``` <project> @@ -133,7 +133,7 @@ mvn site ``` - - `<licenses>` - plugin license + - `\<licenses\>` - plugin license ``` <project> @@ -150,7 +150,7 @@ mvn site ``` - - `<scm>` - the source code management configuration - a plugin without this would raise suspicion, might not be OSS + - `\<scm\>` - the source code management configuration - a plugin without this would raise suspicion, might not be OSS ``` <project> @@ -165,7 +165,7 @@ mvn site ``` - - `<organization>` - the organization maintaining the plugin, just in case we need someone to blame + - `\<organization\>` - the organization maintaining the plugin, just in case we need someone to blame ``` <project> @@ -185,7 +185,7 @@ mvn site ### Plugin Configuration Parameters - The Maven Plugin Plugin is responsible for generating the Plugin Info site and needs to be added to the `<reporting>` section unless it is already inherited from a parent POM: + The Maven Plugin Plugin is responsible for generating the Plugin Info site and needs to be added to the `\<reporting\>` section unless it is already inherited from a parent POM: diff --git a/content/markdown/guides/development/guide-testing-development-plugins.md b/content/markdown/guides/development/guide-testing-development-plugins.md index e1b5a95e..ffc354e7 100644 --- a/content/markdown/guides/development/guide-testing-development-plugins.md +++ b/content/markdown/guides/development/guide-testing-development-plugins.md @@ -93,7 +93,7 @@ under the License. _Note:_ These last two techniques mean that _every_ plugin will be updated to the latest snapshot version. - The development version will stop being used if the `<pluginRepository>` element is removed from your POM and the version is set back to the release version. If you are using the command line or an unspecified version, you will also need to remove the version from the local repository. + The development version will stop being used if the `\<pluginRepository\>` element is removed from your POM and the version is set back to the release version. If you are using the command line or an unspecified version, you will also need to remove the version from the local repository. diff --git a/content/markdown/guides/development/guide-testing-releases.md b/content/markdown/guides/development/guide-testing-releases.md index beba1ccf..1c70c935 100644 --- a/content/markdown/guides/development/guide-testing-releases.md +++ b/content/markdown/guides/development/guide-testing-releases.md @@ -32,7 +32,7 @@ under the License. - add the repository or plugin repository to your POM or settings (see below) - - ensure you are using the version being released of the artifacts in your project, e.g. by setting the `<version>` in the `<plugin>` tag. + - ensure you are using the version being released of the artifacts in your project, e.g. by setting the `\<version\>` in the `\<plugin\>` tag. - test the release @@ -69,11 +69,11 @@ under the License. - - Identifier = `staged-releases` + - Identifier \= `staged-releases` - - Name = Staged Releases + - Name \= Staged Releases - - Directory = `/path/to/repositories/staged-releases` + - Directory \= `/path/to/repositories/staged-releases` - Uncheck 'Scannable' @@ -82,26 +82,26 @@ under the License. - - Identifier = `dfabulich.staged.releases` + - Identifier \= `dfabulich.staged.releases` - - Name = dfabulich Staged Releases + - Name \= dfabulich Staged Releases - - URL = `http://people.apache.org/\~dfabulich/staging-repo/` + - URL \= `http://people.apache.org/\~dfabulich/staging-repo/` Finally, add a proxy connector to connect the two repositories: - - Managed repository = `staged-releases` + - Managed repository \= `staged-releases` - - Remote repository = `dfabulich.staged` + - Remote repository \= `dfabulich.staged` - - Release policy = `once` + - Release policy \= `once` - - Snapshot policy = `never` + - Snapshot policy \= `never` - - White list = `org/apache/maven/\*\*` + - White list \= `org/apache/maven/\*\*` You can then utilise this repository from your POM or settings in the same way, but with the alternate URL of `http://localhost:8080/archiva/repository/staged-releases/`. diff --git a/content/markdown/guides/getting-started/index.md b/content/markdown/guides/getting-started/index.md index 8e215169..53e1ef09 100644 --- a/content/markdown/guides/getting-started/index.md +++ b/content/markdown/guides/getting-started/index.md @@ -177,7 +177,7 @@ mvn -B archetype:generate -DgroupId=com.mycompany.app -DartifactId=my-app -Darch - **groupId** This element indicates the unique identifier of the organization or group that created the project. The groupId is one of the key identifiers of a project and is typically based on the fully qualified domain name of your organization. For example `org.apache.maven.plugins` is the designated groupId for all Maven plugins. - - **artifactId** This element indicates the unique base name of the primary artifact being generated by this project. The primary artifact for a project is typically a JAR file. Secondary artifacts like source bundles also use the artifactId as part of their final name. A typical artifact produced by Maven would have the form `<artifactId>-<version>.<extension>` (for example, `myapp-1.0.jar`). + - **artifactId** This element indicates the unique base name of the primary artifact being generated by this project. The primary artifact for a project is typically a JAR file. Secondary artifacts like source bundles also use the artifactId as part of their final name. A typical artifact produced by Maven would have the form \<artifactId\>-\<version\>.\<extension\> (for example, `myapp-1.0.jar`). - **version** This element indicates the version of the artifact generated by the project. Maven goes a long way to help you with version management and you will often see the `SNAPSHOT` designator in a version, which indicates that a project is in a state of development. We will discuss the use of [snapshots](./index.html#What_is_a_SNAPSHOT_version) and how they work further on in this guide. @@ -493,7 +493,7 @@ mvn clean In other words, a SNAPSHOT version is the 'development' version before the final 'release' version. The SNAPSHOT is "older" than its release. - During the [release](../../plugins/maven-release-plugin/) process, a version of **x.y-SNAPSHOT** changes to **x.y**. The release process also increments the development version to **x.(y+1)-SNAPSHOT**. For example, version **1.0-SNAPSHOT** is released as version **1.0**, and the new development version is version **1.1-SNAPSHOT**. + During the [release](../../plugins/maven-release-plugin/) process, a version of **x.y-SNAPSHOT** changes to **x.y**. The release process also increments the development version to **x.(y\+1)-SNAPSHOT**. For example, version **1.0-SNAPSHOT** is released as version **1.0**, and the new development version is version **1.1-SNAPSHOT**. @@ -643,7 +643,7 @@ InputStream is = getClass().getResourceAsStream( "/test.properties" ); ### How do I filter resource files? - Sometimes a resource file will need to contain a value that can only be supplied at build time. To accomplish this in Maven, put a reference to the property that will contain the value into your resource file using the syntax `${<property name>}`. The property can be one of the values defined in your pom.xml, a value defined in the user's settings.xml, a property defined in an external properties file, or a system property. + Sometimes a resource file will need to contain a value that can only be supplied at build time. To accomplish this in Maven, put a reference to the property that will contain the value into your resource file using the syntax `$\{\<property name\>\}`. The property can be one of the values defined in your pom.xml, a value defined in the user's settings.xml, a property defined in an external properties file, or a system property. To have Maven filter resources when copying, simply set `filtering` to true for the resource directory in your `pom.xml`: @@ -1121,7 +1121,7 @@ mvn archetype:generate \ </project> ``` - Note the `<packaging>` element - this tells Maven to build as a WAR. Change into the webapp project's directory and try: + Note the `\<packaging\>` element - this tells Maven to build as a WAR. Change into the webapp project's directory and try: @@ -1194,7 +1194,7 @@ mvn package </dependencies> ``` - Finally, add the following `<parent>` element to both of the other `pom.xml` files in the subdirectories: + Finally, add the following `\<parent\>` element to both of the other `pom.xml` files in the subdirectories: @@ -1243,7 +1243,7 @@ $ jar tvf my-webapp/target/my-webapp-1.0-SNAPSHOT.war Next, we tell the WAR that it requires the `my-app` JAR. This does a few things: it makes it available on the classpath to any code in the WAR (none in this case), it makes sure the JAR is always built before the WAR, and it indicates to the WAR plugin to include the JAR in its library directory. - You may have noticed that `junit-4.11.jar` was a dependency, but didn't end up in the WAR. The reason for this is the `<scope>test</scope>` element - it is only required for testing, and so is not included in the web application as the compile time dependency `my-app` is. + You may have noticed that `junit-4.11.jar` was a dependency, but didn't end up in the WAR. The reason for this is the `\<scope\>test\</scope\>` element - it is only required for testing, and so is not included in the web application as the compile time dependency `my-app` is. The final step was to include a parent definition. This ensures that the POM can always be located even if the project is distributed separately from its parent by looking it up in the repository. diff --git a/content/markdown/guides/introduction/introduction-to-dependency-mechanism.md b/content/markdown/guides/introduction/introduction-to-dependency-mechanism.md index c7b2b476..e860b944 100644 --- a/content/markdown/guides/introduction/introduction-to-dependency-mechanism.md +++ b/content/markdown/guides/introduction/introduction-to-dependency-mechanism.md @@ -145,7 +145,7 @@ This scope indicates that the dependency is not required for normal use of the a This scope is similar to `provided` except that you have to provide the JAR which contains it explicitly. The artifact is always available and is not looked up in a repository. - **import**\ -This scope is only supported on a dependency of type `pom` in the `<dependencyManagement>` section. It indicates the dependency is to be replaced with the effective list of dependencies in the specified POM's `<dependencyManagement>` section. Since they are replaced, dependencies with a scope of `import` do not actually participate in limiting the transitivity of a dependency. +This scope is only supported on a dependency of type `pom` in the `\<dependencyManagement\>` section. It indicates the dependency is to be replaced with the effective list of dependencies in the specified POM's `\<dependencyManagement\>` section. Since they are replaced, dependencies with a scope of `import` do not actually participate in limiting the transitivity of a dependency. Each of the scopes (except for `import`) affects transitive dependencies in different ways, as is demonstrated in the table below. If a dependency is set to the scope in the left column, a transitive dependency of that dependency with the scope across the top row results in a dependency in the main project with the scope listed at the intersection. If no scope is listed, it means the dependency is omitted. @@ -322,7 +322,7 @@ This scope is only supported on a dependency of type `pom` in the `<dependencyMa ``` - **NOTE:** In two of these dependency references, we had to specify the `<type>` element. This is because the minimal set of information for matching a dependency reference against a dependencyManagement section is actually **\{groupId, artifactId, type, classifier\}**. In many cases, these dependencies will refer to jar artifacts with no classifier. This allows us to shorthand the identity set to **\{groupId, artifactId\}**, since the default for the type field is `jar`, and the default [...] + **NOTE:** In two of these dependency references, we had to specify the \<type/\> element. This is because the minimal set of information for matching a dependency reference against a dependencyManagement section is actually **\{groupId, artifactId, type, classifier\}**. In many cases, these dependencies will refer to jar artifacts with no classifier. This allows us to shorthand the identity set to **\{groupId, artifactId\}**, since the default for the type field is `jar`, and the defaul [...] A second, and very important use of the dependency management section is to control the versions of artifacts used in transitive dependencies. As an example consider these projects: diff --git a/content/markdown/guides/introduction/introduction-to-optional-and-excludes-dependencies.md b/content/markdown/guides/introduction/introduction-to-optional-and-excludes-dependencies.md index 88e29c2f..0545c7e6 100644 --- a/content/markdown/guides/introduction/introduction-to-optional-and-excludes-dependencies.md +++ b/content/markdown/guides/introduction/introduction-to-optional-and-excludes-dependencies.md @@ -45,7 +45,7 @@ under the License. #### How do I use the optional tag? - A dependency is declared optional by setting the `<optional>` element to true in its dependency declaration: + A dependency is declared optional by setting the `\<optional\>` element to true in its dependency declaration: @@ -109,7 +109,7 @@ Project-X -> Project-A #### How to use dependency exclusions - Add an `<exclusions>` element in the `<dependency>` element by which the problematic jar is included. + Add an `\<exclusions\>` element in the `\<dependency\>` element by which the problematic jar is included. @@ -159,7 +159,7 @@ Project-A B, C, D, E, F ``` - Suppose you don't want project D and its dependencies to be added to Project A's classpath because some of Project-D's dependencies are missing from the repository, and you don't need the functionality in Project-B that depends on Project-D anyway. Project-B's developers could have marked the dependency on Project-D `<optional>true</optional>`: + Suppose you don't want project D and its dependencies to be added to Project A's classpath because some of Project-D's dependencies are missing from the repository, and you don't need the functionality in Project-B that depends on Project-D anyway. Project-B's developers could have marked the dependency on Project-D `\<optional\>true\</optional\>`: diff --git a/content/markdown/guides/introduction/introduction-to-plugins.md b/content/markdown/guides/introduction/introduction-to-plugins.md index 8fee0356..1486fe82 100644 --- a/content/markdown/guides/introduction/introduction-to-plugins.md +++ b/content/markdown/guides/introduction/introduction-to-plugins.md @@ -46,7 +46,7 @@ under the License. A Mojo is really just a **goal** in Maven, and plug-ins consist of any number of goals (Mojos). Mojos can be defined as annotated Java classes or Beanshell script. A Mojo specifies metadata about a goal: a goal name, which phase of the lifecycle it fits into, and the parameters it is expecting. - MOJO is a play on POJO (Plain-old-Java-object), substituting "Maven" for "Plain". Mojo is also an interesting word (see [definition](http://www.answers.com/mojo&r=67)). From [Wikipedia](http://www.wikipedia.org), a "mojo" is defined as: "...a small bag worn by a person under the clothes (also known as a mojo hand). Such bags were thought to have supernatural powers, such as protecting from evil, bringing good luck, etc." + MOJO is a play on POJO (Plain-old-Java-object), substituting "Maven" for "Plain". Mojo is also an interesting word (see [definition](http://www.answers.com/mojo&r\=67)). From [Wikipedia](http://www.wikipedia.org), a "mojo" is defined as: "...a small bag worn by a person under the clothes (also known as a mojo hand). Such bags were thought to have supernatural powers, such as protecting from evil, bringing good luck, etc." diff --git a/content/markdown/guides/introduction/introduction-to-profiles.md b/content/markdown/guides/introduction/introduction-to-profiles.md index 5239e22f..4ab06a40 100644 --- a/content/markdown/guides/introduction/introduction-to-profiles.md +++ b/content/markdown/guides/introduction/introduction-to-profiles.md @@ -57,7 +57,7 @@ under the License. - [Profiles in POMs](Profiles_in_POMs) - - [POM elements outside `<profiles>`](POM_elements_outside_.3Cprofiles.3E) + - [POM elements outside \<profiles\>](POM_elements_outside_.3Cprofiles.3E) @@ -109,7 +109,7 @@ under the License. - Profile descriptor - - a descriptor located in [project basedir `(profiles.xml)`](/ref/2.2.1/maven-profile/profiles.html) (no longer supported in Maven 3.0 and above; see [ Maven 3 compatibility notes](https://cwiki.apache.org/confluence/display/MAVEN/Maven+3.x+Compatibility+Notes#Maven3.xCompatibilityNotes-profiles.xml)) + - a descriptor located in [project basedir `(profiles.xml)`](/ref/2.2.1/maven-profile/profiles.html) (no longer supported in Maven 3.0 and above; see [ Maven 3 compatibility notes](https://cwiki.apache.org/confluence/display/MAVEN/Maven\+3.x\+Compatibility\+Notes#Maven3.xCompatibilityNotes-profiles.xml)) @@ -145,7 +145,7 @@ under the License. Profiles can be explicitly specified using the `-P` command line flag. - This flag is followed by a comma-delimited list of profile IDs to use. The profile(s) specified in the option are activated in addition to any profiles which are activated by their activation configuration or the `<activeProfiles>` section in `settings.xml`. From Maven 4 onward, Maven will refuse to activate or deactivate a profile that cannot be resolved. To prevent this, prefix the profile identifier with an `?`, marking it as optional: + This flag is followed by a comma-delimited list of profile IDs to use. The profile(s) specified in the option are activated in addition to any profiles which are activated by their activation configuration or the `\<activeProfiles\>` section in `settings.xml`. From Maven 4 onward, Maven will refuse to activate or deactivate a profile that cannot be resolved. To prevent this, prefix the profile identifier with an `?`, marking it as optional: @@ -153,7 +153,7 @@ under the License. mvn groupId:artifactId:goal -P profile-1,profile-2,?profile-3 ``` - Profiles can be activated in the Maven settings, via the `<activeProfiles>` section. This section takes a list of `<activeProfile>` elements, each containing a profile-id inside. + Profiles can be activated in the Maven settings, via the `\<activeProfiles\>` section. This section takes a list of `\<activeProfile\>` elements, each containing a profile-id inside. @@ -167,14 +167,14 @@ mvn groupId:artifactId:goal -P profile-1,profile-2,?profile-3 </settings> ``` - Profiles listed in the `<activeProfiles>` tag would be activated by default every time a project use it. + Profiles listed in the `\<activeProfiles\>` tag would be activated by default every time a project use it. ##### Implicit profile activation - Profiles can be automatically triggered based on the detected state of the build environment. These triggers are specified via an `<activation>` section in the profile itself. Currently, this detection is limited to JDK version matching, operating system matching or the presence/the value of a system property. Here are some examples. + Profiles can be automatically triggered based on the detected state of the build environment. These triggers are specified via an `\<activation\>` section in the profile itself. Currently, this detection is limited to JDK version matching, operating system matching or the presence/the value of a system property. Here are some examples. ###### JDK @@ -373,7 +373,7 @@ mvn groupId:artifactId:goal -Denvironment=test </profiles> ``` - As of Maven 2.0.9, the tags `<exists>` and `<missing>` could be interpolated. Supported variables are system properties like `${user.home}` and environment variables like `${env.HOME}`. Please note that properties and values defined in the POM itself are not available for interpolation here, e.g. the above example activator cannot use `${project.build.directory}` but needs to hard-code the path `target`. + As of Maven 2.0.9, the tags `\<exists\>` and `\<missing\>` could be interpolated. Supported variables are system properties like `$\{user.home\}` and environment variables like `$\{env.HOME\}`. Please note that properties and values defined in the POM itself are not available for interpolation here, e.g. the above example activator cannot use `$\{project.build.directory\}` but needs to hard-code the path `target`. Profiles can also be active by default using a configuration like the following: @@ -434,10 +434,10 @@ mvn groupId:artifactId:goal -P -profile-1,-profile-2,-?profile-3 #### Profiles in external files - Profiles specified in external files (i.e in `settings.xml` or `profiles.xml`) are not portable in the strictest sense. Anything that seems to stand a high chance of changing the result of the build is restricted to the inline profiles in the POM. Things like repository lists could simply be a proprietary repository of approved artifacts, and won't change the outcome of the build. Therefore, you will only be able to modify the `<repositories>` and `<pluginRepositories>` sections, plus a [...] + Profiles specified in external files (i.e in `settings.xml` or `profiles.xml`) are not portable in the strictest sense. Anything that seems to stand a high chance of changing the result of the build is restricted to the inline profiles in the POM. Things like repository lists could simply be a proprietary repository of approved artifacts, and won't change the outcome of the build. Therefore, you will only be able to modify the `\<repositories\>` and `\<pluginRepositories\>` sections, pl [...] - The `<properties>` section allows you to specify free-form key-value pairs which will be included in the interpolation process for the POM. This allows you to specify a plugin configuration in the form of `${profile.provided.path}`. + The `\<properties\>` section allows you to specify free-form key-value pairs which will be included in the interpolation process for the POM. This allows you to specify a plugin configuration in the form of `$\{profile.provided.path\}`. @@ -451,49 +451,49 @@ mvn groupId:artifactId:goal -P -profile-1,-profile-2,-?profile-3 - - `<repositories>` + - `\<repositories\>` - - `<pluginRepositories>` + - `\<pluginRepositories\>` - - `<dependencies>` + - `\<dependencies\>` - - `<plugins>` + - `\<plugins\>` - - `<properties>` (not actually available in the main POM, but used behind the scenes) + - `\<properties\>` (not actually available in the main POM, but used behind the scenes) - - `<modules>` + - `\<modules\>` - - `<reports>` + - `\<reports\>` - - `<reporting>` + - `\<reporting\>` - - `<dependencyManagement>` + - `\<dependencyManagement\>` - - `<distributionManagement>` + - `\<distributionManagement\>` - - a subset of the `<build>` element, which consists of: + - a subset of the `\<build\>` element, which consists of: - - `<defaultGoal>` + - `\<defaultGoal\>` - - `<resources>` + - `\<resources\>` - - `<testResources>` + - `\<testResources\>` - - `<directory>` + - `\<directory\>` - - `<finalName>` + - `\<finalName\>` - - `<filters>` + - `\<filters\>` - - `<pluginManagement>` + - `\<pluginManagement\>` - - `<plugins>` + - `\<plugins\>` -#### POM elements outside `<profiles>` +#### POM elements outside \<profiles\> We don't allow modification of some POM elements outside of POM-profiles because these runtime modifications will not be distributed when the POM is deployed to the repository system, making that person's build of that project completely unique from others. While you can do this to some extent with the options given for external profiles, the danger is limited. Another reason is that this POM info is sometimes being reused from the parent POM. @@ -621,10 +621,10 @@ mvn groupId:artifactId:goal -P -profile-1,-profile-2,-?profile-3 When you build the **integration-test** lifecycle phase, your integration tests pass, since the path you've provided allows the test plugin to install and test this web application. - _However_, when your colleague attempts to build to **integration-test**, his build fails spectacularly, complaining that it cannot resolve the plugin configuration parameter `<appserverHome>`, or worse, that the value of that parameter - literally `${appserver.home}` - is invalid (if it warns you at all). + _However_, when your colleague attempts to build to **integration-test**, his build fails spectacularly, complaining that it cannot resolve the plugin configuration parameter `\<appserverHome\>`, or worse, that the value of that parameter - literally `$\{appserver.home\}` - is invalid (if it warns you at all). - Congratulations, your project is now non-portable. Inlining this profile in your `pom.xml` can help alleviate this, with the obvious drawback that each project hierarchy (allowing for the effects of inheritance) now have to specify this information. Since Maven provides good support for project inheritance, it's possible to stick this sort of configuration in the `<pluginManagement>` section of a team-level POM or similar, and simply inherit the paths. + Congratulations, your project is now non-portable. Inlining this profile in your `pom.xml` can help alleviate this, with the obvious drawback that each project hierarchy (allowing for the effects of inheritance) now have to specify this information. Since Maven provides good support for project inheritance, it's possible to stick this sort of configuration in the `\<pluginManagement\>` section of a team-level POM or similar, and simply inherit the paths. Another, less attractive answer might be standardization of development environments. However, this will tend to compromise the productivity gain that Maven is capable of providing. @@ -696,7 +696,7 @@ mvn groupId:artifactId:goal -P -profile-1,-profile-2,-?profile-3 </project> ``` - This profile looks quite similar to the one from the last example, with a few important exceptions: it's plainly geared toward a development environment, a new profile named `appserverConfig-dev-2` is added and it has an activation section that will trigger its inclusion when the system properties contain "env=dev" for a profile named `appserverConfig-dev` and "env=dev-2" for a profile named `appserverConfig-dev-2`. So, executing: + This profile looks quite similar to the one from the last example, with a few important exceptions: it's plainly geared toward a development environment, a new profile named `appserverConfig-dev-2` is added and it has an activation section that will trigger its inclusion when the system properties contain "env\=dev" for a profile named `appserverConfig-dev` and "env\=dev-2" for a profile named `appserverConfig-dev-2`. So, executing: @@ -720,7 +720,7 @@ mvn -Denv=dev integration-test mvn -Denv=production integration-test ``` - will not do a successful build. Why? Because, the resulting non-interpolated literal value of `$\{appserver.home\}` will not be a valid path for deploying and testing your web application. We haven't considered the case for the production environment when writing our profiles. The "production" environment (env=production), along with "test" and possibly even "local" constitute a natural set of target environments for which we may want to build the integration-test lifecycle phase. The i [...] + will not do a successful build. Why? Because, the resulting non-interpolated literal value of `$\{appserver.home\}` will not be a valid path for deploying and testing your web application. We haven't considered the case for the production environment when writing our profiles. The "production" environment (env\=production), along with "test" and possibly even "local" constitute a natural set of target environments for which we may want to build the integration-test lifecycle phase. The [...] As a quick aside, it's possible for user-specific profiles to act in a similar way. This means that profiles for handling different environments which are keyed to the user can act up when the team adds a new developer. While I suppose this _could_ act as useful training for the newbie, it just wouldn't be nice to throw them to the wolves in this way. Again, be sure to think of the _whole_ set of profiles. @@ -750,7 +750,7 @@ mvn -Denv=production integration-test mvn help:active-profiles -Denv=dev ``` - The result will be a bulleted list of the id of the profile with an activation property of "env=dev" together with the source where it was declared. See sample below. + The result will be a bulleted list of the id of the profile with an activation property of "env\=dev" together with the source where it was declared. See sample below. @@ -811,7 +811,7 @@ The following profiles are active: This will print the effective POM for this build configuration out to the console. Take note that profiles in the `settings.xml` takes higher priority than profiles in the POM. So the profile that has been applied here is `appserverConfig` not `appserverConfig-dev`. - If you want to redirect the output from the plugin to a file called `effective-pom.xml`, use the command-line option `-Doutput=effective-pom.xml`. + If you want to redirect the output from the plugin to a file called `effective-pom.xml`, use the command-line option `-Doutput\=effective-pom.xml`. @@ -829,7 +829,7 @@ The following profiles are active: mvn -Denv=test <phase> ``` - The right command-line option can be had by simply substituting "=" for "-" in the profile id. + The right command-line option can be had by simply substituting "\=" for "-" in the profile id. diff --git a/content/markdown/guides/introduction/introduction-to-the-lifecycle.md b/content/markdown/guides/introduction/introduction-to-the-lifecycle.md index 5e495e11..5985c608 100644 --- a/content/markdown/guides/introduction/introduction-to-the-lifecycle.md +++ b/content/markdown/guides/introduction/introduction-to-the-lifecycle.md @@ -179,7 +179,7 @@ mvn clean dependency:copy-dependencies package #### Packaging - The first, and most common way, is to set the packaging for your project via the equally named POM element `<packaging>`. Some of the valid packaging values are `jar`, `war`, `ear` and `pom`. If no packaging value has been specified, it will default to `jar`. + The first, and most common way, is to set the packaging for your project via the equally named POM element `\<packaging\>`. Some of the valid packaging values are `jar`, `war`, `ear` and `pom`. If no packaging value has been specified, it will default to `jar`. Each packaging contains a list of goals to bind to a particular phase. For example, the `jar` packaging will bind the following goals to build phases of the default lifecycle. @@ -199,7 +199,7 @@ mvn clean dependency:copy-dependencies package This is an almost [standard set of bindings](/ref/current/maven-core/default-bindings.html); however, some packagings handle them differently. For example, a project that is purely metadata (packaging value is `pom`) only binds goals to the `install` and `deploy` phases (for a complete list of goal-to-build-phase bindings of some of the packaging types, refer to the [Lifecycle Reference](Lifecycle_Reference)). - Note that for some packaging types to be available, you may also need to include a particular plugin in the `<build>` section of your POM and specify `<extensions>true</extensions>` for that plugin. One example of a plugin that requires this is the Plexus plugin, which provides a `plexus-application` and `plexus-service` packaging. + Note that for some packaging types to be available, you may also need to include a particular plugin in the `\<build\>` section of your POM and specify `\<extensions\>true\</extensions\>` for that plugin. One example of a plugin that requires this is the Plexus plugin, which provides a `plexus-application` and `plexus-service` packaging. _[\[top\]](./introduction-to-the-lifecycle.html)._ @@ -215,10 +215,10 @@ mvn clean dependency:copy-dependencies package As you will see in the later sections, plugins can contain information that indicates which lifecycle phase to bind a goal to. Note that adding the plugin on its own is not enough information - you must also specify the goals you want to run as part of your build. - The goals that are configured will be added to the goals already bound to the lifecycle from the packaging selected. If more than one goal is bound to a particular phase, the order used is that those from the packaging are executed first, followed by those configured in the POM. Note that you can use the `<executions>` element to gain more control over the order of particular goals. + The goals that are configured will be added to the goals already bound to the lifecycle from the packaging selected. If more than one goal is bound to a particular phase, the order used is that those from the packaging are executed first, followed by those configured in the POM. Note that you can use the `\<executions\>` element to gain more control over the order of particular goals. - For example, the Modello plugin binds by default its goal `modello:java` to the `generate-sources` phase (Note: The `modello:java` goal generates Java source codes). So to use the Modello plugin and have it generate sources from a model and incorporate that into the build, you would add the following to your POM in the `<plugins>` section of `<build>`: + For example, the Modello plugin binds by default its goal `modello:java` to the `generate-sources` phase (Note: The `modello:java` goal generates Java source codes). So to use the Modello plugin and have it generate sources from a model and incorporate that into the build, you would add the following to your POM in the `\<plugins\>` section of `\<build\>`: @@ -243,7 +243,7 @@ mvn clean dependency:copy-dependencies package </plugin> ``` - You might be wondering why that `<executions>` element is there. That is so that you can run the same goal multiple times with different configuration if needed. Separate executions can also be given an ID so that during inheritance or the application of profiles you can control whether goal configuration is merged or turned into an additional execution. + You might be wondering why that `\<executions\>` element is there. That is so that you can run the same goal multiple times with different configuration if needed. Separate executions can also be given an ID so that during inheritance or the application of profiles you can control whether goal configuration is merged or turned into an additional execution. When multiple executions are given that match a particular phase, they are executed in the order specified in the POM, with inherited executions running first. diff --git a/content/markdown/guides/introduction/introduction-to-the-pom.md b/content/markdown/guides/introduction/introduction-to-the-pom.md index 6ec1cf88..b0d7e81c 100644 --- a/content/markdown/guides/introduction/introduction-to-the-pom.md +++ b/content/markdown/guides/introduction/introduction-to-the-pom.md @@ -120,7 +120,7 @@ under the License. </project> ``` - A POM requires that its groupId, artifactId, and version be configured. These three values form the project's fully qualified artifact name. This is in the form of `<groupId>:<artifactId>:<version>`. As for the example above, its fully qualified artifact name is "com.mycompany.app:my-app:1". + A POM requires that its groupId, artifactId, and version be configured. These three values form the project's fully qualified artifact name. This is in the form of \<groupId\>:\<artifactId\>:\<version\>. As for the example above, its fully qualified artifact name is "com.mycompany.app:my-app:1". Also, as mentioned in the [first section](What_is_a_POM), if the configuration details are not specified, Maven will use their defaults. One of these default values is the packaging type. Every Maven project has a packaging type. If it is not specified in the POM, then the default value "jar" would be used. @@ -271,7 +271,7 @@ under the License. ##### The Solution - To address this directory structure (or any other directory structure), we would have to add the `<relativePath>` element to our parent section. + To address this directory structure (or any other directory structure), we would have to add the `\<relativePath\>` element to our parent section. @@ -382,7 +382,7 @@ under the License. </project> ``` - In the revised com.mycompany.app:my-app:1, the packaging section and the modules sections were added. For the packaging, its value was set to "pom", and for the modules section, we have the element `<module>my-module</module>`. The value of `<module>` is the relative path from the com.mycompany.app:my-app:1 to com.mycompany.app:my-module:1's POM (_by practice, we use the module's artifactId as the module directory's name_). + In the revised com.mycompany.app:my-app:1, the packaging section and the modules sections were added. For the packaging, its value was set to "pom", and for the modules section, we have the element `\<module\>my-module\</module\>`. The value of `\<module\>` is the relative path from the com.mycompany.app:my-app:1 to com.mycompany.app:my-module:1's POM (_by practice, we use the module's artifactId as the module directory's name_). Now, whenever a Maven command processes com.mycompany.app:my-app:1, that same Maven command would be ran against com.mycompany.app:my-module:1 as well. Furthermore, some commands (goals specifically) handle project aggregation differently. diff --git a/content/markdown/guides/mini/guide-configuring-maven.md b/content/markdown/guides/mini/guide-configuring-maven.md index d390f9e2..e457d858 100644 --- a/content/markdown/guides/mini/guide-configuring-maven.md +++ b/content/markdown/guides/mini/guide-configuring-maven.md @@ -38,7 +38,7 @@ under the License. The separation is quite clear - the project defines information that applies to the project, no matter who is building it, while the others both define settings for the current environment. - **Note:** the installation and user configuration cannot be used to add shared project information - for example, setting `<organization>` or `<distributionManagement>` company-wide. + **Note:** the installation and user configuration cannot be used to add shared project information - for example, setting `\<organization\>` or `\<distributionManagement\>` company-wide. For this, you should have your projects inherit from a company-wide parent `pom.xml`. @@ -80,7 +80,7 @@ under the License. ### Configuring Parallel Artifact Resolution - By default, Maven 2.1.0+ will download up to 5 artifacts (from different groups) at once. To change the size of the thread pool, start Maven using `-Dmaven.artifact.threads`. For example, to only download single artifacts at a time: + By default, Maven 2.1.0\+ will download up to 5 artifacts (from different groups) at once. To change the size of the thread pool, start Maven using `-Dmaven.artifact.threads`. For example, to only download single artifacts at a time: @@ -100,7 +100,7 @@ export MAVEN_OPTS=-Dmaven.artifact.threads=3 ### Security and Deployment Settings - Repositories to deploy to are defined in a project in the `<distributionManagement>` section. However, you cannot put your username, password, or other security settings in that project. For that reason, you should add a server definition to your own settings with an `id` that matches that of the deployment repository in the project. + Repositories to deploy to are defined in a project in the `\<distributionManagement\>` section. However, you cannot put your username, password, or other security settings in that project. For that reason, you should add a server definition to your own settings with an `id` that matches that of the deployment repository in the project. In addition, some repositories may require authorization to download from, so the corresponding settings can be specified in a `server` element in the same way. @@ -176,14 +176,14 @@ export MAVEN_OPTS=-Dmaven.artifact.threads=3 #### Security - As of Maven 2.1.0+, you can encrypt passwords in your settings file, however you must first configure a master password. For more information on both server passwords and the master password, see the [Guide to Password Encryption](./guide-encryption.html). + As of Maven 2.1.0\+, you can encrypt passwords in your settings file, however you must first configure a master password. For more information on both server passwords and the master password, see the [Guide to Password Encryption](./guide-encryption.html). #### Toolchains - As of Maven 2.0.9+, you can build a project using a specific version of JDK independent from the one Maven is running with. For more information, see the [Guide to Using Toolchains](./guide-using-toolchains.html). + As of Maven 2.0.9\+, you can build a project using a specific version of JDK independent from the one Maven is running with. For more information, see the [Guide to Using Toolchains](./guide-using-toolchains.html). diff --git a/content/markdown/guides/mini/guide-configuring-plugins.md b/content/markdown/guides/mini/guide-configuring-plugins.md index e4725dba..e3d2ec46 100644 --- a/content/markdown/guides/mini/guide-configuring-plugins.md +++ b/content/markdown/guides/mini/guide-configuring-plugins.md @@ -53,21 +53,21 @@ under the License. - [Configuring Build Plugins](Configuring_Build_Plugins) - - [Using the `<executions>` Tag](Using_the_.3Cexecutions.3E_Tag) + - [Using the \<executions\> Tag](Using_the_.3Cexecutions.3E_Tag) - - [Using the `<dependencies>` Tag](Using_the_.3Cdependencies.3E_Tag) + - [Using the \<dependencies\> Tag](Using_the_.3Cdependencies.3E_Tag) - - [Using the `<inherited>` Tag In Build Plugins](Using_the_.3Cinherited.3E_Tag_In_Build_Plugins) + - [Using the \<inherited\> Tag In Build Plugins](Using_the_.3Cinherited.3E_Tag_In_Build_Plugins) - [Configuring Reporting Plugins](Configuring_Reporting_Plugins) - - [Using the `<reporting>` Tag VS `<build>` Tag](Using_the_.3Creporting.3E_Tag_VS_.3Cbuild.3E_Tag) + - [Using the \<reporting\> Tag VS \<build\> Tag](Using_the_.3Creporting.3E_Tag_VS_.3Cbuild.3E_Tag) - - [Using the `<reportSets>` Tag](Using_the_.3CreportSets.3E_Tag) + - [Using the \<reportSets\> Tag](Using_the_.3CreportSets.3E_Tag) - - [Using the `<inherited>` Tag In Reporting Plugins](Using_the_.3Cinherited.3E_Tag_In_Reporting_Plugins) + - [Using the \<inherited\> Tag In Reporting Plugins](Using_the_.3Cinherited.3E_Tag_In_Reporting_Plugins) @@ -79,22 +79,22 @@ under the License. - - **Build plugins** are executed during the build and configured in the `<build>` element. + - **Build plugins** are executed during the build and configured in the `\<build/\>` element. - - **Reporting plugins** are executed during the site generation and configured in the `<reporting>` element. + - **Reporting plugins** are executed during the site generation and configured in the `\<reporting/\>` element. All plugins should have minimal required [information](/ref/current/maven-model/maven.html#class_plugin): `groupId`, `artifactId` and `version`. - **Important Note**: Always define the version of each plugin used to guarantee build reproducibility. A good practice is to specify each build plugin's version in a `<build><pluginManagement><build>` element. Often the `<pluginManagement>` element is found in the parent POM. For reporting plugins, specify each version in the `<reporting><plugins><reporting>` element (and in the `<build><pluginManagement><build>` element too). + **Important Note**: Always define the version of each plugin used to guarantee build reproducibility. A good practice is to specify each build plugin's version in a `\<build\>\<pluginManagement/\>\</build\>` element. Often the \<pluginManagement/\> element is found in the parent POM. For reporting plugins, specify each version in the `\<reporting\>\<plugins/\>\</reporting\>` element (and in the `\<build\>\<pluginManagement/\>\</build\>` element too). ### Generic Configuration - Maven plugins (build and reporting) are configured by specifying a `<configuration>` element where the child elements of the `<configuration>` element are mapped to fields, or setters, inside your Mojo. (Remember that a plug-in consists of one or more Mojos where a Mojo maps to a goal.) Say, for example, you have a Mojo that performs a query against a particular URL, with a specified timeout and list of options. The Mojo might look like the following: + Maven plugins (build and reporting) are configured by specifying a `\<configuration\>` element where the child elements of the `\<configuration\>` element are mapped to fields, or setters, inside your Mojo. (Remember that a plug-in consists of one or more Mojos where a Mojo maps to a goal.) Say, for example, you have a Mojo that performs a query against a particular URL, with a specified timeout and list of options. The Mojo might look like the following: @@ -151,7 +151,7 @@ public class MyQueryMojo The elements in the configuration match the names of the fields in the Mojo. The mapping is straight forward. The `url` element maps to the `url` field, the `timeout` element maps to the `timeout` field, and the `options` element maps to the `options` field. The mapping mechanism can deal with arrays by inspecting the type of the field and determining if a suitable mapping is possible. - For Mojos that are intended to be executed directly from the CLI, their parameters usually provide a means to be configured via system properties instead of a `<configuration>` section in the POM. The plugin documentation for those parameters will list an _expression_ that denotes the system properties for the configuration. In the Mojo above, the parameter `url` is associated with the expression `${query.url}`, meaning its value can be specified by the system property `query.url` as sh [...] + For Mojos that are intended to be executed directly from the CLI, their parameters usually provide a means to be configured via system properties instead of a `\<configuration\>` section in the POM. The plugin documentation for those parameters will list an _expression_ that denotes the system properties for the configuration. In the Mojo above, the parameter `url` is associated with the expression `$\{query.url\}`, meaning its value can be specified by the system property `query.url` a [...] @@ -186,7 +186,7 @@ mvn javadoc:help -Ddetail -Dgoal=javadoc ##### Mapping Value Objects - Mapping value types, like Boolean or Integer, is very simple. The `<configuration>` element might look like the following: + Mapping value types, like Boolean or Integer, is very simple. The `\<configuration\>` element might look like the following: @@ -232,7 +232,7 @@ mvn javadoc:help -Ddetail -Dgoal=javadoc ##### Mapping Complex Objects - Mapping complex types is also fairly straight forward. Let's look at a simple example where we are trying to map a configuration for Person object. The `<configuration>` element might look like the following: + Mapping complex types is also fairly straight forward. Let's look at a simple example where we are trying to map a configuration for Person object. The `\<configuration/\>` element might look like the following: @@ -449,13 +449,13 @@ public class MyAnimalMojo ### Configuring Build Plugins - The following is only to configure Build plugins in the `<build>` element. + The following is only to configure Build plugins in the `\<build\>` element. -#### Using the `<executions>` Tag +#### Using the `\<executions\>` Tag - You can also configure a mojo using the `<executions>` tag. This is most commonly used for mojos that are intended to participate in some phases of the [build lifecycle](../introduction/introduction-to-the-lifecycle.html). Using `MyQueryMojo` as an example, you may have something that will look like: + You can also configure a mojo using the `\<executions\>` tag. This is most commonly used for mojos that are intended to participate in some phases of the [build lifecycle](../introduction/introduction-to-the-lifecycle.html). Using `MyQueryMojo` as an example, you may have something that will look like: @@ -507,7 +507,7 @@ public class MyAnimalMojo </project> ``` - The first execution with id "execution1" binds this configuration to the test phase. The second execution does not have a `<phase>` tag, how do you think will this execution behave? Well, goals can have a default phase binding as discussed further below. If the goal has a default phase binding then it will execute in that phase. But if the goal is not bound to any lifecycle phase then it simply won't be executed during the build lifecycle. + The first execution with id "execution1" binds this configuration to the test phase. The second execution does not have a `\<phase\>` tag, how do you think will this execution behave? Well, goals can have a default phase binding as discussed further below. If the goal has a default phase binding then it will execute in that phase. But if the goal is not bound to any lifecycle phase then it simply won't be executed during the build lifecycle. Note that while execution id's have to be unique among all executions of a single plugin within a POM, they don't have to be unique across an inheritance hierarchy of POMs. Executions of the same id from different POMs are merged. The same applies to executions that are defined by profiles. @@ -583,7 +583,7 @@ public class MyBoundQueryMojo } ``` - From the above mojo example, `MyBoundQueryMojo` is by default bound to the package phase (see the `@phase` notation). But if we want to execute this mojo during the install phase and not with package we can rebind this mojo into a new lifecycle phase using the `<phase>` tag under `<execution>`. + From the above mojo example, `MyBoundQueryMojo` is by default bound to the package phase (see the `@phase` notation). But if we want to execute this mojo during the install phase and not with package we can rebind this mojo into a new lifecycle phase using the `\<phase\>` tag under `\<execution\>`. @@ -623,7 +623,7 @@ public class MyBoundQueryMojo Now, `MyBoundQueryMojo` default phase which is package has been overridden by install phase. - **Note:** Configurations inside the `<executions>` element used to differ from those that are outside `<executions>` in that they could not be used from a direct command line invocation because they were only applied when the lifecycle phase they were bound to was invoked. So you had to move a configuration section outside of the executions section to apply it globally to all invocations of the plugin. Since Maven 3.3.1 this is not the case anymore as you can specify on the command line [...] + **Note:** Configurations inside the `\<executions\>` element used to differ from those that are outside `\<executions\>` in that they could not be used from a direct command line invocation because they were only applied when the lifecycle phase they were bound to was invoked. So you had to move a configuration section outside of the executions section to apply it globally to all invocations of the plugin. Since Maven 3.3.1 this is not the case anymore as you can specify on the command [...] @@ -632,13 +632,13 @@ mvn myquery:query@execution1 ``` -#### Using the `<dependencies>` Tag +#### Using the `\<dependencies\>` Tag You could configure the dependencies of the Build plugins, commonly to use a more recent dependency version. - For instance, the Maven Antrun Plugin version 1.2 uses Ant version 1.6.5, if you want to use the latest Ant version when running this plugin, you need to add `<dependencies>` element like the following: + For instance, the Maven Antrun Plugin version 1.2 uses Ant version 1.6.5, if you want to use the latest Ant version when running this plugin, you need to add `\<dependencies\>` element like the following: @@ -672,10 +672,10 @@ mvn myquery:query@execution1 ``` -#### Using the `<inherited>` Tag In Build Plugins +#### Using the `\<inherited\>` Tag In Build Plugins - By default, plugin configuration should be propagated to child POMs, so to break the inheritance, you could use the `<inherited>` tag: + By default, plugin configuration should be propagated to child POMs, so to break the inheritance, you could use the `\<inherited\>` tag: @@ -702,26 +702,26 @@ mvn myquery:query@execution1 ### Configuring Reporting Plugins - The following is only to configure Reporting plugins in the `<reporting>` element. + The following is only to configure Reporting plugins in the `\<reporting\>` element. -#### Using the `<reporting>` Tag VS `<build>` Tag +#### Using the `\<reporting\>` Tag VS `\<build\>` Tag - Configuring a reporting plugin in the `<reporting>` or `<build>` elements in the pom does not exactly have the same results. + Configuring a reporting plugin in the `\<reporting\>` or `\<build\>` elements in the pom does not exactly have the same results. - [`mvn site`] Since maven-site-plugin 3.4, it uses the parameters defined in the `<configuration>` element of each reporting Plugin specified in the `<reporting>` element, in addition to the parameters defined in the `<configuration>` element of each plugin specified in `<build>` (parameters from `<build>` section were previously ignored). + [`mvn site`] Since maven-site-plugin 3.4, it uses the parameters defined in the `\<configuration\>` element of each reporting Plugin specified in the `\<reporting\>` element, in addition to the parameters defined in the `\<configuration\>` element of each plugin specified in `\<build\>` (parameters from `\<build\>` section were previously ignored). - [`mvn aplugin:areportgoal`] It **ignores** the parameters defined in the `<configuration>` element of each reporting Plugin specified in the `<reporting>` element; only parameters defined in the `<configuration>` element of each plugin specified in `<build>` are used. + [`mvn aplugin:areportgoal`] It **ignores** the parameters defined in the `\<configuration\>` element of each reporting Plugin specified in the `\<reporting\>` element; only parameters defined in the `\<configuration\>` element of each plugin specified in `\<build\>` are used. -#### Using the `<reportSets>` Tag +#### Using the `\<reportSets\>` Tag - You can configure a reporting plugin using the `<reportSets>` tag. This is most commonly used to generate reports selectively when running `mvn site`. The following will generate only the project team report. + You can configure a reporting plugin using the `\<reportSets\>` tag. This is most commonly used to generate reports selectively when running `mvn site`. The following will generate only the project team report. @@ -767,10 +767,10 @@ mvn myquery:query@execution1 -#### Using the `<inherited>` Tag In Reporting Plugins +#### Using the `\<inherited\>` Tag In Reporting Plugins - Similar to the build plugins, to break the inheritance, you can use the `<inherited>` tag: + Similar to the build plugins, to break the inheritance, you can use the `\<inherited\>` tag: diff --git a/content/markdown/guides/mini/guide-creating-archetypes.md b/content/markdown/guides/mini/guide-creating-archetypes.md index 9bd1233f..db36c862 100644 --- a/content/markdown/guides/mini/guide-creating-archetypes.md +++ b/content/markdown/guides/mini/guide-creating-archetypes.md @@ -110,11 +110,11 @@ under the License. - - `<requiredProperties>` : List of required properties to generate a project from this archetype + - `\<requiredProperties\>` : List of required properties to generate a project from this archetype - - `<fileSets>` : File sets definition + - `\<fileSets\>` : File sets definition - - `<modules>` : Modules definition + - `\<modules\>` : Modules definition At this point one can only specify individual files to be created but not empty directories. diff --git a/content/markdown/guides/mini/guide-default-execution-ids.md b/content/markdown/guides/mini/guide-default-execution-ids.md index b354cc3d..f209957c 100644 --- a/content/markdown/guides/mini/guide-default-execution-ids.md +++ b/content/markdown/guides/mini/guide-default-execution-ids.md @@ -44,7 +44,7 @@ under the License. ### Default `executionId`s for Implied Executions - When you consider the fact that the aforementioned configuration use cases are for mojos that are not explicitly mentioned in the POM, it's reasonable to refer to them as implied executions. But if they're implied, how can Maven allow users to provide configuration for them? The solution we've implemented is rather simple and low-tech, but should be more than adequate to handle even advanced use cases. Starting in Maven 2.2.0, each mojo invoked directly from the command line will have a [...] + When you consider the fact that the aforementioned configuration use cases are for mojos that are not explicitly mentioned in the POM, it's reasonable to refer to them as implied executions. But if they're implied, how can Maven allow users to provide configuration for them? The solution we've implemented is rather simple and low-tech, but should be more than adequate to handle even advanced use cases. Starting in Maven 2.2.0, each mojo invoked directly from the command line will have a [...] #### Example: Command-line variant invocation of the assembly plugin diff --git a/content/markdown/guides/mini/guide-http-settings.md b/content/markdown/guides/mini/guide-http-settings.md index b786b1b9..7f078965 100644 --- a/content/markdown/guides/mini/guide-http-settings.md +++ b/content/markdown/guides/mini/guide-http-settings.md @@ -210,7 +210,7 @@ problems with HTTP servers and proxies that do not support HTTP/1.1 protocol. Without this setting, PUT requests that require authentication transfer their entire payload to the server before that server issues an authentication challenge. In order to complete the PUT request, the client must then re-send the payload with the proper credentials specified in the HTTP headers. This results in twice the bandwidth usage, and twice the time to transfer each artifact. - Another option to avoid this double transfer is what's known as preemptive authentication, which involves sending the authentication headers along with the original PUT request. However, there are a few potential issues with this approach. For one thing, in the event you have an unused `<server>` entry that specifies an invalid username/password combination, some servers may respond with a `401 Unauthorized` even if the server doesn't actually require any authentication for the request. [...] + Another option to avoid this double transfer is what's known as preemptive authentication, which involves sending the authentication headers along with the original PUT request. However, there are a few potential issues with this approach. For one thing, in the event you have an unused `\<server\>` entry that specifies an invalid username/password combination, some servers may respond with a `401 Unauthorized` even if the server doesn't actually require any authentication for the reques [...] We'll discuss preemptive authentication in another example, below. @@ -264,7 +264,7 @@ problems with HTTP servers and proxies that do not support HTTP/1.1 protocol. </settings> ``` - For clarity, the other two sections are `<get>` for GET requests, and `<head>` for HEAD requests. I know that's going to be hard to remember... + For clarity, the other two sections are `\<get\>` for GET requests, and `\<head\>` for HEAD requests. I know that's going to be hard to remember... @@ -334,15 +334,15 @@ problems with HTTP servers and proxies that do not support HTTP/1.1 protocol. - 1 **booleans:** `%b,<value>` + 1 **booleans:** `%b,\<value\>` - 1 **integer:** `%i,<value>` + 1 **integer:** `%i,\<value\>` - 1 **long:** `%l,<value>` (yes, that's an 'L', not a '1') + 1 **long:** `%l,\<value\>` (yes, that's an 'L', not a '1') - 1 **double:** `%d,<value>` + 1 **double:** `%d,\<value\>` - 1 **collection of strings:** `%c,<value1>,<value2>,<value3>,...`, which could also be specified as: + 1 **collection of strings:** `%c,\<value1\>,\<value2\>,\<value3\>,...`, which could also be specified as: ``` %c, @@ -412,7 +412,7 @@ problems with HTTP servers and proxies that do not support HTTP/1.1 protocol. ##### Example: Lifting auth scope restriction for external authentication systems - Maven Wagon by default limits supplied credentials to the host:port combination scope, ignoring any other target servers. When the target server delegates authentication to an external system, you need to deliberately lift that scope limitation. Configure your server element to pass authentication to all target servers which challenge the client. +---+ _settings_ _servers_ _server_ _id_my-server_/id_ _configuration_ _basicAuthScope_ _host_ANY_/host_ _port_ANY_/port_ _!-- or even 443 to [...] + Maven Wagon by default limits supplied credentials to the host:port combination scope, ignoring any other target servers. When the target server delegates authentication to an external system, you need to deliberately lift that scope limitation. Configure your server element to pass authentication to all target servers which challenge the client. \+---\+ _settings_ _servers_ _server_ _id_my-server_/id_ _configuration_ _basicAuthScope_ _host_ANY_/host_ _port_ANY_/port_ _!-- or even 443 t [...] @@ -526,7 +526,7 @@ problems with HTTP servers and proxies that do not support HTTP/1.1 protocol. </settings> ``` - If all you need is a per-server timeout configuration, you still have the option to use the old `<timeout>` parameter. If you need to separate timeout preferences according to HTTP method, you can use one more like that specified directly above. + If all you need is a per-server timeout configuration, you still have the option to use the old `\<timeout\>` parameter. If you need to separate timeout preferences according to HTTP method, you can use one more like that specified directly above. diff --git a/content/markdown/guides/mini/guide-large-scale-centralized-deployments.md b/content/markdown/guides/mini/guide-large-scale-centralized-deployments.md index 235d162c..2ef58003 100644 --- a/content/markdown/guides/mini/guide-large-scale-centralized-deployments.md +++ b/content/markdown/guides/mini/guide-large-scale-centralized-deployments.md @@ -68,7 +68,7 @@ under the License. - a hosted repository for snapshots - - a hosted repository that can contain both releases and snapshots (Only needed if some projects are still using Maven Deploy Plugin < 2.8. See [Managing Uploads to the Repository Manager](Managing_Uploads_to_the_Repository_Manager) for more info.) + - a hosted repository that can contain both releases and snapshots (Only needed if some projects are still using Maven Deploy Plugin \< 2.8. See [Managing Uploads to the Repository Manager](Managing_Uploads_to_the_Repository_Manager) for more info.) Separate hosted repositories are generally used for releases and snapshots due to the need for different artifact retention policies. @@ -120,13 +120,13 @@ under the License. All proprietary artifacts produced by Maven projects in the organization should be uploaded to the repository manager's hosted repositories. - The [Maven Deploy Plugin](../../plugins/maven-deploy-plugin) can be instructed to upload artifacts to the repository manager's repositories by defining the `alt\*DeploymentRepository` properties in the Maven `settings.xml` file. When these properties are defined, the Maven Deploy Plugin's [deploy](../../plugins/maven-deploy-plugin/deploy-mojo.html) goal uses them instead of the `<distributionManagement>` section of `pom.xml` files to determine where to upload artifacts. + The [Maven Deploy Plugin](../../plugins/maven-deploy-plugin) can be instructed to upload artifacts to the repository manager's repositories by defining the `alt\*DeploymentRepository` properties in the Maven `settings.xml` file. When these properties are defined, the Maven Deploy Plugin's [deploy](../../plugins/maven-deploy-plugin/deploy-mojo.html) goal uses them instead of the `\<distributionManagement\>` section of `pom.xml` files to determine where to upload artifacts. - Defining the upload destination of artifacts in `settings.xml` files rather than in the `<distributionManagement>` section of `pom.xml` files allows the destinations to be centrally managed, which simplifies maintenance if the destinations need to change. In other words, rather than changing a huge number of `pom.xml` files, you just need to change [relatively few](Settings_File_Locations) `settings.xml` files if/when the distribution locations need to change. + Defining the upload destination of artifacts in `settings.xml` files rather than in the `\<distributionManagement\>` section of `pom.xml` files allows the destinations to be centrally managed, which simplifies maintenance if the destinations need to change. In other words, rather than changing a huge number of `pom.xml` files, you just need to change [relatively few](Settings_File_Locations) `settings.xml` files if/when the distribution locations need to change. - The ability to specify separate alternate deployment repositories for releases and snapshots via the `altReleaseDeploymentRepository` and `altSnapshotDeploymentRepository` properties, respectively, was added in Maven Deploy Plugin 2.8. To get the most out of the approach defined in this document, all projects should use Maven Deploy Plugin >=2.8. If some projects are still using an older version of Maven Deploy Plugin (>=2.3 and <2.8), then specify a single alternate deployment reposito [...] + The ability to specify separate alternate deployment repositories for releases and snapshots via the `altReleaseDeploymentRepository` and `altSnapshotDeploymentRepository` properties, respectively, was added in Maven Deploy Plugin 2.8. To get the most out of the approach defined in this document, all projects should use Maven Deploy Plugin \>\=2.8. If some projects are still using an older version of Maven Deploy Plugin (\>\=2.3 and \<2.8), then specify a single alternate deployment rep [...] Typically, only continuous integration servers are allowed to upload artifacts to the repository manager. Therefore, these settings should only be specified in `settings.xml` files on continuous integration servers, and should not be in `settings.xml` files on developer machines. Alternatively, if you want developers to be able to upload artifacts to the repository manager, then include these properties in the `settings.xml` files used by developers. diff --git a/content/markdown/guides/mini/guide-maven-classloading.md b/content/markdown/guides/mini/guide-maven-classloading.md index f2d14366..3f4045d7 100644 --- a/content/markdown/guides/mini/guide-maven-classloading.md +++ b/content/markdown/guides/mini/guide-maven-classloading.md @@ -105,7 +105,7 @@ under the License. <img src="../../buildExtensionClassRealm.svg" />Build Extension Class Realm - For every plugin which is marked with `<extensions>true</extensions>` or a build extension listed in the according section of the POM, there is a dedicated classloader. Those are isolated. That is, one build extension does not have access to other build extensions. It imports everything from the API classloader. All JSR 330 or Plexus components declared in the underlying JAR are registered as components in the global Plexus container while creating the classloader. In addition all compo [...] + For every plugin which is marked with `\<extensions\>true\</extensions\>` or a build extension listed in the according section of the POM, there is a dedicated classloader. Those are isolated. That is, one build extension does not have access to other build extensions. It imports everything from the API classloader. All JSR 330 or Plexus components declared in the underlying JAR are registered as components in the global Plexus container while creating the classloader. In addition all c [...] @@ -123,7 +123,7 @@ under the License. Each plugin (which is not marked as build extension) has its own classloader that imports the Project classloader. - Plugins marked with `<extensions>true</extensions>` leverage the Build Extension classloader instead of the Plugin classloader. + Plugins marked with `\<extensions\>true\</extensions\>` leverage the Build Extension classloader instead of the Plugin classloader. Users can add dependencies to this classloader by adding dependencies to a plugin in the `[plugins/plugin](/ref/current/maven-model/maven.html#class_plugin)` section of their project `pom.xml`. Here is a sample of adding `ant-nodeps` to the plugin classloader of the Antrun Plugin and hereby enabling the use of additional/optional Ant tasks: diff --git a/content/markdown/guides/mini/guide-mirror-settings.md b/content/markdown/guides/mini/guide-mirror-settings.md index 3fc4d46d..1def66a2 100644 --- a/content/markdown/guides/mini/guide-mirror-settings.md +++ b/content/markdown/guides/mini/guide-mirror-settings.md @@ -56,7 +56,7 @@ under the License. </settings> ``` - Note that there can be at most one mirror for a given repository. In other words, you cannot map a single repository to a group of mirrors that all define the same `<mirrorOf>` value. Maven will not aggregate the mirrors but simply picks the first match. If you want to provide a combined view of several repositories, use a [repository manager](../../repository-management.html) instead. + Note that there can be at most one mirror for a given repository. In other words, you cannot map a single repository to a group of mirrors that all define the same `\<mirrorOf\>` value. Maven will not aggregate the mirrors but simply picks the first match. If you want to provide a combined view of several repositories, use a [repository manager](../../repository-management.html) instead. The settings descriptor documentation can be found on the [Maven Local Settings Model Website](../../maven-settings/settings.html). @@ -78,7 +78,7 @@ under the License. To achieve this, set `mirrorOf` to `\*`. - **Note:** This feature is only available in Maven 2.0.5+. + **Note:** This feature is only available in Maven 2.0.5\+. @@ -119,26 +119,26 @@ under the License. - an exclamation mark may be used in conjunction with one of the above wildcards to exclude a repository id - Be careful not to include extra whitespace around identifiers or wildcards in comma separated lists. For example, a mirror with `<mirrorOf`> set to `!repo1, *` will not mirror anything while `!repo1,*` will mirror everything but `repo1`. + Be careful not to include extra whitespace around identifiers or wildcards in comma separated lists. For example, a mirror with `\<mirrorOf`\> set to `!repo1, \*` will not mirror anything while `!repo1,\*` will mirror everything but `repo1`. The position of wildcards within a comma separated list of repository identifiers is not important as the wildcards defer to further processing and explicit includes or excludes stop the processing, overruling any wildcard match. - When you use the advanced syntax and configure multiple mirrors, the declaration order matters. When Maven looks for a mirror of some repository, it first checks for a mirror whose `<mirrorOf>` exactly matches the repository identifier. If no direct match is found, Maven picks the first mirror declaration that matches according to the rules above (if any). Hence, you may influence match order by changing the order of the definitions in the `settings.xml` + When you use the advanced syntax and configure multiple mirrors, the declaration order matters. When Maven looks for a mirror of some repository, it first checks for a mirror whose `\<mirrorOf\>` exactly matches the repository identifier. If no direct match is found, Maven picks the first mirror declaration that matches according to the rules above (if any). Hence, you may influence match order by changing the order of the definitions in the `settings.xml` Examples: - - `*` = everything + - `\*` \= everything - - `external:*` = everything not on the localhost and not file based. + - `external:\*` \= everything not on the localhost and not file based. - - `repo,repo1` = repo or repo1 + - `repo,repo1` \= repo or repo1 - - `*,!repo1` = everything except repo1 + - `\*,!repo1` \= everything except repo1 diff --git a/content/markdown/guides/mini/guide-multiple-modules.md b/content/markdown/guides/mini/guide-multiple-modules.md index 8beff0a0..e42ef598 100644 --- a/content/markdown/guides/mini/guide-multiple-modules.md +++ b/content/markdown/guides/mini/guide-multiple-modules.md @@ -61,7 +61,7 @@ under the License. - a build extension declaration on another module in the build - - the order declared in the `<modules>` element (if no other rule applies) + - the order declared in the `\<modules\>` element (if no other rule applies) Note that only "instantiated" references are used - `dependencyManagement` and `pluginManagement` elements do not cause a change to the reactor sort order. diff --git a/content/markdown/guides/mini/guide-proxies.md b/content/markdown/guides/mini/guide-proxies.md index 016915ce..ccd2f1e4 100644 --- a/content/markdown/guides/mini/guide-proxies.md +++ b/content/markdown/guides/mini/guide-proxies.md @@ -53,7 +53,7 @@ under the License. ``` - Please note that currently NTLM proxies are not supported as they have not been tested. You may be able to use the relevant system properties on JDK 1.4+ to make this work. + Please note that currently NTLM proxies are not supported as they have not been tested. You may be able to use the relevant system properties on JDK 1.4\+ to make this work. ### Resources diff --git a/content/markdown/guides/mini/guide-releasing.md b/content/markdown/guides/mini/guide-releasing.md index 61f7593e..7997c9c4 100644 --- a/content/markdown/guides/mini/guide-releasing.md +++ b/content/markdown/guides/mini/guide-releasing.md @@ -309,7 +309,7 @@ checkpoint.check-in-development-version=OK #### I get a "The authenticity of host '_host_' can't be established." error and the build hangs - This is because your `\~user/.ssh/known_hosts` file doesn't have the host listed. You'd normally get a prompt to add the host to the known host list but Maven doesn't propagate that prompt. The solution is to add the host the `known_hosts` file before executing Maven. On Windows, this can be done by installing an OpenSSH client (for example [SSHWindows](http://sshwindows.sourceforge.net/download/)), running `ssh <host>` and accepting to add the host. + This is because your `\~user/.ssh/known_hosts` file doesn't have the host listed. You'd normally get a prompt to add the host to the known host list but Maven doesn't propagate that prompt. The solution is to add the host the `known_hosts` file before executing Maven. On Windows, this can be done by installing an OpenSSH client (for example [SSHWindows](http://sshwindows.sourceforge.net/download/)), running `ssh \<host`\> and accepting to add the host. diff --git a/content/markdown/guides/mini/guide-relocation.md b/content/markdown/guides/mini/guide-relocation.md index 949f3bf2..e92bf55a 100644 --- a/content/markdown/guides/mini/guide-relocation.md +++ b/content/markdown/guides/mini/guide-relocation.md @@ -109,7 +109,7 @@ under the License. 1 has published its releases until 1.6.5 to Maven 1-compliant `ant:ant` coordinates (see [repository content](https://repo.maven.apache.org/maven2/ant/ant/)), - 1 starting with 1.7.0, moved to reverse-DNS compliant Maven 2+ `org.apache.ant:ant` coordinates, (see [repository content](https://repo.maven.apache.org/maven2/org/apache/ant/ant/)), + 1 starting with 1.7.0, moved to reverse-DNS compliant Maven 2\+ `org.apache.ant:ant` coordinates, (see [repository content](https://repo.maven.apache.org/maven2/org/apache/ant/ant/)), 1 published one `ant:ant:1.7.0` relocation POM in old groupId to advertise about the move (see [repository content](https://repo.maven.apache.org/maven2/ant/ant/1.7.0/)). @@ -124,7 +124,7 @@ under the License. 1 has published its releases until 3.0-alpha-3 to Maven 1-compliant `poi:poi` coordinates (see [repository content](https://repo.maven.apache.org/maven2/poi/poi/)), - 1 starting with 3.0-FINAL, moved to reverse-DNS compliant Maven 2+ `org.apache.poi:poi` coordinates, (see [repository content](https://repo.maven.apache.org/maven2/org/apache/poi/poi/)), + 1 starting with 3.0-FINAL, moved to reverse-DNS compliant Maven 2\+ `org.apache.poi:poi` coordinates, (see [repository content](https://repo.maven.apache.org/maven2/org/apache/poi/poi/)), 1 published `poi:poi:3.0-FINAL` relocation POM **with jars** in old groupId to advertise about the move (see [repository content](https://repo.maven.apache.org/maven2/poi/poi/3.0-FINAL/)). diff --git a/content/markdown/guides/mini/guide-reproducible-builds.md b/content/markdown/guides/mini/guide-reproducible-builds.md index 5dfb89b0..3d96e5bf 100644 --- a/content/markdown/guides/mini/guide-reproducible-builds.md +++ b/content/markdown/guides/mini/guide-reproducible-builds.md @@ -47,7 +47,7 @@ mvn artifact:check-buildplan ``` - 1 Enable Reproducible Builds mode for plugins, by adding [`project.build.outputTimestamp` property](https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=74682318#Reproducible/VerifiableBuilds-OutputArchiveEntriesTimestamp) to the project's `pom.xml`: + 1 Enable Reproducible Builds mode for plugins, by adding [`project.build.outputTimestamp` property](https://cwiki.apache.org/confluence/pages/viewpage.action?pageId\=74682318#Reproducible/VerifiableBuilds-OutputArchiveEntriesTimestamp) to the project's `pom.xml`: ``` <properties> @@ -113,7 +113,7 @@ mvn clean verify artifact:compare - Generally depend on the **major version of the JDK** used to compile. (Even with source/target defined, each major JDK version changes the generated bytecode) - For detailed explanations, see [Maven "Reproducible/Verifiable Builds" Wiki page](https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=74682318). + For detailed explanations, see [Maven "Reproducible/Verifiable Builds" Wiki page](https://cwiki.apache.org/confluence/pages/viewpage.action?pageId\=74682318). @@ -170,7 +170,7 @@ mvn clean verify artifact:compare |MojoHaus [properties-maven-plugin](https://www.mojohaus.org/properties-maven-plugin/)|1.1.0|| - For more details, see [Maven "Reproducible/Verifiable Builds" Wiki page](https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=74682318#Reproducible/VerifiableBuilds-Whataretheissuestosolve?) + For more details, see [Maven "Reproducible/Verifiable Builds" Wiki page](https://cwiki.apache.org/confluence/pages/viewpage.action?pageId\=74682318#Reproducible/VerifiableBuilds-Whataretheissuestosolve?) diff --git a/content/markdown/guides/mini/guide-site.md b/content/markdown/guides/mini/guide-site.md index 7a8df717..a168471e 100644 --- a/content/markdown/guides/mini/guide-site.md +++ b/content/markdown/guides/mini/guide-site.md @@ -130,9 +130,9 @@ mvn site ``` - - the `<id>` element identifies the repository, so that you can attach credentials to it in your `settings.xml` file using the [ `<servers>` element](../../settings.html#Servers) as you would for any other repository, + - the `\<id\>` element identifies the repository, so that you can attach credentials to it in your `settings.xml` file using the [ `\<servers\>` element](../../settings.html#Servers) as you would for any other repository, - - the `<url>` gives the location to deploy to. Currently, only SSH is supported by default, as above which copies to the host `www.mycompany.com` in the path `/www/docs/project/`, but you can [add more protocols as required](/plugins/maven-site-plugin/examples/adding-deploy-protocol.html). If subprojects inherit the site URL from a parent POM, they will automatically get their `<artifactId>` appended to form their effective deployment location. + - the `\<url\>` gives the location to deploy to. Currently, only SSH is supported by default, as above which copies to the host `www.mycompany.com` in the path `/www/docs/project/`, but you can [add more protocols as required](/plugins/maven-site-plugin/examples/adding-deploy-protocol.html). If subprojects inherit the site URL from a parent POM, they will automatically get their `\<artifactId\>` appended to form their effective deployment location. Once distribution location is configured, deploying the site is done by using the `site-deploy` phase of the site lifecycle. @@ -222,7 +222,7 @@ mvn site-deploy ``` <!-- TODO: deserves more explanation. --> - **Note:** The `<menu ref="reports">` element above. When building the site, this is replaced by a menu with links to all the reports that you have configured. + **Note:** The `\<menu ref\="reports"/\>` element above. When building the site, this is replaced by a menu with links to all the reports that you have configured. More information about the site descriptor is available at the [dedicated page of Maven Site Plugin](/plugins/maven-site-plugin/examples/sitedescriptor.html). @@ -282,7 +282,7 @@ mvn site-deploy To find out more please refer to the [Project Info Reports Plugin](../../plugins/maven-project-info-reports-plugin/). - To add these reports to your site, you must add the Project Info Reports plugin to a special `<reporting>` section in the POM. The following example shows how to configure the standard project information reports that display information from the POM in a friendly format: + To add these reports to your site, you must add the Project Info Reports plugin to a special `\<reporting\>` section in the POM. The following example shows how to configure the standard project information reports that display information from the POM in a friendly format: @@ -302,7 +302,7 @@ mvn site-deploy </project> ``` - If you have included the appropriate `<menu ref="reports">` tag in your `site.xml` descriptor, then when you regenerate the site those items will appear in the menu. + If you have included the appropriate `\<menu ref\="reports"/\>` tag in your `site.xml` descriptor, then when you regenerate the site those items will appear in the menu. Many other plugins provide reporting goals: look for "R" (Reporting) value in the "Type" column of the [ list of plugins](/plugins/). When plugins are both Build and Reporting plugins, defining explicitely the version in the reporting section is usually not necessary since reporting will use the version from `build/plugins` or `build/pluginManagement`. Since Maven Site Plugin 3.4, reporting plugin also get configuration from `build/pluginManagement`. diff --git a/content/markdown/guides/mini/guide-using-extensions.md b/content/markdown/guides/mini/guide-using-extensions.md index 0493b852..d5e15b36 100644 --- a/content/markdown/guides/mini/guide-using-extensions.md +++ b/content/markdown/guides/mini/guide-using-extensions.md @@ -44,7 +44,7 @@ under the License. - Registered via extension jar in `$\{maven.home\}/lib/ext` - - Registered via CLI argument `mvn -Dmaven.ext.class.path=extension.jar` + - Registered via CLI argument `mvn -Dmaven.ext.class.path\=extension.jar` - Registered via [`.mvn/extensions.xml` file](../../configure.html#mvn-extensions-xml-file) diff --git a/content/markdown/guides/mini/guide-using-toolchains.md b/content/markdown/guides/mini/guide-using-toolchains.md index 66b6034f..5912a84c 100644 --- a/content/markdown/guides/mini/guide-using-toolchains.md +++ b/content/markdown/guides/mini/guide-using-toolchains.md @@ -108,10 +108,10 @@ under the License. </plugins> ``` - As you can see in the example above, a JDK toolchain with `<version>` "1.5" and `<vendor>` "sun" is to be used. Now how does the plugin know where this JDK is installed? This is where the `toolchains.xml` file comes in. + As you can see in the example above, a JDK toolchain with `\<version\>` "1.5" and `\<vendor\>` "sun" is to be used. Now how does the plugin know where this JDK is installed? This is where the `toolchains.xml` file comes in. - The `toolchains.xml` file (see below) is the configuration file where you set the installation paths of your toolchains. This file should be put in your `${user.home}/.m2` directory. When the `maven-toolchains-plugin` executes, it looks for the `toolchains.xml` file, reads it and looks for a toolchain matching the toolchains requirements configured in the plugin. In our example, that would be a JDK toolchain with `<version>` "1.5" and `<vendor>` "sun". Once a match is found, the plugin [...] + The `toolchains.xml` file (see below) is the configuration file where you set the installation paths of your toolchains. This file should be put in your `$\{user.home\}/.m2` directory. When the `maven-toolchains-plugin` executes, it looks for the `toolchains.xml` file, reads it and looks for a toolchain matching the toolchains requirements configured in the plugin. In our example, that would be a JDK toolchain with `\<version\>` "1.5" and `\<vendor\>` "sun". Once a match is found, the p [...] Starting with [Maven 3.3.1](/docs/3.3.1/release-notes.html) you can put the `toolchains.xml` file wherever you like by using the `--global-toolchains file` option but it is recommended to locate it into `$\{user.home\}/.m2/`. diff --git a/content/markdown/guides/mini/guide-wagon-providers.md b/content/markdown/guides/mini/guide-wagon-providers.md index 5954fc63..4b582416 100644 --- a/content/markdown/guides/mini/guide-wagon-providers.md +++ b/content/markdown/guides/mini/guide-wagon-providers.md @@ -29,16 +29,16 @@ under the License. Maven 2.2.0 attempted to amend this problem by switching over to a Wagon implementation that's based on Apache HttpClient. Unfortunately, it soon became apparent that HttpClient doesn't support NTLM (at least, version 2), which effectively means users behind NTLMv2 proxies cannot use Maven 2.2.0. - To hopefully resolve this once and for all, Maven 2.2.1 will contain support for specifying which Wagon provider you want to use for a given protocol during the build. The provider name will then be appended to the protocol using the format `<protocol>-<provider>` to form the component role-hint for the Wagon. + To hopefully resolve this once and for all, Maven 2.2.1 will contain support for specifying which Wagon provider you want to use for a given protocol during the build. The provider name will then be appended to the protocol using the format `\<protocol\>-\<provider\>` to form the component role-hint for the Wagon. - As of Maven 2.2.1, there are two ways to specify which Wagon provider should be used: via the command line, or in the `<server>` configuration section of the `settings.xml`. + As of Maven 2.2.1, there are two ways to specify which Wagon provider should be used: via the command line, or in the `\<server\>` configuration section of the `settings.xml`. ### Command-Line Configuration - To specify the Wagon provider from the command line, simply use the `-Dmaven.wagon.provider.<protocol>=<provider-name>` command-line option, like the following: + To specify the Wagon provider from the command line, simply use the `-Dmaven.wagon.provider.\<protocol\>\=\<provider-name\>` command-line option, like the following: @@ -53,7 +53,7 @@ mvn -Dmaven.wagon.provider.http=httpclient clean install ### `settings.xml` Configuration - To specify which Wagon provider to use for a particular server, modify your `settings.xml` file to add the `<wagonProvider>` configuration to your `<server>` entry, like the following: + To specify which Wagon provider to use for a particular server, modify your `settings.xml` file to add the `\<wagonProvider\>` configuration to your `\<server\>` entry, like the following: @@ -74,7 +74,7 @@ mvn -Dmaven.wagon.provider.http=httpclient clean install ### Available Wagon Providers - Maven 2.2.1 provides two providers for HTTP/HTTPS Wagons: `lightweight` and `httpclient`. If you add a new HTTP Wagon implementation via build extension, you'll need to make sure the extension binds its Wagon components to role-hints of the form `<protocol>-<provider>` in order to allow users to specify your alternative Wagon provider. For instance, the HttpClient HTTP Wagon component definition looks like this: + Maven 2.2.1 provides two providers for HTTP/HTTPS Wagons: `lightweight` and `httpclient`. If you add a new HTTP Wagon implementation via build extension, you'll need to make sure the extension binds its Wagon components to role-hints of the form `\<protocol\>-\<provider\>` in order to allow users to specify your alternative Wagon provider. For instance, the HttpClient HTTP Wagon component definition looks like this: diff --git a/content/markdown/guides/plugin/guide-java-plugin-development.md b/content/markdown/guides/plugin/guide-java-plugin-development.md index e818f88f..d5550dd1 100644 --- a/content/markdown/guides/plugin/guide-java-plugin-development.md +++ b/content/markdown/guides/plugin/guide-java-plugin-development.md @@ -69,10 +69,10 @@ under the License. ### Important Notice: [Plugin Naming Convention and Apache Maven Trademark](../mini/guide-naming-conventions.html) - You will typically name your plugin `<yourplugin>-maven-plugin`. + You will typically name your plugin `\<yourplugin\>-maven-plugin`. - Calling it `maven-<yourplugin>-plugin` (note "Maven" is at the beginning of the plugin name) is **strongly discouraged** since it's a **reserved naming pattern for official Apache Maven plugins maintained by the Apache Maven team** with groupId `org.apache.maven.plugins`. Using this naming pattern is an infringement of the Apache Maven Trademark. + Calling it `maven-\<yourplugin\>-plugin` (note "Maven" is at the beginning of the plugin name) is **strongly discouraged** since it's a **reserved naming pattern for official Apache Maven plugins maintained by the Apache Maven team** with groupId `org.apache.maven.plugins`. Using this naming pattern is an infringement of the Apache Maven Trademark. diff --git a/content/markdown/guides/plugin/guide-java-report-plugin-development.md b/content/markdown/guides/plugin/guide-java-report-plugin-development.md index 41eae439..9da83e57 100644 --- a/content/markdown/guides/plugin/guide-java-report-plugin-development.md +++ b/content/markdown/guides/plugin/guide-java-report-plugin-development.md @@ -39,7 +39,7 @@ under the License. - 1 A regular Maven project usually invokes _reporting goals_ of a plugin by declaring such plugin in the [`<reporting>`](/plugins/maven-site-plugin/examples/configuring-reports.html) section of its `pom.xml` as in the example below: + 1 A regular Maven project usually invokes _reporting goals_ of a plugin by declaring such plugin in the [`\<reporting\>`](/plugins/maven-site-plugin/examples/configuring-reports.html) section of its `pom.xml` as in the example below: ``` <project> @@ -398,7 +398,7 @@ simple:simple #### Invoking the Simple Plugin - To invoke the _report Mojo_ of our plugin in another Maven project, we just need to declare the plugin in the [`<reporting>`](/plugins/maven-site-plugin/examples/configuring-reports.html) section of its `pom.xml` as in the example below: + To invoke the _report Mojo_ of our plugin in another Maven project, we just need to declare the plugin in the [`\<reporting\>`](/plugins/maven-site-plugin/examples/configuring-reports.html) section of its `pom.xml` as in the example below: diff --git a/content/markdown/maven-jsr330.md b/content/markdown/maven-jsr330.md index 0ce05fbc..402f12d1 100644 --- a/content/markdown/maven-jsr330.md +++ b/content/markdown/maven-jsr330.md @@ -25,10 +25,10 @@ uses - since 3.0-beta-3 - is named [Sisu][sisu] and is based on [Guice 3.x][guic If you are using [Plexus annotations and APIs][plexus-container] currently, there is no rush to switch and no big bang conversions are necessary: Plexus, JSR-330 and Guice APIs all happily -co-exist within Maven's core and you can choose to use JSR-330 when you wish. There are hundreds of components +co-exist within Maven\'s core and you can choose to use JSR-330 when you wish. There are hundreds of components written using the Plexus APIs. -If you want to use JSR-330, you must understand that your code won't be compatible with Maven 3.0.x +If you want to use JSR-330, you must understand that your code won\'t be compatible with Maven 3.0.x but only with Maven 3.1.0 and later. Even though JSR-330 has been available in core since Maven 3.0-beta-3, it was made available to plugins and extensions only in Maven 3.1.0 (see [MNG-5343][MNG-5343] for more details). @@ -58,7 +58,7 @@ org.apache.maven.lifecycle.profiler.internal.DefaultSessionProfileRenderer org.apache.maven.lifecycle.profiler.internal.DefaultTimer ``` -Enumerating the implementations means that no classpath scanning is required in runtime to find them, which keeps Maven's +Enumerating the implementations means that no classpath scanning is required in runtime to find them, which keeps Maven\'s startup time fast. Note that our container is configured by default to only use the index. While this keeps things fast, if you use JSR-330 components in dependencies that do not contain an index, those implementations will currently not be discovered. This is a compromise that is reasonable given Maven is a command-line tool where startup speed @@ -66,11 +66,11 @@ is important. ## How to use JSR-330 in extensions -Let's take a look at an example extension. We'll take a look at the POM, and a little bit of the implementation -so you can get an idea of how JSR-330 extensions work. Really, it's just a simple JSR-330 component. +Let\'s take a look at an example extension. We\'ll take a look at the POM, and a little bit of the implementation +so you can get an idea of how JSR-330 extensions work. Really, it\'s just a simple JSR-330 component. If you want to look at the full implementation, you can find it [here][tesla-profiler] on Github. -Ok, so let's take a look at the POM: +Ok, so let\'s take a look at the POM: ```xml <?xml version="1.0"?> @@ -220,7 +220,7 @@ public class LifecycleProfiler extends AbstractEventSpy { ## How to use JSR-330 in plugins -Let's take a look at an example plugin. The POM is setup in a similar way to an extension, but we add a dependency +Let\'s take a look at an example plugin. The POM is setup in a similar way to an extension, but we add a dependency to `maven-plugin-api` and `maven-plugin-annotations` to extend the `AbstractMojo` and use the Java 5 plugin annotations in our example. @@ -310,7 +310,7 @@ annotations in our example. </project> ``` -Now let's take a look at the plugin code. You'll notice that we're using constructor injection +Now let\'s take a look at the plugin code. You\'ll notice that we\'re using constructor injection which makes testing a lot easier. If you want to test your `Jsr330Component`, you do not need the container to instantiate the `Mojo`. In this simple case, you can actually test this plugin without using the plugin testing harness because you can instantiate the `Jsr330Component` and `Jsr330Mojo` directly and wire diff --git a/content/markdown/maven-logging.md b/content/markdown/maven-logging.md index c218f8ac..918fab4d 100644 --- a/content/markdown/maven-logging.md +++ b/content/markdown/maven-logging.md @@ -22,7 +22,7 @@ to stdout. We have reached the decision that [SLF4J][1] is the best option for a logging API: SLF4J has reached a certain level of ubiquity and while SLF4J may not be perfect, -it's the de facto standard and it's pointless to try and remake another one. +it\'s the de facto standard and it\'s pointless to try and remake another one. There are many implementations to choose from, including [Logback][4] and [Log4j2][3]. All the hard work has been done. All the bridges and funnels for other systems function well, which allows others to use whatever logging implementation they like in their components, diff --git a/content/markdown/plugin-developers/common-bugs.md b/content/markdown/plugin-developers/common-bugs.md index 95d21d2c..92acb1b3 100644 --- a/content/markdown/plugin-developers/common-bugs.md +++ b/content/markdown/plugin-developers/common-bugs.md @@ -77,9 +77,9 @@ Reader reader = new FileReader( javaFile ); - - [Source File Encoding](https://cwiki.apache.org/confluence/display/MAVEN/POM+Element+for+Source+File+Encoding) + - [Source File Encoding](https://cwiki.apache.org/confluence/display/MAVEN/POM\+Element\+for\+Source\+File\+Encoding) - - [Report Output Encoding](http://cwiki.apache.org/confluence/display/MAVENOLD/Reporting+Encoding+Configuration) + - [Report Output Encoding](http://cwiki.apache.org/confluence/display/MAVENOLD/Reporting\+Encoding\+Configuration) Finally note that XML files require special handling because they are equipped with an encoding declaration in the XML prolog. Reading or writing XML files with an encoding that does not match their XML prolog's `encoding` attribute is a bad idea: @@ -138,10 +138,10 @@ URL url = new URL( "file:/C:/Program%20Files/Java/bin/java.exe" ); File path = new File( url.getPath() ); ``` - To decode a URL, people sometimes also choose `[java.net.URLDecoder](http://java.sun.com/javase/6/docs/api/java/net/URLDecoder.html)`. The pitfall with this class is that is actually performs HTML form decoding which is yet another encoding and not the same as the URL encoding (compare the last paragraph in class javadoc about `[java.net.URL](http://java.sun.com/javase/6/docs/api/java/net/URL.html)`). For instance, a `URLDecoder` will erroneously convert the character "+" into a space a [...] + To decode a URL, people sometimes also choose `[java.net.URLDecoder](http://java.sun.com/javase/6/docs/api/java/net/URLDecoder.html)`. The pitfall with this class is that is actually performs HTML form decoding which is yet another encoding and not the same as the URL encoding (compare the last paragraph in class javadoc about `[java.net.URL](http://java.sun.com/javase/6/docs/api/java/net/URL.html)`). For instance, a `URLDecoder` will erroneously convert the character "\+" into a space [...] - In an ideal world, code targetting JRE 1.4+ could easily avoid these problems by using the constructor `[File(URI)](http://java.sun.com/javase/6/docs/api/java/io/File.html#File(java.net.URI))` as suggested by the following snippet: + In an ideal world, code targetting JRE 1.4\+ could easily avoid these problems by using the constructor `[File(URI)](http://java.sun.com/javase/6/docs/api/java/io/File.html#File(java.net.URI))` as suggested by the following snippet: @@ -209,14 +209,14 @@ src/ Now, if a resource bundle is to be looked up for English on a JVM whose default locale happens to be French, the bundle `mymojo-report_fr.properties` will be loaded instead of the intended bundle `mymojo-report.properties`. - Reporting plugins that suffer from this bug can easily be detected by executing `mvn site -D locales=xy,en` where `xy` denotes any other language code supported by the particular plugin. Specifying `xy` as the first locale will have the Maven Site Plugin change the JVM's default locale to `xy` which in turn causes the lookup for `en` to fail as outlined above unless the plugin has a dedicated resource bundle for English. + Reporting plugins that suffer from this bug can easily be detected by executing `mvn site -D locales\=xy,en` where `xy` denotes any other language code supported by the particular plugin. Specifying `xy` as the first locale will have the Maven Site Plugin change the JVM's default locale to `xy` which in turn causes the lookup for `en` to fail as outlined above unless the plugin has a dedicated resource bundle for English. ### Using System Properties - Maven's command line supports the definition of system properties via arguments of the form `-D key=value`. While these properties are called system properties, plugins should never use `[System.getProperty()](http://java.sun.com/javase/6/docs/api/java/lang/System.html#getProperty(java.lang.String))` and related methods to query these properties. For example, the following code snippet will not work reliably when Maven is embedded, say into an IDE or a CI server: + Maven's command line supports the definition of system properties via arguments of the form `-D key\=value`. While these properties are called system properties, plugins should never use `[System.getProperty()](http://java.sun.com/javase/6/docs/api/java/lang/System.html#getProperty(java.lang.String))` and related methods to query these properties. For example, the following code snippet will not work reliably when Maven is embedded, say into an IDE or a CI server: @@ -403,7 +403,7 @@ public MyMojo extends AbstractMojo } ``` - In case of the logger, the above mojo will simply use a default console logger, i.e. the code defect is not immediately noticeable by a `NullPointerException`. This default logger will however use a different message format for its output and also outputs debug messages even if Maven's debug mode was not enabled. For this reason, developers must not try to cache the logger during construction time. The method `getLog()` is fast enough and can simply be called whenever one needs it. +--- + In case of the logger, the above mojo will simply use a default console logger, i.e. the code defect is not immediately noticeable by a `NullPointerException`. This default logger will however use a different message format for its output and also outputs debug messages even if Maven's debug mode was not enabled. For this reason, developers must not try to cache the logger during construction time. The method `getLog()` is fast enough and can simply be called whenever one needs it. \+--- diff --git a/content/markdown/plugin-developers/cookbook/plexus-plugin-upgrade.md b/content/markdown/plugin-developers/cookbook/plexus-plugin-upgrade.md index 3a0436c3..dd79debb 100644 --- a/content/markdown/plugin-developers/cookbook/plexus-plugin-upgrade.md +++ b/content/markdown/plugin-developers/cookbook/plexus-plugin-upgrade.md @@ -38,7 +38,7 @@ under the License. 1 update sources with [Java Annotations for Plexus](https://codehaus-plexus.github.io/plexus-containers/plexus-component-annotations/). - **Notice**: if you're targeting components for Maven 3.1.0+, using [`@Named`/`@Inject` JSR-330 annotations](/maven-jsr330.html) instead of `@Component`/`@Requirement` Plexus Java Annotations may be a good next step + **Notice**: if you're targeting components for Maven 3.1.0\+, using [`@Named`/`@Inject` JSR-330 annotations](/maven-jsr330.html) instead of `@Component`/`@Requirement` Plexus Java Annotations may be a good next step diff --git a/content/markdown/plugin-developers/plugin-documenting.md b/content/markdown/plugin-developers/plugin-documenting.md index 66d56f7d..dcd6dc5c 100644 --- a/content/markdown/plugin-developers/plugin-documenting.md +++ b/content/markdown/plugin-developers/plugin-documenting.md @@ -46,6 +46,6 @@ mvn docck:check - - [Maven Plugin Documentation](http://cwiki.apache.org/confluence/display/MAVENOLD/Maven+Plugin+Documentation) + - [Maven Plugin Documentation](http://cwiki.apache.org/confluence/display/MAVENOLD/Maven\+Plugin\+Documentation) diff --git a/content/markdown/plugin-developers/plugin-testing.md b/content/markdown/plugin-developers/plugin-testing.md index 6080159c..0dc417e6 100644 --- a/content/markdown/plugin-developers/plugin-testing.md +++ b/content/markdown/plugin-developers/plugin-testing.md @@ -121,7 +121,7 @@ public class YourMojoTest } ``` - For more information, refer to [Maven Plugin Harness Wiki](http://cwiki.apache.org/confluence/display/MAVENOLD/Maven+Plugin+Harness) + For more information, refer to [Maven Plugin Harness Wiki](http://cwiki.apache.org/confluence/display/MAVENOLD/Maven\+Plugin\+Harness) @@ -135,7 +135,7 @@ public class YourMojoTest maven-verifier tests are run using JUnit or TestNG, and provide a simple class allowing you to launch Maven and assert on its log file and built artifacts. It also provides a ResourceExtractor, which extracts a Maven project from your src/test/resources directory into a temporary working directory where you can do tricky stuff with it. Follow the [Getting Started](/shared/maven-verifier/getting-started.html) guide to learn more about creating maven-verifier tests. - Maven itself uses maven-verifier to run its core integration tests. For more information, please refer to [Creating a Maven Integration Test](https://cwiki.apache.org/confluence/display/MAVEN/Creating+a+Maven+Integration+Test). + Maven itself uses maven-verifier to run its core integration tests. For more information, please refer to [Creating a Maven Integration Test](https://cwiki.apache.org/confluence/display/MAVEN/Creating\+a\+Maven\+Integration\+Test). **Note**: maven-verifier and maven-verifier-plugin sound similar, but are totally different unrelated pieces of code. maven-verifier-plugin simply verifies the existence/absence of files on the filesystem. You could use it for functional testing, but you may need more features than maven-verifier-plugin provides. diff --git a/content/markdown/plugins/index.md b/content/markdown/plugins/index.md index 484bd08b..45e04b5e 100644 --- a/content/markdown/plugins/index.md +++ b/content/markdown/plugins/index.md @@ -27,9 +27,9 @@ under the License. - - **Build plugins** will be executed during the build and they should be configured in the `<build>` element from the POM. + - **Build plugins** will be executed during the build and they should be configured in the `\<build/\>` element from the POM. - - **Reporting plugins** will be executed during the site generation and they should be configured in the `<reporting>` element from the POM. Because the result of a Reporting plugin is part of the generated site, Reporting plugins should be both internationalized and localized. You can read more about the [localization of our plugins](./localization.html) and how you can help. + - **Reporting plugins** will be executed during the site generation and they should be configured in the `\<reporting/\>` element from the POM. Because the result of a Reporting plugin is part of the generated site, Reporting plugins should be both internationalized and localized. You can read more about the [localization of our plugins](./localization.html) and how you can help. ### Supported By The Maven Project diff --git a/content/markdown/plugins/localization.md b/content/markdown/plugins/localization.md index 51b6d210..fd2b1ddd 100644 --- a/content/markdown/plugins/localization.md +++ b/content/markdown/plugins/localization.md @@ -121,16 +121,16 @@ native2ascii checkstyle-report_es.properties checkstyle-report_es-encoded.proper - [cpdetector](http://cpdetector.sourceforge.net/) - - [IntelliJ IDEA ShowEncodingPlugin](http://plugins.intellij.net/plugin/?id=24) + - [IntelliJ IDEA ShowEncodingPlugin](http://plugins.intellij.net/plugin/?id\=24) - - [Notepad++](http://notepad-plus.sourceforge.net/) + - [Notepad\+\+](http://notepad-plus.sourceforge.net/) #### Tools to write a file in a given charset - Any editor like Notepad++, Eclipse, IntelliJ IDEA, ... + Any editor like Notepad\+\+, Eclipse, IntelliJ IDEA, ... @@ -140,7 +140,7 @@ native2ascii checkstyle-report_es.properties checkstyle-report_es-encoded.proper - Unix `iconv` command - - Notepad++ + - Notepad\+\+ diff --git a/content/markdown/repository/central-index.md b/content/markdown/repository/central-index.md index c4b6dfed..e104e72d 100644 --- a/content/markdown/repository/central-index.md +++ b/content/markdown/repository/central-index.md @@ -23,7 +23,7 @@ under the License. ## Central Index - Central repository provides [an index](https://repo.maven.apache.org/maven2/.index/) that is updated weekly as full (`nexus-maven-repository-index.gz`) and incremental (`nexus-maven-repository-index.<n>.gz` + `nexus-maven-repository-index.properties`). + Central repository provides [an index](https://repo.maven.apache.org/maven2/.index/) that is updated weekly as full (`nexus-maven-repository-index.gz`) and incremental (`nexus-maven-repository-index.\<n\>.gz` \+ `nexus-maven-repository-index.properties`). This index is build using [Maven Indexer](/maven-indexer/): see [LATEST indexer-core documentation](/maven-indexer-archives/maven-indexer-LATEST/indexer-core/) for more details on the fields that are available. diff --git a/content/markdown/settings.md b/content/markdown/settings.md index 1ff140e9..7a3dde0b 100644 --- a/content/markdown/settings.md +++ b/content/markdown/settings.md @@ -367,7 +367,7 @@ all accessible from the `settings.xml` file: 4. Java System Properties: All properties accessible via `java.lang.System.getProperties()` are available as POM properties, such as `${java.home}`. -5. `x`: Set within a `<properties\>` element or an external files, the +5. `x`: Set within a \<properties /\> element or an external files, the value may be used as `${someVar}`. <!-- -->
