Merged with rev. 428207 of assembly-plugin trunk.

git-svn-id: https://svn.apache.org/repos/asf/maven/plugins/branches/MASSEMBLY-124@428208 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/pom.xml b/pom.xml
index 2d959be..b2c4c7d 100755
--- a/pom.xml
+++ b/pom.xml
@@ -1,8 +1,26 @@
+<?xml version="1.0"?>
+
+<!--
+  ~ Copyright 2006 The Apache Software Foundation.
+  ~
+  ~ Licensed 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/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
   <parent>
     <artifactId>maven-plugins</artifactId>
     <groupId>org.apache.maven.plugins</groupId>
-    <version>1</version>
+    <version>2-SNAPSHOT</version>
   </parent>
   <modelVersion>4.0.0</modelVersion>
   <artifactId>maven-assembly-plugin.MASSEMBLY-124</artifactId>
@@ -12,6 +30,60 @@
   <prerequisites>
     <maven>2.0.4</maven>
   </prerequisites>
+  <issueManagement>
+    <system>jira</system>
+    <url>http://jira.codehaus.org/browse/MASSEMBLY</url>
+  </issueManagement>
+  <mailingLists>
+    <!-- duplication from maven-plugins pom - temporary until they inherit properly -->
+    <mailingList>
+      <name>Maven User List</name>
+      <subscribe>users-subscribe@maven.apache.org</subscribe>
+      <unsubscribe>users-unsubscribe@maven.apache.org</unsubscribe>
+      <post>users@maven.apache.org</post>
+      <archive>http://mail-archives.apache.org/mod_mbox/maven-users</archive>
+      <otherArchives>
+        <otherArchive>http://www.mail-archive.com/users@maven.apache.org/</otherArchive>
+        <otherArchive>http://www.nabble.com/Maven---Users-f178.html</otherArchive>
+      </otherArchives>
+    </mailingList>
+    <mailingList>
+      <name>Maven Developer List</name>
+      <subscribe>dev-subscribe@maven.apache.org</subscribe>
+      <unsubscribe>dev-unsubscribe@maven.apache.org</unsubscribe>
+      <post>dev@maven.apache.org</post>
+      <archive>http://mail-archives.apache.org/mod_mbox/maven-dev</archive>
+    </mailingList>
+    <mailingList>
+      <name>Maven Commits List</name>
+      <subscribe>commits-subscribe@maven.apache.org</subscribe>
+      <unsubscribe>commits-unsubscribe@maven.apache.org</unsubscribe>
+      <post>commits@maven.apache.org</post>
+      <archive>http://mail-archives.apache.org/mod_mbox/maven-dev</archive>
+    </mailingList>
+    <!-- duplication from maven-parent pom - temporary until they inherit properly -->
+    <mailingList>
+      <name>Maven Announcements List</name>
+      <post>announce@maven.apache.org</post>
+      <subscribe>announce-subscribe@maven.apache.org</subscribe>
+      <unsubscribe>announce-unsubscribe@maven.apache.org</unsubscribe>
+      <archive>http://mail-archives.apache.org/mod_mbox/maven-announce/</archive>
+    </mailingList>
+    <mailingList>
+      <name>Maven Issues List</name>
+      <post>issues@maven.apache.org</post>
+      <subscribe>issues-subscribe@maven.apache.org</subscribe>
+      <unsubscribe>issues-unsubscribe@maven.apache.org</unsubscribe>
+      <archive>http://mail-archives.apache.org/mod_mbox/maven-issues/</archive>
+    </mailingList>
+    <mailingList>
+      <name>Maven Notifications List</name>
+      <post>notifications@maven.apache.org</post>
+      <subscribe>notifications-subscribe@maven.apache.org</subscribe>
+      <unsubscribe>notifications-unsubscribe@maven.apache.org</unsubscribe>
+      <archive>http://mail-archives.apache.org/mod_mbox/maven-notifications/</archive>
+    </mailingList>
+  </mailingLists>
   <build>
     <plugins>
       <plugin>
diff --git a/src/main/mdo/component.mdo b/src/main/mdo/component.mdo
index b5aa655..e6aaa45 100755
--- a/src/main/mdo/component.mdo
+++ b/src/main/mdo/component.mdo
@@ -1,19 +1,43 @@
 <?xml version="1.0"?>
 
-<!-- Note Definitions of FileSet, FileItem, and DependencySet are 
+<!--
+  ~ Copyright 2006 The Apache Software Foundation.
+  ~
+  ~ Licensed 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 Definitions of FileSet, FileItem, and DependencySet are
      already defined in descriptor.mod, but repeated  here since
      Modello currently does not have capability to share files
 -->
+
 <model>
   <id>component</id>
   <name>Component</name>
   <description>
     <![CDATA[
-	<p>
-	Component contains FileSets, FileItems, and DependencySets already
-	define in Assembly. It allows multiple assemblies to share a set of user
-	defined collections.
-	</p>
+    <p>
+    When creating several assemblies for a project with a custom assembly
+    descriptor, it can't be helped that you will be duplicating some parts of
+    a defined assembly. These duplicates can be extracted and placed in a
+    separate file called a descriptor component.
+    </p>
+    <p>
+    Descriptor components contain FileSets, Files, and DependencySets meant
+    to be shared by assembly descriptors by referencing them using
+    &lt;componentDescriptors&gt;. It allows multiple assemblies to share a set
+    of user defined collections.
+    </p>
     ]]>
   </description>
   <defaults>
@@ -36,7 +60,11 @@
             <multiplicity>*</multiplicity>
           </association>
           <description>
-            Specify assembly parameters for groups of files.
+            <![CDATA[
+            Specifies which groups of files to include in the assembly. A
+            fileSet is specified by providing one or more of &lt;fileSet&gt;
+            subelements.
+            ]]>
           </description>
         </field>
         <field>
@@ -47,7 +75,11 @@
             <multiplicity>*</multiplicity>
           </association>
           <description>
-            Specify assembly parameters for single files.
+            <![CDATA[
+            Specifies which single files to include in the assembly. A file
+            is specified by providing one or more of &lt;file&gt;
+            subelements.
+            ]]>
           </description>
         </field>
         <field>
@@ -58,7 +90,11 @@
             <multiplicity>*</multiplicity>
           </association>
           <description>
-            Specify assembly behavior for sets of dependencies.
+            <![CDATA[
+            Specifies which dependencies to include in the assembly. A
+            dependencySet is specified by providing one or more of
+            &lt;dependencySet&gt; subelements.
+            ]]>
           </description>
         </field>
         <field>
@@ -69,7 +105,11 @@
             <multiplicity>*</multiplicity>
           </association>
           <description>
-            Specify assembly behavior for sets of repositories.
+            <![CDATA[
+            Specifies a set of repositories to include in the assembly. A
+            repository is specified by providing one or more of
+            &lt;repository&gt; subelements.
+            ]]>
           </description>
         </field>
       </fields>
@@ -84,7 +124,7 @@
           <version>1.0.0</version>
           <type>String</type>
           <description>
-            Specifies the output directory relative to the root
+            Sets the output directory relative to the root
             of the root directory of the assembly. For example,
             "log" will put the specified files in the log directory.
           </description>
@@ -98,8 +138,9 @@
           </association>
           <description>
             <![CDATA[
-            When &lt;include&gt; subelements are present, they define
-            a set of files and directory to include.
+            When &lt;include&gt; subelements are present, they define a set of
+            files and directory to include. If none is present, then
+            &lt;includes&gt; represents all valid values.
             ]]>
           </description>
         </field>
@@ -112,8 +153,9 @@
           </association>
           <description>
             <![CDATA[
-            When &lt;exclude&gt; subelements are present, they define
-            a set of files and directory to exclude.
+            When &lt;exclude&gt; subelements are present, they define a set of
+            files and directory to exclude. If none is present, then
+            &lt;excludes&gt; represents no exclusions.
             ]]>
           </description>
         </field>
@@ -124,10 +166,10 @@
           <defaultValue>0644</defaultValue>
           <description>
             <![CDATA[
-            Similar to a UNIX permission.  Format: (User)(Group)(Other) where each
-            component is a sum of Read = 4, Write = 2, and Execute = 1.  For example,
-            the default value of 0644 translates to User read-write, Group and Other 
-            read-only. 
+            Similar to a UNIX permission, sets the file mode of the files included.
+            Format: (User)(Group)(Other) where each component is a sum of Read = 4,
+            Write = 2, and Execute = 1.  For example, the default value of 0644
+            translates to User read-write, Group and Other read-only.
             <a href="http://www.onlamp.com/pub/a/bsd/2000/09/06/FreeBSD_Basics.html">(more on unix-style permissions)</a>
           	]]>
           </description>
@@ -139,10 +181,10 @@
           <defaultValue>0755</defaultValue>
           <description>
             <![CDATA[
-            Similar to a UNIX permission.  Format: (User)(Group)(Other) where each
-            component is a sum of Read = 4, Write = 2, and Execute = 1.  For example,
-            the default value of 0644 translates to User read-write, Group and Other 
-            read-only. 
+            Similar to a UNIX permission, sets the directory mode of the directories
+            included. Format: (User)(Group)(Other) where each component is a sum of
+            Read = 4, Write = 2, and Execute = 1.  For example, the default value of
+            0644 translates to User read-write, Group and Other read-only.
             <a href="http://www.onlamp.com/pub/a/bsd/2000/09/06/FreeBSD_Basics.html">(more on unix-style permissions)</a>
           	]]>
           </description>
@@ -153,15 +195,18 @@
       <name>FileSet</name>
       <version>1.0.0</version>
       <superClass>SetBase</superClass>
+      <description>
+        A fileSet allows the inclusion of groups of files into the assembly.
+      </description>
       <fields>
         <field>
           <name>directory</name>
           <version>1.0.0</version>
           <type>String</type>
           <description>
-            Absolute or relative from the module's directory. For
-            example, "src/main/bin" would select this subdirectory
-            of the project in which this dependency is defined.
+            Sets the absolute or relative location from the module's
+            directory. For example, "src/main/bin" would select this
+            subdirectory of the project in which this dependency is defined.
           </description>
           <required>true</required>
         </field>
