From 605aa115fda67f2867b3eba5345532c7b6302fed Mon Sep 17 00:00:00 2001
From: Vincent Massol <vmassol@apache.org>
Date: Fri, 6 Oct 2006 14:46:59 +0000
Subject: [PATCH] [maven-scm] copy for tag maven-clover-plugin-2.3

git-svn-id: https://svn.apache.org/repos/asf/maven/plugins/tags/maven-clover-plugin-2.3@453619 13f79535-47bb-0310-9956-ffa450edef68
---
 pom.xml                                       |  12 +-
 src/it/contexts/goals.txt                     |   2 +-
 src/it/contexts/pom.xml                       |  23 +-
 .../clover/samples/contexts/Simple.java       |  14 +-
 .../src/test/verifier/verifications.xml       |   9 +
 src/it/multiproject/goals.txt                 |   1 +
 src/it/simple/goals.txt                       |   1 +
 src/site/apt/examples/contexts.apt            |  35 +
 src/site/apt/examples/multiproject.apt        |  41 ++
 src/site/apt/examples/simple.apt              |  35 +
 src/site/apt/index.apt                        |  55 +-
 src/site/apt/usage.apt                        | 613 ++++++++++++------
 src/site/fml/faq.fml                          |  38 ++
 src/site/site.xml                             |   6 +
 14 files changed, 660 insertions(+), 225 deletions(-)
 create mode 100644 src/it/contexts/src/test/verifier/verifications.xml
 create mode 100644 src/it/multiproject/goals.txt
 create mode 100644 src/it/simple/goals.txt
 create mode 100644 src/site/apt/examples/contexts.apt
 create mode 100644 src/site/apt/examples/multiproject.apt
 create mode 100644 src/site/apt/examples/simple.apt
 create mode 100644 src/site/fml/faq.fml

diff --git a/pom.xml b/pom.xml
index d377d36cc7..c8f42379a3 100644
--- a/pom.xml
+++ b/pom.xml
@@ -2,7 +2,7 @@
   <parent>
     <artifactId>maven-plugins</artifactId>
     <groupId>org.apache.maven.plugins</groupId>
-    <version>2-SNAPSHOT</version>
+    <version>3</version>
   </parent>
   <prerequisites>
     <maven>2.0.1</maven>
@@ -11,7 +11,7 @@
   <artifactId>maven-clover-plugin</artifactId>
   <packaging>maven-plugin</packaging>
   <name>Maven Clover Plugin</name>
-  <version>2.3-SNAPSHOT</version>
+  <version>2.3</version>
   <description>Maven plugin for Clover</description>
   <issueManagement>
     <system>jira</system>
@@ -173,6 +173,8 @@
               <projectsDirectory>src/it</projectsDirectory>
               <pomIncludes>
                 <pomInclude>**/contexts/pom.xml</pomInclude>
+                <pomInclude>**/simple/pom.xml</pomInclude>
+                <pomInclude>**/multiproject/pom.xml</pomInclude>
               </pomIncludes>
               <postBuildHookScript>verify.bsh</postBuildHookScript>
             </configuration>
@@ -190,4 +192,10 @@
       </build>
     </profile>
   </profiles>
+
+  <scm>
+    <connection>scm:svn:https://svn.apache.org/repos/asf/maven/plugins/tags/maven-clover-plugin-2.3</connection>
+    <developerConnection>scm:svn:https://svn.apache.org/repos/asf/maven/plugins/tags/maven-clover-plugin-2.3</developerConnection>
+    <url>https://svn.apache.org/repos/asf/maven/plugins/tags/maven-clover-plugin-2.3</url>
+  </scm>
 </project>
diff --git a/src/it/contexts/goals.txt b/src/it/contexts/goals.txt
index 9cb8855c79..8e5f26baf0 100644
--- a/src/it/contexts/goals.txt
+++ b/src/it/contexts/goals.txt
@@ -1 +1 @@
-clean install
+clean install site verifier:verify
diff --git a/src/it/contexts/pom.xml b/src/it/contexts/pom.xml
index 8b3c9a276f..6ae84b5cd1 100644
--- a/src/it/contexts/pom.xml
+++ b/src/it/contexts/pom.xml
@@ -14,18 +14,28 @@
       <scope>test</scope>
     </dependency>
   </dependencies>
-  <build>
+  <reporting>
+    <excludeDefaults>true</excludeDefaults>
     <plugins>
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-clover-plugin</artifactId>
         <configuration>
-
           <!-- Verify that context filters work -->
-          <contextFilters>static</contextFilters>
-
-          <targetPercentage>80%</targetPercentage>
-
+          <contextFilters>try</contextFilters>
+        </configuration>
+      </plugin>
+    </plugins>
+  </reporting>
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-clover-plugin</artifactId>
+        <configuration>
+          <!-- Without the block filter the TPC is 50% and with it it's 57,1%. Thus we check for a TPC above of
+               55% to verify the filter has been applied correctly -->
+          <targetPercentage>55%</targetPercentage>
         </configuration>
         <executions>
           <execution>
@@ -34,7 +44,6 @@
             <goals>
               <goal>instrument</goal>
               <goal>check</goal>
-              <goal>log</goal>
             </goals>
           </execution>
         </executions>
