Port the site documentation from APT to Markdown

src/site/markdown/index.md.vm

@@ -0,0 +1,75 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# ${project.name}
+
+This component has been built from the filtering process/code in Maven Resources Plugin.
+
+The goal is to provide a shared component for all plugins that needs to filter resources.
+
+MavenResourcesExecution
+-----------------------
+
+#[[### POM Interpolation]]#
+
+POM values will be interpolated **only** with expressions starting with `pom` or `project` (it's configurable). In previous versions something like ${esc.d}{foo.version} or ${esc.d}{version} was interpolated with the current POM version, but it won't be interpolated with a POM value any more.
+
+#[[### Escaping Interpolation]]#
+
+It's possible now to define a String which will escape interpolation. ${esc.b}${esc.b}${esc.d}{java.home} will be interpolated to ${esc.d}{java.home}.
+
+#[[### `targetPath` parameter]]#
+
+It also accepts absolute paths.
+
+#[[### `overwrite` parameter]]#
+
+The parameter `overwrite` forces file copy even if the destination file is newer.
+
+MavenResourcesFiltering
+-----------------------
+
+This component will apply filtering on a `List` of `org.apache.maven.model.Resource`s.
+
+If you want to use the default `List` of `FileUtils.FilterWrapper` (see below) you should use the method without the `filterWrappers` parameter.
+
+The component will not filter a predefined set of file extensions (jpg, jpeg, gif, bmp, png).
+
+**Note:** You can easily add extra file extensions.
+
+MavenFileFilter
+---------------
+
+This component has a method which returns the default `FileUtils.FilterWrapper`s. These are:
+
+- Interpolation with token ${esc.d}{ } and values from properties files, `<project>`/`<build>`/`<filters`, `project.properties` and `mavenSession.executionProperties`
+- Interpolation with token @ @ and values from properties files, `<project>`/`<build>`/`<filters`, `project.properties` and `mavenSession.executionProperties`
+- Interpolation with token ${esc.d}{ } and values from `mavenProject` interpolation
+- Interpolation with token @ @ and values from `mavenProject` interpolation
+
+The values used for interpolation are stored in a `Properties` object and are loaded in the following order:
+
+- A `List` of properties files, provided as a parameter to the method
+- Filters defined in the `<build>`/`<filters>` section of the POM
+- Properties defined in the `<properties>` section of the POM
+- The `executionProperties` from the current `MavenSession`
+
+**Note:** As it's a `Properties` object, the last defined key/value pair wins.
+
+**Note:** When building the `Properties` object and reading the properties files that defines the different filters, interpolation with the token ${esc.d}{ } is supported for these filters with limited properties values coming from `project.properties` and `mavenSession.executionProperties`. The last wins here too.

src/site/markdown/usage.md

@@ -0,0 +1,84 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Usage
+
+## Filter a `List` of `org.apache.maven.model.Resource`
+
+Lookup the component in your Mojo:
+
+```unknown
+    @Required
+    private MavenResourcesFiltering mavenResourcesFiltering;
+```
+
+Apply filtering on your `List` of resources, see [Introduction](./index.html) for the default `FilterWrappers` that are used.
+
+```unknown
+        MavenResourcesExecution mavenResourcesExecution =
+            new MavenResourcesExecution ( resources, outputDirectory, mavenProject,
+                                          encoding, fileFilters,
+                                          nonFilteredFileExtensions, mavenSession );
+
+        mavenResourcesFiltering.filterResources( mavenResourcesExecution );
+```
+
+## Add a new filtering token
+
+You must use the other methods from the `MavenResourcesFiltering` component and construct your own `List` of `FilterWrappers`. The following example adds interpolation for the token @ @ using values coming from reflection with the Maven Project.
+
+```unknown
+        // Create your FilterWrapper
+        FileUtils.FilterWrapper filterWrapper = new FileUtils.FilterWrapper()
+        {
+            public Reader getReader( Reader reader )
+            {
+                Interpolator propertiesInterpolator =
+                    new RegexBasedInterpolator(  "\\@", "(.+?)\\@" );
+                ValueSource valueSource = new MavenProjectValueSource( mavenProject,
+                                                                       true );
+                propertiesInterpolator.addValueSource( valueSource );
+                return new InterpolatorFilterReader( reader,
+                                                     propertiesInterpolator,
+                                                     "@", "@" );
+            }
+        };
+
+        // Add the new filterWrapper to your MavenResourcesExecution instance
+        mavenResourcesExecution.addFilterWrapper( filterWrapper );
+```
+
+There is a helper method to simplify this. Here's how you would use it to do what we did above:
+
+```unknown
+        mavenResourcesExecution.addFilerWrapper( new MavenProjectValueSource( mavenProject,
+                                                                              true ),
+                                                 "\\@", "(.+?)\\@", "@", "@" );
+```
+
+**Note:** If `mavenResourcesExecution.useDefaultFilterWrappers` is set to `true`, the default `FilterWrapper`s will be added first.
+
+Now it's time to filter the resources:
+
+```unknown
+        // Apply filtering on your resources
+        mavenResourcesFiltering.filterResources( mavenResourcesExecution );
+```
+
+**Note:** Maven Filtering uses the [plexus-interpolation component](http://codehaus-plexus.github.io/plexus-interpolation/).