From 2dc4581e40b57549c135dd1df6dfb7a4f592db0d Mon Sep 17 00:00:00 2001 From: Sylwester Lachiewicz Date: Thu, 6 Aug 2026 14:54:37 +0200 Subject: [PATCH 1/2] Rename the site documents ahead of converting them A pure rename, so that git records it and `git log --follow` and `git blame` still reach the history of each page after the conversion that follows. The content is still APT at this point and the site does not build between the two commits. --- src/site/{apt/index.apt.vm => markdown/index.md.vm} | 0 src/site/{apt/usage.apt => markdown/usage.md} | 0 2 files changed, 0 insertions(+), 0 deletions(-) rename src/site/{apt/index.apt.vm => markdown/index.md.vm} (100%) rename src/site/{apt/usage.apt => markdown/usage.md} (100%) diff --git a/src/site/apt/index.apt.vm b/src/site/markdown/index.md.vm similarity index 100% rename from src/site/apt/index.apt.vm rename to src/site/markdown/index.md.vm diff --git a/src/site/apt/usage.apt b/src/site/markdown/usage.md similarity index 100% rename from src/site/apt/usage.apt rename to src/site/markdown/usage.md From 5683a747d3a59059345a2c1320c875fbf62e9f73 Mon Sep 17 00:00:00 2001 From: Sylwester Lachiewicz Date: Thu, 6 Aug 2026 14:54:37 +0200 Subject: [PATCH 2/2] Port the site documentation from APT to Markdown 2 page(s) converted with doxia-converter and then cleaned up by hand: - <<>> becomes backticks, <> 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 / becoming / 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 06a8cfa8..f26fcb06 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 - ------ + - 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 <> with expressions starting with <<>> or <<>> (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. -** <<>> 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}. -** <<>> parameter +#[[### `targetPath` parameter]]# - The parameter <<>> 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 <<>> of <<>>s. +MavenResourcesFiltering +----------------------- - If you want to use the default <<>> of <<>> (see below) - you should use the method without the <<>> 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. - <> 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 <<>>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, <<<\>>>/<<<\>>>/<<<\>>, <<>> - and <<>> +- Interpolation with token ${esc.d}{ } and values from properties files, ``/``/``/``/`>>>/<<<\>>>/<<<\>>, <<>> - and <<>> +The values used for interpolation are stored in a `Properties` object and are loaded in the following order: - * Interpolation with token $\{ \} and values from <<>> interpolation +- A `List` of properties files, provided as a parameter to the method +- Filters defined in the ``/`` section of the POM +- Properties defined in the `` section of the POM +- The `executionProperties` from the current `MavenSession` - * Interpolation with token @ @ and values from <<>> interpolation +**Note:** As it's a `Properties` object, the last defined key/value pair wins. - [] - - The values used for interpolation are stored in a <<>> object - and are loaded in the following order: - - * A <<>> of properties files, provided as a parameter to the method - - * Filters defined in the <<<\>>>/<<<\>>> section of the POM - - * Properties defined in the <<<\>>> section of the POM - - * The <<>> from the current <<>> - - [] - - <> As it's a <<>> object, the last defined key/value pair wins. - - <> When building the <<>> 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 - <<>> and <<>>. 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 bc867efa..2256c593 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 <<>> of <<>> - - Lookup the component in your Mojo: - -+-----+ + + +# 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 <<>> of resources, see {{{./index.html}Introduction}} for the default <<>> - 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 <<>> component and construct your own <<>> of - <<>>. 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 ), "\\@", "(.+?)\\@", "@", "@" ); -+-----+ +``` - <> If <<>> is set to <<>>, - the default <<>>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 ); -+-----+ - - <> 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/).