diff --git a/src/it/contexts/src/main/java/org/apache/maven/plugin/clover/samples/contexts/Simple.java b/src/it/contexts/src/main/java/org/apache/maven/plugin/clover/samples/contexts/Simple.java
index e7db72e822..19a15bec32 100644
--- a/src/it/contexts/src/main/java/org/apache/maven/plugin/clover/samples/contexts/Simple.java
+++ b/src/it/contexts/src/main/java/org/apache/maven/plugin/clover/samples/contexts/Simple.java
@@ -17,18 +17,20 @@ package org.apache.maven.plugin.clover.samples.contexts;
 
 public class Simple
 {
-    static
-    {
-        System.getProperties();
-    }
-    
     public void someMethod1()
     {        
     }
 
     public void someMethodToReduceStatementCoverage()
     {
-        System.getProperties();        
+        try
+        {
+            System.getProperties();
+        }
+        finally
+        {
+            // We use a try/finally so that we can use a block context of 
+        }
     }
     
     public void someMethod2(int i)
diff --git a/src/it/contexts/src/test/verifier/verifications.xml b/src/it/contexts/src/test/verifier/verifications.xml
new file mode 100644
index 0000000000..5e642cd503
--- /dev/null
+++ b/src/it/contexts/src/test/verifier/verifications.xml
@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<verifications>
+  <files>
+    <file>
+      <location>target/site/clover/pkgs-summary.html</location>
+      <contains>57.1%</contains>
+    </file>
+  </files>
+</verifications>
diff --git a/src/it/multiproject/goals.txt b/src/it/multiproject/goals.txt
new file mode 100644
index 0000000000..d32445c40a
--- /dev/null
+++ b/src/it/multiproject/goals.txt
@@ -0,0 +1 @@
+clean install site
diff --git a/src/it/simple/goals.txt b/src/it/simple/goals.txt
new file mode 100644
index 0000000000..d32445c40a
--- /dev/null
+++ b/src/it/simple/goals.txt
@@ -0,0 +1 @@
+clean install site
diff --git a/src/site/apt/examples/contexts.apt b/src/site/apt/examples/contexts.apt
new file mode 100644
index 0000000000..a6bbc7fb60
--- /dev/null
+++ b/src/site/apt/examples/contexts.apt
@@ -0,0 +1,35 @@
+ ------
+ Contexts Example
+ ------
+ Vincent Massol
+ <vmassol@apache.org>
+ ------
+ October 6th, 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
+
+{Contexts Example}
+
+  This example demonstrates how to configure {{{http://cenqua.com/clover/doc/adv/contexts.html}Clover filter contexts}}
+  using the Clover plugin.
+
+* {Sources}
+
+  Sources are available {{{http://svn.apache.org/viewvc/maven/plugins/trunk/maven-clover-plugin/src/it/contexts/}here}}.
+
+  To execute the project run either <<<mvn install>>> to verify the TPC or <<<mvn site>>> to generate the Clover report.
diff --git a/src/site/apt/examples/multiproject.apt b/src/site/apt/examples/multiproject.apt
new file mode 100644
index 0000000000..b244cca292
--- /dev/null
+++ b/src/site/apt/examples/multiproject.apt
@@ -0,0 +1,41 @@
+ ------
+ Multiproject Example
+ ------
+ Vincent Massol
+ <vmassol@apache.org>
+ ------
+ October 6th, 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
+
+{Multiproject Example}
+
+  This example demonstrates how to use the Clover plugin in a multiproject scenario (i.e. a master Maven project with
+  several children modules. It also demonstrates how to perform Clover report aggregation and how functional tests
+  can be accounted for in the Clove report.
+
+* {Sources}
+
+  Sources are available {{{http://svn.apache.org/viewvc/maven/plugins/trunk/maven-clover-plugin/src/it/multiproject/}here}}.
+
+  To execute the project run <<<mvn install>>> to generate the Clover report.
+
+  Note: Because of a {{{http://jira.codehaus.org/browse/MCLOVER-34}bug in Maven2}} you'll need to run
+  <<<mvn install>>> twice at the top level if you want to generate an aggregated report. This is because it currently
+  works only if the Clover databases int he children exist prior to the top level project running the Clover report
+  generation.
diff --git a/src/site/apt/examples/simple.apt b/src/site/apt/examples/simple.apt
new file mode 100644
index 0000000000..1d339c81eb
--- /dev/null
+++ b/src/site/apt/examples/simple.apt
@@ -0,0 +1,35 @@
+ ------
+ Simple Example
+ ------
+ Vincent Massol
+ <vmassol@apache.org>
+ ------
+ October 6th, 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
+
+{Simple Example}
+
+  This example demonstrates how to use the Clover plugin both for report generation and for Test Percentage
+  Clover (TPC) verification, on a single Maven project.
+
+* {Sources}
+
+  Sources are available {{{http://svn.apache.org/viewvc/maven/plugins/trunk/maven-clover-plugin/src/it/simple/}here}}.
+
+  To execute the project run either <<<mvn install>>> to verify the TPC or <<<mvn site>>> to generate the Clover report.
diff --git a/src/site/apt/index.apt b/src/site/apt/index.apt
index 9de793fe54..ac171988ed 100644
--- a/src/site/apt/index.apt
+++ b/src/site/apt/index.apt
@@ -4,8 +4,8 @@
  Vincent Massol
  <vmassol@apache.org>
  ------
- April 8th, 2006
-
+ October 6th, 2006
+ 
  ~~ Copyright 2006 The Apache Software Foundation.
  ~~
  ~~ Licensed under the Apache License, Version 2.0 (the "License");
@@ -23,7 +23,7 @@
  ~~ NOTE: For help with the syntax of this file, see:
  ~~ http://maven.apache.org/guides/mini/guide-apt-format.html
 
-Introduction
+Maven Clover Plugin
 
   The Clover plugin is the place where build actions related to 
   {{{http://www.cenqua.com/clover/}Clover}} are found in Maven.
@@ -32,9 +32,7 @@ Introduction
   If your project is a commercial project you will need to get a license for the Clover jar 
   before using this plugin. Please note that a 30 days license is included in this plugin.
 
-  The full description of goals is available {{{index.html}here}}.
-
-Features
+* Features
 
   The Clover plugin currently supports the following features:
 
@@ -59,9 +57,48 @@ Features
   test compiled tests classes. It creates a parallel directory in <<<target/clover>>> in order not
   to tamper with your main files.
 
-  See the {{{howto.html}Howto}} section to learn how to use these features.
-
-Examples
+* Usage
+
+  Instructions on how to use Maven Clover Plugin can be found {{{usage.html}here}}.
+
+* Goals Overview
+
+  The <<<maven-clover-plugin>>> has seven goals, but only six are called directly by the user. The full description
+  of goals, generated automatically from the source code, is available {{{plugin-info.html}here}}.
+
+  * {{{aggregate-mojo.html}clover:aggregate}} - Aggregate children module Clover databases if there are any. This mojo
+    should  not exist. It's only there because the site plugin doesn't handle @aggregators properly at the moment...
+  
+  * {{{check-mojo.html}clover:check}} - Verify Test Percentage Coverage (TPC) from an existing Clover database and fail
+    the build if it is below the defined threshold. The check is done on main Clover databases and also on merged Clover 
+    databases when they exist.
+    
+  * {{{instrumentInternal-mojo.html}clover:instrumentInternal}} - Instrument source roots.
+
+    <<Note: Do not call this MOJO directly. It is meant to be called in a custom forked lifecycle by the other Clover 
+    plugin MOJOs.>>
+    
+  * {{{instrument-mojo.html}clover:instrument}} - Instrument all sources using Clover and forks a custom lifecycle to
+    execute project's tests on the instrumented code so that a Clover database is created.
+
+    Note: We're forking a lifecycle because we don't want the Clover instrumentation to affect the main lifecycle build.
+    This will prevent instrumented sources to be put in production by error. Thus running mvn install on a project where
+    this instrument goal has been specified will run the build twice: once for building the project as usual and another
+    time for instrumenting the sources with Clover and generating the Clover database.
+  
+  * {{{log-mojo.html}clover:log}} - Provides information on the current Clover database.
+  
+  * {{{clover-mojo.html}clover:clover}} - Generate a Clover report from existing Clover databases. The generated report is
+    an external report generated by Clover itself. If the project generating the report is a top level project and if 
+    the aggregate configuration element is set to true then an aggregated report will also be created.
+
+    Note: This report mojo should be an @aggregator and the clover:aggregate mojo shouldn't exist. This is a limitation 
+    of the site plugin which doesn't support @aggregator reports...
+  
+  * {{{save-history-mojo.html}clover:save-history}} - Save a
+    {{{http://cenqua.com/clover/doc/tutorial/part2.html}Clover history point}}.
+
+* Examples
 
   Check the {{{http://svn.apache.org/viewcvs.cgi/maven/plugins/trunk/maven-clover-plugin/src/it/}plugin test suite}}
   for example of how to use this plugin.
diff --git a/src/site/apt/usage.apt b/src/site/apt/usage.apt
index bf10316fda..5628010ee1 100644
--- a/src/site/apt/usage.apt
+++ b/src/site/apt/usage.apt
@@ -1,104 +1,220 @@
  ------
- Maven 2 Clover Plugin: using
+ Usage
  ------
  Vincent Massol
  <vmassol@apache.org>
+ Franz Allan Valencia see
+ <franz.see@gmail.com>
+ ------
+ October 11th, 2006
  ------
- September 9th, 2006
 
-User Guide
+ ~~ 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.
 
- * {{{usage.html#Generating a Clover report when generating the site}Generating a Clover report when generating the site}}
+ ~~ NOTE: For help with the syntax of this file, see:
+ ~~ http://maven.apache.org/guides/mini/guide-apt-format.html
+ 
+{Usage}
 
- * {{{usage.html#Generating a Clover report without modifying your POM}Generating a Clover report without modifying your POM}}
+* Table Of Contents
 
- * {{{usage.html#Generating HTML, XML and PDF reports}Generating HTML, XML and PDF reports}}
+ * {{{usage.html#Getting Started}Getting Started}}
 
- * {{{usage.html#Generating historical reports}Generating historical reports}}
+   * {{{usage.html#Controlling files to instrument}Controlling files to instrument}}
 
  * {{{usage.html#Checking test coverage}Checking test coverage}}
 
- * {{{usage.html#Using Clover with JDK 1.4 and JDK 1.5 keywords}Using Clover with JDK 1.4 and JDK 1.5 keywords}}
+   * {{{usage.html#Using block contexts}Using block contexts}}
+   
+   * {{{usage.html#Using Clover with different JDK versions}Using Clover with different JDK versions}}
 
- * {{{usage.html#Specifying a Clover flush policy}Specifying a Clover flush policy}}
+   * {{{usage.html#Specifying a Clover flush policy}Specifying a Clover flush policy}}
 
- * {{{usage.html#Specifying a custom license file}Specifying a custom license file}}
+ * {{{usage.html#Generating a Clover report}Generating a Clover report}}
+
+   * {{{usage.html#Specifying report formats}Specifying report formats}}
 
- * {{{usage.html#Aggregating Clover reports}Aggregating Clover reports}}
+   * {{{usage.html#Generating historical reports}Generating historical reports}}
 
- * {{{usage.html#Controlling files to instrument}Controlling files to instrument}}
+   * {{{usage.html#Aggregating Clover Reports}Aggregating Clover Reports}}
 
  * {{{usage.html#Getting information on an existing Clover database}Getting information on an existing Clover database}}
 
+ * {{{usage.html#Specifying a custom license file}Specifying a custom license file}}
+
  []
+ 
+* {Getting Started}
 
-* {Generating a Clover report when generating the site}
+  The first thing to do is to create a {{{http://cenqua.com/clover/doc/adv/database.html}Clover database}}. To do
+  this, you must either do: 
 
-  Add the Clover report in your <<<pom.xml>>> under the <<<reporting>>> section:
++------+
+  mvn clover:instrument
++------+
 
-+--------
-<project>
-  [...]
-  <reporting>
+ or 
+ 
++------+
+  <build>
     <plugins>
-      [...]
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-clover-plugin</artifactId>
         <configuration>
           [...]
         </configuration>
+        <executions>
+          <execution>
+            [...]
+            <goals>
+              <goal>instrument</goal>
+            </goals>
+            [...]
+          </execution>
+        </executions>
       </plugin>
     </plugins>
-  </reporting>
+  </build>
++------+ 
+  
+  This instruments all sources using Clover so that a
+  {{{http://cenqua.com/clover/doc/adv/database.html}Clover database}} is created (or if it already exists, the plugin
+  will simply use it and add data on top of the existing one). When you execute your tests
+  the instrumented code will start generating logs into the Clover database. These logs can then be used for
+  Test Coverage Percentage checks, for report generation or for logging.
+
+  Note that the Clover plugin takes great care not to mix the instrumented code nor any artifact generated from it
+  with main production sources and artifacts. This is the reason why you may see your tests executed twice: once
+  for the production sources and once for the Clover-instrumented sources.
+
+  <Back to {{{usage.html}top}}.>
+  
+** {Controlling files to instrument}
+  
+  By default all Java files are included during the instrumentation. To specify
+  inclusion and exclusion use the <<<includes>>> and <<<excludes>>> 
+  configuration elements as shown in this example:
+
++--------
+  <plugin>
+    <groupId>org.apache.maven.plugins</groupId>
+    <artifactId>maven-clover-plugin</artifactId>
+    <configuration>
+      <includes>
+        <include>**/api/**/*.java</include>
+        <include>some/path/MyFile.java</include>
+        [...]
+      </includes>
+      <excludes>
+        <exclude>**/*Test/java</exclude>
+        [...]
+      </excludes>
 [...]
 +---------
 
-  The <<<maven-clover-plugin>>> report will only generate a report out of an existing Clover database
-  so if you don't have a Clover database available you'll need to configure your build to generate one.
-  This is achieved by binding the <<<clover:instrument>>> goal to the <<<pre-site>>> phase so that it
-  executes before the report executes. For example:
+  <Back to {{{usage.html}top}}.>
+  
+* {Checking test coverage}
 
-+--------
-<project>
-  [...]
+  In order to check for a test coverage percentage and fail the build in case of
+  non-compliance, you'll need to configure the Clover plugin to tell it what 
+  test coverage threshold you wish to use:
+
++------+
+  mvn clover:check -DtargetPercentage=50%
++------+
+
+ or 
+ 
++------+
   <build>
     <plugins>
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-clover-plugin</artifactId>
         <configuration>
-          [...]
+          <targetPercentage>50%</targetPercentage>
         </configuration>
         <executions>
           <execution>
-            <phase>pre-site</phase>
+            <phase>verify</phase>
             <goals>
-              <goal>instrument</goal>
+              <goal>check</goal>
             </goals>
           </execution>
         </executions>
       </plugin>
     </plugins>
   </build>
-[...]
-+---------
++------+
 
-  Then, to generate the report as part of the site simply type <<<mvn site:site>>>.
+  In this example you've told Maven to run <<<clover:check>>> whenever the 
+  <<<verify>>> phase is reached (this will be the case if you run 
+  <<<mvn install>>> for example). 
   
-* {Generating a Clover report without modifying your POM}
+  Furthermore, you specified that the <<<targetPercentage>>> is <<<50%>>>, 
+  meaning the test must result to at least <<<50%>>> test coverage percentage to
+  pass. If the <<<targetPercentage>>> was not specified, the default value of 
+  <<<70%>>> will be used.
+  
+  However, as previously mentioned, Clover needs an existing 
+  {{{http://cenqua.com/clover/doc/adv/database.html}Clover database}}. Thus, a call
+  to <<<clover:instrument>>> may be neccessary:
+  
++------+
+  mvn clover:instrument clover:check -DtargetPercentage=50%
++------+
 
-  If you simply want to generate a Clover report on the fly without modifying your POM, simply
-  type <<<mvn clover:instrument clover:clover>>>. Alternatively if you want to aggregate children
-  module reports into a master Clover report, run <<<mvn clover:instrument clover:aggregate clover:clover>>>
-  instead.
+ or 
+ 
++------+
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-clover-plugin</artifactId>
+        <configuration>
+          <targetPercentage>50%</targetPercentage>
+        </configuration>
+        <executions>
+          <execution>
+            <phase>verify</phase>
+            <goals>
+              <goal>instrument</goal>
+              <goal>check</goal>
+            </goals>
+          </execution>
+        </executions>
+      </plugin>
+    </plugins>
+  </build>
++------+
 
-* {Generating HTML, XML and PDF reports}
+  Note: The <<<clover:check>>> goal will also check the test percentage coverage
+  for merged Clover databases if any is found (see the
+  {{{usage.html#Aggregating Clover Reports}Aggregating Clover Reports}} section for more on that).
+ 
+  <Back to {{{usage.html}top}}.>
+  
+** {Using block contexts}
 
-  By default the Clover plugin will generate a HTML report. If you want to generate a PDF or XML report, or
-  if you simply do not want to generate the HTML report use the <<<generateHtml>>>, <<<generatePdf>>> and
-  <<<generateXml>>> configuration elements. By default the <<<generateHtml>>> element is set to true.
-  For example if you wish to generate the PDF and XML reports you would use:
+  Clover allows specifying {{{http://cenqua.com/clover/doc/adv/contexts.html}block contexts}}
+  (i.e. elements to be excluded from the Test Percentage Coverage). To configure a block context use
+  the <<<contextFilters>>> element. For example to exclude <<<try>>> and <<<static>>> block contexts, you would
+  write:
 
 +--------
 [...]
@@ -106,244 +222,300 @@ User Guide
     <groupId>org.apache.maven.plugins</groupId>
     <artifactId>maven-clover-plugin</artifactId>
     <configuration>
-      <generatePdf>true</generatePdf>
-      <generateXml>true</generateXml>
+      <contextFilters>try,static</contextFilters>
     </configuration>
-  </plugin>
 [...]
 +---------
 
-  Note that only the HTML report gets a link in the "Project Reports" section in generated menu on the site. If
-  you want to link the PDF or XML reports you'll need to do that by modifying your <<<site.xml>>>. For example:
-
-+--------
-[...]
-  <menu name="Other Reports">
-    <item name="Clover PDF" href="clover/clover.pdf"/>
-    <item name="Clover XML" href="clover/clover.xml"/>
-  </menu>
-[...]
-+---------
+  <Back to {{{usage.html}top}}.>
 
-  If you do not want to generate the HTML report then you should not configure the Clover plugin in the
-  <<<reporting>>> section as this section is for plugins which generate HTML reports. In that case, simply
-  bind the <<<clover:clover>>> goal to the <<<site>>> phase in the <<<build>>> section. For example:
+** {Using Clover with different JDK versions}
 
+  If your code is using JDK 1.4 or JDK 1.5 specific keywords, you'll need to 
+  configure the Clover plugin. For example for JDK 1.4:
+  
 +--------
-<project>
-  [...]
   <build>
     <plugins>
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-clover-plugin</artifactId>
         <configuration>
-          <generateHtml>false</generateHtml>
-          <generatePdf>true</generatePdf>
-          <generateXml>true</generateXml>
-        </configuration>
-        <executions>
-          <execution>
-            <phase>site</phase>
-            <goals>
-              <goal>instrument</goal>
-              <goal>clover</goal>
-            </goals>
-          </execution>
-        </executions>
-      </plugin>
-    </plugins>
-  </build>
+          <jdk>1.4</jdk>
 [...]
 +---------
 
-* {Generating historical reports}
-
-  This is done in the same manner as you generate a standard Clover report but in addition you need to set the
-  <<<generateHistorical>>> configuration property to true (it's false by default). For example:
+  <Back to {{{usage.html}top}}.>
+  
+** {Specifying a Clover flush policy}
 
+  If you want to specify the Clover 
+  {{{http://cenqua.com/clover/doc/adv/flushpolicies.html}flush policy}} that the
+  plugin should use, then specify it in the plugin's configuration. Valid 
+  policies are <<<threaded>>>, <<<directed>>> and <<<interval>>>.
+  
+  For example to use a <<<threaded>>> policy with a flush interval of <<<5000>>>
+  ms you would write:
+  
 +--------
-<project>
-  [...]
   <build>
     <plugins>
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-clover-plugin</artifactId>
         <configuration>
-          <generateHistorical>true</generateHistorical>
-          [...]
-        </configuration>
-[...]
-      </plugin>
-    </plugins>
-  </build>
+          <flushPolicy>threaded</flushPolicy>
+          <flushInterval>5000</flushInterval>
 [...]
 +---------
 
-  Now this will generate a historical report only if you have saved Clover historical savepoints. In order to save a
-  Clover savepoint, run the <<<clover:save-history>>> goal. It's up to you to decide when you want to call this goal.
-  For example you could call it every time a build is executing on your CI server, or you could call it at every
-  project release, etc. The location of the history directory for saving the savepoints is controlled by the
-  <<<historyDir>>> configuration property, which points to <<<${project.build.directory}/clover/history>>> by default.
-  It is recommended to use another location that will not get erased by a <<<mvn clean>>>. For example:
+  <Back to {{{usage.html}top}}.>
+  
+* {Generating a Clover report}
+  
+  To generate a Clover report, simply execute the following command:
+  
++------+
+mvn clover:clover
++------+
 
+  Also, you may want to generate a Clover Report everytime you generate site for
+  your maven project (i.e. <<<mvn site>>>):
+  
 +--------
 <project>
-  [...]
-  <build>
+  [...] 
+  <reporting>
     <plugins>
+      [...]
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-clover-plugin</artifactId>
         <configuration>
-          <generateHistorical>true</generateHistorical>
-          <historyDir>${myHistoryDir}</historyDir>
           [...]
         </configuration>
-[...]
       </plugin>
     </plugins>
-  </build>
+  </reporting>
 [...]
 +---------
+  
+  But just like the <<<clover:check>>> goal, the <<<clover:clover>>> goal
+  also needs an existing 
+  {{{http://cenqua.com/clover/doc/adv/database.html}Clover database}}. Thus, if
+  if it still does not exist, a call to <<<clover:instrument>>> must first be 
+  made:
+  
++------+
+mvn clover:instrument clover:clover
++------+
 
-  Where <<<myHistoryDir>>> could be a Maven property that you define in a profile.
-
-* {Checking test coverage}
-
-  In order to check for a test coverage percentage and fail the build in case of non-compliance,
-  you'll need to configure the Clover plugin to tell it what test coverage threshold you wish to use:
+  or 
   
 +--------
+<project>
+  [...]
   <build>
     <plugins>
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-clover-plugin</artifactId>
         <configuration>
-          <targetPercentage>50%</targetPercentage>
+          [...]
         </configuration>
         <executions>
           <execution>
-            <phase>verify</phase>
+            <phase>pre-site</phase>
             <goals>
               <goal>instrument</goal>
-              <goal>check</goal>
             </goals>
           </execution>
         </executions>
       </plugin>
     </plugins>
   </build>
+  [...]
+  <reporting>
+    <plugins>
+      [...]
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-clover-plugin</artifactId>
+        <configuration>
+          [...]
+        </configuration>
+      </plugin>
+    </plugins>
+  </reporting>
+[...]
 +---------
+ 
+  Note that in the above example that <<<clover:instrument>>> was bound to the
+  <<<pre-site>>> phase. This is done to ensure that a 
+  {{{http://cenqua.com/clover/doc/adv/database.html}Clover database}} is 
+  generated before the report executes. 
 
-  In this example you've told Maven to run <<<clover:instrument>>> and <<<clover:check>>> whenever the <<<verify>>>
-  phase is reached (this will be the case if you run <<<mvn install>>> for example). You need to call
-  <<<clover:instrument>>> before the check because <<<clover:check>>> requires an existing Clover datababase to
-  perform the verification.
+  <Back to {{{usage.html}top}}.>
+  
+** {Specifying report formats}
+
+  By default the Clover plugin will generate a HTML report. If you want to 
+  generate a PDF or XML report, or if you simply do not want to generate the 
+  HTML report use the <<<generateHtml>>>, <<<generatePdf>>> and 
+  <<<generateXml>>> configuration elements. By default the <<<generateHtml>>> 
+  element is set to true.
+  
+  For example if you wish to generate the PDF and XML reports you would use:
 
-  If you don't specify a target percentage the default value used is 70%.
++--------
+[...]
+  <plugin>
+    <groupId>org.apache.maven.plugins</groupId>
+    <artifactId>maven-clover-plugin</artifactId>
+    <configuration>
+      <generatePdf>true</generatePdf>
+      <generateXml>true</generateXml>
+    </configuration>
+  </plugin>
+[...]
++---------
 
-  You can also invoke <<<mvn clover:check>>> directly on the command line.
+  Note that only the HTML report gets a link in the "Project Reports" section in
+  generated menu on the site. If you want to link the PDF or XML reports you'll 
+  need to do that by modifying your <<<site.xml>>>. For example:
 
-  Note: The <<<clover:check>>> goal will also check the test percentage coverage for merged databases if any is found.
++--------
+[...]
+  <menu name="Other Reports">
+    <item name="Clover PDF" href="clover/clover.pdf"/>
+    <item name="Clover XML" href="clover/clover.xml"/>
+  </menu>
+[...]
++---------
 
-* {Using Clover with JDK 1.4 and JDK 1.5 keywords}
+  If you do not want to generate the HTML report then you should not configure 
+  the Clover plugin in the <<<reporting>>> section as this section is for 
+  plugins which generate HTML reports. In that case, simply bind the 
+  <<<clover:clover>>> goal to the <<<site>>> phase in the <<<build>>> section. 
+  For example:
 
-  If your code is using JDK 1.4 or JDK 1.5 specific keywords, you'll need to configure the Clover
-  plugin. For example for JDK 1.4:
-  
 +--------
+<project>
+  [...]
   <build>
     <plugins>
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-clover-plugin</artifactId>
         <configuration>
-          <jdk>1.4</jdk>
+          <generateHtml>false</generateHtml>
+          <generatePdf>true</generatePdf>
+          <generateXml>true</generateXml>
+        </configuration>
+        <executions>
+          <execution>
+            <phase>site</phase>
+            <goals>
+              <goal>instrument</goal>
+              <goal>clover</goal>
+            </goals>
+          </execution>
+        </executions>
+      </plugin>
+    </plugins>
+  </build>
 [...]
 +---------
 
-* {Specifying a Clover flush policy}
-
-  If you want to specify the Clover 
-  {{{http://cenqua.com/clover/doc/adv/flushpolicies.html}flush policy}} that the plugin should use,
-  then specify it in the plugin's configuration. Valid policies are <<<threaded>>>, <<<directed>>>
-  and <<<interval>>>.
-  
-  For example to use a <<<threaded>>> policy with a flush interval of <<<5000>>> ms you would write:
+  <Back to {{{usage.html}top}}.>
   
+** {Generating historical reports}
+
+  Generating historical reports is done in the same manner as you generate a 
+  standard Clover report but in addition you need to set the 
+  <<<generateHistorical>>> configuration property to true (it's false by 
+  default). For example:
+
 +--------
+<project>
+  [...]
   <build>
     <plugins>
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-clover-plugin</artifactId>
         <configuration>
-          <flushPolicy>threaded</flushPolicy>
-          <flushInterval>5000</flushInterval>
+          <generateHistorical>true</generateHistorical>
+          [...]
+        </configuration>
+        [...]
+      </plugin>
+    </plugins>
+  </build>
 [...]
 +---------
 
-* {Specifying a custom license file}
-
-  The Clover plugin provides a default evaulation license. However if your project is a commercial project
-  you need to purchase your own license to use Clover. To use your license specify it using a
-  <<<licenseLocation>>> configuration element. For example if you wanted to automatically execute the
-  <<<check>>> goal when you type <<<mvn install>>> and if you wanted to use your license located in
-  <<<${basedir}/src/test/clover/myclover.license>>> you would use:
+  Now this will generate a 
+  {{{http://cenqua.com/clover/doc/tutorial/part2.html}Clover historical report}}
+  only if you have saved Clover historical savepoints. In order to save a Clover
+  savepoint, run the <<<clover:save-history>>> goal. It's up to you to decide 
+  when you want to call this goal. 
+  
+  For example you could call it every time a build is executing on your CI 
+  server, or you could call it at every project release, etc. The location of 
+  the history directory for saving the savepoints is controlled by the 
+  <<<historyDir>>> configuration property, which points to 
+  <<<${project.build.directory}/clover/history>>> by default. 
+  
+  It is recommended to use another location that will not get erased by a 
+  <<<mvn clean>>>. For example:
 
 +--------
+<project>
+  [...]
   <build>
     <plugins>
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-clover-plugin</artifactId>
         <configuration>
-          <licenseLocation>${basedir}/src/test/clover/myclover.license</licenseLocation>
+          <generateHistorical>true</generateHistorical>
+          <historyDir>${myHistoryDir}</historyDir>
+          [...]
         </configuration>
-        <executions>
-          <execution>
-            <configuration>
-              <targetPercentage>50%</targetPercentage>
-            </configuration>
-            <phase>verify</phase>
-            <goals>
-              <goal>instrument</goal>
-              <goal>check</goal>
-            </goals>
-          </execution>
-        </executions>
+        [...]
       </plugin>
     </plugins>
   </build>
+[...]
 +---------
 
-  Important note: The <<<licenseLocation>>> element needs to be defined in the global <<<configuration>>> element
-  and not in the <<<configuration>>> element under the <<<execution>>> tag.
-
-  Instead of specifying a file, you can also specify either a <<URL>> or a <<relative path inside a JAR>> (to learn
-  how to use this last feature, refer to the
-  {{{http://maven.apache.org/plugins/maven-checkstyle-plugin/tips.html}Checkstlye plugin documentation}}.
+  Where <<<myHistoryDir>>> could be a Maven property that you define in a 
+  profile.
 
-* {Aggregating Clover reports}
+  <Back to {{{usage.html}top}}.>
+  
+** {Aggregating Clover Reports}
 
-  <<Note: There's currently a {{{http://jira.codehaus.org/browse/MCLOVER-34}bug in Maven2}} which results in the clover
-  aggregation not working properly. More specifically the aggregate goal requires an existing Clover database and
-  thus the first time your run "mvn site" the aggregated report won't be generated. It'll work the second time
-  though. Just ensure that you run the aggregate goal after you've generated the children Clover databases.>>
+  <Note: There's currently a 
+  {{{http://jira.codehaus.org/browse/MCLOVER-34}bug in Maven2}} which results in
+  the clover aggregation not working properly. More specifically the >
+  <<<aggregate>>> <goal requires an existing Clover database and the first
+  time your run> <<<mvn site>>> <it won't find the generated children databases as they'll be produced after it
+  executes. It'll work the second time though. Just ensure that you run the aggregate goal after
+  you've generated the children Clover databases.>
 
-  You can aggregate children modules Clover reports into a single master report by running the <<<clover:aggregate>>>
-  goal. For example if you have the following project layout:
+  You can aggregate children modules Clover databases into a single merged database
+  by running the <<<clover:aggregate>>> goal. This For example if you have the
+  following project layout:
 
 +--------
-myproject/
-  |_ project1/
-    |_ pom.xml
-  |_ project2/
-    |_ pom.xml
-  |_ pom.xml
+myproject
+ |-- project1
+ |   `-- pom.xml
+ |-- project2
+ |   `-- pom.xml
+ `-- pom.xml
 +---------
 
   Then, ensure that your <<<myproject/pom.xml>>> contains the following:
@@ -381,35 +553,31 @@ myproject/
 [...]
 +---------
 
-  When you run <<<mvn site>>> in <<<myproject/>>>, the plugin will instrument your sources, run your tests,
-  aggregate the different Clover databases generated for each build module (i.e. <<<project1>>> and <<<project2>>>)
-  and generate a master Clover report in the site for the <<<myproject>>> project.
-
-  Note that you can control the location of the master Clover database by using the <<<cloverMergeDatabase>>>
-  configuration property.
-
-* {Controlling files to instrument}
-
-  By default all Java files are included during the instrumentation. To specify inclusion and exclusion use the
-  <<<includes>>> and <<<excludes>>> configuration elements as shown in this example:
+  When you run <<<mvn site>>> in <<<myproject/>>>, the plugin will instrument 
+  your sources, run your tests, aggregate the different 
+  {{{http://cenqua.com/clover/doc/adv/database.html}Clover database}} generated 
+  for each build module (i.e. <<<project1>>> and <<<project2>>>) and generate an
+  aggregated Clover report in the site for the <<<myproject>>> project.
+  
+  Alternatively, you can execute
+  
++------+
+mvn clover:aggregate clover:clover
++------+
 
-+--------
-  <plugin>
-    <groupId>org.apache.maven.plugins</groupId>
-    <artifactId>maven-clover-plugin</artifactId>
-    <configuration>
-      <includes>
-        <include>**/api/**/*.java</include>
-        <include>some/path/MyFile.java</include>
-        [...]
-      </includes>
-      <excludes>
-        <exclude>**/*Test/java</exclude>
-        [...]
-      </excludes>
-[...]
-+---------
+  or if there is no existing 
+  {{{http://cenqua.com/clover/doc/adv/database.html}Clover database}}:
+  
++------+
+mvn clover:instrument clover:aggregate clover:clover
++------+
 
+  Note that you can control the location of the merged
+  {{{http://cenqua.com/clover/doc/adv/database.html}Clover database}} by using
+  the <<<cloverMergeDatabase>>> configuration property.
+  
+  <Back to {{{usage.html}top}}.>
+  
 * {Getting information on an existing Clover database}
 
   You can dump information about your project's Clover database (after it has been populated) by running
@@ -429,3 +597,48 @@ Coverage Overview -
  Conditionals: 1/2 (50%)
         TOTAL: 62,5%
 +---------
+
+  <Back to {{{usage.html}top}}.>
+  
+* {Specifying a custom license file}
+
+  The Clover plugin provides a default evaulation license. However if you continue to use Clover you'll need your
+  own license (they are free for open source/non-commercial project but you'll need to contact Cenqua to get a
+  license). To use your license specify it using a <<<licenseLocation>>> configuration element. For example if you
+  wanted to automatically execute the <<<check>>> goal when you type <<<mvn install>>> and if you wanted to use your
+  license located in <<<${basedir}/src/test/clover/myclover.license>>> you would use:
+
++--------
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-clover-plugin</artifactId>
+        <configuration>
+          <licenseLocation>${basedir}/src/test/clover/myclover.license</licenseLocation>
+        </configuration>
+        <executions>
+          <execution>
+            <configuration>
+              <targetPercentage>50%</targetPercentage>
+            </configuration>
+            <phase>verify</phase>
+            <goals>
+              <goal>instrument</goal>
+              <goal>check</goal>
+            </goals>
+          </execution>
+        </executions>
+      </plugin>
+    </plugins>
+  </build>
++---------
+
+  Important note: The <<<licenseLocation>>> element needs to be defined in the global <<<configuration>>> element
+  and not in the <<<configuration>>> element under the <<<execution>>> tag.
+
+  Instead of specifying a file, you can also specify either a <<URL>> or a <<relative path inside a JAR>> (to learn
+  how to use this feature, refer to the
+  {{{http://maven.apache.org/plugins/maven-checkstyle-plugin/tips.html}Checkstlye plugin documentation}}.
+
+  <Back to {{{usage.html}top}}.>
diff --git a/src/site/fml/faq.fml b/src/site/fml/faq.fml
new file mode 100644
index 0000000000..7413e5fe39
--- /dev/null
+++ b/src/site/fml/faq.fml
@@ -0,0 +1,38 @@
+<?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="Does Clover work on the Source code or the bytecode?">
+     <question>Does Clover work on the Source code or the bytecode?</question>
+     <answer>
+       <p>Clover works on the source code. It is not possible for Clover to work
+       on bytecodes.</p>
+     </answer>
+   </faq>
+   <faq id="Why are my tests executed twice?">
+     <question>Why are my tests executed twice?</question>
+     <answer>
+       <p>The Clover plugin takes great care not to mix the instrumented code nor any artifact generated from it
+       with main production sources and artifacts. This is the reason why you may see your tests executed twice: once
+       for the production sources and once for the Clover-instrumented sources.
+       </p>
+     </answer>
+   </faq>
+ </part>
+</faqs>
diff --git a/src/site/site.xml b/src/site/site.xml
index c507e9b909..e0234071c2 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -37,6 +37,12 @@
       <item name="Usage" href="usage.html"/>
       <item name="FAQ" href="faq.html"/>
     </menu>
+    
+    <menu name="Examples">
+      <item name="Simple" href="/examples/simple.html"/>
+      <item name="Filter Contexts" href="/examples/contexts.html"/>
+      <item name="Multiproject" href="/examples/multiproject.html"/>
+    </menu>
 
     <!-- To be uncommented once it's up to date again -->
     <!--menu name="Architecture">
-- 
GitLab