You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by sl...@apache.org on 2026/08/06 17:08:52 UTC
(maven-filtering) 02/02: Port the site documentation from APT to Markdown
This is an automated email from the ASF dual-hosted git repository.
slachiewicz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-filtering.git
commit 83ab29fd6bb60a9466216c1d27f12b6bbbd061bc
Author: Sylwester Lachiewicz <sl...@apache.org>
AuthorDate: Thu Aug 6 14:54:37 2026 +0200
Port the site documentation from APT to Markdown
2 page(s) converted with doxia-converter and then cleaned up by hand:
- <<<code>>> becomes backticks, <<bold>> becomes **bold**, {{{url}text}}
becomes [text](url)
- the ASF license header becomes a single block HTML comment
- a page whose only Velocity reference was ${project.name} is now a plain
.md with the title spelled out
- a page that keeps a reference stays a .vm. Velocity reads ## as a line
comment and would silently swallow every ATX heading below level one, so
subsections use setext underlines and anything deeper is wrapped in
#[[ ... ]]#
- references APT rendered literally are escaped, so they do not resolve
Verified by building the site before and after and comparing every
generated page: the visible text and the link targets are unchanged apart
from <b>/<i> becoming <strong>/<em> and quotes in prose picking up the
Markdown module's typographic substitution.
---
src/site/markdown/index.md.vm | 124 +++++++++++++++++-------------------------
src/site/markdown/usage.md | 96 ++++++++++++++------------------
2 files changed, 91 insertions(+), 129 deletions(-)
diff --git a/src/site/markdown/index.md.vm b/src/site/markdown/index.md.vm
index 06a8cfa..f26fcb0 100644
--- a/src/site/markdown/index.md.vm
+++ b/src/site/markdown/index.md.vm
@@ -1,101 +1,75 @@
- ------
- Introduction
- ------
- Olivier Lamy
- ------
- 2013-07-24
- ------
+<!--
+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
- ~~ 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.
+http://www.apache.org/licenses/LICENSE-2.0
-${project.name}
+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.
+-->
- This component has been built from the filtering process/code in Maven Resources Plugin.
+# ${project.name}
- The goal is to provide a shared component for all plugins that needs to filter resources.
+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
+MavenResourcesExecution
+-----------------------
-** POM Interpolation
-
- POM values will be interpolated <<only>> with expressions starting with <<<pom>>> or <<<project>>> (it's configurable).
- In previous versions something like $\{foo.version\} or $\{version\} was interpolated with the current POM version, but
- it won't be interpolated with a POM value any more.
-
-** Escaping Interpolation
+#[[### POM Interpolation]]#
- It's possible now to define a String which will escape interpolation.
- \$\{java.home\} will be interpolated to $\{java.home\}.
+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.
-** <<<targetPath>>> parameter
+#[[### Escaping Interpolation]]#
- It also accepts absolute paths.
+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}.
-** <<<overwrite>>> parameter
+#[[### `targetPath` parameter]]#
- The parameter <<<overwrite>>> forces file copy even if the destination file is newer.
+It also accepts absolute paths.
+#[[### `overwrite` parameter]]#
-* MavenResourcesFiltering
+The parameter `overwrite` forces file copy even if the destination file is newer.
- This component will apply filtering on a <<<List>>> of <<<org.apache.maven.model.Resource>>>s.
+MavenResourcesFiltering
+-----------------------
- If you want to use the default <<<List>>> of <<<FileUtils.FilterWrapper>>> (see below)
- you should use the method without the <<<filterWrappers>>> parameter.
+This component will apply filtering on a `List` of `org.apache.maven.model.Resource`s.
- The component will not filter a predefined set of file extensions (jpg, jpeg, gif, bmp, png).
+If you want to use the default `List` of `FileUtils.FilterWrapper` (see below) you should use the method without the `filterWrappers` parameter.
- <<Note:>> You can easily add extra file extensions.
+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
+MavenFileFilter
+---------------
- This component has a method which returns the default <<<FileUtils.FilterWrapper>>>s.
- These are:
+This component has a method which returns the default `FileUtils.FilterWrapper`s. These are:
- * Interpolation with token $\{ \} and values from properties files, <<<\<project\>>>>/<<<\<build\>>>>/<<<\<filters>>>, <<<project.properties>>>
- and <<<mavenSession.executionProperties>>>
+- 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
- * Interpolation with token @ @ and values from properties files, <<<\<project\>>>>/<<<\<build\>>>>/<<<\<filters>>>, <<<project.properties>>>
- and <<<mavenSession.executionProperties>>>
+The values used for interpolation are stored in a `Properties` object and are loaded in the following order:
- * Interpolation with token $\{ \} and values from <<<mavenProject>>> interpolation
+- 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`
- * Interpolation with token @ @ and values from <<<mavenProject>>> interpolation
+**Note:** As it's a `Properties` object, the last defined key/value pair wins.
- []
-
- 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 $\{ \} is supported for these filters with limited properties values coming from
- <<<project.properties>>> and <<<mavenSession.executionProperties>>>. The last wins here too.
+**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.
diff --git a/src/site/markdown/usage.md b/src/site/markdown/usage.md
index bc867ef..2256c59 100644
--- a/src/site/markdown/usage.md
+++ b/src/site/markdown/usage.md
@@ -1,58 +1,49 @@
- ------
- Usage
- ------
- Olivier Lamy
- ------
- 2011-01-05
- ------
-
- ~~ 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:
-
-+-----+
+<!--
+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 {{{./index.html}Introduction}} for the default <<<FilterWrappers>>>
- that are used.
+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
+## 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.
+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()
{
@@ -71,26 +62,23 @@ Usage
// 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:
+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.
+**Note:** If `mavenResourcesExecution.useDefaultFilterWrappers` is set to `true`, the default `FilterWrapper`s will be added first.
- Now it's time to filter the resources:
+Now it's time to filter the resources:
-+-----+
+```unknown
// Apply filtering on your resources
mavenResourcesFiltering.filterResources( mavenResourcesExecution );
-+-----+
-
- <<Note:>> Maven Filtering uses the
- {{{http://codehaus-plexus.github.io/plexus-interpolation/}plexus-interpolation component}}.
+```
+**Note:** Maven Filtering uses the [plexus-interpolation component](http://codehaus-plexus.github.io/plexus-interpolation/).