MACR-2: added documentation.
git-svn-id: https://svn.apache.org/repos/asf/maven/plugins/trunk@1085698 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/src/site/apt/examples/app-client-dependency.apt.vm b/src/site/apt/examples/app-client-dependency.apt.vm
new file mode 100644
index 0000000..c7212a0
--- /dev/null
+++ b/src/site/apt/examples/app-client-dependency.apt.vm
@@ -0,0 +1,54 @@
+ ------
+ Using the app-client as a dependency
+ ------
+ Pete Marvin King
+ Stephane Nicoll
+ ------
+ 2011-03-26
+ ------
+
+ ~~ 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
+
+
+Using the app-client as a dependency
+
+ Once the ACR Plugin has been used to generate an application client, the generated artifact can be used as a
+ dependency by specifying the the <<<type>>> as <<<app-client>>>.
+
+* Normal way of adding an Application Client dependency
+
+ The following dependency declaration would include the <<<application-client-project-1.0-SNAPSHOT.jar>>> in your
+ project's package.
+
++------------+
+<project>
+ [...]
+ <dependencies>
+ <dependency>
+ <groupId>com.example</groupId>
+ <artifactId>application-client-project</artifactId>
+ <version>1.0-SNAPSHOT</version>
+ <type>app-client</type>
+ </dependency>
+ </dependencies>
+ [...]
+</project>
++------------+
diff --git a/src/site/apt/examples/filter-deployment-descriptor.apt.vm b/src/site/apt/examples/filter-deployment-descriptor.apt.vm
new file mode 100644
index 0000000..145f0a5
--- /dev/null
+++ b/src/site/apt/examples/filter-deployment-descriptor.apt.vm
@@ -0,0 +1,56 @@
+ ------
+ Filter the deployment descriptor
+ ------
+ Dennis Lundberg
+ Stephane Nicoll
+ ------
+ 2011-03-26
+ ------
+
+~~ 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
+
+Filter the deployment descriptor
+
+ The ACR Plugin is capable of filtering the deployment descriptor
+ (<<</META-INF/application-client.xml>>>) for you, if you have the need to inject values
+ into it during the build.
+
+ To filter the deployment descriptor add the following configuration to your
+ POM:
+
++-------+
+<project>
+ ...
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-acr-plugin</artifactId>
+ <version>${project.version}</version>
+ <configuration>
+ <filterDeploymentDescriptor>true</filterDeploymentDescriptor>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+ ...
+</project>
++-------+
diff --git a/src/site/apt/index.apt b/src/site/apt/index.apt
new file mode 100644
index 0000000..d763572
--- /dev/null
+++ b/src/site/apt/index.apt
@@ -0,0 +1,72 @@
+ ------
+ Introduction
+ ------
+ Stephane Nicoll
+ <snicoll@apache.org>
+ ------
+ 2011-03-26
+ ------
+
+ ~~ 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
+
+
+Maven ACR Plugin
+
+ This plugin generates J2EE Application Client file.
+
+* Goals Overview
+
+ {{{./acr-mojo.html}acr:acr}} - used by Maven for projects with <<<app-client>>> package type.
+
+* Usage
+
+ General instructions on how to use the ACR 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 have a look at the {{{./faq.html}FAQ}} and feel
+ free to contact the {{{./mail-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 {{{./mail-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-tracking.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
+ {{{./source-repository.html}source repository}} and will find supplementary information in the
+ {{{http://maven.apache.org/guides/development/guide-helping.html}guide to helping with Maven}}.
+
+* Examples
+
+ To provide you with better understanding on some usages of the Maven ACR Plugin,
+ you can take a look into the following examples:
+
+ * {{{./examples/filter-deployment-descriptor.html}Filter the deployment descriptor}}
+
+ * {{{./examples/app-client-dependency.html}Using the app-client as a dependency}}
+
+ []
+
+* Related Links
+
+ * {{{http://maven.apache.org/shared/maven-archiver/index.html}How to configure the archive, including its manifest}}
+
+ []
diff --git a/src/site/apt/usage.apt.vm b/src/site/apt/usage.apt.vm
new file mode 100644
index 0000000..7442d5d
--- /dev/null
+++ b/src/site/apt/usage.apt.vm
@@ -0,0 +1,65 @@
+ ------
+ Usage
+ ------
+ Stephane Nicoll
+ <snicoll@apache.org>
+ ------
+ 2011-03-26
+ ------
+
+ ~~ 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
+
+ The ACR Plugin is used to package a JavaEE Application Client module. There are two ways to use the ACR Plugin:
+
+ * If the packaging type defined in the <<<pom.xml>>> is <<<app-client>>>, the <<<package>>> lifecycle phase can be used
+
++--------------+
+ mvn package
++--------------+
+
+ Pay attention that prior to Maven 3.0.4, the plugin's extension must be enabled since the <<<app-client>>>
+ packaging type is new.
+
++-------+
+<project>
+ ...
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-acr-plugin</artifactId>
+ <version>${project.version}</version>
+ <extensions>true</extensions>
+ </plugin>
+ </plugins>
+ </build>
+ ...
+</project>
++-------+
+
+ * or using the <<<acr:acr>>> goal
+
++--------------+
+ mvn acr:acr
++--------------+
diff --git a/src/site/fml/faq.fml b/src/site/fml/faq.fml
new file mode 100644
index 0000000..ca1e997
--- /dev/null
+++ b/src/site/fml/faq.fml
@@ -0,0 +1,89 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+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.
+-->
+
+
+<faqs xmlns="http://maven.apache.org/FML/1.0.1"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/FML/1.0.1 http://maven.apache.org/xsd/fml-1.0.1.xsd"
+ id="FAQ" title="Frequently Asked Questions">
+ <part id="General">
+ <faq id="How can I specify a Class-Path: entry in the manifest of an Application Client jar?">
+ <question>How can I specify a Class-Path: entry in the manifest of an Application Client jar?</question>
+ <answer>
+ <p>
+ You just have to configure it:
+ <source><![CDATA[
+<project>
+ ...
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-acr-plugin</artifactId>
+ <version>${project.version}</version>
+ ...
+ <configuration>
+ <archive>
+ <manifest>
+ <addClasspath>true</addClasspath>
+ </manifest>
+ </archive>
+ </configuration>
+ ...
+ </plugin>
+ </plugins>
+ </build>
+ ...
+</project>
+ ]]></source>
+Please see the <a href="http://maven.apache.org/shared/maven-archiver/examples/classpath.html">Maven Archiver Reference</a>
+for more information about controlling the exact format of the generated class path entries.
+ </p>
+ </answer>
+ </faq>
+ <faq id="extensions">
+ <question>Why the app-client packaging type is not recognized?</question>
+ <answer>
+ <p>The app-client packaging type has been added as from Maven 3.0.4. If you are running an older version of Maven,
+ it does not know about that packaging type so you need to configure your project accordingly as follows:
+ <source><![CDATA[
+<project>
+ ...
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-acr-plugin</artifactId>
+ <version>${project.version}</version>
+ <extensions>true</extensions>
+ ...
+ </plugin>
+ </plugins>
+ </build>
+ ...
+</project>
+ ]]></source>
+
+ </p>
+ </answer>
+ </faq>
+ </part>
+</faqs>
\ No newline at end of file
diff --git a/src/site/site.xml b/src/site/site.xml
new file mode 100644
index 0000000..b35f318
--- /dev/null
+++ b/src/site/site.xml
@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+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.
+-->
+
+<project xmlns="http://maven.apache.org/DECORATION/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/DECORATION/1.0.0 http://maven.apache.org/xsd/decoration-1.0.0.xsd">
+ <body>
+ <menu name="Overview">
+ <item name="Introduction" href="index.html"/>
+ <item name="Goals" href="plugin-info.html"/>
+ <item name="Usage" href="usage.html"/>
+ <item name="FAQ" href="faq.html"/>
+ </menu>
+ <menu name="Examples">
+ <item name="Filter the deployment descriptor" href="examples/filter-deployment-descriptor.html" />
+ <item name="Using the app-client as a dependency" href="examples/app-client-dependency.html"/>
+ </menu>
+ </body>
+</project>
