From b19697146bc682521e2a6daa6cf6d0d2cbb72ec4 Mon Sep 17 00:00:00 2001 From: Sylwester Lachiewicz Date: Thu, 6 Aug 2026 13:53:05 +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. --- .../examples/binaries-filtering.md.vm} | 0 .../examples/copy-resources.md.vm} | 0 .../examples/custom-resource-filters.md.vm} | 0 .../examples/encoding.apt.vm => markdown/examples/encoding.md.vm} | 0 .../examples/escape-filtering.md.vm} | 0 src/site/{apt/examples/filter.apt => markdown/examples/filter.md} | 0 .../examples/filtering-properties-files.md.vm} | 0 .../include-exclude.apt => markdown/examples/include-exclude.md} | 0 .../examples/resource-directory.md} | 0 src/site/{apt/index.apt.vm => markdown/index.md} | 0 src/site/{apt/usage.apt.vm => markdown/usage.md.vm} | 0 11 files changed, 0 insertions(+), 0 deletions(-) rename src/site/{apt/examples/binaries-filtering.apt.vm => markdown/examples/binaries-filtering.md.vm} (100%) rename src/site/{apt/examples/copy-resources.apt.vm => markdown/examples/copy-resources.md.vm} (100%) rename src/site/{apt/examples/custom-resource-filters.apt.vm => markdown/examples/custom-resource-filters.md.vm} (100%) rename src/site/{apt/examples/encoding.apt.vm => markdown/examples/encoding.md.vm} (100%) rename src/site/{apt/examples/escape-filtering.apt.vm => markdown/examples/escape-filtering.md.vm} (100%) rename src/site/{apt/examples/filter.apt => markdown/examples/filter.md} (100%) rename src/site/{apt/examples/filtering-properties-files.apt.vm => markdown/examples/filtering-properties-files.md.vm} (100%) rename src/site/{apt/examples/include-exclude.apt => markdown/examples/include-exclude.md} (100%) rename src/site/{apt/examples/resource-directory.apt => markdown/examples/resource-directory.md} (100%) rename src/site/{apt/index.apt.vm => markdown/index.md} (100%) rename src/site/{apt/usage.apt.vm => markdown/usage.md.vm} (100%) diff --git a/src/site/apt/examples/binaries-filtering.apt.vm b/src/site/markdown/examples/binaries-filtering.md.vm similarity index 100% rename from src/site/apt/examples/binaries-filtering.apt.vm rename to src/site/markdown/examples/binaries-filtering.md.vm diff --git a/src/site/apt/examples/copy-resources.apt.vm b/src/site/markdown/examples/copy-resources.md.vm similarity index 100% rename from src/site/apt/examples/copy-resources.apt.vm rename to src/site/markdown/examples/copy-resources.md.vm diff --git a/src/site/apt/examples/custom-resource-filters.apt.vm b/src/site/markdown/examples/custom-resource-filters.md.vm similarity index 100% rename from src/site/apt/examples/custom-resource-filters.apt.vm rename to src/site/markdown/examples/custom-resource-filters.md.vm diff --git a/src/site/apt/examples/encoding.apt.vm b/src/site/markdown/examples/encoding.md.vm similarity index 100% rename from src/site/apt/examples/encoding.apt.vm rename to src/site/markdown/examples/encoding.md.vm diff --git a/src/site/apt/examples/escape-filtering.apt.vm b/src/site/markdown/examples/escape-filtering.md.vm similarity index 100% rename from src/site/apt/examples/escape-filtering.apt.vm rename to src/site/markdown/examples/escape-filtering.md.vm diff --git a/src/site/apt/examples/filter.apt b/src/site/markdown/examples/filter.md similarity index 100% rename from src/site/apt/examples/filter.apt rename to src/site/markdown/examples/filter.md diff --git a/src/site/apt/examples/filtering-properties-files.apt.vm b/src/site/markdown/examples/filtering-properties-files.md.vm similarity index 100% rename from src/site/apt/examples/filtering-properties-files.apt.vm rename to src/site/markdown/examples/filtering-properties-files.md.vm diff --git a/src/site/apt/examples/include-exclude.apt b/src/site/markdown/examples/include-exclude.md similarity index 100% rename from src/site/apt/examples/include-exclude.apt rename to src/site/markdown/examples/include-exclude.md diff --git a/src/site/apt/examples/resource-directory.apt b/src/site/markdown/examples/resource-directory.md similarity index 100% rename from src/site/apt/examples/resource-directory.apt rename to src/site/markdown/examples/resource-directory.md diff --git a/src/site/apt/index.apt.vm b/src/site/markdown/index.md similarity index 100% rename from src/site/apt/index.apt.vm rename to src/site/markdown/index.md diff --git a/src/site/apt/usage.apt.vm b/src/site/markdown/usage.md.vm similarity index 100% rename from src/site/apt/usage.apt.vm rename to src/site/markdown/usage.md.vm From 775d3d13555c8ea13fb5a2526371d3236f7cb66a Mon Sep 17 00:00:00 2001 From: Sylwester Lachiewicz Date: Thu, 6 Aug 2026 13:53:05 +0200 Subject: [PATCH 2/2] Port the site documentation from APT to Markdown 11 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 #[[ ... ]]# - a reference APT rendered literally is escaped with ${esc.d}, which always yields a literal dollar; a backslash only works when the reference itself resolves 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 and ellipses in prose picking up the Markdown module's typographic substitution. --- .../examples/binaries-filtering.md.vm | 55 +++--- .../markdown/examples/copy-resources.md.vm | 52 +++--- .../examples/custom-resource-filters.md.vm | 111 ++++++------ src/site/markdown/examples/encoding.md.vm | 75 +++----- .../markdown/examples/escape-filtering.md.vm | 58 +++--- src/site/markdown/examples/filter.md | 169 ++++++++---------- .../examples/filtering-properties-files.md.vm | 165 +++++++---------- src/site/markdown/examples/include-exclude.md | 82 ++++----- .../markdown/examples/resource-directory.md | 75 ++++---- src/site/markdown/index.md | 127 +++++-------- src/site/markdown/usage.md.vm | 112 +++++------- 11 files changed, 438 insertions(+), 643 deletions(-) diff --git a/src/site/markdown/examples/binaries-filtering.md.vm b/src/site/markdown/examples/binaries-filtering.md.vm index 059ee33b..21be9dc1 100644 --- a/src/site/markdown/examples/binaries-filtering.md.vm +++ b/src/site/markdown/examples/binaries-filtering.md.vm @@ -1,40 +1,29 @@ - ------ - Binaries Filtering - ------ - Olivier Lamy - ------ - 2008-10-14 - ------ + -Binary filtering +# Binary filtering - The plugin will prevent binary files filtering without adding some <<>> configuration - for the following file extensions <<>>, <<>>, <<>>, <<>> and <<>>. - - If you like to add supplemental file extensions this can simply achieved by - using a configuration like the following: +The plugin will prevent binary files filtering without adding some `excludes` configuration for the following file extensions `jpg`, `jpeg`, `gif`, `bmp` and `png`. -+-----+ +If you like to add supplemental file extensions this can simply achieved by using a configuration like the following: + +```xml ... @@ -57,4 +46,4 @@ Binary filtering ... -+-----+ +``` diff --git a/src/site/markdown/examples/copy-resources.md.vm b/src/site/markdown/examples/copy-resources.md.vm index b955f843..269ae437 100644 --- a/src/site/markdown/examples/copy-resources.md.vm +++ b/src/site/markdown/examples/copy-resources.md.vm @@ -1,37 +1,27 @@ - ------ - Copy Resources - ------ - Olivier Lamy - ------ - 2008-09-13 - ------ + -Copy Resources +# Copy Resources - You can use the mojo copy-resources to copy resources which are not in the default maven layout or not declared in the build/resources element - and attach it to a phase - -+-----+ +You can use the mojo copy-resources to copy resources which are not in the default maven layout or not declared in the build/resources element and attach it to a phase + +```xml ... @@ -64,4 +54,4 @@ Copy Resources ... -+-----+ +``` diff --git a/src/site/markdown/examples/custom-resource-filters.md.vm b/src/site/markdown/examples/custom-resource-filters.md.vm index 639e74e1..50c47f0d 100644 --- a/src/site/markdown/examples/custom-resource-filters.md.vm +++ b/src/site/markdown/examples/custom-resource-filters.md.vm @@ -1,43 +1,34 @@ - ------ - Custom resource filters - ------ - Olivier Lamy - ------ - 2010-09-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 -~~ -~~ 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/doxia/references/apt-format.html - -Custom resources filters - - With version 2.5 you are now able to build your own custom resources filter(s). - - Your custom resources filter classes must implements - {{{/shared/maven-filtering/apidocs/org/apache/maven/shared/filtering/MavenResourcesFiltering.html}org.apache.maven.shared.filtering.MavenResourcesFiltering}}. - -* Custom Resources Filter Implementation - - Your custom resources filter classes must be marked as a Plexus Component. Below a sample with a roleHint itFilter. - -+-----+ + + +# Custom resources filters + +With version 2.5 you are now able to build your own custom resources filter(s). + +Your custom resources filter classes must implements [org.apache.maven.shared.filtering.MavenResourcesFiltering](/shared/maven-filtering/apidocs/org/apache/maven/shared/filtering/MavenResourcesFiltering.html). + +Custom Resources Filter Implementation +-------------------------------------- + +Your custom resources filter classes must be marked as a Plexus Component. Below a sample with a roleHint itFilter. + +```unknown /** * @plexus.component role="org.apache.maven.shared.filtering.MavenResourcesFiltering" @@ -45,12 +36,11 @@ Custom resources filters */ public class ItFilter implements MavenResourcesFiltering +``` -+-----+ +Then you must activate in your build the mojo which will scan javadoc annotations to transform thoses to plexus component metadata. - Then you must activate in your build the mojo which will scan javadoc annotations to transform thoses to plexus component metadata. - -+-----+ +```xml org.codehaus.plexus @@ -64,14 +54,14 @@ public class ItFilter +``` + +Dependency declaration +---------------------- + +Your classes must be available in the maven-resources-plugin classpath, this can be done with adding your artifact to the plugin dependencies. -+-----+ - -* Dependency declaration - - Your classes must be available in the maven-resources-plugin classpath, this can be done with adding your artifact to the plugin dependencies. - -+-----+ +```xml ... @@ -96,13 +86,14 @@ public class ItFilter ... -+-----+ - -* Use of your Custom Resource Filter with the maven-resources-plugin +``` - You must now declare you custom filter in the plugin. mavenFilteringHint must respect same syntax as your Plexus Component roleHint. - -+-----+ +Use of your Custom Resource Filter with the maven-resources-plugin +------------------------------------------------------------------ + +You must now declare you custom filter in the plugin. mavenFilteringHint must respect same syntax as your Plexus Component roleHint. + +```xml org.apache.maven.plugins maven-resources-plugin @@ -116,6 +107,6 @@ public class ItFilter ... -+-----+ - - And that's it ! +``` + +And that's it \! diff --git a/src/site/markdown/examples/encoding.md.vm b/src/site/markdown/examples/encoding.md.vm index 9d0ec63c..403a3fbc 100644 --- a/src/site/markdown/examples/encoding.md.vm +++ b/src/site/markdown/examples/encoding.md.vm @@ -1,42 +1,29 @@ - ------ - Specifying a character encoding scheme - ------ - Franz Allan See - Karl Heinz Marbaise - ------ - 2016-05-13 - ------ + -Specifying a character encoding scheme +# Specifying a character encoding scheme - A character encoding scheme such as <<>>, <<>> or <<>> can be chosen to be - used for the reading and writing of files. +A character encoding scheme such as `ASCII`, `UTF-8` or `UTF-16` can be chosen to be used for the reading and writing of files. - The best practice is to {{{https://maven.apache.org/general.html#encoding-warning}define encoding}} - for copying filtered resources via the property <<<$\{project.build.sourceEncoding}>>> which should be - defined in the pom properties section like this: - -+-----+ +The best practice is to [define encoding](https://maven.apache.org/general.html#encoding-warning) for copying filtered resources via the property `${esc.d}{project.build.sourceEncoding}` which should be defined in the pom properties section like this: + +```xml ... @@ -45,16 +32,13 @@ Specifying a character encoding scheme .. -+-----+ +``` + +By using the above property `maven-resources-plugin` will automatically use this [encoding](../resources-mojo.html#encoding). + +Occasionally you need to change the encoding explicitly for different purposes. This can be done by defining the encoding via the configuration like this: - By using the above property <<>> will automatically - use this {{{../resources-mojo.html#encoding}encoding}}. - - Occasionally you need to change the encoding explicitly for different purposes. - This can be done by defining the encoding via the configuration - like this: - -+-----+ +```xml ... @@ -74,7 +58,4 @@ Specifying a character encoding scheme ... -+-----+ - - - \ No newline at end of file +``` diff --git a/src/site/markdown/examples/escape-filtering.md.vm b/src/site/markdown/examples/escape-filtering.md.vm index ebcfd746..02e7079c 100644 --- a/src/site/markdown/examples/escape-filtering.md.vm +++ b/src/site/markdown/examples/escape-filtering.md.vm @@ -1,41 +1,31 @@ - ------ - Escape Filtering - ------ - Olivier Lamy - ------ - 2008-09-05 - ------ + -Escape filtering +# Escape filtering - You can escape filtering with configurable String. - - This means expression $\{ \} and @ @ preceded will replace by the expression : \$\{java.home\} -> $\{java.home\}. - - <> - +You can escape filtering with configurable String. -+-----+ +This means expression ${esc.d}{ } and @ @ preceded will replace by the expression : ${esc.b}${esc.b}${esc.d}{java.home} -> ${esc.d}{java.home}. + +**The escapeString will be removed** + +```xml ... @@ -55,4 +45,4 @@ Escape filtering ... -+-----+ +``` diff --git a/src/site/markdown/examples/filter.md b/src/site/markdown/examples/filter.md index d7343edf..6228d09c 100644 --- a/src/site/markdown/examples/filter.md +++ b/src/site/markdown/examples/filter.md @@ -1,46 +1,35 @@ - ------ - Filtering - ------ - Franz Allan See - ------ - 2008-09-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. - -~~ NOTE: For help with the syntax of this file, see: -~~ http://maven.apache.org/doxia/references/apt-format.html - -Filtering - - Variables can be included in your resources. These variables, denoted by the - <<<$\{...\}>>> or <<<@...@>>> delimiters, can come from the system properties, your project - properties, from your filter resources and from the command line. - - For example, if we have a resource <<>> containing - -+-----+ + + +# Filtering + +Variables can be included in your resources. These variables, denoted by the `${...}` or `@...@` delimiters, can come from the system properties, your project properties, from your filter resources and from the command line. + +For example, if we have a resource `src/main/resources/hello.txt` containing + +```unknown Hello ${name} -+-----+ +``` - And a POM like this +And a POM like this -+-----+ +```xml ... My Resources Plugin Practice Project @@ -57,24 +46,23 @@ Hello ${name} ... -+-----+ +``` - Upon calling +Upon calling -+-----+ +```shell mvn resources:resources -+-----+ +``` - This will create a resource output in <<>> which contains - exactly the same text. +This will create a resource output in `target/classes/hello.txt` which contains exactly the same text. -+-----+ +```unknown Hello ${name} -+-----+ +``` - However, if we add a <<<\>>> element to our POM and set it to <<>> like this: +However, if we add a `` element to our POM and set it to `true` like this: -+-----+ +```xml ... @@ -83,43 +71,37 @@ Hello ${name} ... -+-----+ +``` - Our <<>> after calling +Our `target/classes/hello.txt` after calling -+-----+ +```shell mvn resources:resources -+-----+ +``` - would be +would be -+-----+ +```unknown Hello My Resources Plugin Practice Project -+-----+ +``` - That's because the name variable was replaced by the value of the project's - name (which was specified in the POM). +That's because the name variable was replaced by the value of the project's name (which was specified in the POM). - Moreover, we can also assign values through the command line using the "-D" - option. For example, to change the value for the variable <<>> to "world", we can - simply invoke this command: +Moreover, we can also assign values through the command line using the "-D" option. For example, to change the value for the variable `name` to "world", we can simply invoke this command: -+-----+ +```shell mvn resources:resources -Dname="world" -+-----+ +``` - And the output in <<>> would be +And the output in `target/classes/hello.txt` would be -+-----+ +```unknown Hello world -+-----+ +``` - Furthermore, we are not limited to use pre-defined project variables. We can - specify our own variables and their values in the <<<\>>> element. For - example, if we want to change the variable from "name" to "your.name", we can - do so by adding a <<<\>>> element within the <<<\>>> element. +Furthermore, we are not limited to use pre-defined project variables. We can specify our own variables and their values in the `` element. For example, if we want to change the variable from "name" to "your.name", we can do so by adding a `` element within the `` element. -+-----+ +```xml ... @@ -127,14 +109,11 @@ Hello world ... -+-----+ +``` - But to organize your project, you may want to put all your variables and their - values in a separate file so that you will not have to rewrite your POM, or set - their values all the time with every build. This can be done by adding a - filter. +But to organize your project, you may want to put all your variables and their values in a separate file so that you will not have to rewrite your POM, or set their values all the time with every build. This can be done by adding a filter. -+-----+ +```xml ... My Resources Plugin Practice Project @@ -148,18 +127,17 @@ Hello world ... -+-----+ +``` - For example, we can separate "your.name" from the POM by specifying a filter file - <<>> containing: +For example, we can separate "your.name" from the POM by specifying a filter file `my-filter-values.properties` containing: -+-----+ +```properties your.name = world -+-----+ +``` - and adding that to our POM +and adding that to our POM -+-----+ +```xml ... @@ -167,16 +145,13 @@ your.name = world ... -+-----+ +``` - - <> Do not filter files with binary content like images! This will most likely result in corrupt output. +**Warning:** Do not filter files with binary content like images\! This will most likely result in corrupt output. - If you have both text files and binary files as resources it is recommended to have two separated - folders. One folder <<>> (default) for the resources which are not filtered and - another folder <<>> for the resources which are filtered. +If you have both text files and binary files as resources it is recommended to have two separated folders. One folder `src/main/resources` (default) for the resources which are not filtered and another folder `src/main/resources-filtered` for the resources which are filtered. -+-----+ +```xml ... @@ -192,12 +167,8 @@ your.name = world ... -+-----+ +``` - Now you can put those files into <<>> which should not filtered and the other files - into <<>>. - - As already mentioned filtering binary files like images,pdf`s etc. could result in corrupted output. - To prevent such problems you can {{{./binaries-filtering.html}configure file extensions}} - which will not being filtered. +Now you can put those files into `src/main/resources` which should not filtered and the other files into `src/main/resources-filtered`. +As already mentioned filtering binary files like images,pdf\`s etc. could result in corrupted output. To prevent such problems you can [configure file extensions](./binaries-filtering.html) which will not being filtered. diff --git a/src/site/markdown/examples/filtering-properties-files.md.vm b/src/site/markdown/examples/filtering-properties-files.md.vm index e43106bb..608614ab 100644 --- a/src/site/markdown/examples/filtering-properties-files.md.vm +++ b/src/site/markdown/examples/filtering-properties-files.md.vm @@ -1,96 +1,69 @@ - ------ - Filtering Properties Files - ------ - Dennis Lundberg - ------ - 2020-07-16 - ------ - -~~ 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. - -~~ NOTE: For help with the syntax of this file, see: -~~ http://maven.apache.org/doxia/references/apt-format.html - -Filtering Properties Files - - When filtering resources, special care has to be taken if you are filtering - properties files. If your filtered properties files include non-ascii - characters and your <<>> is set to anything other - than ISO-8859-1 you might be affected and should continue reading. - -* What has <<>> got to do with resources? - - Maven Resources Plugin has, up until version 3.2.0, defaulted to use - <<>> as the encoding when filtering resources, - unless you configure the <<>> parameter of the plugin explicitly. So - unless you have configured the <<>> parameter in Maven Resources - Plugin explicitly this is what you get. - -* Properties files handled by the <<>> class - - When the Properties class is used to read and write properties files they - require that the properties files use ISO-8859-1 encoding. - This is still the case for Java 11, as can be seen in the - {{{https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Properties.html}API documentation for the Properties class}}. - So, properties files that are used in this way needs to use ISO-8859-1 - encoding. - -* Properties files used as <<>> - - When properties files are used as <<>>s the encoding required - differs between versions of Java. Up to and including Java 8 these files are - required to use ISO-8859-1 encoding. - - Starting with Java 9 the preferred encoding is UTF-8 for property resource - bundles. It might work with ISO-8859-1, but as you can see in the - {{{https://docs.oracle.com/javase/9/intl/internationalization-enhancements-jdk-9.htm#JSINT-GUID-5ED91AA9-B2E3-4E05-8E99-6A009D2B36AF}Internationalization Enhancements in JDK 9}} - documentation you should consider converting your property resource bundles - into UTF-8 encoding. - -* What do I need to do? - - You need to do 2 things: - - [[1]] Decide which encoding to use for properties files, based on how you use them - in your project. - - [[1]] Explicitly configure Maven Resource Plugin accordingly using the - <<>> configuration parameter, that was introduced in - version 3.2.0. In most cases it would look like this: - -+-----+ - - ... - - - - org.apache.maven.plugins - maven-resources-plugin - ${project.version} - - ... - ISO-8859-1 - ... - - - - ... - - ... - -+-----+ + + +# Filtering Properties Files + +When filtering resources, special care has to be taken if you are filtering properties files. If your filtered properties files include non-ascii characters and your `project.build.sourceEncoding` is set to anything other than ISO-8859-1 you might be affected and should continue reading. + +What has `project.build.sourceEncoding` got to do with resources? +----------------------------------------------------------------- + +Maven Resources Plugin has, up until version 3.2.0, defaulted to use `project.build.sourceEncoding` as the encoding when filtering resources, unless you configure the `encoding` parameter of the plugin explicitly. So unless you have configured the `encoding` parameter in Maven Resources Plugin explicitly this is what you get. + +Properties files handled by the `Properties` class +-------------------------------------------------- + +When the Properties class is used to read and write properties files they require that the properties files use ISO-8859-1 encoding. This is still the case for Java 11, as can be seen in the [API documentation for the Properties class](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Properties.html). So, properties files that are used in this way needs to use ISO-8859-1 encoding. + +Properties files used as `ResourceBundle` +----------------------------------------- + +When properties files are used as `ResourceBundle`s the encoding required differs between versions of Java. Up to and including Java 8 these files are required to use ISO-8859-1 encoding. + +Starting with Java 9 the preferred encoding is UTF-8 for property resource bundles. It might work with ISO-8859-1, but as you can see in the [Internationalization Enhancements in JDK 9](https://docs.oracle.com/javase/9/intl/internationalization-enhancements-jdk-9.htm#JSINT-GUID-5ED91AA9-B2E3-4E05-8E99-6A009D2B36AF) documentation you should consider converting your property resource bundles into UTF-8 encoding. + +What do I need to do? +--------------------- + +You need to do 2 things: + +1. Decide which encoding to use for properties files, based on how you use them in your project. +1. Explicitly configure Maven Resource Plugin accordingly using the `propertiesEncoding` configuration parameter, that was introduced in version 3.2.0. In most cases it would look like this: + + ```xml + + ... + + + + org.apache.maven.plugins + maven-resources-plugin + ${project.version} + + ... + ISO-8859-1 + ... + + + + ... + + ... + + ``` diff --git a/src/site/markdown/examples/include-exclude.md b/src/site/markdown/examples/include-exclude.md index 521e8683..264638a1 100644 --- a/src/site/markdown/examples/include-exclude.md +++ b/src/site/markdown/examples/include-exclude.md @@ -1,40 +1,29 @@ - ------ - Including and excluding files and directories - ------ - Franz Allan See - ------ - 2008-09-05 - ------ + -Including and excluding files and directories +# Including and excluding files and directories - When specifying a resource directory, every file within that directory may not - be used. Thus, we may have to specify only the files that we want to include or - specify the files that we want to exclude. +When specifying a resource directory, every file within that directory may not be used. Thus, we may have to specify only the files that we want to include or specify the files that we want to exclude. - To include a resource, we only need to add an <<<\>>> element. +To include a resource, we only need to add an `` element. -+-----+ +```xml ... My Resources Plugin Practice Project @@ -58,11 +47,11 @@ Including and excluding files and directories ... -+-----+ +``` - And to exclude a resource, we only need to add an <<<\>>> element. +And to exclude a resource, we only need to add an `` element. -+-----+ +```xml ... My Resources Plugin Practice Project @@ -86,13 +75,11 @@ Including and excluding files and directories ... -+-----+ +``` - For example, if we want to include all text and RTF files under our - <<>> directory and in all its subdirectories, we can do the - following: +For example, if we want to include all text and RTF files under our `src/my-resources` directory and in all its subdirectories, we can do the following: -+-----+ +```xml ... My Resources Plugin Practice Project @@ -113,12 +100,11 @@ Including and excluding files and directories ... -+-----+ +``` - Also, if we want to include everything except the bitmaps, jpegs, and gifs, we - can simply exclude them by: +Also, if we want to include everything except the bitmaps, jpegs, and gifs, we can simply exclude them by: -+-----+ +```xml ... My Resources Plugin Practice Project @@ -141,13 +127,11 @@ Including and excluding files and directories ... -+-----+ +``` - Of course, we can also have both <<<\>>> and <<<\>>> elements. For example, if we - want to include all text files that does not contain the word "test" in their - filename. +Of course, we can also have both `` and `` elements. For example, if we want to include all text files that does not contain the word "test" in their filename. -+-----+ +```xml ... My Resources Plugin Practice Project @@ -170,4 +154,4 @@ Including and excluding files and directories ... -+-----+ +``` diff --git a/src/site/markdown/examples/resource-directory.md b/src/site/markdown/examples/resource-directory.md index 55b4d85d..252d94d9 100644 --- a/src/site/markdown/examples/resource-directory.md +++ b/src/site/markdown/examples/resource-directory.md @@ -1,48 +1,37 @@ - ------ - Specifying resource directories - ------ - Franz Allan See - ------ - 2008-09-05 - ------ + -Specifying resource directories +# Specifying resource directories - By default, Maven will look for your project's resources under - <<>>. +By default, Maven will look for your project's resources under `src/main/resources`. -+-----+ +```unknown Project |-- pom.xml `-- src `-- main `-- resources -+-----+ +``` - However, all your resources may not be in <<>>. Thus, you'd have - to specify those directories by adding the following to your POM. +However, all your resources may not be in `src/main/resources`. Thus, you'd have to specify those directories by adding the following to your POM. -+-----+ +```xml ... @@ -56,20 +45,20 @@ Project ... -+-----+ +``` - So if your resources resides in <<>> +So if your resources resides in `src/my-resources` -+-----+ +```unknown Project |-- pom.xml `-- src `-- my-resources -+-----+ +``` - you can specify that directory by doing the following: +you can specify that directory by doing the following: -+-----+ +```xml ... @@ -79,11 +68,11 @@ Project ... -+-----+ +``` - Furthermore, you can have several directories by adding multiple <<<\>>> elements: +Furthermore, you can have several directories by adding multiple `` elements: -+-----+ +```xml ... @@ -99,4 +88,4 @@ Project ... -+-----+ +``` diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md index 5b731c47..f037a477 100644 --- a/src/site/markdown/index.md +++ b/src/site/markdown/index.md @@ -1,105 +1,62 @@ - ------ - Introduction - ------ - Franz Allan See - ------ - 2013-07-22 - ------ + -${project.name} +# Apache Maven Resources Plugin +The Resources Plugin handles the copying of project resources to the output directory. There are two different kinds of resources: main resources and test resources. The difference is that the main resources are the resources associated to the main source code while the test resources are associated to the test source code. - The Resources Plugin handles the copying of project resources to the output - directory. There are two different kinds of resources: main resources and test resources. The - difference is that the main resources are the resources associated to the main - source code while the test resources are associated to the test source code. +Thus, this allows the separation of resources for the main source code and its unit tests. - Thus, this allows the separation of resources for the main source code and its - unit tests. +This plugin uses the [Maven Filtering](http://maven.apache.org/shared/maven-filtering/) shared component for filtering resources. - This plugin uses the {{{http://maven.apache.org/shared/maven-filtering/}Maven Filtering}} - shared component for filtering resources. +## Goals Overview -* Goals Overview +The Resources Plugin copies files specified by Resource elements, to an output directory. The three variations below only differ in how the resource and output directory elements are specified or defaulted. The Resources Plugin has three goals: - The Resources Plugin copies files specified by Resource elements, to an output directory. The three - variations below only differ in how the resource and output directory elements are specified or defaulted. - The Resources Plugin has three goals: +- [resources:resources](./resources-mojo.html) copies the resources for the main source code to the main output directory. - * {{{./resources-mojo.html}resources:resources}} copies the - resources for the main source code to the main output directory. - - This goal usually executes automatically, because it is bound by default to the process-resources life-cycle phase. - It always uses the project.build.resources element to specify the resources, and by default uses the - project.build.outputDirectory to specify the copy destination. + This goal usually executes automatically, because it is bound by default to the process-resources life-cycle phase. It always uses the project.build.resources element to specify the resources, and by default uses the project.build.outputDirectory to specify the copy destination. - * {{{./testResources-mojo.html}resources:testResources}} copies the - resources for the test source code to the test output directory. - - This goal usually executes automatically, because it is bound by default to the process-test-resources life-cycle phase. - It always uses the project.build.testResources element to specify the resources, and by default uses the - project.build.testOutputDirectory to specify the copy destination. +- [resources:testResources](./testResources-mojo.html) copies the resources for the test source code to the test output directory. - * {{{./copy-resources-mojo.html}resources:copy-resources}} copies resources to an output directory. - - This goal requires that you configure the resources to be copied, and specify the outputDirectory. + This goal usually executes automatically, because it is bound by default to the process-test-resources life-cycle phase. It always uses the project.build.testResources element to specify the resources, and by default uses the project.build.testOutputDirectory to specify the copy destination. -* Usage +- [resources:copy-resources](./copy-resources-mojo.html) copies resources to an output directory. - General instructions on how to use the Resources Plugin can be found on the {{{./usage.html}usage page}}. Some more - specific use cases are described in the examples given below. + This goal requires that you configure the resources to be copied, and specify the outputDirectory. - In case you still have questions regarding the plugin's usage, please have a look at the {{{./faq.html}FAQ}} and feel - free to contact the {{{./mailing-lists.html}user mailing list}}. The posts to the mailing list are archived and could - already contain the answer to your question as part of an older thread. Hence, it is also worth browsing/searching - the {{{./mailing-lists.html}mail archive}}. +## Usage - If you feel like the plugin is missing a feature or has a defect, you can fill a feature request or bug report in our - {{{./issue-management.html}issue tracker}}. When creating a new issue, please provide a comprehensive description of your - concern. Especially for fixing bugs it is crucial that the developers can reproduce your problem. For this reason, - entire debug logs, POMs or most preferably little demo projects attached to the issue are very much appreciated. - Of course, patches are welcome, too. Contributors can check out the project from our - {{{./scm.html}source repository}} and will find supplementary information in the - {{{http://maven.apache.org/guides/development/guide-helping.html}guide to helping with Maven}}. +General instructions on how to use the Resources Plugin can be found on the [usage page](./usage.html). Some more specific use cases are described in the examples given below. -* Examples +In case you still have questions regarding the plugin's usage, please have a look at the [FAQ](./faq.html) and feel free to contact the [user mailing list](./mailing-lists.html). The posts to the mailing list are archived and could already contain the answer to your question as part of an older thread. Hence, it is also worth browsing/searching the [mail archive](./mailing-lists.html). - The following examples show how to use the Resources Plugin in more advanced - use cases: +If you feel like the plugin is missing a feature or has a defect, you can fill a feature request or bug report in our [issue tracker](./issue-management.html). When creating a new issue, please provide a comprehensive description of your concern. Especially for fixing bugs it is crucial that the developers can reproduce your problem. For this reason, entire debug logs, POMs or most preferably little demo projects attached to the issue are very much appreciated. Of course, patches are welcome, too. Contributors can check out the project from our [source repository](./scm.html) and will find supplementary information in the [guide to helping with Maven](http://maven.apache.org/guides/development/guide-helping.html). - * {{{./examples/encoding.html}Specifying a character encoding scheme}} +## Examples - * {{{./examples/resource-directory.html}Specifying resource directories}} +The following examples show how to use the Resources Plugin in more advanced use cases: - * {{{./examples/filter.html}Filtering}} - - * {{{./examples/include-exclude.html}Including and excluding files and directories}} - - * {{{./examples/escape-filtering.html}Escape filtering}} - - * {{{./examples/copy-resources.html}Copy resources}} - - * {{{./examples/binaries-filtering.html}Binaries filtering}} - - * {{{./examples/custom-resource-filters.html}Custom resources filters}} - - [] +- [Specifying a character encoding scheme](./examples/encoding.html) +- [Specifying resource directories](./examples/resource-directory.html) +- [Filtering](./examples/filter.html) +- [Including and excluding files and directories](./examples/include-exclude.html) +- [Escape filtering](./examples/escape-filtering.html) +- [Copy resources](./examples/copy-resources.html) +- [Binaries filtering](./examples/binaries-filtering.html) +- [Custom resources filters](./examples/custom-resource-filters.html) diff --git a/src/site/markdown/usage.md.vm b/src/site/markdown/usage.md.vm index c8b8e615..49c6ff61 100644 --- a/src/site/markdown/usage.md.vm +++ b/src/site/markdown/usage.md.vm @@ -1,77 +1,57 @@ - ------ - Usage - ------ - Franz Allan See - ------ - 2011-02-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. - -~~ NOTE: For help with the syntax of this file, see: -~~ http://maven.apache.org/doxia/references/apt-format.html - -Usage - - The Resources Plugin handles the copying of project resources to the output - directory. The following examples describe the basic usage of the Plugin. - - To handle filtering this version of Maven Resources Plugin uses - {{{http://maven.apache.org/shared/maven-filtering/index.html}Maven Filtering}} ${mavenFilteringVersion}. - - -* Copy resources for the main source code - -+-----+ -mvn resources:resources -+-----+ + +# Usage -* Copy resources for the unit tests +The Resources Plugin handles the copying of project resources to the output directory. The following examples describe the basic usage of the Plugin. -+-----+ -mvn resources:testResources -+-----+ +To handle filtering this version of Maven Resources Plugin uses [Maven Filtering](http://maven.apache.org/shared/maven-filtering/index.html) ${mavenFilteringVersion}. + +Copy resources for the main source code +--------------------------------------- - Like the first goal this goal copies resources, but this time for your test source code to your - test build output directory, as specified by the \ element. - Also, this does not affect the resources for the main source - code. +```shell +mvn resources:resources +``` + +Upon executing this command, the resources for your main source code, as specified by the <resources> element, will be copied to your main build output directory. This does not affect the resources for your test code. - Furthermore, this is bound to the <<>> phase. +Moreover, this goal is bound to the `process-resources` phase. +Copy resources for the unit tests +--------------------------------- -* Copy resources specified by a \ configuration element +```shell +mvn resources:testResources +``` -+-----+ +Like the first goal this goal copies resources, but this time for your test source code to your test build output directory, as specified by the <testResources> element. Also, this does not affect the resources for the main source code. + +Furthermore, this is bound to the `process-test-resources` phase. + +Copy resources specified by a <resources> configuration element +--------------------------------------------------------------------- + +```shell mvn resources:copy-resources -+-----+ - - Rather than using the \ or \ elements or their - defaults, this uses a \ element that is specified as part of the - plugin configuration. - - See the examples for how to configure this. See the Maven Model for - how to write \ elements. \ No newline at end of file +``` + +Rather than using the <resources> or <testResources> elements or their defaults, this uses a <resources> element that is specified as part of the plugin configuration. + +See the examples for how to configure this. See the Maven Model for how to write <resources> elements.