diff --git a/src/site/apt/index.apt.vm b/src/site/apt/index.apt.vm deleted file mode 100644 index a69f9d03..00000000 --- a/src/site/apt/index.apt.vm +++ /dev/null @@ -1,95 +0,0 @@ - ------ - Introduction - ------ - Maria Odea Ching - Vincent Siveton - ------ - 2013-07-22 - ------ - - ~~ Licensed to the Apache Software Foundation (ASF) under one - ~~ or more contributor license agreements. See the NOTICE file - ~~ distributed with this work for additional information - ~~ regarding copyright ownership. The ASF licenses this file - ~~ to you under the Apache License, Version 2.0 (the - ~~ "License"); you may not use this file except in compliance - ~~ with the License. You may obtain a copy of the License at - ~~ - ~~ http://www.apache.org/licenses/LICENSE-2.0 - ~~ - ~~ Unless required by applicable law or agreed to in writing, - ~~ software distributed under the License is distributed on an - ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - ~~ KIND, either express or implied. See the License for the - ~~ specific language governing permissions and limitations - ~~ under the License. - -~~ NOTE: For help with the syntax of this file, see: -~~ http://maven.apache.org/doxia/references/apt-format.html - -${project.name} - - The Maven Help Plugin is used to get relative information about a project or the system. It can be used to get a - description of a particular plugin, including the plugin's goals with their parameters and component requirements, - the effective POM and effective settings of the current build, and the profiles applied to the current project being - built. - -* Goals Overview - - The Help Plugin has 8 goals: - - * {{{./active-profiles-mojo.html}help:active-profiles}} lists the profiles which are currently active for the build. - - * {{{./all-profiles-mojo.html}help:all-profiles}} lists the available profiles under the current project. - - * {{{./describe-mojo.html}help:describe}} describes the attributes of a Plugin and/or a Mojo (Maven plain Old Java - Object). - - * {{{./effective-pom-mojo.html}help:effective-pom}} displays the effective POM as an XML for the current build, with - the active profiles factored in. If <<>>, a comment is added to each XML element describing the origin of the line. - - * {{{./effective-settings-mojo.html}help:effective-settings}} displays the calculated settings as an XML for the - project, given any profile enhancement and the inheritance of the global settings into the user-level settings. - - * {{{./evaluate-mojo.html}help:evaluate}} evaluates Maven expressions given by the user in an interactive mode. - - * {{{./help-mojo.html}help:help}} Display help information for the maven-help-plugin itself. - - * {{{./system-mojo.html}help:system}} displays a list of the platform details like system properties and environment - variables. - - [] - -* Major Version Upgrade to version 3.0.0 - - Please note that the goal <<>> has been completely removed from the plugin. All the Maven expressions - that are supported as plugin parameters are available in the Javadoc of the - {{{/ref/current/maven-core/apidocs/org/apache/maven/plugin/PluginParameterExpressionEvaluator.html} - <<>>}} class. - -* Usage - - General instructions on how to use the Help Plugin can be found on the {{{./usage.html}usage page}}. Some more - specific use cases are described in the examples given below. - - In case you still have questions regarding the plugin's usage, please feel free to contact the - {{{./mailing-lists.html}user mailing list}}. The posts to the mailing list are archived and could - already contain the answer to your question as part of an older thread. Hence, it is also worth browsing/searching - the {{{./mailing-lists.html}mail archive}}. - - If you feel like the plugin is missing a feature or has a defect, you can fill a feature request or bug report in our - {{{./issue-management.html}issue tracker}}. When creating a new issue, please provide a comprehensive description of your - concern. Especially for fixing bugs it is crucial that the developers can reproduce your problem. For this reason, - entire debug logs, POMs or most preferably little demo projects attached to the issue are very much appreciated. - Of course, patches are welcome, too. Contributors can check out the project from our - {{{./scm.html}source repository}} and will find supplementary information in the - {{{https://maven.apache.org/guides/development/guide-helping.html}guide to helping with Maven}}. - -* Examples - - To better understand some usages of the Help Plugin, see the - following example(s): - - * {{{./examples/describe-configuration.html}Configuring Describe Goal}} - - [] diff --git a/src/site/apt/usage.apt b/src/site/apt/usage.apt deleted file mode 100644 index e61239a9..00000000 --- a/src/site/apt/usage.apt +++ /dev/null @@ -1,148 +0,0 @@ - ------ - Usage - ------ - John Casey - Maria Odea Ching - Vincent Siveton - ------ - 2010-01-21 - ------ - - ~~ Licensed to the Apache Software Foundation (ASF) under one - ~~ or more contributor license agreements. See the NOTICE file - ~~ distributed with this work for additional information - ~~ regarding copyright ownership. The ASF licenses this file - ~~ to you under the Apache License, Version 2.0 (the - ~~ "License"); you may not use this file except in compliance - ~~ with the License. You may obtain a copy of the License at - ~~ - ~~ http://www.apache.org/licenses/LICENSE-2.0 - ~~ - ~~ Unless required by applicable law or agreed to in writing, - ~~ software distributed under the License is distributed on an - ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - ~~ KIND, either express or implied. See the License for the - ~~ specific language governing permissions and limitations - ~~ under the License. - -~~ NOTE: For help with the syntax of this file, see: -~~ http://maven.apache.org/doxia/references/apt-format.html - -Usage - - Below are the different goals and the minimalist configurations of the Help Plugin. - -* The <<>> Goal - - The <<<{{{./active-profiles-mojo.html}active-profiles}}>>> goal is used to discover which profiles have been - applied to the projects currently being built. For each project in the build session, it will output a list of - profiles which have been applied to that project, along with the source of the profile (POM, <<>> - or <<>>). - - You can execute this goal using the following command: - -+-----+ -# mvn help:active-profiles -+-----+ - - <>: you could also use the <<>> parameter to redirect output to a file. - -* The <<>> Goal - - The <<<{{{./all-profiles-mojo.html}all-profiles}}>>> goal is used to discover all available profiles under the - current project. - - You can execute this goal using the following command: - -+-----+ -# mvn help:all-profiles -+-----+ - - <>: you could also use the <<>> parameter to redirect output to a file. - -* The <<>> Goal - - The <<<{{{./describe-mojo.html}describe}}>>> goal is used to discover information about Maven plugins. Given either - a <<>> or a <<>>, an <<>> and optionally a <<>>, the goal will lookup that - plugin and output details about it. If the user also specifies which <<>> to describe, the <<>> - goal will limit output to the details of that goal, including parameters. - - You can execute this goal using the following command: - -+-----+ -# mvn help:describe -DgroupId=org.somewhere -DartifactId=some-plugin -Dversion=0.0.0 -+-----+ - - <>: you could also use the <<>> parameter to redirect output to a file. - - Refer to {{{./examples/describe-configuration.html}Configuring Describe Goal}} for more information about its - configuration. - -* The <<>> Goal - - The <<<{{{./effective-pom-mojo.html}effective-pom}}>>> goal is used to make visible the POM that results from the - application of interpolation, inheritance and active profiles. It provides a useful way of removing the guesswork - about just what ends up in the POM that Maven uses to build your project. It will iterate over all projects in the - current build session, printing the effective POM for each. - - You can execute this goal using the following command: - -+-----+ -# mvn help:effective-pom -+-----+ - - <>: you could also use the <<>> parameter to redirect output to a file. - -* The <<>> Goal - - The <<<{{{./effective-settings-mojo.html}effective-settings}}>>> goal is used to view the settings that Maven - actually uses to run the build. These settings are a result of merging the global file with the user's file, - with the user's file taking precedence. - - You can execute this goal using the following command: - -+-----+ -# mvn help:effective-settings -+-----+ - - <>: you could also use the <<>> parameter to redirect output to a file. - -* The <<>> Goal - - The <<<{{{./system-mojo.html}system}}>>> goal is used to view the system information like system properties and - environment variables. - - You can execute this goal using the following command: - -+-----+ -# mvn help:system -+-----+ - - <>: you could also use the <<>> parameter to redirect output to a file. - -* The <<>> Goal - - You could use this interactive goal to evaluate some Maven expressions. To do it, just call the - {{{./evaluate-mojo.html}help:evaluate}} goal: - -+-----+ -# mvn help:evaluate -Dartifact=org.apache.maven.plugins:maven-help-plugin -... -[INFO] [help:evaluate] -[INFO] Enter the Maven expression i.e. ${project.groupId} or 0 to exit?: -${project.artifactId} -[INFO] -maven-help-plugin -[INFO] Enter the Maven expression i.e. ${project.groupId} or 0 to exit?: -${project.none} -[INFO] -null object or invalid expression -... -+-----+ - - The <<>> parameter refers to ask expressions on the artifact POM. If omitted, the evaluate goal uses the current - pom. - - You could ask for all Maven expressions listed in the Javadoc of the - {{{/ref/current/maven-core/apidocs/org/apache/maven/plugin/PluginParameterExpressionEvaluator.html} - <<>>}} class. diff --git a/src/site/apt/examples/describe-configuration.apt b/src/site/markdown/examples/describe-configuration.md similarity index 62% rename from src/site/apt/examples/describe-configuration.apt rename to src/site/markdown/examples/describe-configuration.md index 9887e2f4..b05d75b1 100644 --- a/src/site/apt/examples/describe-configuration.apt +++ b/src/site/markdown/examples/describe-configuration.md @@ -1,96 +1,82 @@ - ------ - Configuring Describe Goal - ------ - John Casey - Maria Odea Ching - Vincent Siveton - ------ - 2010-01-21 - ------ - - ~~ Licensed to the Apache Software Foundation (ASF) under one - ~~ or more contributor license agreements. See the NOTICE file - ~~ distributed with this work for additional information - ~~ regarding copyright ownership. The ASF licenses this file - ~~ to you under the Apache License, Version 2.0 (the - ~~ "License"); you may not use this file except in compliance - ~~ with the License. You may obtain a copy of the License at - ~~ - ~~ http://www.apache.org/licenses/LICENSE-2.0 - ~~ - ~~ Unless required by applicable law or agreed to in writing, - ~~ software distributed under the License is distributed on an - ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - ~~ KIND, either express or implied. See the License for the - ~~ specific language governing permissions and limitations - ~~ under the License. - -~~ NOTE: For help with the syntax of this file, see: -~~ http://maven.apache.org/doxia/references/apt-format.html - -Configuring Describe Goal - - Below are other configuration examples for the <<<{{{../describe-mojo.html}help:describe}}>>> goal. - -* The <<>> Parameter - - The <<>> parameter is meant to provide two things: convenience and prefix-based access. - - The convenience comes when specifying a plugin by <<>>, or by <<>>. - Where the more traditional specification of separate fields would mean specifying this: - -+---+ + + +# Configuring Describe Goal + +Below are other configuration examples for the [`help:describe`](../describe-mojo.html) goal. + +## The `plugin` Parameter + +The `plugin` parameter is meant to provide two things: convenience and prefix-based access. + +The convenience comes when specifying a plugin by `groupId:artifactId`, or by `groupId:artifactId:version`. Where the more traditional specification of separate fields would mean specifying this: + +```unknown # mvn help:describe -DgroupId=org.somewhere -DartifactId=some-plugin -Dversion=0.0.0 -+---+ +``` - the use of the plugin parameter allows this: +the use of the plugin parameter allows this: -+---+ +```unknown # mvn help:describe -Dplugin=org.somewhere:some-plugin:0.0.0 -+---+ +``` - Here is an example to describe the Help plugin: +Here is an example to describe the Help plugin: -+-----+ +```unknown # mvn help:describe -Dplugin=org.apache.maven.plugins:maven-help-plugin -+-----+ +``` - <>: <<>> is always optional here. +**Note**: `version` is always optional here. - On the other hand, the plugin parameter also offers the option to specify a plugin by its prefix, like this: +On the other hand, the plugin parameter also offers the option to specify a plugin by its prefix, like this: -+---+ +```unknown # mvn help:describe -Dplugin=help -+---+ +``` -* The <<>> Parameter +## The `goal` Parameter - You can use the <<>> parameter of the <<>> goal to show or display relative information about a - particular goal of the plugin you specified. +You can use the `goal` parameter of the `describe` goal to show or display relative information about a particular goal of the plugin you specified. - For example, when you execute the following command: +For example, when you execute the following command: -+-----+ +```unknown # mvn help:describe -Dgoal=describe -DgroupId=org.apache.maven.plugins -DartifactId=maven-help-plugin -+-----+ +``` - This would display brief information about the <<>> goal only. +This would display brief information about the `describe` goal only. -* The <<>> Parameter +## The `cmd` Parameter - You could also ask for a single Maven command, i.e. a goal or a phase or a lifecycle. It is the command when you call - Maven, i.e.: +You could also ask for a single Maven command, i.e. a goal or a phase or a lifecycle. It is the command when you call Maven, i.e.: -+-----+ +```unknown # mvn -help usage: mvn [options] [] [] ... -+-----+ +``` - The following are some examples: +The following are some examples: -+-----+ +```unknown # mvn help:describe -Dcmd=clean ... [INFO] [help:describe] @@ -99,9 +85,9 @@ usage: mvn [options] [] [] * clean: org.apache.maven.plugins:maven-clean-plugin:clean * post-clean: NOT DEFINED ... -+-----+ +``` -+-----+ +```unknown # mvn help:describe -Dcmd=compile ... [INFO] [help:describe] @@ -132,9 +118,9 @@ It is a part of the lifecycle for the POM packaging 'jar'. This lifecycle includ * install: org.apache.maven.plugins:maven-install-plugin:install * deploy: org.apache.maven.plugins:maven-deploy-plugin:deploy ... -+-----+ +``` -+-----+ +```unknown # mvn help:describe -Dcmd=compiler:compile ... [INFO] 'compiler:compile' is a plugin goal (aka mojo). @@ -145,16 +131,15 @@ compiler:compile For more information, run 'mvn help:describe [...] -Ddetail' ... -+-----+ +``` -* The <<>>, and <<>> Parameters +## The `minimal`, and `detail` Parameters - If you want to display less or more detailed information, you can use the <<>>, or <<>> - parameters. +If you want to display less or more detailed information, you can use the `minimal`, or `detail` parameters. - The <<>> parameter adds a minimal list of information: +The `minimal` parameter adds a minimal list of information: -+-----+ +```unknown # mvn help:describe -Dplugin=help -Dminimal=true ... [INFO] [help:describe] @@ -171,12 +156,11 @@ Description: The Maven Help plugin provides goals aimed at helping to make For more information, run 'mvn help:describe [...] -Ddetail' ... -+-----+ +``` - If you don't provide a paremeter a list is added with the mojos of the plugin and their - descriptions: +If you don't provide a paremeter a list is added with the mojos of the plugin and their descriptions: -+-----+ +```unknown # mvn help:describe -Dplugin=help ... [INFO] org.apache.maven.plugins:maven-help-plugin:2.1-SNAPSHOT @@ -240,20 +224,18 @@ help:system For more information, run 'mvn help:describe [...] -Ddetail' ... -+-----+ +``` - The <<>> parameter also displays information about the goal's implementation, their parameters and component - requirements, among others. +The `detail` parameter also displays information about the goal's implementation, their parameters and component requirements, among others. -+-----+ +```unknown # mvn help:describe -Dplugin=help -Ddetail=true -+-----+ +``` -* The <<>> Parameter +## The `output` Parameter - This <<>> goal can use the optional <<>> parameter to - redirect the output to a file. Here is an example of that: +This `describe` goal can use the optional `output` parameter to redirect the output to a file. Here is an example of that: -+-----+ +```unknown # mvn help:describe -Dplugin=help -Ddetail=true -Doutput=/path/to/file -+-----+ +``` diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md new file mode 100644 index 00000000..00f9d0ba --- /dev/null +++ b/src/site/markdown/index.md @@ -0,0 +1,51 @@ + + +# Apache Maven Help Plugin +The Maven Help Plugin is used to get relative information about a project or the system. It can be used to get a description of a particular plugin, including the plugin's goals with their parameters and component requirements, the effective POM and effective settings of the current build, and the profiles applied to the current project being built. + +## Goals Overview + +The Help Plugin has 8 goals: + +- [help:active-profiles](./active-profiles-mojo.html) lists the profiles which are currently active for the build. +- [help:all-profiles](./all-profiles-mojo.html) lists the available profiles under the current project. +- [help:describe](./describe-mojo.html) describes the attributes of a Plugin and/or a Mojo (Maven plain Old Java Object). +- [help:effective-pom](./effective-pom-mojo.html) displays the effective POM as an XML for the current build, with the active profiles factored in. If `verbose`, a comment is added to each XML element describing the origin of the line. +- [help:effective-settings](./effective-settings-mojo.html) displays the calculated settings as an XML for the project, given any profile enhancement and the inheritance of the global settings into the user-level settings. +- [help:evaluate](./evaluate-mojo.html) evaluates Maven expressions given by the user in an interactive mode. +- [help:help](./help-mojo.html) Display help information for the maven-help-plugin itself. +- [help:system](./system-mojo.html) displays a list of the platform details like system properties and environment variables. +## Major Version Upgrade to version 3.0.0 + +Please note that the goal `expressions` has been completely removed from the plugin. All the Maven expressions that are supported as plugin parameters are available in the Javadoc of the [`PluginParameterExpressionEvaluator`](/ref/current/maven-core/apidocs/org/apache/maven/plugin/PluginParameterExpressionEvaluator.html) class. + +## Usage + +General instructions on how to use the Help Plugin can be found on the [usage page](./usage.html). Some more specific use cases are described in the examples given below. + +In case you still have questions regarding the plugin's usage, please feel free to contact the [user mailing list](./mailing-lists.html). The posts to the mailing list are archived and could already contain the answer to your question as part of an older thread. Hence, it is also worth browsing/searching the [mail archive](./mailing-lists.html). + +If you feel like the plugin is missing a feature or has a defect, you can fill a feature request or bug report in our [issue tracker](./issue-management.html). When creating a new issue, please provide a comprehensive description of your concern. Especially for fixing bugs it is crucial that the developers can reproduce your problem. For this reason, entire debug logs, POMs or most preferably little demo projects attached to the issue are very much appreciated. Of course, patches are welcome, too. Contributors can check out the project from our [source repository](./scm.html) and will find supplementary information in the [guide to helping with Maven](https://maven.apache.org/guides/development/guide-helping.html). + +## Examples + +To better understand some usages of the Help Plugin, see the following example(s): + +- [Configuring Describe Goal](./examples/describe-configuration.html) diff --git a/src/site/markdown/usage.md b/src/site/markdown/usage.md new file mode 100644 index 00000000..d1a6d9fa --- /dev/null +++ b/src/site/markdown/usage.md @@ -0,0 +1,119 @@ + + +# Usage + +Below are the different goals and the minimalist configurations of the Help Plugin. + +## The `help:active-profiles` Goal + +The [`active-profiles`](./active-profiles-mojo.html) goal is used to discover which profiles have been applied to the projects currently being built. For each project in the build session, it will output a list of profiles which have been applied to that project, along with the source of the profile (POM, `settings.xml` or `profiles.xml`). + +You can execute this goal using the following command: + +```unknown +# mvn help:active-profiles +``` + +**Note**: you could also use the `output` parameter to redirect output to a file. + +## The `help:all-profiles` Goal + +The [`all-profiles`](./all-profiles-mojo.html) goal is used to discover all available profiles under the current project. + +You can execute this goal using the following command: + +```unknown +# mvn help:all-profiles +``` + +**Note**: you could also use the `output` parameter to redirect output to a file. + +## The `help:describe` Goal + +The [`describe`](./describe-mojo.html) goal is used to discover information about Maven plugins. Given either a `plugin` or a `groupId`, an `artifactId` and optionally a `version`, the goal will lookup that plugin and output details about it. If the user also specifies which `goal` to describe, the `describe` goal will limit output to the details of that goal, including parameters. + +You can execute this goal using the following command: + +```unknown +# mvn help:describe -DgroupId=org.somewhere -DartifactId=some-plugin -Dversion=0.0.0 +``` + +**Note**: you could also use the `output` parameter to redirect output to a file. + +Refer to [Configuring Describe Goal](./examples/describe-configuration.html) for more information about its configuration. + +## The `help:effective-pom` Goal + +The [`effective-pom`](./effective-pom-mojo.html) goal is used to make visible the POM that results from the application of interpolation, inheritance and active profiles. It provides a useful way of removing the guesswork about just what ends up in the POM that Maven uses to build your project. It will iterate over all projects in the current build session, printing the effective POM for each. + +You can execute this goal using the following command: + +```unknown +# mvn help:effective-pom +``` + +**Note**: you could also use the `output` parameter to redirect output to a file. + +## The `help:effective-settings` Goal + +The [`effective-settings`](./effective-settings-mojo.html) goal is used to view the settings that Maven actually uses to run the build. These settings are a result of merging the global file with the user's file, with the user's file taking precedence. + +You can execute this goal using the following command: + +```unknown +# mvn help:effective-settings +``` + +**Note**: you could also use the `output` parameter to redirect output to a file. + +## The `help:system` Goal + +The [`system`](./system-mojo.html) goal is used to view the system information like system properties and environment variables. + +You can execute this goal using the following command: + +```unknown +# mvn help:system +``` + +**Note**: you could also use the `output` parameter to redirect output to a file. + +## The `help:evaluate` Goal + +You could use this interactive goal to evaluate some Maven expressions. To do it, just call the [help:evaluate](./evaluate-mojo.html) goal: + +```unknown +# mvn help:evaluate -Dartifact=org.apache.maven.plugins:maven-help-plugin +... +[INFO] [help:evaluate] +[INFO] Enter the Maven expression i.e. ${project.groupId} or 0 to exit?: +${project.artifactId} +[INFO] +maven-help-plugin +[INFO] Enter the Maven expression i.e. ${project.groupId} or 0 to exit?: +${project.none} +[INFO] +null object or invalid expression +... +``` + +The `artifact` parameter refers to ask expressions on the artifact POM. If omitted, the evaluate goal uses the current pom. + +You could ask for all Maven expressions listed in the Javadoc of the [`PluginParameterExpressionEvaluator`](/ref/current/maven-core/apidocs/org/apache/maven/plugin/PluginParameterExpressionEvaluator.html) class.