@@ -171,8 +216,8 @@
           <type>String</type>
           <description>
             <![CDATA[
-            Controls the line-endings of files in this fileSet.
-            Valid values: 
+            Sets the line-endings of the files in this fileSet.
+            Valid values:
             <ul>
               <li><b>"keep"</b> - Preserve all line endings</li>
               <li><b>"unix"</b> - Use Unix-style line endings</li>
@@ -189,8 +234,8 @@
       <name>FileItem</name>
       <version>1.0.0</version>
       <description>
-        Allows individual file copy with option to change destination
-        file name not supported by fileSet
+        A file allows individual file inclusion with the option to change
+        the destination filename not supported by fileSets.
       </description>
       <fields>
         <field>
@@ -199,7 +244,8 @@
           <type>String</type>
           <required>true</required>
           <description>
-            Absolute or relative from the module's directory.
+            Sets the absolute or relative path from the module's directory
+            of the file to be included in the assembly.
           </description>
         </field>
         <field>
@@ -208,7 +254,7 @@
           <type>String</type>
           <required>false</required>
           <description>
-            Specifies the output directory relative to the root
+            Sets the output directory relative to the root
             of the root directory of the assembly. For example,
             "log" will put the specified files in the log directory.
           </description>
@@ -218,7 +264,7 @@
           <version>1.0.0</version>
           <type>String</type>
           <description>
-            Destination file name in outputDirectory.
+            Sets the destination filename in the outputDirectory.
             Default is the same name as the source's file.
           </description>
         </field>
@@ -229,10 +275,10 @@
           <defaultValue>0644</defaultValue>
           <description>
             <![CDATA[
-            Similar to a UNIX permission.  Format: (User)(Group)(Other) where each
-            component is a sum of Read = 4, Write = 2, and Execute = 1.  For example,
-            the default value of 0644 translates to User read-write, Group and Other 
-            read-only. 
+            Similar to a UNIX permission, sets the file mode of the files included.
+            Format: (User)(Group)(Other) where each component is a sum of Read = 4,
+            Write = 2, and Execute = 1.  For example, the default value of 0644
+            translates to User read-write, Group and Other read-only.
             <a href="http://www.onlamp.com/pub/a/bsd/2000/09/06/FreeBSD_Basics.html">(more on unix-style permissions)</a>
           	]]>
           </description>
@@ -243,8 +289,8 @@
           <type>String</type>
           <description>
             <![CDATA[
-            Controls the line-endings of files in this fileSet.
-            Valid values are: 
+            Sets the line-endings of the files in this file.
+            Valid values are:
             <ul>
               <li><b>"keep"</b> - Preserve all line endings</li>
               <li><b>"unix"</b> - Use Unix-style line endings</li>
@@ -260,7 +306,7 @@
           <version>1.0.0</version>
           <type>boolean</type>
           <description>
-            Flag used to determine if the file is filtered.
+            Sets whether to determine if the file is filtered.
           </description>
         </field>
       </fields>
@@ -270,7 +316,10 @@
       <name>DependencySet</name>
       <version>1.0.0</version>
       <superClass>SetBase</superClass>
-      <description>Defines a dependency set</description>
+      <description>
+        A dependencySet allows inclusion and exclusion of project dependencies
+        in the assembly.
+      </description>
       <fields>
         <field>
           <name>outputFileNameMapping</name>
@@ -278,9 +327,8 @@
           <type>String</type>
           <defaultValue>${artifactId}-${version}.${extension}</defaultValue>
           <description>
-            Specify the mapping pattern for all dependencies included
-            in this assembly.
-            Default is ${artifactId}-${version}.${extension}.
+            Sets the mapping pattern for all dependencies included in this
+            assembly. Default is ${artifactId}-${version}.${extension}.
           </description>
         </field>
         <field>
@@ -301,7 +349,7 @@
           <defaultValue>runtime</defaultValue>
           <required>true</required>
           <description>
-            Specifies the dependency scope for this dependencySet.
+            Sets the dependency scope for this dependencySet.
             Default scope value is "runtime".
           </description>
         </field>
diff --git a/src/main/mdo/descriptor.mdo b/src/main/mdo/descriptor.mdo
index 9b8d9d7..afaa675 100644
--- a/src/main/mdo/descriptor.mdo
+++ b/src/main/mdo/descriptor.mdo
@@ -1,32 +1,47 @@
 <?xml version="1.0"?>
 
 <!--
+  ~ Copyright 2006 The Apache Software Foundation.
+  ~
+  ~ Licensed 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.
+  -->
+
+<!--
   Since modello does not have the capability to share descriptor,
   If you make changes to FileSet, FileItem, DependendencySet, or
   adding new collection, make sure to propagate your changes
-  to "component.xml".
+  to "component.mdo".
 -->
 
-
 <model>
   <id>assembly</id>
   <name>Assembly</name>
   <description>
     <![CDATA[
-	<p>
-	A definition of an assembly.  This descriptor specifies the 
-	type of assembly archive to create, the contents of the 
-	assembly, and the ways in which dependencies are bundled with
-	an assembly.
-	</p>
-	<p>
-	An assembly defines a collection of files usually distributed in an
-	archive format such as zip, tar, or tar.gz that is generated from a
-	project.  For example, a project could produce a ZIP assembly which
-	contains a project's JAR artifact in the root directory, the 
-	runtime dependencies in a lib/ directory, and a shell script to launch
-	a stand-alone application.
-	</p>
+    <p>
+    Maven Assembly Plugin relies on the provided assembly descriptors to dictate
+    its execution. Although there are already prefabricated descriptors available
+    for use, they can only suffice some of the common assembly requirements.
+    </p>
+    <p>
+    So in order for you to customize the way the Assembly Plugin creates your
+    assemblies, you need to know how to use the Assembly Descriptor.
+    </p>
+    <p>
+    This descriptor specifies the type of assembly archive to create, the contents
+    of the assembly, and the ways in which dependencies or its modules are bundled
+    with an assembly.
+    </p>
     ]]>
   </description>
   <defaults>
@@ -38,7 +53,16 @@
   <classes>
     <class rootElement="true" xml.tagName="assembly">
       <name>Assembly</name>
-      <description>Describes the assembly layout and packaging.</description>
+      <description>
+        <![CDATA[
+        An assembly defines a collection of files usually distributed in an
+        archive format such as zip, tar, or tar.gz that is generated from a
+        project.  For example, a project could produce a ZIP assembly which
+        contains a project's JAR artifact in the root directory, the
+        runtime dependencies in a lib/ directory, and a shell script to launch
+        a stand-alone application.
+        ]]>
+      </description>
       <version>1.0.0</version>
       <fields>
         <field>
@@ -47,8 +71,11 @@
           <required>true</required>
           <type>String</type>
           <description>
-            The id of this assembly. This is a symbolic name for a
-            particular assembly of files from this project.
+            Sets the id of this assembly. This is a symbolic name for a
+            particular assembly of files from this project. Also, aside from
+            being used to distinctly name the assembled package by attaching
+            its value to the generated archive, the id is used as your
+            artifact's classifier when deploying.
           </description>
         </field>
         <field>
@@ -61,8 +88,11 @@
           </association>
           <description>
             <![CDATA[
-            Specify the formats of the assembly.  A format is specified by 
-            supplying one of the following values in a &lt;format&gt; subelement:
+            Specifies the formats of the assembly. Multiple formats can be
+            supplied and the Assembly Plugin will generate an archive for each
+            desired formats. When deploying your project, all file formats
+            specified will also be deployed. A format is specified by supplying
+            one of the following values in a &lt;format&gt; subelement:
             <ul>
               <li><b>"zip"</b> - Creates a ZIP file format</li>
               <li><b>"gz"</b> - Creates a GZIP format</li>
@@ -83,13 +113,18 @@
             includeBaseDirectory to true will create an archive that
             includes this base directory. If this option is set to false
             the archive created will unzip its content to the current
-            directory.
+            directory. Default value is true.
           </description>
         </field>
         <field>
           <name>includeSiteDirectory</name>
           <type>boolean</type>
           <defaultValue>false</defaultValue>
+          <description>
+            Includes a site directory in the final archive. The site directory
+            location of a project is determined by the siteDirectory parameter
+            of the Assembly Plugin. Default value is false.
+          </description>
         </field>
         <field>
           <name>moduleSets</name>
@@ -99,7 +134,11 @@
             <multiplicity>*</multiplicity>
           </association>
           <description>
-            Specify which modules source files to include in the assembly
+            <![CDATA[
+            Specifies which module files to include in the assembly. A moduleSet
+            is specified by providing one or more of &lt;moduleSet&gt;
+            subelements.
+            ]]>
           </description>
         </field>
         <field>
@@ -110,7 +149,11 @@
             <multiplicity>*</multiplicity>
           </association>
           <description>
-            Specify assembly parameters for groups of files.
+            <![CDATA[
+            Specifies which groups of files to include in the assembly. A
+            fileSet is specified by providing one or more of &lt;fileSet&gt;
+            subelements.
+            ]]>
           </description>
         </field>
         <field>
@@ -121,7 +164,11 @@
             <multiplicity>*</multiplicity>
           </association>
           <description>
-            Specify assembly parameters for single files.
+            <![CDATA[
+            Specifies which single files to include in the assembly. A file
+            is specified by providing one or more of &lt;file&gt;
+            subelements.
+            ]]>
           </description>
         </field>
         <field>
@@ -132,7 +179,11 @@
             <multiplicity>*</multiplicity>
           </association>
           <description>
-            Specify assembly behavior for sets of dependencies.
+            <![CDATA[
+            Specifies which dependencies to include in the assembly. A
+            dependencySet is specified by providing one or more of
+            &lt;dependencySet&gt; subelements.
+            ]]>
           </description>
         </field>
         <field>
@@ -143,7 +194,11 @@
             <multiplicity>*</multiplicity>
           </association>
           <description>
-            Specify assembly behavior for sets of repositories.
+            <![CDATA[
+            Specifies which repository files to include in the assembly. A
+            repository is specified by providing one or more of
+            &lt;repository&gt; subelements.
+            ]]>
           </description>
         </field>
         <field>
@@ -154,11 +209,17 @@
             <multiplicity>*</multiplicity>
           </association>
           <description>
-            File relative to basedir containing Component.
+            <![CDATA[
+            Specifies the shared components xml file locations to include in the
+            assembly. The locations specified must be relative to the basedir of
+            the project. When multiple componentDescriptors are found, their
+            contents are merged. Check out the <a href="component.html">
+            descriptor components</a> for more information. A
+            componentDescriptor is specified by providing one or more of
+            &lt;componentDescriptor&gt; subelements.
+            ]]>
           </description>
         </field>
-
-
       </fields>
     </class>
 
@@ -172,7 +233,7 @@
           <version>1.0.0</version>
           <type>String</type>
           <description>
-            Specifies the output directory relative to the root
+            Sets the output directory relative to the root
             of the root directory of the assembly. For example,
             "log" will put the specified files in the log directory.
           </description>
@@ -186,8 +247,9 @@
           </association>
           <description>
             <![CDATA[
-            When &lt;include&gt; subelements are present, they define
-            a set of files and directory to include.
+            When &lt;include&gt; subelements are present, they define a set of
+            files and directory to include. If none is present, then
+            &lt;includes&gt; represents all valid values.
             ]]>
           </description>
         </field>
@@ -200,8 +262,9 @@
           </association>
           <description>
             <![CDATA[
-            When &lt;exclude&gt; subelements are present, they define
-            a set of files and directory to exclude.
+            When &lt;exclude&gt; subelements are present, they define a set of
+            files and directory to exclude. If none is present, then
+            &lt;excludes&gt; represents no exclusions.
             ]]>
           </description>
         </field>
@@ -212,10 +275,10 @@
           <defaultValue>0644</defaultValue>
           <description>
             <![CDATA[
-            Similar to a UNIX permission.  Format: (User)(Group)(Other) where each
-            component is a sum of Read = 4, Write = 2, and Execute = 1.  For example,
-            the default value of 0644 translates to User read-write, Group and Other
-            read-only.
+            Similar to a UNIX permission, sets the file mode of the files included.
+            Format: (User)(Group)(Other) where each component is a sum of Read = 4,
+            Write = 2, and Execute = 1.  For example, the default value of 0644
+            translates to User read-write, Group and Other read-only.
             <a href="http://www.onlamp.com/pub/a/bsd/2000/09/06/FreeBSD_Basics.html">(more on unix-style permissions)</a>
           	]]>
           </description>
@@ -227,10 +290,10 @@
           <defaultValue>0755</defaultValue>
           <description>
             <![CDATA[
-            Similar to a UNIX permission.  Format: (User)(Group)(Other) where each
-            component is a sum of Read = 4, Write = 2, and Execute = 1.  For example,
-            the default value of 0644 translates to User read-write, Group and Other
-            read-only.
+            Similar to a UNIX permission, sets the directory mode of the directories
+            included. Format: (User)(Group)(Other) where each component is a sum of
+            Read = 4, Write = 2, and Execute = 1.  For example, the default value of
+            0755 translates to User read-write, Group and Other read-only.
             <a href="http://www.onlamp.com/pub/a/bsd/2000/09/06/FreeBSD_Basics.html">(more on unix-style permissions)</a>
           	]]>
           </description>
@@ -241,15 +304,18 @@
       <name>FileSet</name>
       <version>1.0.0</version>
       <superClass>SetBase</superClass>
+      <description>
+        A fileSet allows the inclusion of groups of files into the assembly.
+      </description>
       <fields>
         <field>
           <name>directory</name>
           <version>1.0.0</version>
           <type>String</type>
           <description>
-            Absolute or relative from the module's directory. For
-            example, "src/main/bin" would select this subdirectory
-            of the project in which this dependency is defined.
+            Sets the absolute or relative location from the module's
+            directory. For example, "src/main/bin" would select this
+            subdirectory of the project in which this dependency is defined.
           </description>
           <required>true</required>
         </field>
@@ -259,7 +325,7 @@
           <type>String</type>
           <description>
             <![CDATA[
-            Controls the line-endings of files in this fileSet.
+            Sets the line-endings of the files in this fileSet.
             Valid values:
             <ul>
               <li><b>"keep"</b> - Preserve all line endings</li>
@@ -277,8 +343,8 @@
       <name>FileItem</name>
       <version>1.0.0</version>
       <description>
-        Allows individual file copy with option to change destination
-        file name not supported by fileSet
+        A file allows individual file inclusion with the option to change
+        the destination filename not supported by fileSets.
       </description>
       <fields>
         <field>
@@ -287,7 +353,8 @@
           <type>String</type>
           <required>true</required>
           <description>
-            Absolute or relative from the module's directory.
+            Sets the absolute or relative path from the module's directory
+            of the file to be included in the assembly.
           </description>
         </field>
         <field>
@@ -296,7 +363,7 @@
           <type>String</type>
           <required>false</required>
           <description>
-            Specifies the output directory relative to the root
+            Sets the output directory relative to the root
             of the root directory of the assembly. For example,
             "log" will put the specified files in the log directory.
           </description>
@@ -306,7 +373,7 @@
           <version>1.0.0</version>
           <type>String</type>
           <description>
-            Destination file name in outputDirectory.
+            Sets the destination filename in the outputDirectory.
             Default is the same name as the source's file.
           </description>
         </field>
@@ -317,10 +384,10 @@
           <defaultValue>0644</defaultValue>
           <description>
             <![CDATA[
-            Similar to a UNIX permission.  Format: (User)(Group)(Other) where each
-            component is a sum of Read = 4, Write = 2, and Execute = 1.  For example,
-            the default value of 0644 translates to User read-write, Group and Other 
-            read-only. 
+            Similar to a UNIX permission, sets the file mode of the files included.
+            Format: (User)(Group)(Other) where each component is a sum of Read = 4,
+            Write = 2, and Execute = 1.  For example, the default value of 0644
+            translates to User read-write, Group and Other read-only.
             <a href="http://www.onlamp.com/pub/a/bsd/2000/09/06/FreeBSD_Basics.html">(more on unix-style permissions)</a>
           	]]>
           </description>
@@ -331,8 +398,8 @@
           <type>String</type>
           <description>
             <![CDATA[
-            Controls the line-endings of files in this fileSet.
-            Valid values are: 
+            Sets the line-endings of the files in this file.
+            Valid values are:
             <ul>
               <li><b>"keep"</b> - Preserve all line endings</li>
               <li><b>"unix"</b> - Use Unix-style line endings</li>
@@ -348,7 +415,7 @@
           <version>1.0.0</version>
           <type>boolean</type>
           <description>
-            Flag used to determine if the file is filtered.
+            Sets whether to determine if the file is filtered.
           </description>
         </field>
       </fields>
@@ -358,7 +425,10 @@
       <name>DependencySet</name>
       <version>1.0.0</version>
       <superClass>SetBase</superClass>
-      <description>Defines a dependency set</description>
+      <description>
+        A dependencySet allows inclusion and exclusion of project dependencies
+        in the assembly.
+      </description>
       <fields>
         <field>
           <name>outputFileNameMapping</name>
@@ -366,9 +436,8 @@
           <type>String</type>
           <defaultValue>${artifactId}-${version}.${extension}</defaultValue>
           <description>
-            Specify the mapping pattern for all dependencies included
-            in this assembly.
-            Default is ${artifactId}-${version}.${extension}.
+            Sets the mapping pattern for all dependencies included in this
+            assembly. Default is ${artifactId}-${version}.${extension}.
           </description>
         </field>
         <field>
@@ -378,8 +447,8 @@
           <description>
             If set to true, this property will unpack all dependencies
             into the specified output directory. When set to false
-            dependencies will be includes as archives (jars).
-            Default value is false.
+            dependencies will be includes as archives (jars). Can only unpack
+            jar, zip, tar.gz, and tar.bz archives. Default value is false.
           </description>
         </field>
         <field>
@@ -389,7 +458,7 @@
           <defaultValue>runtime</defaultValue>
           <required>true</required>
           <description>
-            Specifies the dependency scope for this dependencySet.
+            Sets the dependency scope for this dependencySet.
             Default scope value is "runtime".
           </description>
         </field>
@@ -398,6 +467,17 @@
 
     <class>
       <name>ModuleSet</name>
+      <description>
+        <![CDATA[
+        A moduleSet represent one or more project &lt;module&gt; present inside
+        a project's pom.xml. This allows you to include sources or binaries
+        belonging to a project's &lt;modules&gt;.
+
+        <br/><b>NOTE:</b> When using &lt;moduleSets&gt; from the command-line, it
+        is required to pass first the package phase by doing: "mvn package
+        assembly:assembly". This bug/issue is scheduled to be addressed by Maven 2.1.
+        ]]>
+      </description>
       <version>1.0.0</version>
       <fields>
         <field>
@@ -405,8 +485,10 @@
           <version>1.0.0</version>
           <description>
             <![CDATA[
-            This is a list of <include/> elements, each containing a module reference of the type groupId:artifactId.
-            Modules matching these elements will be included in this set.
+            This is a list of &lt;include/&gt; subelements, each containing a
+            module reference of the type groupId:artifactId. Modules matching
+            these elements will be included in this set. If none is present,
+            then &lt;includes&gt; represents all valid values.
             ]]>
           </description>
           <association>
@@ -419,8 +501,9 @@
           <version>1.0.0</version>
           <description>
             <![CDATA[
-            This is a list of <exclude/> elements, each containing a module reference of the type groupId:artifactId.
-            Modules matching these elements will be excluded from this set.
+            This is a list of &lt;exclude/&gt; subelements, each containing a
+            module reference of the type groupId:artifactId. Modules matching
+            these elements will be excluded from this set.
             ]]>
           </description>
           <association>
@@ -432,8 +515,8 @@
           <name>sources</name>
           <version>1.0.0</version>
           <description>
-            When this is configured, the plugin will include the source files of the included modules from this set in 
-            the resulting assembly, according to the configuration.
+            When this is present, the plugin will include the source files of
+            the included modules from this set in the resulting assembly.
           </description>
           <association>
             <type>ModuleSources</type>
@@ -443,8 +526,8 @@
           <name>binaries</name>
           <version>1.0.0</version>
           <description>
-            When this is configured, the plugin will include the binaries of the included modules from this set in 
-            the resulting assembly, according to the configuration.
+            When this is present, the plugin will include the binaries of the
+            included modules from this set in the resulting assembly.
           </description>
           <association>
             <type>ModuleBinaries</type>
@@ -457,14 +540,20 @@
       <name>ModuleSources</name>
       <version>1.0.0</version>
       <superClass>FileSet</superClass>
-      <description>Configuration for including the source files for a Module in an assembly.</description>
+      <description>
+        Contains configuration options for including the source files of a
+        project module in an assembly.
+      </description>
     </class>
 
     <class>
       <name>ModuleBinaries</name>
       <version>1.0.0</version>
       <superClass>SetBase</superClass>
-      <description>Configuration for including the binary files for a Module in an assembly.</description>
+      <description>
+        Contains configuration options for including the binary files of a
+        project module in an assembly.
+      </description>
       <fields>
         <field>
           <name>includeDependencies</name>
@@ -494,7 +583,7 @@
           <type>String</type>
           <defaultValue>${artifactId}-${version}.${extension}</defaultValue>
           <description>
-            Specify the mapping pattern for all dependencies included
+            Sets the mapping pattern for all dependencies included
             in this assembly.
             Default is ${artifactId}-${version}.${extension}.
           </description>
@@ -506,7 +595,18 @@
       <name>Repository</name>
       <version>1.0.0</version>
       <superClass>SetBase</superClass>
-      <description>Defines a Maven repository to be included in the assembly.</description>
+      <description>
+        <![CDATA[
+        Defines a Maven repository to be included in the assembly. The artifacts
+        available to be included in a repository are your project's dependency
+        artifacts. The repository created contains the needed metadata entries
+        and also contains both sha1 and md5 checksums. This is useful for creating
+        archives which will be deployed to internal repositories.
+
+        <br/><b>NOTE:</b> Currently, only artifacts from the central repository
+        are allowed.
+        ]]>
+      </description>
       <fields>
         <field>
           <name>includeMetadata</name>
@@ -516,13 +616,19 @@
           <description>
             If set to true, this property will trigger the creation of repository
             metadata which will allow the repository to be used as a functional remote
-            repository.
+            repository. Default value is false.
           </description>
         </field>
         <field>
           <name>groupVersionAlignments</name>
           <version>1.0.0</version>
-          <description>Align a group to a version or an individual artifact.</description>
+          <description>
+            <![CDATA[
+            Specifies that you want to align a group of artifacts to a specified
+            version. A groupVersionAlignment is specified by providing one or
+            more of &lt;groupVersionAlignment&gt; subelements.
+            ]]>
+          </description>
           <association>
             <type>GroupVersionAlignment</type>
             <multiplicity>*</multiplicity>
@@ -544,24 +650,38 @@
     <class>
       <name>GroupVersionAlignment</name>
       <version>1.0.0</version>
-      <description>Defines a Maven repository to be included in the assembly.</description>
+      <description>
+        Allows a group of artifacts to be aligned to a specified version.
+      </description>
       <fields>
         <field>
           <name>id</name>
           <version>1.0.0</version>
           <type>String</type>
-          <description>The groupId for which you want to align the versions.</description>
+          <description>
+            The groupId of the artifacts for which you want to align the
+            versions.
+          </description>
         </field>
         <field>
           <name>version</name>
           <version>1.0.0</version>
           <type>String</type>
-          <description>The version you want to align this group to.</description>
+          <description>
+            The version you want to align this group to.
+          </description>
         </field>
         <field>
           <name>excludes</name>
           <version>1.0.0</version>
-          <description>Artifact Ids of the artifacts you want excluded from version alignment.</description>
+          <description>
+            <![CDATA[
+            When &lt;exclude&gt; subelements are present, they define the
+            artifactIds of the artifacts to exclude. If none is present, then
+            &lt;excludes&gt; represents no exclusions. An exclude is specified
+            by providing one or more of &lt;exclude&gt; subelements.
+            ]]>
+          </description>
           <association>
             <type>String</type>
             <multiplicity>*</multiplicity>
@@ -571,4 +691,3 @@
     </class>
   </classes>
 </model>
-
diff --git a/src/main/resources/META-INF/plexus/components.xml b/src/main/resources/META-INF/plexus/components.xml
index fca0de3..5d6be11 100644
--- a/src/main/resources/META-INF/plexus/components.xml
+++ b/src/main/resources/META-INF/plexus/components.xml
@@ -1,3 +1,21 @@
+<?xml version="1.0"?>
+
+<!--
+  ~ Copyright 2006 The Apache Software Foundation.
+  ~
+  ~ Licensed 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.
+  -->
+
 <component-set>
   <components>
     <component>
diff --git a/src/main/resources/assemblies/bin.xml b/src/main/resources/assemblies/bin.xml
index e2650b4..95f3985 100755
--- a/src/main/resources/assemblies/bin.xml
+++ b/src/main/resources/assemblies/bin.xml
@@ -1,3 +1,21 @@
+<?xml version="1.0"?>
+
+<!--
+  ~ Copyright 2006 The Apache Software Foundation.
+  ~
+  ~ Licensed 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.
+  -->
+
 <assembly>
   <id>bin</id>
   <formats>
diff --git a/src/main/resources/assemblies/jar-with-dependencies.xml b/src/main/resources/assemblies/jar-with-dependencies.xml
index 8dbdc5f..e585bed 100644
--- a/src/main/resources/assemblies/jar-with-dependencies.xml
+++ b/src/main/resources/assemblies/jar-with-dependencies.xml
@@ -1,3 +1,21 @@
+<?xml version="1.0"?>
+
+<!--
+  ~ Copyright 2006 The Apache Software Foundation.
+  ~
+  ~ Licensed 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.
+  -->
+
 <assembly>
   <!-- TODO: a jarjar format would be better -->
   <id>jar-with-dependencies</id>
diff --git a/src/main/resources/assemblies/src.xml b/src/main/resources/assemblies/src.xml
index ee1a0d6..d3ce12a 100755
--- a/src/main/resources/assemblies/src.xml
+++ b/src/main/resources/assemblies/src.xml
@@ -1,3 +1,21 @@
+<?xml version="1.0"?>
+
+<!--
+  ~ Copyright 2006 The Apache Software Foundation.
+  ~
+  ~ Licensed 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.
+  -->
+
 <assembly>
   <id>src</id>
   <formats>
diff --git a/src/site/apt/descriptor-refs.apt b/src/site/apt/descriptor-refs.apt
index 9c82d6e..d8a4c52 100644
--- a/src/site/apt/descriptor-refs.apt
+++ b/src/site/apt/descriptor-refs.apt
@@ -1,43 +1,90 @@
  ------
- Maven 2 Assembly Plugin 
+ Predefined Assembly Descriptors 
  ------
- Johnny R. Ruiz III
- <jruiz@exist.com>
+ Johnny R. Ruiz III <jruiz@exist.com>
+ Edwin Punzalan
  ------
- September 20, 2005
+ 21 July 2006
+
+~~ Copyright 2006 The Apache Software Foundation.
+~~
+~~ Licensed 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/guides/mini/guide-apt-format.html
+
 
 Pre-defined Descriptor Files
 
-*bin.xml    descriptorId:bin
+  There are three predefined descriptor formats available for reuse, packaged
+  within the Assembly Plugin.  Their descriptorIds are:
 
-------
-    <assembly>
-      <id>bin</id>
-      <formats>
-        <format>tar.gz</format>
-        <format>tar.bz2</format>
-        <format>zip</format>
-      </formats>
-      <fileSets>
-        <fileSet>
-          <includes>
-            <include>README*</include>
-            <include>LICENSE*</include>
-            <include>NOTICE*</include>
-          </includes>
-        </fileSet>
-        <fileSet>
-          <directory>target</directory>
-          <outputDirectory></outputDirectory>
-          <includes>
-            <include>*.jar</include>
-          </includes>
-        </fileSet>
-      </fileSets>
-    </assembly>
+  * {{{#bin}bin}} - can be used for general assembly of binary packages.
+
+  * {{{#jar-with-dependencies}jar-with-dependencies}} - can be used for general
+  assembly of a binary package with all the dependency libraries included
+  unpacked inside the archive.
+
+  * {{{#src}src}} - can be used for general assembly of a source archive which can
+  be used to build your project.
+
+* {bin}
+
+  Use <<<bin>>> as the <<<descriptorId>>> of your assembly to create a binary
+  distribution archive of your project. The <<<bin>>> descriptorId produces
+  the archive in three formats: tar.gz, tar.bz2, and zip.
+
+  The assembled archive contains the binary jar produced by running
+  <<<mvn package>>> plus any README, LICENSE, and NOTICE files available in the
+  project root directory.
+
+  Below is the <<<bin>>> descriptor format:
+
+-----
+<assembly>
+  <id>bin</id>
+  <formats>
+    <format>tar.gz</format>
+    <format>tar.bz2</format>
+    <format>zip</format>
+  </formats>
+  <fileSets>
+    <fileSet>
+      <includes>
+        <include>README*</include>
+        <include>LICENSE*</include>
+        <include>NOTICE*</include>
+      </includes>
+    </fileSet>
+    <fileSet>
+      <directory>target</directory>
+      <outputDirectory></outputDirectory>
+      <includes>
+        <include>*.jar</include>
+      </includes>
+    </fileSet>
+  </fileSets>
+</assembly>
 ------
 
-*jar-with-dependencies.xml  descriptorId:jar-with-dependencies
+* {jar-with-dependencies}
+
+  Use the <<<jar-with-dependencies>>> as the <<<descriptorId>>> of your assembly
+  to create a jar archive which contains the binary output of your project along
+  with the unpacked dependencies. The <<<jar-with-dependencies>>> descriptorId
+  produces one archive in jar format.
+
+  Below is the <<<jar-with-dependencies>>> descriptor format:
 
 -----
 <assembly>
@@ -46,12 +93,6 @@
     <format>jar</format>
   </formats>
   <includeBaseDirectory>false</includeBaseDirectory>
-  <fileSets>
-    <fileSet>
-      <directory>target/classes</directory>
-      <outputDirectory>/</outputDirectory>
-    </fileSet>
-  </fileSets>
   <dependencySets>
     <dependencySet>
       <outputDirectory>/</outputDirectory>
@@ -62,7 +103,14 @@
 </assembly>
 -----
 
-*src.xml   descriptorId:xml
+* {src}
+
+  Use <<<src>>> as the <<<descriptorId>>> of your assembly to create source
+  archives for your project.  The archive should contain enough information
+  for anyone to be able to build your project. The <<<src>>> descriptorId
+  produces the archive in three formats: tar.gz, tar.bz2, and zip.
+
+  Below is the <<<src>>> descriptor format:
 
 -----
 <assembly>
@@ -87,7 +135,3 @@
   </fileSets>
 </assembly>
 -----
-
-
- 
-
diff --git a/src/site/apt/examples/index.apt b/src/site/apt/examples/index.apt
index 62d276e..7c4786f 100644
--- a/src/site/apt/examples/index.apt
+++ b/src/site/apt/examples/index.apt
@@ -1,5 +1,5 @@
   ---
-  Assembly Plugin - Examples
+  Examples
   ---
   John Casey
   ---
@@ -23,24 +23,31 @@
 ~~ NOTE: For help with the syntax of this file, see:
 ~~ http://maven.apache.org/guides/mini/guide-apt-format.html
                                                                                                                         
-Assembly Plugin - Examples
+Examples
 
 * Table of Contents
 
-  Below, you will see a series of examples showing how to use the assembly
-  plugin in various contexts.
+  Below, you will see a series of examples showing how to use the Assembly
+  Plugin in various contexts.
+
+  * {{{single/index.html}Working with Single Projects}}
+
+    * {{{single/filtering-some-distribution-files.html}Filtering Some Distribution Files}}
+
+    * {{{single/including-and-excluding-artifacts.html}Including/Excluding Artifacts}}
+
+    * {{{single/using-components.html}Using Component Descriptors}}
+
+    * {{{single/using-repositories.html}Using Repositories}}
+
+    []
+
+  * {{{multimodule/index.html}Working with Multi-Module Projects}}
   
-  * Working with Multi-Module Projects
-  
-    * {{{multimodule/module-source-inclusion-simple.html}Adding Module Sources to the Assembly}} <(Simple)>
+    * {{{multimodule/module-source-inclusion-simple.html}Adding Module Sources to the Assembly}}
     
-    * {{{multimodule/module-binary-inclusion-simple.html}Adding Module Binaries to the Assembly}} <(Simple)>
+    * {{{multimodule/module-binary-inclusion-simple.html}Adding Module Binaries to the Assembly}}
     
     []
     
   []
-
-
-    
-    
-
diff --git a/src/site/apt/examples/multimodule/index.apt b/src/site/apt/examples/multimodule/index.apt
new file mode 100644
index 0000000..94665f0
--- /dev/null
+++ b/src/site/apt/examples/multimodule/index.apt
@@ -0,0 +1,35 @@
+  ---
+  Multi-Module Examples
+  ---
+  Edwin Punzalan
+  ---
+  24-July-2006
+  ---
+
+~~ Copyright 2006 The Apache Software Foundation.
+~~
+~~ Licensed 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/guides/mini/guide-apt-format.html
+
+Multi-Module Examples
+
+  Multimodule Projects use \<moduleSets\> in their assemblies.
+
+  The examples below may be able to help you when creating assemblies for your
+  multimodule project.
+
+    * {{{module-source-inclusion-simple.html}Adding Module Sources to the Assembly}}
+
+    * {{{module-binary-inclusion-simple.html}Adding Module Binaries to the Assembly}}
diff --git a/src/site/apt/examples/multimodule/module-binary-inclusion-simple.apt b/src/site/apt/examples/multimodule/module-binary-inclusion-simple.apt
index 70691fb..bba2c27 100644
--- a/src/site/apt/examples/multimodule/module-binary-inclusion-simple.apt
+++ b/src/site/apt/examples/multimodule/module-binary-inclusion-simple.apt
@@ -1,5 +1,5 @@
   ---
-  Assembly Plugin Example - Including Module Artifacts
+  Including Module Binaries
   ---
   John Casey
   ---
@@ -23,13 +23,13 @@
 ~~ NOTE: For help with the syntax of this file, see:
 ~~ http://maven.apache.org/guides/mini/guide-apt-format.html
                                                                                                                         
-Assembly Plugin Example - Including Module Artifacts
+Including Module Binaries
 
 * Introduction
 
   It is common practice to create an assembly using the parent POM of a
   multimodule build. At times, you may want to ensure that this assembly also
-  includes one or more of the module artifacts.
+  includes one or more of the module binaries.
   
   This example demonstrates how to include the artifact and dependencies of a 
   module, under the directory <<<modules/\<module-name\>>>>.
@@ -113,7 +113,7 @@
 </project>
 +---+
 
-  This POM simply directs the assembly plugin to use the <<<bin.xml>>>
+  This POM simply directs the Assembly Plugin to use the <<<bin.xml>>>
   assembly descriptor when executing.
   
 * Execute!
diff --git a/src/site/apt/examples/multimodule/module-source-inclusion-simple.apt b/src/site/apt/examples/multimodule/module-source-inclusion-simple.apt
index 89697f3..a1a7085 100644
--- a/src/site/apt/examples/multimodule/module-source-inclusion-simple.apt
+++ b/src/site/apt/examples/multimodule/module-source-inclusion-simple.apt
@@ -1,5 +1,5 @@
   ---
-  Assembly Plugin Example - Including Module Sources
+  Including Module Sources
   ---
   John Casey
   ---
@@ -23,7 +23,7 @@
 ~~ NOTE: For help with the syntax of this file, see:
 ~~ http://maven.apache.org/guides/mini/guide-apt-format.html
                                                                                                                         
-Assembly Plugin Example - Including Module Sources
+Including Module Sources
 
 * Introduction
 
@@ -111,7 +111,7 @@
 </project>
 +---+
 
-  This POM simply directs the assembly plugin to use the <<<src.xml>>>
+  This POM simply directs the Assembly Plugin to use the <<<src.xml>>>
   assembly descriptor when executing.
   
 * Execute!
diff --git a/src/site/apt/examples/single/filtering-some-distribution-files.apt b/src/site/apt/examples/single/filtering-some-distribution-files.apt
new file mode 100644
index 0000000..0187569
--- /dev/null
+++ b/src/site/apt/examples/single/filtering-some-distribution-files.apt
@@ -0,0 +1,176 @@
+  ---
+  Filtering Some Distribution Files
+  ---
+  Edwin Punzalan
+  ---
+  26-July-2006
+  ---
+
+~~ Copyright 2006 The Apache Software Foundation.
+~~
+~~ Licensed 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/guides/mini/guide-apt-format.html
+
+
+Filtering Some Distribution Files
+
+* Introduction
+
+  File filtering is used to substitute variable fields from inside a file to
+  their represented values. For the Assembly Plugin, and most Maven filtering
+  procedures, these variables are enclosed between $\{ and \}. For
+  example, before a file is filtered, it contains <<<$\{project.artifactId\}>>>.
+  But after filtering is complete, a new file is created with the project's
+  <<<artifactId>>> substituting <<<$\{project.artifactId\}>>> and that this new
+  file is used instead of the original one.
+
+  Although filtering can be done during the process-resources phase, not all
+  files going into your distribution will be coming from a project resource.
+  Thus, the Assembly Plugin allows filtering of files before copying them into
+  the created assembly.
+
+  This example demonstrates how to filter files before adding them into the
+  assembly. In this example, we need to filter distribution files into the
+  archive. The files included in the distribution are:
+
+    * README.txt
+
+    * LICENSE.txt
+
+    * NOTICE.txt
+
+    []
+
+  All the above files are in the root directory of the project but only the
+  README and the NOTICE files should be filtered. The property file used to
+  filter these are files is found in <<<src/assemble/filter.properties>>>.
+
+  A property file is a file which contains the names of the variables and their
+  corresponding string value. The format of its contents is identical to how Java
+  Property files are saved. Below is an example of a property file:
+
++---
+# lines beginning with the # sign are comments
+
+variable1=value1
+variable2=value2
++---
+
+
+* The Assembly Descriptor
+
+  Filtering is only enabled inside \<files\> so that's what we will use. Thus,
+  our assembly descriptor will be:
+
++-----
+<assembly>
+  <id>distribution</id>
+  <formats>
+    <format>jar</format>
+  </formats>
+  <files>
+    <file>
+      <source>README.txt</source>
+      <outputDirectory>/</outputDirectory>
+      <filtered>true</filtered>
+    </file>
+    <file>
+      <source>LICENSE.txt</source>
+      <outputDirectory>/</outputDirectory>
+    </file>
+    <file>
+      <source>NOTICE.txt</source>
+      <outputDirectory>/</outputDirectory>
+      <filtered>true</filtered>
+    </file>
+  </files>
+</assembly>
++-----
+
+  The above descriptor tells the Assembly Plugin to filter both the README.txt
+  and the NOTICE.txt files and to just copy the LICENSE.txt file.
+
+  Alternatively, if there are many .txt files to include inside \<files\>, we can
+  setup both \<fileSets\> and \<files\> like so:
+
++-----
+<assembly>
+  <id>distribution</id>
+  <formats>
+    <format>jar</format>
+  </formats>
+  <fileSets>
+    <fileSet>
+      <directory>${basedir}</directory>
+      <includes>*.txt</includes>
+      <excludes>
+        <exclude>README.txt</exclude>
+        <exclude>NOTICE.txt</exclude>
+      </excludes>
+    </fileSet>
+  </fileSets>
+  <files>
+    <file>
+      <source>README.txt</source>
+      <outputDirectory>/</outputDirectory>
+      <filtered>true</filtered>
+    </file>
+    <file>
+      <source>NOTICE.txt</source>
+      <outputDirectory>/</outputDirectory>
+      <filtered>true</filtered>
+    </file>
+  </files>
+</assembly>
++-----
+
+  The above descriptor adds all .txt files to the assembly but filters README.txt
+  and NOTICE.txt files.
+
+
+* The POM
+
+  The configuration of the Assembly Plugin inside pom.xml should not be
+  different from the others, except for the configuration of the filter file, so:
+
++-----
+<project>
+  [...]
+  <build>
+    [...]
+    <plugins>
+      [...]
+      <plugin>
+        <artifactId>maven-assembly-plugin</artifactId>
+        <configuration>
+          <filters>
+            <filter>src/assemble/filter.properties</filter>
+          </filters>
+          <descriptors>
+            <descriptor>src/assemble/distribution.xml</descriptor>
+          </descriptors>
+        </configuration>
+      </plugin>
+   [...]
+</project>
++-----
+
+* Generating The Assembly
+
+  To generate the distribution assembly, we then use:
+
++-----
+mvn assembly:assembly
++-----
diff --git a/src/site/apt/examples/single/including-and-excluding-artifacts.apt b/src/site/apt/examples/single/including-and-excluding-artifacts.apt
new file mode 100644
index 0000000..c26b722
--- /dev/null
+++ b/src/site/apt/examples/single/including-and-excluding-artifacts.apt
@@ -0,0 +1,74 @@
+  ---

+  Including and Excluding Artifacts

+  ---

+  Barrie Treloar

+  ---

+  31-July-2006

+  ---

+

+~~ Copyright 2006 The Apache Software Foundation.

+~~

+~~ Licensed 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/guides/mini/guide-apt-format.html

+

+

+Including and Excluding Artifacts

+

+  Currently the include/exclude format is based upon the dependency conflict id

+  which has a form of: <<<groupId:artifactId:type:classifier>>>. A shortened

+  form of the dependency conflict id may also be used <<<groupId:artifactId>>>.

+

+  The check for inclusion/exclusion is done based on either the dependency

+  conflict id or the shortened form as a <<<String.equals()>>> so it must

+  be an identical match for it to be included or excluded. At present there is

+  no support for regular expressions.

+

+  This example excludes the log4j and commons-lang jar files from the assembly.

+  This would be useful when you are building a super distribution assembly which

+  contained sub distributions (i.e. other already assembled zips or tars) where

+  in your pom you are depenedent upon those distributions.  But because the

+  distributions transitively depend upon the project's dependencies the assembly

+  also includes the jar files (which are already in the assemblies and don't

+  need to be duplicated)

+

+  Your pom might include something like:

+

+-----

+    <dependencies>

+        <dependency>

+            <groupId>YOUR GROUP</groupId>

+            <artifactId>YOUR ARTIFACT</artifactId>

+            <version>YOUR VERSION</version>

+            <classifier>bin</classifier>

+            <type>zip</type>

+        </dependency>

+-----

+

+  And then in your assembly you exclude all the jar dependencies pulled in

+  from the binary assembly. In this example the commons-lang and log4j jars

+  are included unnecessarily (as they are in the bin.zip file already)

+

+-----

+  <dependencySets>

+    <dependencySet>

+      ....

+      <excludes>

+        <exclude>commons-lang:commons-lang</exclude>

+        <exclude>log4j:log4j</exclude>

+      </excludes>

+    </dependencySet>

+    ....

+  </dependencySets>

+-----

diff --git a/src/site/apt/examples/single/index.apt b/src/site/apt/examples/single/index.apt
new file mode 100644
index 0000000..24c0645
--- /dev/null
+++ b/src/site/apt/examples/single/index.apt
@@ -0,0 +1,39 @@
+  ---
+  Single Project Examples
+  ---
+  Edwin Punzalan
+  ---
+  24-July-2006
+  ---
+
+~~ Copyright 2006 The Apache Software Foundation.
+~~
+~~ Licensed 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/guides/mini/guide-apt-format.html
+
+Single Project Examples
+
+  A Single Project is a project whose assemblies does not use \<moduleSets\>.
+
+  The examples below may help you in creating assemblies for your single
+  projects.
+
+  * {{{filtering-some-distribution-files.html}Filtering Some Distribution Files}}
+
+  * {{{including-and-excluding-artifacts.html}Including/Excluding Artifacts}}
+
+  * {{{using-components.html}Using Component Descriptors}}
+
+  * {{{using-repositories.html}Using Repositories}}
diff --git a/src/site/apt/examples/single/using-components.apt b/src/site/apt/examples/single/using-components.apt
new file mode 100644
index 0000000..e73cd48
--- /dev/null
+++ b/src/site/apt/examples/single/using-components.apt
@@ -0,0 +1,187 @@
+  ---
+  Using Component Descriptors
+  ---
+  Edwin Punzalan
+  ---
+  24-July-2006
+  ---
+
+~~ Copyright 2006 The Apache Software Foundation.
+~~
+~~ Licensed 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/guides/mini/guide-apt-format.html
+
+Using Component Descriptors
+
+* Introduction
+
+  Suppose you have a project which will be distributed in two forms: one for
+  use with appserver A and another for appserver B. And as customization for
+  these two servers, you need to exclude some dependencies which are not used
+  by the appserver you will be distributing.
+
+  <<NOTE:>> <Although putting \<excludes\> inside \<dependencySets\> may provide
+  the result we want, it is not recommended because if a new appserver becomes
+  available, you will have to maintain the excludes of the other distributions
+  to exclude dependencies meant for the new appserver.>
+
+  This example demonstrate the use of \<componentDescriptors\>, more information
+  can be found {{{../../assembly.html}here}}.
+
+* The Assembly Descriptors
+
+  First, let's write the assembly descriptor for appserver A distribution. It
+  should like this:
+
++-----
+<assembly>
+  <id>appserverA</id>
+  <formats>
+    <format>zip</format>
+  </formats>
+  <dependencySets>
+    <dependencySet>
+      <outputDirectory>/lib</outputDirectory>
+      <includes>
+        <include>application:logging</include>
+        <include>application:core</include>
+        <include>application:utils</include>
+        <include>application:appserverA</include>
+      </includes>
+    </dependencySet>
+  </dependencySets>
+</assembly>
++-----
+
+  The assembly descriptor for appserver B distribution would then be similar:
+
++-----
+<assembly>
+  <id>appserverB</id>
+  <formats>
+    <format>zip</format>
+  </formats>
+  <dependencySets>
+    <dependencySet>
+      <outputDirectory>/lib</outputDirectory>
+      <includes>
+        <include>application:logging</include>
+        <include>application:core</include>
+        <include>application:utils</include>
+        <include>application:appserverB</include>
+      </includes>
+    </dependencySet>
+  </dependencySets>
+</assembly>
++-----
+
+  From the two descriptors shown, we can say that there are three artifacts
+  common for both, thus we separate them into a common component descriptor
+  and save it as <<<src/assemble/component.xml>>>.  Its contents would
+  be:
+
++-----
+<component>
+  <dependencySets>
+    <dependencySet>
+      <outputDirectory>/lib</outputDirectory>
+      <includes>
+        <include>application:logging</include>
+        <include>application:core</include>
+        <include>application:utils</include>
+      </includes>
+    </dependencySet>
+  </dependencySets>
+</component>
++-----
+
+  Then the final assembly descriptor for the appserver A would be:
+
++-----
+<assembly>
+  <id>appserverA</id>
+  <formats>
+    <format>zip</format>
+  </formats>
+  <componentDescriptors>
+    <componentDescriptor>src/assemble/component.xml</componentDescriptor>
+  </componentDescriptors>
+  <dependencySets>
+    <dependencySet>
+      <outputDirectory>/lib</outputDirectory>
+      <includes>
+        <include>application:appserverA</include>
+      </includes>
+    </dependencySet>
+  </dependencySets>
+</assembly>
++-----
+
+  And the corresponding assembly descriptor for the appserver B then would be:
+
++-----
+<assembly>
+  <id>appserverB</id>
+  <formats>
+    <format>zip</format>
+  </formats>
+  <componentDescriptors>
+    <componentDescriptor>src/assemble/component.xml</componentDescriptor>
+  </componentDescriptors>
+  <dependencySets>
+    <dependencySet>
+      <outputDirectory>/lib</outputDirectory>
+      <includes>
+        <include>application:appserverB</include>
+      </includes>
+    </dependencySet>
+  </dependencySets>
+</assembly>
++-----
+
+* The POM
+
+  Now we should update the POM configuration of the project for the Assembly
+  Plugin, which should look like:
+
++-----
+<project>
+  [...]
+  <build>
+    [...]
+    <plugins>
+      [...]
+      <plugin>
+        <artifactId>maven-assembly-plugin</artifactId>
+        <configuration>
+          <descriptors>
+            <descriptor>src/assemble/appserverA-assembly.xml</descriptor>
+            <descriptor>src/assemble/appserverB-assembly.xml</descriptor>
+          </descriptors>
+        </configuration>
+      </plugin>
+   [...]
+</project>
++-----
+
+* Creating The Distributions
+
+  Since we didn't configure the assembly plugin to always generate the
+  configured assemblies during the project's normal build lifecycles, we create
+  the distributions by:
+
++-----
+  mvn assembly:assembly
++-----
diff --git a/src/site/apt/examples/single/using-repositories.apt b/src/site/apt/examples/single/using-repositories.apt
new file mode 100644
index 0000000..55933be
--- /dev/null
+++ b/src/site/apt/examples/single/using-repositories.apt
@@ -0,0 +1,125 @@
+  ---
+  Using Repositories
+  ---
+  Edwin Punzalan
+  ---
+  26-July-2006
+  ---
+
+~~ Copyright 2006 The Apache Software Foundation.
+~~
+~~ Licensed 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/guides/mini/guide-apt-format.html
+
+Using Repositories
+
+* Introduction
+
+  The Assembly Plugin allows the inclusion of needed artifacts from your local
+  repository to the generated archive. They are copied into the assembly in a
+  directory similar to what's in your remote repository, complete with metadata
+  and the checksums.
+
+  This example demonstrates the creation of repository artifacts in an assembly
+  so that the archive can easily be used to update an internal repository with
+  the artifacts used by your project.
+
+* The Assembly Descriptor
+
+  A functional repository archive for your project can be created with:
+
++-----
+<assembly>
+  <id>repository</id>
+  <formats>
+    <format>jar</format>
+  </formats>
+  <repositories>
+    <repository>
+      <includeMetadata>true</includeMetadata>
+      <outputDirectory>maven2</outputDirectory>
+    </repository>
+  </repositories>
+</assembly>
++-----
+
+  The above descriptor tells the Assembly Plugin to create a repository-like
+  directory structure inside the <<<maven2>>> directory from within the
+  generated archive. Setting <<<includeMetadata>>> to <<<true>>> will make the
+  plugin to also copy metadata information into the generated archive.
+
+* The POM
+
+  The pom.xml for your project is very similar to how you configure the Assembly
+  Plugin for other distribution types.
+
++-----
+<project>
+  [...]
+  <build>
+    [...]
+    <plugins>
+      [...]
+      <plugin>
+        <artifactId>maven-assembly-plugin</artifactId>
+        <configuration>
+          <descriptors>
+            <descriptor>src/assemble/repository.xml</descriptor>
+          </descriptors>
+        </configuration>
+      </plugin>
+   [...]
+</project>
++-----
+
+* Generating The Assembly Archive
+
+  The assembly archive is then created using:
+
++-----
+mvn assembly:assembly
++-----
+
+  The generated archive can be extracted to an internal repository so users of
+  your project can download the dependencies from it.
+
+* Examining the Output
+
+  When the Maven execution completes, the archive contents should be similar to:
+
++-----
+target/artifactId-version-repository.jar
+`-- maven2
+    |-- groupId
+    |   |-- maven-metadata.xml
+    |   |-- maven-metadata.xml.md5
+    |   |-- maven-metadata.xml.sha1
+    |   `-- artifactId
+    |       |-- maven-metadata.xml
+    |       |-- maven-metadata.xml.md5
+    |       |-- maven-metadata.xml.sha1
+    |       `-- version
+    |           |-- artifactId-version.jar
+    |           |-- artifactId-version.jar.md5
+    |           |-- artifactId-version.jar.sha1
+    |           |-- artifactId-version.pom
+    |           |-- artifactId-version.pom.md5
+    |           |-- artifactId-version.pom.sha1
+    |           |-- maven-metadata.xml
+    |           |-- maven-metadata.xml.md5
+    |           `-- maven-metadata.xml.sha1
+    `-- groupId2
+        `-- [...]
++-----
diff --git a/src/site/apt/features.apt b/src/site/apt/features.apt
index dbdd809..98a64b8 100644
--- a/src/site/apt/features.apt
+++ b/src/site/apt/features.apt
@@ -1,13 +1,30 @@
   ---
-  Assembly Plugin - Features
+  Features
   ---
   John Casey
   ---
   12-May-2006
 
-Assembly Plugin - Features
+~~ Copyright 2006 The Apache Software Foundation.
+~~
+~~ Licensed 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.
 
-* Assembly Plugin Features
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/guides/mini/guide-apt-format.html
+
+Features
+
+  The current version of this plugin can be found {{{project-summary.html}here}}.
 
   <NOTE: Features with no version information have been present since the first final release of the plugin.>
 
@@ -25,7 +42,9 @@
   
   * Reusable assembly-descriptor components <[2.1]>
   
-  * Supported archive formats include: tar.gz, tar.bz2, zip, jar
+  * Supported archive formats include: zip, tar, tar.gz, tar.bz2, jar, dir, war
+   (and any other format that the ArchiveManager has been configured for).
+
   
   * Directory-only assemblies
   
diff --git a/src/site/apt/howto.apt b/src/site/apt/howto.apt
deleted file mode 100644
index fa2a0fb..0000000
--- a/src/site/apt/howto.apt
+++ /dev/null
@@ -1,187 +0,0 @@
- ------
- Maven 2 Assembly Plugin
- ------
- Johnny R. Ruiz III
- <jruiz@exist.com>
- ------
- October 16, 2005
-
-How to Use
-
-  These are brief examples of how to use the assembly:assembly and assembly:unpack goals.
-
-  To use the assembly:assembly goal, you must define the descriptor file that you are going to use or
-  define the descriptorId from the predefined {{{descriptor.html}descriptor ids}}.
-
-
-* How To use assembly:assembly using a customized descriptor file.
-
------
-  mvn assembly:assembly -Ddescriptor=path/to/descriptor.xml
------
-
-
-** How to assemble your project with your project modules only.
-  
-  There may be some situations that you only needed the jars of your project 
-  modules. You may exclude their dependencies but what if you have 10 
-  modules with 10 dependencies each? Isn't it a bit hassle to exclude 100 where 
-  you only needed 10. To achieve this goal, set the "projectModulesOnly" 
-  parameter to true and maven will do it for you.
-
------
- mvn assembly:assembly -DprojectModulesOnly=true
------
-
-
-* How to use assembly:assembly using predefined descriptor ids.
-
-----
-
-  mvn assembly:assembly -DdescriptorId=bin
-
-  or  mvn assembly:assembly -DdescriptorId=jar-with-dependencies
-
-  or  mvn assembly:assembly -DdescriptorId=src
-
------
-
-* How to configure the assembly:assembly plugin in your POM
-
- You can also configure this plugin inside your pom.xml.  To run use "mvn assembly:assembly".
-
------
-
-<project>
-  ...
-  <build>
-    ...
-    <plugins>
-      <plugin>
-        <artifactId>maven-assembly-plugin</artifactId>
-        <version>2.0-beta-1</version>
-        <configuration>
-          <descriptors>
-            <descriptor>path/to/descriptor.xml</descriptor>
-          </descriptors>
-          <finalName>final_name</finalName>
-          <outputDirectory>output/directory</outputDirectory>
-          <workDirectory>target/assembly/work</workDirectory>
-        </configuration>
-      </plugin>
-     </plugins>
-     ...
-   </build>
-   ...
-</project>
-
------
-
-
-* How to use assembly:unpack
-
-  After running this goal, all dependencies will be extracted into the location specified in the
-  \<workDirectory\> element.
-
------
- mvn assembly:unpack
------
-
-  For full documentation of plugin's goals and parameters, click {{{index.html}here}}.
-
-* How to assemble a repository
-
- The simplest descriptor you can create for assembly a repository would be something like the following:
-
------
-
-<assembly>
-  <id>bin</id>
-  <formats>
-    <format>zip</format>
-  </formats>
-  <repositories>
-    <repository>
-      <outputDirectory>repository</outputDirectory>
-    </repository>
-  </repositories>
-</assembly>
-
------
-
- With no <<<includes>>> or <<<excludes>>> specified all dependencies are used to create a repository. In fact when you
- specify no <<<includes>>> the default will be to include them all, but you can still specify <<<excludes>>> if you need
- to keep certain artifacts from making it into the repository you're trying to assemble.
-
- By default no repository metadata is generated when the repository is assembled. If you are trying to create a repository
- that is going to be used as a remote repository then you will need to have the metadata generated in order to for it
- to function properly as a remote repository. To do this just enable repository metadata generation by using the
- <<<includeMetadata>>> element:
-
------
-
-<assembly>
-  <id>bin</id>
-  <formats>
-    <format>zip</format>
-  </formats>
-  <repositories>
-    <repository>
-      <outputDirectory>repository</outputDirectory>
-      <includeMetadata>true</includeMetadata>
-    </repository>
-  </repositories>
-</assembly>
-
------
-
- Keep in mind that any dependencies specified in the POM will have their transitive dependencies placed in the
- assembly as well.
- 
- 
-* How to reuse assembly's component
- 
-   There are situations where your project can produce multiple assemblies with the same set of 
-   denpendencySets, fileSets and/or files. Instead of duplicating those elements in all assembly descriptors, 
-   you can refactor them out into  common component descriptor(s)
- 
-   Here is an example of assembly descriptor that uses component descriptor(s)
- 
------
- <assembly>
-   <id>someid</id>
-   <formats>
-     <format>zip</format>
-   </formats>
-   <componentDescriptors>
-     <componentDescriptor>src/main/assembly/component.xml</componentDescriptor>
-   </componentDescriptors>
- </assembly>
------
- 
- 
-  and here is an example of component descriptor file
-
------
-<component>
-  <dependencySets>
-    <dependencySet>
-       ....
-    </dependencySet>
-    ....
-  </dependencySets>
-  <fileSets>
-    <fileSet>
-      .....
-    </fileSet>
-    .....
-  </fileSets>
-  <files>
-    <file>
-      .....
-    </file>
-  </files>
-</component>
------
- 
- 
diff --git a/src/site/apt/index.apt b/src/site/apt/index.apt
index 080f5eb..8baf326 100644
--- a/src/site/apt/index.apt
+++ b/src/site/apt/index.apt
@@ -1,42 +1,141 @@
   ---
-  Assembly Plugin - Overview
+  Introduction
   ---
   John Casey
+  Edwin Punzalan
   ---
-  12-May-2006
+  18 July 2006
 
-Assembly Plugin - Overview
+~~ Copyright 2006 The Apache Software Foundation.
+~~
+~~ Licensed 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.
 
-* Introduction
-
-  The assembly plugin for Maven 2.0 is primarily intended to allow users to aggregate the project output along with its dependencies, modules, site documentation, and other files into a single distributable archive. 
-  
-  Your project build can build distribution assemblies easily, using one of the convenient, prefabricated assembly descriptors. These descriptors handle many common operations, such as packaging a project's artifact along with its dependencies in a single jar. Alternatively, your project can provide its own descriptor and assume a much higher level of control over how dependencies, modules, file-sets, and individual files are packaged in the assembly.
-
-* Table of Contents
-
-  * {{{features.html}Features}}
-
-  * {{{examples/index.html}Examples}}
-
-  * {{{usage.html}Configuration and Usage}}
-
-  * {{{advanced-configuration.html}Advanced Configuration}} <<[TODO]>>
-  
-  * {{{assembly-descriptor-howto.apt}Descriptor How-To}} <<[TODO]>>
-
-  * {{{assembly.html}Descriptor Reference}}
-
-  * {{{component.html}Reusable Descriptor Component Reference}}
-
-  []
-
-* XML Schema Locations
-
-  * {{{xsd/descriptor.xsd}Assembly Descriptor}}
-  
-  * {{{xsd/component.xsd}Reusable Assembly Component}}
-
-  []
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/guides/mini/guide-apt-format.html
 
 
+Maven Assembly Plugin
+
+  Do you want to create a binary distribution from a Maven project that includes
+  supporting scripts, configuration files, and all runtime dependencies?  You
+  need to use the Assembly Plugin to create a distribution for your project.
+
+  This plugin generates "assemblies". It is the equivalent of the Maven 1
+  distribution plug-in.  This plugin provides the capability to create binary
+  and source distributions.  These distributions (assemblies) are defined using
+  an assembly descriptor.  You can write your own {{{assembly.html}descriptor}}
+  to create a custom assembly, or you can reuse one of the three
+  {{{descriptor-refs.html}pre-defined assemblies}}.
+
+  Currently it can create distributions in the following formats:
+
+    * zip
+
+    * tar.gz
+
+    * tar.bz2
+
+    * jar
+
+    * dir
+
+    * war
+
+    * and any other format that the ArchiveManager has been configured for
+
+  To use the Assembly Plugin in Maven 2, you simply need to:
+
+    * choose or write the assembly descriptor to use,
+
+    * configure the Assembly Plugin in your project's pom.xml, and
+
+    * run "mvn assembly:assembly" on your project.
+
+  To write your own custom assembly, you will need to refer to the
+  {{{assembly.html}Assembly Descriptor Format}} reference.
+
+
+What is an Assembly?
+
+  An "assembly" is a group of files, directories, and dependencies that are
+  assembled into an archive format and distributed.  For example, assume that
+  a Maven project defines a single JAR artifact that contains both a console
+  application and a Swing application.  Such a project could define two
+  "assemblies" that bundle the application with a different set of supporting
+  scripts and dependency sets.  One assembly would be the assembly for the
+  console application, and the other assembly could be a Swing application
+  bundled with a slightly different set of dependencies.
+
+  The Assembly Plugin provides a descriptor format which allows you to define
+  an arbitrary assembly of files and directories from a project.  For example,
+  if your Maven 2 project contains the directory "src/main/bin", you can
+  instruct the Assembly Plugin to copy the contents of this directory to the
+  "bin" directory of an assembly and to change the permissions of the files in
+  the "bin" directory to UNIX mode 755.  The parameters for configuring this
+  behavior are supplied to the Assembly Plugin by way of the
+  {{{assembly.html}assembly descriptor}}.
+
+
+The Maven Assembly Plugin
+
+  The Assembly Plugin for Maven 2.0 is primarily intended to allow users to
+  aggregate the project output along with its dependencies, modules, site
+  documentation, and other files into a single distributable archive.
+
+  Your project build can build distribution assemblies easily, using one of the
+  convenient, prefabricated assembly descriptors. These descriptors handle many
+  common operations, such as packaging a project's artifact along with its
+  dependencies in a single jar. Alternatively, your project can provide its own
+  descriptor and assume a much higher level of control over how dependencies,
+  modules, file-sets, and individual files are packaged in the assembly.
+
+
+* Goals Overview
+
+  The Assembly Plugin has six goals:
+
+  * {{{assembly-mojo.html}assembly:assembly}} Assembles an application bundle
+  or distribution based on an assembly descriptor into an archive of a chosen
+  format. Executed from the command-line.
+
+  * {{{attached-mojo.html}assembly:attached}} Assembles an application bundle
+  or distribution from an assembly descriptor into an archive of a chosen
+  format. Executed within the Maven Lifecycle.
+
+  * {{{directory-mojo.html}assembly:directory}} Assembles an application bundle
+  from an assembly descriptor or distribution into a directory. Executed from
+  the command-line.
+
+  * {{{directory-inline-mojo.html}assembly:directory-inline}} Assembles an
+  application bundle or distribution into a directory. Executed within the Maven
+  Lifecycle.
+
+  * {{{unpack-mojo.html}assembly:unpack}} Assembles an application bundle or
+  distribution from an assembly descriptor into an archive of a chosen format
+  but with the dependencies unpacked inside the archive.
+
+  * {{{single-mojo.html}assembly:single}} An assembly mojo created as a
+  work-around for lifecycle issues until addressed in the Maven 2.1 release.
+
+
+* Usage
+
+  Instructions on how to use the Assembly Plugin can be found
+  {{{usage.html}here}}.
+
+
+* Examples
+
+  To provide you with better understanding on some usages of the Assembly
+  Plugin, you can take a look into the examples which can be found
+  {{{examples/index.html}here}}.
diff --git a/src/site/apt/introduction.apt b/src/site/apt/introduction.apt
deleted file mode 100644
index d801221..0000000
--- a/src/site/apt/introduction.apt
+++ /dev/null
@@ -1,58 +0,0 @@
- ------
- Maven 2 Assembly Plugin 
- ------
- Maven Development Team
- <dev@maven.apache.org>
- ------
- September 20, 2005
-
-Introduction
-
- Want to create a binary distribution from a Maven project that includes supporting 
- scripts, configuration files, and all runtime dependencies?  You need to use the assembly 
- plugin to create a distribution for your project.
-
- This plugin generates "assemblies". It is the equivalent of the 
- Maven 1 distribution plug-in.  This plugin provides the capability to create binary 
- and source distributions.  These distributions (assemblies) are defined using
- an assembly descriptor.  You can {{{assembly.html}write your own description}} to create a custom assembly,
- or you can reuse one of the {{{descriptor.html}three pre-defined assemblies}}.
-
- Currently it can create distribution formats such as: zip, tar.bz, tar.gz2, and jar.
-
- To use the assembly plugin in Maven 2, you simply need to:
- 
-   * configure the assembly in pom.xml, 
- 
-   * write an assembly descriptor, and
- 
-   * run "mvn assembly:assembly"  
-   
- For a more detailed, step-by-step 
- introduction to the assembly plugin, read this {{{howto.html}HOW-TO}}.
- 
- To write your own custom assembly, you will need to refer to the {{{assembly.html}Assembly
- Descriptor Format}} reference.
- 
-What is an Assembly?
-
- An "assembly" is a group of files, directories, and dependencies that is assembled into an 
- archive format and distributed.  For example, assume that a Maven project defines a single 
- JAR artifact that contains both a console application and a Swing application.  Such a 
- project could define two "assemblies" that bundle the application with a different set of 
- supporting scripts and dependency sets.  One assembly would be the assembly for the 
- console application, and the other assembly could be a Swing application bundled 
- with a slightly different set of dependencies.  
- 
- This assembly plugin provides a descriptor format which allows you to define an arbitrary
- assembly of files and directories from a project.  For example, if your Maven 2 project contains
- the directory "src/main/bin", you can instruct the assembly plugin to copy the contents of this 
- directory to the "bin" directory of an assembly and to change the permissions of the files in
- the "bin" directory to UNIX mode 755.  The parameters for configuring this behavior are supplied
- to the assembly plugin by way of the {{{assembly.html}assembly descriptor}}.
-
-Goal Overview
-
- An overview of the assembly plugin's goals can be found {{{index.html}here}}.
- To create a binary distribution for a project, use the {{{index.html}"assembly:assembly"}} goal.  
- To extract all project dependencies on certain working directory, use the {{{index.html}"assembly:unpack"}}.
diff --git a/src/site/apt/usage.apt b/src/site/apt/usage.apt
index fa78b65..7cb627a 100644
--- a/src/site/apt/usage.apt
+++ b/src/site/apt/usage.apt
@@ -1,11 +1,28 @@
   ---
-  Assembly Plugin - Configuration and Usage
+  Configuration and Usage
   ---
   John Casey
   ---
   12-May-2006
 
-Assembly Plugin - Configuration and Usage
+~~ Copyright 2006 The Apache Software Foundation.
+~~
+~~ Licensed 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/guides/mini/guide-apt-format.html
+
+Configuration and Usage
 
 * Introduction
 
@@ -14,19 +31,23 @@
   critical to cover two topics: configuration of the plugin - both inside the
   POM and, where possible, from the command line - and the different execution
   styles. For the sake of clarity, we'll cover configuration before execution.
-  
+
 * Configuring the Assembly Plugin
 
-  Getting started with the assembly plugin is pretty simple. If you're using one
+  Getting started with the Assembly Plugin is pretty simple. If you're using one
   of the prefabricated assembly descriptors, you just tell it which one; if
   you're using a custom assembly descriptor, you give it the path to the
-  descriptor. Note that a single invocation of the assembly plugin can actually
+  descriptor. Note that a single invocation of the Assembly Plugin can actually
   produce assemblies from multiple descriptors, allowing you maximum flexibility
-  to customize the suite of binaries your project produces.
+  to customize the suite of binaries your project produces. When the assembly is
+  created it will use the assemblyId as the artifact's classifier and will attach
+  the created assembly to the project and will be uploaded into the repository
+  on an install and deploy goal.
+  
   
   For example, imagine that our project produces a jar. If we want to create an
   assembly binary that includes our project's dependencies, we can take
-  advantage of one of the assembly plugin's prefabricated descriptors, as
+  advantage of one of the Assembly Plugin's prefabricated descriptors, as
   follows:
   
 +---+
@@ -49,12 +70,14 @@
 </project>
 +---+
 
-  Note that the assembly plugin allows you to specify multiple
+  Note that the Assembly Plugin allows you to specify multiple
   <<<descriptorRefs>>> at once, to produce multiple types of assemblies in a
   single invocation.
   
-  Alternatively, if we've created a custom assembly descriptor called
-  <<<src.xml>>> in the <<<src/assembly>>> directory (see the {{{#resources}Resources}} section for more information), we can tell the assembly plugin to use it instead:
+  Alternatively, we've created a custom assembly descriptor called
+  <<<src.xml>>> in the <<<src/assembly>>> directory (see the
+  {{{#Resources}Resources}} section for more information), we can tell the
+  Assembly Plugin to use it instead:
   
 +---+
 <project>
@@ -63,9 +86,6 @@
     [...]
     <plugins>
       <plugin>
-        <!-- NOTE: We don't need a groupId specification because the group is
-             org.apache.maven.plugins ...which is assumed by default.
-         -->
         <artifactId>maven-assembly-plugin</artifactId>
         <configuration>
           <descriptors>
@@ -81,7 +101,7 @@
   <<<descriptorRefs>>> within the same configuration.
   
   <<NOTE:>> Many other configuration options are available for the various mojos
-  in the assembly plugin. For more information, see the
+  in the Assembly Plugin. For more information, see the
   {{{examples/index.html}examples section}} or the {{{plugin-info.html}plugin
   parameter documentation}}.
   
@@ -93,7 +113,7 @@
   
   Currently, there are two basic approaches to building assemblies: as a
   dedicated build action, or bound to a phase of the normal build lifecycle.
-  Beyond this, it's also possible to have the assembly plugin simply create an
+  Beyond this, it's also possible to have the Assembly Plugin simply create an
   assembly directory for any given <<<descriptor>>> or <<<descriptorRef>>>,
   instead of creating archives.
   
@@ -105,7 +125,7 @@
 
   <<NOTE:>> Invoking the <<<assembly>>> and <<<directory>>> mojos will cause
   Maven to build the project using the normal lifecycle, up to the <<<package>>>
-  phase. Because many assemblies will contains compiled classes and other
+  phase. Because many assemblies will contain compiled classes and other
   binaries, it's reasonable to assume that the package phase will be required to
   ensure those binaries exist and have been tested. The main advantage of
   producing an assembly in this way is to avoid producing it as part of your
@@ -172,7 +192,7 @@
   discussed above, except that they are meant to bind into the default build
   lifecycle.
   
-  The <<<assembly>>> mojo forces a <<<package>>>-phase build to execute, in
+  The <<<assembly>>> mojo forces a <<<package>>> phase build to execute, in
   order to guarantee the availability of project binaries. Unfortunately, this
   currently means that binding the <<<assembly>>> mojo to the default lifecycle
   will cause Maven to execute the build twice - once for the main process, and
@@ -302,14 +322,14 @@
 
 * Advanced Configuration
 
-  As you've no doubt noticed, the assembly plugin can be a very useful way to
+  As you've no doubt noticed, the Assembly Plugin can be a very useful way to
   create a self-contained binary artifact for your project, among many other
   things. However, once you've created this self-contained jar, you will
   probably want the ability to execute it using the <<<-jar>>> JVM switch.
   
-  To accommodate this, the assembly plugin supports configuration of an
+  To accommodate this, the Assembly Plugin supports configuration of an
   <<<\<archive\>>>> element which is identical to that supported by the
-  <<<maven-jar-plugin>>> (see {{{#resources}Resources}}). Using this
+  <<<maven-jar-plugin>>> (see {{{#Resources}Resources}}). Using this
   configuration, it's easy to configure the <<<Main-Class>>> attribute of the
   jar manifest:
   
@@ -344,8 +364,8 @@
 Main-Class: org.sample.App
 +---+
 
-  For more information on advanced configuration for the assembly plugin, see
-  the {{{#resources}Resources}} section.
+  For more information on advanced configuration for the Assembly Plugin, see
+  the {{{#Resources}Resources}} section.
   
 ** GOTCHA!
 
@@ -353,16 +373,16 @@
   <<<directory-inline>>> - <<do not>> support the <<<\<archive\>>>>
   configuration element.
 
-* {resources}Resources
+* {Resources}
 
   [[1]] For more information on writing your own assembly descriptor, read the 
-        {{{assembly-descriptor-howto.apt}Assembly Descriptor How-To}}
+        {{{assembly.html}Assembly Descriptor}}
         
-  [[2]] For more information about the <<<maven-jar-plugin>>>,
-        {{{/plugins/maven-jar-plugin}look here}}.
+  [[2]] For more information about the <<<maven-jar-plugin>>>, look
+        {{{http://maven.apache.org/plugins/maven-jar-plugin/}here}}.
         
   [[3]] For more information on advanced <<<maven-assembly-plugin>>>
-        configuration, {{{advanced-configuration.html}look here}}.
+        configuration, see the {{{examples/index.html}examples}}.
   
   []
 
diff --git a/src/site/fml/faq.fml b/src/site/fml/faq.fml
new file mode 100644
index 0000000..f2e3aac
--- /dev/null
+++ b/src/site/fml/faq.fml
@@ -0,0 +1,41 @@
+<?xml version="1.0"?>
+
+<!--
+  ~ Copyright 2006 The Apache Software Foundation.
+  ~
+  ~ Licensed 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 id="FAQ" title="Frequently Asked Questions">
+  <part id="General">
+    <faq id="deploy">
+      <question>If the Assembly Plugin is run during the package phase, do my assemblies get deployed during the deploy phase?</question>
+      <answer>
+        <p>Yes. The assemblies created by the Assembly Plugin is attached to your project so it gets deployed too.</p>
+      </answer>
+    </faq>
+    <faq id="classifier">
+      <question>Can I use an artifact created by the assembly plugin as a dependency?</question>
+      <answer>
+        <p>Yes. You can refer to it using the id of the assembly as the dependency classifier.</p>
+      </answer>
+    </faq>
+    <faq id="javadoc">
+      <question>How do I use the Assembly Plugin to package my project's javadoc files?</question>
+      <answer>
+        <p>The Javadoc Plugin can generate the javadoc files of your projects. Also, the Javadoc Plugin can package them!</p>
+        <p>Please see the <a href="http://maven.apache.org/plugins/maven-javadoc-plugin/">Javadoc Plugin Documentation</a>.</p>
+      </answer>
+    </faq>
+  </part>
+</faqs>
diff --git a/src/site/site.xml b/src/site/site.xml
index 17034bc..3d7e480 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -1,22 +1,20 @@
 <?xml version="1.0" encoding="ISO-8859-1"?>
 
 <!--
-/*
- * Copyright 2001-2005 The Apache Software Foundation.
- *
- * Licensed 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.
- */
--->
+  ~ Copyright 2006 The Apache Software Foundation.
+  ~
+  ~ Licensed 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 name="Maven Assembly Plugin">
   <bannerLeft>
@@ -33,12 +31,31 @@
     </links>
 
     <menu name="Overview">
-      <item name="Introduction" href="introduction.html"/>
-      <item name="How to Use" href="howto.html"/>
-      <item name="Examples" href="examples/index.html"/>
+      <item name="Introduction" href="index.html"/>
+      <item name="Goals" href="plugin-info.html"/>
+      <item name="Usage" href="usage.html"/>
+      <item name="Features" href="features.html"/>
       <item name="Descriptor Format" href="assembly.html"/>
+      <item name="Component Format" href="component.html"/>
       <item name="Predefined Descriptors" href="descriptor-refs.html"/>
+      <item name="FAQ" href="faq.html"/>
     </menu>
+
+    <menu name="Examples">
+      <item name="Examples Index" href="examples/index.html"/>
+      <item name="Single Project" collapse="false" href="examples/single/index.html">
+        <item name="Filtering Some Distribution Files" href="examples/single/filtering-some-distribution-files.html"/>
+        <item name="Including/Excluding Artifacts" href="examples/single/including-and-excluding-artifacts.html"/>
+        <item name="Using Component Descriptors" href="examples/single/using-components.html"/>
+        <item name="Using Repositories" href="examples/single/using-repositories.html"/>
+      </item>
+      <item name="Multimodule Projects" collapse="false" href="examples/multimodule/index.html">
+        <item name="Include Module Artifacts" href="examples/multimodule/module-binary-inclusion-simple.html"/>
+        <item name="Include Module Sources" href="examples/multimodule/module-source-inclusion-simple.html"/>
+      </item>
+    </menu>
+
     ${reports}
+
   </body>
 </project>