o converting a few more docuements

git-svn-id: https://svn.apache.org/repos/asf/maven/components/trunk@321498 13f79535-47bb-0310-9956-ffa450edef68

maven-site/src/site/apt/guides/getting-started/index.apt

@@ -33,10 +33,10 @@ Sections
  * {{{index.html#How do I compile my test sources and run my unit tests?}How do I compile my test sources and run my unit tests?}}
 
  * {{{index.html#How do I create a JAR and install it in my local repository?}How do I create a JAR and install it in my local repository?}}
+ 
+ * {{{index.html#How do add resources to my JAR?}How do add resources to my JAR?}}
 
- * {{{index.html#How do I filter resources against my POM?}How do I filter resources against my POM?}}
+ * {{{index.html#How do I filter resource files?}How do I filter resource files?}}
-
- * {{{index.html#How do I filter resources against a properties file?}How do I filter resources against a properties file?}}
 
  * {{{index.html#How do I use external dependencies?}How do I use external dependencies?}}
 
@@ -48,7 +48,9 @@ Sections
 
  * {{{index.html#How do I use plug-ins?}How do I use plug-ins?}}
 
- * {{{index.html#How do I control what version of plug-in I use?}How do I control what version of plug-in I use?}}
+ * {{{index.html#How do I control what version of a plug-in I use?}How do I control what version of a plug-in I use?}}
+ 
+ * {{{index.html#How do I build more than one project at once?}How do I build more than one project at once?}}
 
  []
 
@@ -255,8 +257,11 @@ Compiling 1 source file to <dir>/my-app/target/classes
 
 +-----+
 
-~~DJ  When they run this the first time, it will take a LONG time because of downloading all the dependencies.
+ The first time you execute this (or any other) command, Maven will need to download all the plugins and related
-~~DJ  You really should say something about that here so they understand what's going on and don't get scared.
+ dependencies it needs to fulfill the command.  From a clean installation of Maven this can take quite a while (in
+ the output above, it took almost 4 minutes).  If you execute the command again, Maven will now have what it needs,
+ so it won't need to download anything new and will be able to execute the command much quicker.
+
  As you can see from the output, the compiled classes were placed in <<<$\{basedir\}/target/classes>>>, which is
  another standard convention employed by Maven. So, if you're a keen observer you'll notice that using the
  standard conventions the POM above is very small and you haven't explicity had to tell Maven where any of
@@ -269,8 +274,8 @@ Compiling 1 source file to <dir>/my-app/target/classes
 
 * {How do I compile my test sources and run my unit tests?}
 
- So you can now compile your applications sources and now you've got some unit tests that you want to compile
+ Now you're successfully compiling your application's sources and now you've got some unit tests that you want to compile
- and execute because every programmer always writes and executes their unit tests (nudge nudge wink wink).
+ and execute (because every programmer always writes and executes their unit tests *nudge nudge wink wink*).
 
  Execute the following command:
 
@@ -288,20 +293,23 @@ m2 test
 [INFO] Building Maven Quick Start Archetype
 [INFO]    task-segment: [test]
 [INFO] ----------------------------------------------------------------------------
+[INFO] artifact org.apache.maven.plugins:maven-surefire-plugin: checking for updates from central
+...
 [INFO] [resources:resources]
 [INFO] [compiler:compile]
-Compiling 1 source file to <dir>/my-app/target/classes
+[INFO] Nothing to compile - all classes are up to date
 [INFO] [resources:testResources]
 [INFO] [compiler:testCompile]
-Compiling 1 source file to <dir>/my-app/target/test-classes
+Compiling 1 source file to C:\Test\Maven2\test\my-app\target\test-classes
+...
 [INFO] [surefire:test]
-[INFO] Setting reports dir: <dir>/my-app/target/surefire-reports
+[INFO] Setting reports dir: C:\Test\Maven2\test\my-app\target/surefire-reports
 
 -------------------------------------------------------
  T E S T S
 -------------------------------------------------------
 [surefire] Running com.mycompany.app.AppTest
-[surefire] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 0.005 sec
+[surefire] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 0 sec
 
 Results :
 [surefire] Tests run: 1, Failures: 0, Errors: 0
@@ -309,14 +317,21 @@ Results :
 [INFO] ----------------------------------------------------------------------------
 [INFO] BUILD SUCCESSFUL
 [INFO] ----------------------------------------------------------------------------
-[INFO] Total time: 2 seconds
+[INFO] Total time: 15 seconds
-[INFO] Finished at: Mon Oct 03 15:06:22 GMT-05:00 2005
+[INFO] Finished at: Thu Oct 06 08:12:17 MDT 2005
-[INFO] Final Memory: 2M/6M
+[INFO] Final Memory: 2M/8M
 [INFO] ----------------------------------------------------------------------------
-
 +----+
 
- If you simply want to compile your test sources you can execute the following which does not run your unit tests:
+ Some things to notice about the output:
+ 
+    * Maven downloads more dependencies this time. These are the dependencies and plugins necessary for executing the tests
+      (it already has the dependencies it needs for compiling and won't download them again).
+    
+    * Before compiling and executing the tests Maven compiles the main code (all these classes are up to date because
+      we haven't changed anything since we compiled last).
+ 
+ If you simply want to compile your test sources (but not execute the tests), you can execute the following:
 
 +----+
 
@@ -324,7 +339,7 @@ Results :
 
 +----+
 
- Now that you can compile your application sources and compile your tests and execute them you'll want to move
+ Now that you can compile your application sources, compile your tests, and execute the tests, you'll want to move
  on to the next logical step so you'll be asking ...
 
 * {How do I create a JAR and install it in my local repository?}
@@ -337,13 +352,13 @@ m2 package
 
 +----+
 
- If you take a look at the POM for this project you will notice the <<<packaging>>> element is set to <<<jar>>>.
+ If you take a look at the POM for your project you will notice the <<<packaging>>> element is set to <<<jar>>>.
- This is how Maven knows to produce a JAR file from the above command and we'll talk more about this later.
+ This is how Maven knows to produce a JAR file from the above command (we'll talk more about this later).
- You can now take a look in the the <<<${basedir}/target>>> directory and you will see the generated JAR file.
+ You can now take a look in the the <<<$\{basedir\}/target>>> directory and you will see the generated JAR file.
 
- Now you'll want to install the artifact you've generated, the JAR file, in your local repository
+ Now you'll want to install the artifact you've generated (the JAR file) in your local repository
- (<<<~/.m2/repository>>> is the default value). For more information on repositories you can refer to our
+ (<<<~/.m2/repository>>> is the default location). For more information on repositories you can refer to our
- {{{introduction-to-archetypes.html}Introduction to Repositories}} but now on to installing our artifact!
+ {{{introduction-to-repositories.html}Introduction to Repositories}} but let's move on to installing our artifact!
  To do so execute the following command:
 
 +----+
@@ -392,7 +407,7 @@ Results :
 
 +----+
 
- Note that the surefire plugin looks for tests contained in files with a particular naming convention. By default
+ Note that the surefire plugin (which executes the test) looks for tests contained in files with a particular naming convention. By default
  the tests included are:
 
  * <<<\*\*/\*Test.java>>>
@@ -405,25 +420,25 @@ Results :
 
  And the default excludes are:
 
- * <<<\*\*/Abstract\\*Test.java>>>
+ * <<<\*\*/Abstract\*Test.java>>>
 
  * <<<\*\*/Abstract\*TestCase.java>>>
 
  []
 
- Now you have walked through setting up setting up a typical Maven project, building, testing, packaging and installing.
+ You have walked through the process for setting up, building, testing, packaging, and installing a typical Maven project.
- This is likely the vast majority of what you will be doing with Maven and if you'ved noticed everything you've been
+ This is likely the vast majority of what projects will be doing with Maven and if you'ved noticed, everything you've been
- able to do up to this point has been driven by an 18 line file, namely the project's model or POM. If you look at
+ able to do up to this point has been driven by an 18-line file, namely the project's model or POM. If you look at
  a typical Ant {{{../../ant/build-a1.xml}build file}} that provides the same functionality that we've achieved thus
  far you'll notice it's already twice the size of the POM and we're just getting started! There is far more
- functionality available to you as a user of Maven without requiring any additions to our POM as it is currently. To
+ functionality available to you from Maven without requiring any additions to our POM as it currently stands. To
- get any more functionality out of our example Ant build file you must keep making error prone additions.
+ get any more functionality out of our example Ant build file you must keep making error-prone additions.
 
  So what else can you get for free? There are a great number of Maven plug-ins that work out of the box with
  even a simple POM like we have above. We'll mention one here specifically as it is one of the highly
  prized features of Maven: without any work on your part this POM has enough information to generate
  a web site for your project! You will most likely want to customize your Maven site but if you're pressed for
- time all you need to do to provide basic information about your project is execution the following command:
+ time all you need to do to provide basic information about your project is execute the following command:
 
 +----+
 
@@ -431,16 +446,18 @@ m2 site:site
 
 +----+
 
- We'll touch on one more common usecase that can be satisfied which requires no changes to the POM that we have
+* {How do add resources to my JAR?}
- above which is packaging resources in JAR files. For this common task Maven again relies on the
+
- {{{introduction-to-the-standard-directory-layout.html}Standard Directory Layout}} which means by using
+ Another common usecase that can be satisfied which requires no changes to the POM that we have
- standard Maven coventions you can package resources within JARs simply by placing resources in a standard
+ above is packaging resources in the JAR file. For this common task, Maven again relies on the
+ {{{introduction-to-the-standard-directory-layout.html}Standard Directory Layout}}, which means by using
+ standard Maven coventions you can package resources within JARs simply by placing those resources in a standard
  directory structure.
 
- You see below in our example we have added the directory <<<${basedir}/src/main/resources>>> into which we place
+ You see below in our example we have added the directory <<<$\{basedir\}/src/main/resources>>> into which we place
  any resources we wish to package in our JAR. The simple rule employed by Maven is this: any directories or files
- placed within the <<<${basedir}/src/main/resources>>> directory are packaged in your JAR with the exact same
+ placed within the <<<$\{basedir\}/src/main/resources>>> directory are packaged in your JAR with the exact same
- structure starting at the base of the JAR
+ structure starting at the base of the JAR.
 
 +----+
 
@@ -485,16 +502,16 @@ my-app
 
 +----+
 
- As you can see the contents of <<<${basedir}/src/main/resources>>> can be found starting at the base of the
+ As you can see, the contents of <<<$\{basedir\}/src/main/resources>>> can be found starting at the base of the
- JAR and you will see our <<<application.properties>>> file. You will also notice some other files there
+ JAR and our <<<application.properties>>> file is there in the <<<META-INF>>> directory. You will also notice some other files there
- like <<<META-INF/MANIFEST.MF>>> and a <<<pom.xml>>> and <<<pom.properties>>> file. These come standard with
+ like <<<META-INF/MANIFEST.MF>>> as well as a <<<pom.xml>>> and <<<pom.properties>>> file. These come standard with
- generation of a JAR in Maven. You create your own manifest if you choose, but Maven will generate one by
+ generation of a JAR in Maven. You can create your own manifest if you choose, but Maven will generate one by
- default for you if you don't. You may also modify the entries in the default manifest which we will touch on
+ default if you don't. (You can also modify the entries in the default manifest. We will touch on this
- later. The <<<pom.xml>>> and <<<pom.properties>>> files are packaged up in the JAR so that each artifact
+ later.) The <<<pom.xml>>> and <<<pom.properties>>> files are packaged up in the JAR so that each artifact
- produced by Maven is self-describing and it also allows you to utilize the metadata in your own application
+ produced by Maven is self-describing and also allows you to utilize the metadata in your own application
  if the need arises. One simple use might be to retrieve the version of your application. Operating on the POM
  file would require you to use some Maven utilities but the properties can be utilized using the standard
- Java API and looks like the following:
+ Java API and look like the following:
 
 +----+
 
@@ -506,8 +523,8 @@ artifactId=my-app
 
 +----+
 
- To use resources with your unit tests you follow the same pattern except the directory you place resources in
+ To add resources to the classpath for your unit tests, you follow the same pattern as you do for adding resources to the JAR
- is ${basedir}/src/test/resources which are then availabe to you at the base of the classpath. So you would have a
+ except the directory you place resources in is $\{basedir\}/src/test/resources. At this point you would have a
  project directory structure that would look like the following:
 
 +---+
@@ -535,7 +552,7 @@ my-app
             `-- test.properties
 +---+
 
- So in a unit test you could use a simple snippet of code like the following to access the resource required for
+ In a unit test you could use a simple snippet of code like the following to access the resource required for
  testing:
 
 +----+
@@ -551,7 +568,14 @@ InputStream is = Thread.currentThread().getContextClassLoader().getResourceAsStr
 
 +----+
 
-* {How do I filter resources against my POM?}
+* {How do I filter resource files?}
+
+ Sometimes a resource file will need to contain a value that can only be supplied at build time.  To accomplish this in
+ Maven, put a reference to the property that will contain the value into your resource file using the syntax <<<$\{<property name}>\}>>>.
+ The property can be one of the values defined in your pom.xml, a value defined in the user's settings.xml, a property
+ defined in an external properties file, or a system property.
+ 
+ To have Maven filter resources when copying, simply set <<<filtering>>> to true for the resource directory in your pom.xml:
 
 +----+
 
@@ -564,7 +588,6 @@ InputStream is = Thread.currentThread().getContextClassLoader().getResourceAsStr
   <version>1.0-SNAPSHOT</version>
   <name>Maven Quick Start Archetype</name>
   <url>http://maven.apache.org</url>
-  <description>Killer App</description>
   <dependencies>
     <dependency>
       <groupId>junit</groupId>
@@ -585,16 +608,60 @@ InputStream is = Thread.currentThread().getContextClassLoader().getResourceAsStr
 
 +----+
 
+ You'll notice that we had to add the <<<build>>>, <<<resources>>>, and <<<resource>>> elements which weren't there before.
+ In addition, we had to explicitly state that the resources are located in the src/main/resources directory.  All of this
+ information was provided as default values previously, but because the default value for <<<filtering>>> is false, we had
+ to add this to our pom.xml in order to override that default value and set <<<filtering>>> to true.
+ 
+ To reference a property defined in your pom.xml, the property name uses the names of the XML elements that define the value,
+ with "pom" being allowed as an alias for the project (root) element.  So $\{pom.name\} refers to the name of the project,
+ $\{pom.version\} refers to the version of the project, $\{pom.build.finalName\} refers to the final name of the file created
+ when the built project is packaged, etc.  Note that some elements of the POM have default values, so don't need to be explicitly
+ defined in your pom.xml for the values to be available here.  Similarly, values in the user's settings.xml can be referenced
+ using property names beginning with "settings" (for example, $\{settings.localRepository\} refers to the path of the user's
+ local repository).
+ 
+ To continue our example, let's add a couple of properties to the application.properties file (which we put in the 
+ src/main/resources directory) whose values will be supplied when the resource is filtered:
+
 +----+
 
 # application.properties
-
 application.name=${pom.name}
 application.version=${pom.version}
 
 +----+
 
-* {How do I filter resources against a properties file?}
+ With that in place, you can execute the following command (process-resources is the build lifecycle phase where the resources are
+ copied and filtered):
+
++----+
+
+m2 process-resources
+
++----+
+
+ and the application.properties file under target/classes (and will eventually go into the jar) looks like this:
+
++----+
+
+# application.properties
+application.name=Maven Quick Start Archetype
+application.version=1.0-SNAPSHOT
+
++----+
+
+ To reference a property defined in an external file, all you need to do is add a reference to this external file in your pom.xml.
+ First, let's create our external properties file and call it src/main/filters/filter.properties:
+
++----+
+
+# filter.properties
+my.filter.value=hello!
+
++----+
+
+ Next, we'll add a reference to this new file in the pom.xml: 
 
 +----+
 
@@ -607,7 +674,6 @@ application.version=${pom.version}
   <version>1.0-SNAPSHOT</version>
   <name>Maven Quick Start Archetype</name>
   <url>http://maven.apache.org</url>
-  <description>Killer App</description>
   <dependencies>
     <dependency>
       <groupId>junit</groupId>
@@ -618,7 +684,7 @@ application.version=${pom.version}
   </dependencies>
   <build>
     <filters>
-      <filter>src/main/filters/filters.properties</filter>
+      <filter>src/main/filters/filter.properties</filter>
     </filters>
     <resources>
       <resource>
@@ -631,48 +697,87 @@ application.version=${pom.version}
 
 +----+
 
-+----+
+ Then, if we add a reference to this property in the application.properties file:
-
-# filtering.properties
-
-environment=development
-
-+----+
-
-+----+
-
-# application.properties
-
-application.name=${pom.name}
-application.version=${pom.version}
-
-environment=${environment}
-
-+----+
-
-* How do I filter against system properties
-
- You simply specify the system property using the standard variable notion as show below:
 
 +----+
 
 # application.properties
-
 application.name=${pom.name}
 application.version=${pom.version}
+message=${my.filter.value}
 
-environment=${environment}
++----+
+ 
+ the next execution of the <<<m2 process-resources>>> command will put our new property value into application.properties.
+ As an alternative to defining the my.filter.value property in an external file, you could also have defined it in the <<<properties>>>
+ section of your pom.xml and you'd get the same effect (notice I don't need the references to src/main/filters/filter.properties either):
 
++----+
+
+<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">
+  <modelVersion>4.0.0</modelVersion>
+  <groupId>com.mycompany.app</groupId>
+  <artifactId>my-app</artifactId>
+  <packaging>jar</packaging>
+  <version>1.0-SNAPSHOT</version>
+  <name>Maven Quick Start Archetype</name>
+  <url>http://maven.apache.org</url>
+  <dependencies>
+    <dependency>
+      <groupId>junit</groupId>
+      <artifactId>junit</artifactId>
+      <version>3.8.1</version>
+      <scope>test</scope>
+    </dependency>
+  </dependencies>
+  <build>
+    <resources>
+      <resource>
+        <directory>src/main/resources</directory>
+        <filtering>true</filtering>
+      </resource>
+    </resources>
+  </build>
+  <properties>
+    <my.filter.value>hello</my.filter.value>
+  </properties>
+</project>
+
++----+
+
+ Filtering resources can also get values from system properties; either the system properties built into Java (like java.version or
+ user.home) or properties defined on the command line using the standard Java -D parameter.  To continue the example, let's change
+ our application.properties file to look like this:
+ 
++----+
+
+# application.properties
 java.version=${java.version}
+command.line.prop=${command.line.prop}
 
 +----+
 
+ Now, when you execute the following command (note the definition of the command.line.prop property on the command line), the
+ application.properties file will contain the values from the system properties.
+
++----+
+
+m2 process-resources "-Dcommand.line.prop=hello again"
+
++----+
+ 
+
 * {How do I use external dependencies?}
 
- You probably already noticed a <<<dependencies>>> element in the POM we've been using as an example
+ You've probably already noticed a <<<dependencies>>> element in the POM we've been using as an example.
- so you have in fact been using an external dependency but we'll here we'll go more in depth about how Maven's
+ You have, in fact, been using an external dependency all this time, but here we'll talk about how this
- dependency management system works. For a thorough introduction please refer to our
+ works in a bit more detail. For a more thorough introduction, please refer to our
- {{{introduction-to-archetypes.html}Introduction to Dependency Management}}.
+ {{{introduction-to-dependency-management.html}Introduction to Dependency Management}}.
+ 
+ The <<<dependencies>>> section of the pom.xml lists all of the external dependencies that particular needs
+ in order to build (whether it needs that dependency at compile time, test time, run time, or whatever).  Right
+ now, our project is depending on JUnit only (I took out all of the resource filtering stuff for clarity):
 
 +----+
 
@@ -685,7 +790,6 @@ java.version=${java.version}
   <version>1.0-SNAPSHOT</version>
   <name>Maven Quick Start Archetype</name>
   <url>http://maven.apache.org</url>
-  <description>Killer App</description>
   <dependencies>
     <dependency>
       <groupId>junit</groupId>
@@ -693,32 +797,123 @@ java.version=${java.version}
       <version>3.8.1</version>
       <scope>test</scope>
     </dependency>
-    <!--
-     |
-     | New external dependency
-     |
-     -->
-    <dependency>
-      <groupId>org.apache.codehaus.plexus</groupId>
-      <artifactId>plexus-utils</artifactId>
-      <version>1.0.4</version>
-    </dependency>
   </dependencies>
-  <build>
-    <filters>
-      <filter>src/main/filters/filters.properties</filter>
-    </filters>
-    <resources>
-      <resource>
-        <directory>src/main/resources</directory>
-        <filtering>true</filtering>
-      </resource>
-    </resources>
-  </build>
 </project>
 
 +----+
 
+ For each external dependency, you'll need to define at least 4 things: groupId, artifactId, version, and scope.  The groupId,
+ artifactId, and version are the same as those given in the pom.xml for the project that built that dependency.  The scope
+ element indicates how your project uses that dependency, and can be values like <<<compile>>>, <<<test>>>, and <<<runtime>>>.
+ For more information on everything you can specify for a dependency, see the {{{../../../maven-model/maven.html}Project Descriptor Reference}}.
+ ~~DJ: Does this link work? I can't find the document.
+ For more information about the dependency mechanism as a whole, see {{{../../dependency-mechanism.html}Dependency Mechanism}}.
+ 
+ With this information about a dependency, Maven will be able to reference the dependency when it builds the project.  Where does
+ Maven reference the dependency from?  Maven looks in your local repository (<<<~/.m2/repository>>> is the default location) to find
+ all dependencies.  In a {{{How do I create a JAR and install it in my local repository?}previous section}}, we installed the artifact
+ from our project (my-app-1.0-SNAPSHOT.jar) into the local repository.  Once it's installed there, another project can reference that jar
+ as a dependency simply by adding the dependency information to its pom.xml:
+ 
++----+
+
+<project>
+  <groupId>com.mycompany.app</groupId>
+  <artifactId>my-other-app</artifactId>
+  ...
+  <dependencies>
+    ...
+    <dependency>
+      <groupId>com.mycompany.app</groupId>
+      <artifactId>my-app</artifactId>
+      <version>1.0-SNAPSHOT</version>
+      <scope>compile</scope>
+    </dependency>
+  </dependencies>
+</project>
+
++----+
+ 
+ What about dependencies built somewhere else?  How do they get into my local repository?  Whenever a project references a dependency
+ that isn't available in the local repository, Maven will download the dependency from a remote repository into the local repository.  You
+ probably noticed Maven downloading a lot of things when you built your very first project (these downloads were dependencies for the
+ various plugins used to build the project).  By default, the remote repository Maven uses can be found (and browsed) at
+ {{http://www.ibiblio.org/Maven2}}.  You can also set up your own remote repository (maybe a central repository for your company) to
+ use instead of or in addition to ibiblio.  For more information on repositories you can refer to the
+ {{{introduction-to-repositories.html}Introduction to Repositories}}.
+
+ Let's add another dependency to our project.  Let's say we've added some logging to the code and need to add log4j as a dependency.
+ First, we need to know what the groupId, artifactId, and version are for log4j.  We can browse ibiblio and look for it, or use Google
+ to help by searching for "site:www.ibiblio.org maven2 log4j".  The search shows a directory called /maven2/log4j/log4j (or
+ /pub/packages/maven2/log4j/log4j).  In that directory is a file called maven-metadata.xml.  Here's what the maven-metadata.xml for
+ log4j looks like:
+
++----+
+
+<metadata>
+  <groupId>log4j</groupId>
+  <artifactId>log4j</artifactId>
+  <version>1.1.3</version>
+  <versioning>
+    <versions>
+      <version>1.1.3</version>
+      <version>1.2.4</version>
+      <version>1.2.5</version>
+      <version>1.2.6</version>
+      <version>1.2.7</version>
+      <version>1.2.8</version>
+      <version>1.2.11</version>
+      <version>1.2.9</version>
+      <version>1.2.12</version>
+    </versions>
+  </versioning>
+</metadata>
+
++----+
+
+ From this file, we can see that the groupId we want is "log4j" and the artifactId is "log4j".  We see lots of different version values
+ to choose from; for now, we'll just use the latest version, 1.2.12 (some maven-metadata.xml files may also specify which version is
+ the current release version).  Alongside the maven-metadata.xml file, we can see a directory corresponding to each version of the
+ log4j library.  Inside each of these, we'll find the actual jar file (e.g. log4j-1.2.12.jar) as well as a pom file (this is the pom.xml
+ for the dependency, indicating any further dependencies it might have and other information) and another maven-metadata.xml file.
+ There's also an md5 file corresponding to each of these, which contains an MD5 hash for these files.  You can use this to authenticate 
+ the library or to figure out which version of a particular library you may be using already.
+ 
+ Now that we know the information we need, we can add the dependency to our pom.xml:
+ 
++----+
+
+<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">
+  <modelVersion>4.0.0</modelVersion>
+  <groupId>com.mycompany.app</groupId>
+  <artifactId>my-app</artifactId>
+  <packaging>jar</packaging>
+  <version>1.0-SNAPSHOT</version>
+  <name>Maven Quick Start Archetype</name>
+  <url>http://maven.apache.org</url>
+  <dependencies>
+    <dependency>
+      <groupId>junit</groupId>
+      <artifactId>junit</artifactId>
+      <version>3.8.1</version>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>log4j</groupId>
+      <artifactId>log4j</artifactId>
+      <version>1.2.12</version>
+      <scope>compile</scope>
+    </dependency>
+  </dependencies>
+</project>
+
++----+
+ 
+ Now, when we compile the project (<<<m2 compile>>>), we'll see Maven download the log4j dependency for us.
+ 
+~~DJ: Current
+
 * {How do I deploy my jar in my remote repository?}
 
 +----+
@@ -732,7 +927,6 @@ java.version=${java.version}
   <version>1.0-SNAPSHOT</version>
   <name>Maven Quick Start Archetype</name>
   <url>http://maven.apache.org</url>
-  <description>Killer App</description>
   <dependencies>
     <dependency>
       <groupId>junit</groupId>
@@ -1047,8 +1241,9 @@ m2 site:site site:deploy
 
 * {How do I use plug-ins?}
 
-* {How do I control what version of plug-in I use?}
+* {How do I control what version of a plug-in I use?}
 
 ~~http://docs.codehaus.org/display/MAVEN/Maven+Plugin+Matrix
 
+* {How do I build more than one project at once?}
 

maven-site/src/site/apt/guides/index.apt

@@ -52,8 +52,6 @@ Documentation
 
  * {{{mini/guide-multi-module.html}Guide to creating a multi-module build}}
 
- * {{{mini/guide-multi-module.html~}Guide to creating a multi-module build}}
-
  * {{{mini/guide-multiple-repositories.html}Guide to using Multiple Repositories}}
 
  * {{{mini/guide-pom-properties.html}Guide to using POM properties}}

maven-site/src/site/apt/guides/introduction/introduction-to-repositories.apt

@@ -8,6 +8,166 @@
 
 Introduction to Repositories
 
-~~  o Explain the standard layout of the m2 repository
+* Artifact Repositories
 
- * http://docs.codehaus.org/pages/viewpage.action?pageId=22230
+ A repository in Maven is used to hold build artifacts and dependencies of varying types.
+
+ There are strictly only two types of repositories: local and remote. The local repository refers to a copy
+ on your own installation that is a cache of the remote downloads, and also contains the temporary
+ build artifacts that you have not yet released.
+
+ Remote repositories refer to any other type of repository, accessed by a variety of protocols such as
+ <<<file://>>> and <<<http://>>>. These repositories might be a truely remote repository
+ set up by a third party to provide their artifacts for downloading (for example,
+ <a href="http://www.ibiblio.org/maven/">Ibiblio</a> houses Maven's central repository).
+ Other "remote" repositories may be <a href="../reference/internal-repositories.html">internal repositories</a>
+ set up on a file or HTTP server within your company, used to share private artifacts between development teams
+ and for releases.
+
+ The local and remote repositories are structured the same way so that scripts can easily be run on either
+ side, or they can be synced for offline used. In general use, the layout of the repositories is completely
+ transparent to the Maven user, however.
+
+* Why not Store JARs in CVS?
+
+ It is not recommended that you store your JARs in CVS. Maven tries to
+ promote the notion of a user local repository where JARs, or any
+ project artifacts, can be stored and used for any number of builds.
+ Many projects have dependencies such as XML parsers and standard utilities that
+ are often replicated in typical builds. With Maven these standard utilities
+ can be stored in your local repository and shared by any number of builds.
+
+ This has the following advantages:
+
+ * <<It uses less storage>> - while a repository is typically quite large, because each JAR is only kept
+   in the one place it is actually saving space, even though it may not seem that way</li>
+
+ * <<It makes checking out a project quicker>> - initial checkout, and to a small degree updating, a
+   project will be faster if there are no large binary files in CVS. While they may need to be downloaded
+   again afterwards anyway, this only happens once and may not be necessary for some common JARs already in
+   place.
+
+ * <<No need for versioning>> - CVS and other source control systems are designed for versioning files,
+   but external dependencies typically don't change, or if they do their filename changes anyway to indicate the
+   new version. Storing these in CVS doesn't have any added benefit over keeping them in a local artifact cache.
+
+
+* Using Repositories
+
+  In general, you should not need to do anything with the local repository on a regular basis, except clean
+  it out if you are short on disk space (or erase it completely if you are willing to download everything again).
+
+  For the remote repositories, they are used for both downloading and uploading (if you have the permission to
+  do so).
+
+** Downloading from a Remote Repository">
+
+ Downloading in Maven is triggered by a project declaring a dependency that is not present in the local
+ repository (or for a <<<SNAPSHOT>>>, when the remote repository contains one that is newer).
+ By default, Maven will download from Ibiblio.
+
+ To override this, you need to specify a <<<repositories>>> element as follows:
+
++----+
+
+<project>
+  ...
+  <repositories>
+    <repository>
+      <id></id>
+      <url></url>
+    </repository>
+  </repositories>
+  ...
+</project>
+
++----+
+
+ You can set this in your <code>~/build.properties</code> file to globally use a certain mirror, however
+ note that it is common for a project to customise the repository in their <code>project.properties</code>
+ and that your setting will take precedence. If you find that dependencies are not being found, check you
+ have not overridden the remote repository.
+
+ (Future versions should allow you to use a setting of
+ <<<${maven.repo.remote},http://planetmirror.com/maven>>>, but currently this causes an infinite recursion).
+
+ For more information on dependencies, see <a href="managing-dependencies.html">Handling Dependencies</a>.
+
+* Building Offline
+
+ If you find you need to build your projects offline you can either use the offline switch on the CLI:
+
++---+
+
+ m2 -o package
+
++---+
+
+ Note that many plugins will honour the offline setting and not perform any operations that would connect to
+ the internet. Some examples are resolving Javadoc links and link checking the site.
+
+* Uploading to a Remote Repository">
+
+ While this is possible for any type of remote repository, you must have the permission to do so.
+ To have someone upload to the central Maven repository, see {{../guide/guide-ibiblio-upload.html}Uploading to Ibiblio}}.
+
+Internal Repositories
+
+ When using Maven, particularly in a corporate environment, connecting to the internet to download dependencies
+ is not acceptable for security, speed or bandwidth reasons. For that reason, it is desirable to set up an
+ internal repository to house a copy of artifacts, and to publish private artifacts to.
+
+ Such an internal repository can be downloaded from using HTTP or the file system (using a <code>file://</code>
+ URL), and uploaded to using SCP, FTP, or a file copy.
+
+ Note that as far as Maven is concerned, there is nothing special about this repository: it is another
+ <<remote repository>> that contains artifacts to download to a user's local cache, and is a publish
+ destination for artifact releases.
+
+ Additionally, you may want to share the repository server with your generated project sites. For more
+ information on creating and deploying sites, see <a href="../using/site.html">Creating a Site</a>.
+
+* Setting up the Internal Repository
+
+ To set up an internal repository just requires that you have a place to put it, and then start copying
+ required artifacts there using the same layout as in a remote repository such as {{{http://www.ibiblio.org/maven/}Ibiblio}}.
+
+ It is <not> recommended that you scrape or <<<rsync://>>> a full copy of Ibiblio as there is a large amount
+ of data there. You can use a program such as <a href="http://maven-proxy.codehaus.org/">Maven Proxy</a>,
+ running on your internal repository's server, to download from the internet as required and then hold
+ the artifacts in your internal repository for faster downloading later.
+
+ The other options available are to manually download and vet releases, then copy them to the internal
+ repository, or to have Maven download them for a user, and manually upload the vetted artifacts to the
+ internal repository which is used for releases. This step is the only one available for artifacts where
+ the license forbids their distribution automatically, such as several J2EE JARs provided by Sun.
+ Refer to the {{{../mini/guide-coping-with-sun-jars.html}Guide to coping with SUN JARs}} document for more information.
+
+ It should be noted that Maven intends to include enhanced support for such features in the future,
+ including click through licenses on downloading, and verification of signatures.
+
+* Using the Internal Repository
+
+ Using the internal repository is quite simple. Simply make a change to add a <<<repositories>>> element:
+
++----+
+
+<project>
+   ...
+   <repositories>
+     <repository>
+      <id></id>
+     <repository>
+   </repositories>
+   ...
+</project>
+
++----+
+
+* Deploying to the Internal Repository
+
+ One of the most important reasons to have one or more internal repositories is to be able to publish
+ your own private releases to share.
+
+ To publish to the repository, you will need to have access via one of SCP, SFTP, FTP, or the filesystem.
+ For example, to set up an SCP transfer. ~~ show the scp example.

maven-site/src/site/apt/guides/mktoc.sh

@@ -1,6 +1,9 @@
+#!/bin/sh
 
 toc=`pwd`/index.apt
 
+find . -name '*~' -exec rm -rf {} \;
+
 #
 # Top matter
 #
@@ -103,4 +106,4 @@ echo " * {{{development/guide-m2-development.html}Guide to Developing Maven 2.x}
 echo " " >> $toc
 echo " * {{{development/guide-building-m2.html}Guide to Building Maven 2.x}}" >> $toc
 
-cat tail.apt >> $toc
+cat tail.txt >> $toc

maven-site/src/site/apt/maven-features.apt

@@ -0,0 +1,44 @@
+ ------
+ Maven Features
+ ------
+ Jason van Zyl
+ ------
+ 12 October 2005
+ ------
+
+Feature Summary
+
+ The following are the key features of Maven in a nutshell:
+
+ * Model based builds:
+   Maven is able to build any number of projects into predefined output types
+   such as a JAR, WAR, or distribution based on metadata about the project, without
+   any need to do any scripting in most cases.
+
+ * Coherent site of project information:
+   Using the same metadata as for the build process, Maven is able to generate a
+   web site or PDF including any documentation you care to add, and adds to that
+   standard reports about the state of development of the project.
+   Examples of this information can be seen at the bottom of the left-hand navigation of
+   this site under the "Project Information" and "Project Reports" submenus.
+
+ * Release management and distribution publication:
+   Without much additional configuration, Maven will integrate with your source control
+   system such as CVS and manage the release of a project based on a certain tag.
+   It can also publish this to a distribution location for use by other projects.
+   Maven is able to publish individual outputs such as a JAR, an archive including other
+   dependencies and documentation, or as a source distribution.
+
+ * Dependency management:
+   Maven encourages the use of a central repository of JARs and other dependencies. Maven
+   comes with a mechanism that your project's clients can use to
+   download any JARs required for building your project from a
+   central JAR repository much like Perl's CPAN. This allows users
+   of Maven to reuse JARs across projects and encourages communication
+   between projects to ensure backward compatibility issues are
+   dealt with. We are collaborating with the folks at {{{http://www.ibiblio.org}Ibiblio}} who have graciously
+   allowed the central repository to live on their servers.
+
+ []
+
+~~ this needs to be greatly expanded and is too detailed here ... jvz

maven-site/src/site/apt/what-is-maven.apt

@@ -0,0 +1,135 @@
+ ------
+ What is Maven?
+ ------
+ Jason van Zyl
+ ------
+ 12 October 2005
+ ------
+
+Introduction
+
+ Maven was originally started as an attempt to simplify the build
+ processes in the Jakarta Turbine project. There were several
+ projects each with their own Ant build files that were all slightly
+ different and JARs were checked into CVS. We wanted a standard way to
+ build the projects, a clear definition of what the project consisted
+ of, an easy way to publish project information and a way to share JARs
+ across several projects.
+
+ What resulted is a tool that can now be used for building and managing
+ any Java-based project. We hope that we have created something that
+ will make the day-to-day work of Java developers easier and generally
+ help with the comprehension of any Java-based project.
+
+Maven's Objectives
+
+ Maven's primary goal is to allow a developer to comprehend the
+ complete state of a development effort in the shortest period of
+ time. In order to attain this goal there are several areas of concern
+ that Maven attempts to deal with:
+
+ * Making the build process easy
+
+ * Providing a uniform build system
+
+ * Providing quality project information
+
+ * Providing guidelines for best practices development
+
+ * Allowing transparent migration to new features
+
+* Making the build process easy
+
+ While using Maven doesn't eliminate the need to know about the
+ underlying mechanisms, Maven does provide a lot of shielding
+ from the details.
+
+* Providing a uniform build system
+
+ Maven allows a project to build using its project object model (POM) and
+ a set of plugins that are shared by all projects using
+ Maven, providing a uniform build system. Once you familiarize yourself
+ with how one Maven project builds you automatically know how all Maven
+ projects build saving you immense amounts of time when trying to
+ navigate many projects.
+
+* Providing quality project information
+
+ Maven provides plenty of useful project information that is in
+ part taken from your POM and in part generated from your project's
+ sources. For example, Maven can provide:
+
+ * Change log document created directly from source control
+
+ * Cross referenced sources
+
+ * Mailing lists
+
+ * Dependency list
+
+ * Unit test reports including coverage
+
+ []
+
+ As Maven improves the information set provided will improve, all of
+ which will be transparent to users of Maven.
+
+ Other products can also provide Maven plugins to allow their set of
+ project information alongside some of the standard information given by
+ Maven, all still based from the POM.
+
+* Providing guidelines for best practices development
+
+ Maven aims to gather current principles for best practices development, and
+ make it easy to guide a project in that direction.
+
+ For example, specification, execution, and reporting of unit tests are part of
+ the normal build cycle using Maven.
+ Current unit testing best practices were used as guidelines:
+
+ * Keeping your test source code in a separate, but parallel source tree
+
+ * Using test case naming conventions to locate and execute tests
+
+ * Have test cases setup their environment and don't rely on customizing the build  for test preparation.
+
+ []
+
+ Maven also aims to assist in project workflow such as release management and
+ issue tracking.
+
+ Maven also suggests some guidelines on how to layout your project's directory structure
+ so that once you learn the layout you can easily navigate any other project that uses
+ Maven and the same defaults.
+
+* Allowing transparent migration to new features
+
+ Maven provides an easy way for Maven clients to update their installations
+ so that they can take advantage of any changes that been made to
+ Maven itself.
+
+ Installation of new or updated plugins from third parties or Maven itself has
+ been made trivial for this reason.
+
+What is Maven Not?
+
+ You may have heard some of the following things about Maven:
+
+ * Maven is a site and documentation tool
+
+ * Maven extends Ant to let you download dependencies
+
+ * Maven is a set of reusable Ant scriptlets
+
+ []
+
+ While Maven does these things, as you can read above in the "What is Maven?" section,
+ these are not the only features Maven has, and it's objectives are quite different.
+
+ Maven does encourage best practices, but we realise that some projects may not fit with
+ these ideals for historical reasons.  While Maven is designed to be flexible, to an extent, in these
+ situations and to the needs of different projects, it can not cater to every situation without making
+ compromises to the integrity of its objectives.
+
+ If you decide to use Maven, and have an unusual build structure that you cannot reorganise, you may
+ have to forgo some features or the use of Maven altogether.