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/09 23:52:23 UTC
(maven-war-plugin) branch faq-to-markdown created (now f40af62)
This is an automated email from the ASF dual-hosted git repository.
slachiewicz pushed a change to branch faq-to-markdown
in repository https://gitbox.apache.org/repos/asf/maven-war-plugin.git
at f40af62 Convert the FAQ from FML to Markdown
This branch includes the following new commits:
new 3ff74a0 Rename the FAQ ahead of converting it
new f40af62 Convert the FAQ from FML to Markdown
The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
(maven-war-plugin) 02/02: Convert the FAQ from FML to Markdown
Posted by sl...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
slachiewicz pushed a commit to branch faq-to-markdown
in repository https://gitbox.apache.org/repos/asf/maven-war-plugin.git
commit f40af627cd16df7886b1cbb8b502cc3feed606de
Author: Sylwester Lachiewicz <sl...@apache.org>
AuthorDate: Mon Aug 10 01:50:39 2026 +0200
Convert the FAQ from FML to Markdown
doxia-converter cannot target FML usefully - the questions come out as
link-reference syntax rather than headings, the [top] back-links become
links to a nonexistent 'top' page, and the contents links lose their #
anchors. The page is written out by hand instead.
The page stays a Velocity template: the two sample POMs interpolate
${project.version}, which renders as the current plugin version. In a
.vm file an ATX heading starting '##' is swallowed as a Velocity line
comment, so the title uses a setext underline and each question is
wrapped in #[[### ... ]]# to reach the renderer intact.
Explicit anchors keep the existing deep links working. The <a name>
emitted here reproduces the anchor the rendered page serves today, not
the raw <faq id> attribute.
Verified by building the site before and after and comparing the set of
anchors the generated faq.html actually serves. Every anchor present
before is still present after:
before: filtering, classifieruse, transitiveexclude,
dependentwarexclude, webresourcesexclude, waroverlaysexclude,
configurationdoc, attached, top, bodyColumn
after: the same ten, plus nine heading-derived ids
The <head> is byte-identical, so the title and metadata are unchanged.
site.xml needs no edit - src/site/fml/faq.fml.vm and
src/site/markdown/faq.md.vm both render to faq.html.
FML generates a [top] back-link after each answer; those are dropped
rather than hand-written. The question now renders as an h3 heading
instead of a definition term. Those are the only rendering losses.
Generated-by: Claude Opus 5 (1M context)
---
src/site/markdown/faq.md.vm | 188 ++++++++++++++++++++++++--------------------
1 file changed, 101 insertions(+), 87 deletions(-)
diff --git a/src/site/markdown/faq.md.vm b/src/site/markdown/faq.md.vm
index 19fc6f8..196474b 100644
--- a/src/site/markdown/faq.md.vm
+++ b/src/site/markdown/faq.md.vm
@@ -1,4 +1,6 @@
-<?xml version="1.0" encoding="UTF-8"?>
+---
+title: Frequently Asked Questions
+---
<!--
Licensed to the Apache Software Foundation (ASF) under one
@@ -19,17 +21,27 @@ specific language governing permissions and limitations
under the License.
-->
+<a name="top"></a>
-<faqs xmlns="http://maven.apache.org/FML/1.0.1"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/FML/1.0.1 http://maven.apache.org/xsd/fml-1.0.1.xsd"
- id="FAQ" title="Frequently Asked Questions">
- <part id="General">
- <faq id="filtering">
- <question>How is filtering done in the WAR plugin?</question>
- <answer>
- <p>To enable filtering of <code>web.xml</code> you must configure the WAR Plugin like this:
- <source><
+1. [How does the classifier of dependency artifacts affect my WAR project?](#classifieruse)
+1. [How do I exclude transitive dependencies from my project?](#transitiveexclude)
+1. [What's the difference between using dependentWarExclude and provided scope?](#dependentwarexclude)
+1. [How do I exclude files in my web resources?](#webresourcesexclude)
+1. [How do I exclude files when doing overlays?](#waroverlaysexclude)
+1. [Where can I find the documentation for the plugin's configuration?](#configurationdoc)
+1. [How do I create a JAR containing the classes in my webapp?](#attached)
+
+<a name="filtering"></a>
+
+#[[### How is filtering done in the WAR plugin?]]#
+
+To enable filtering of `web.xml` you must configure the WAR Plugin like this:
+
+```xml
<plugin>
<artifactId>maven-war-plugin</artifactId>
<version>${project.version}</version>
@@ -37,66 +49,69 @@ under the License.
<filteringDeploymentDescriptors>true</filteringDeploymentDescriptors>
</configuration>
</plugin>
-]]></source>
- </p>
- <p>Examples can be found <a href="examples/adding-filtering-webresources.html">here</a>.</p>
- </answer>
- </faq>
- <faq id="classifieruse">
- <question>How does the classifier of dependency artifacts affect my WAR project?</question>
- <answer>
- <p>When used, the copy of the dependency artifact in your project will have the classifier appended to its
- filename. This can be used to differentiate duplicate artifacts.</p>
- </answer>
- </faq>
- <faq id="transitiveexclude">
- <question>How do I exclude transitive dependencies from my project?</question>
- <answer>
- <p>Give it a "provided" scope.</p>
- </answer>
- </faq>
- <faq id="dependentwarexclude">
- <question>What's the difference between using dependentWarExclude and provided scope?</question>
- <answer>
- <p><code>dependentWarExclude</code> is used in <a href="overlays.html">overlays</a> for excluding dependent
- WAR files from the assembled webapp.</p>
- </answer>
- </faq>
- <faq id="webresourcesexclude">
- <question>How do I exclude files in my web resources?</question>
- <answer>
- <p>Use the <code><webResources></code> / <code><exclude></code> parameter to identify the tokens to exclude.</p>
- <p>For more information refer to <a href="examples/adding-filtering-webresources.html">Adding and Filtering
- External Web Resources</a>.</p>
- </answer>
- </faq>
- <faq id="waroverlaysexclude">
- <question>How do I exclude files when doing overlays?</question>
- <answer>
- <p>Use the <code>dependentWarExcludes</code> parameter to identify the tokens to exclude.</p>
- </answer>
- </faq>
- <faq id="configurationdoc">
- <question>Where can I find the documentation for the plugin's configuration?</question>
- <answer>
- <p>
- For each goal, you can use the documentation from the <a href="plugin-info.html">plugin site</a>.
- </p>
- <p>
- If you need a specific version, generate it using <code>mvn site:site</code> or use:
- <source><.
+
+<a name="classifieruse"></a>
+
+#[[### How does the classifier of dependency artifacts affect my WAR project?]]#
+
+When used, the copy of the dependency artifact in your project will have the
+classifier appended to its filename. This can be used to differentiate
+duplicate artifacts.
+
+<a name="transitiveexclude"></a>
+
+#[[### How do I exclude transitive dependencies from my project?]]#
+
+Give it a "provided" scope.
+
+<a name="dependentwarexclude"></a>
+
+#[[### What's the difference between using dependentWarExclude and provided scope?]]#
+
+`dependentWarExclude` is used in [overlays](overlays.html) for excluding
+dependent WAR files from the assembled webapp.
+
+<a name="webresourcesexclude"></a>
+
+#[[### How do I exclude files in my web resources?]]#
+
+Use the `<webResources>` / `<exclude>` parameter to identify the tokens to
+exclude.
+
+For more information refer to [Adding and Filtering External Web
+Resources](examples/adding-filtering-webresources.html).
+
+<a name="waroverlaysexclude"></a>
+
+#[[### How do I exclude files when doing overlays?]]#
+
+Use the `dependentWarExcludes` parameter to identify the tokens to exclude.
+
+<a name="configurationdoc"></a>
+
+#[[### Where can I find the documentation for the plugin's configuration?]]#
+
+For each goal, you can use the documentation from the [plugin
+site](plugin-info.html).
+
+If you need a specific version, generate it using `mvn site:site` or use:
+
+```
mvn help:describe -Dplugin=war -Dfull=true -Dversion=<your-plugin-version-here>
-]]></source>
- </p>
- </answer>
- </faq>
- <faq id="attached">
- <question>How do I create a JAR containing the classes in my webapp?</question>
- <answer>
- <p>If you would simply like to package the classes and resources as a JAR in <code>WEB-INF/lib</code>
- rather than as loose files under <code>WEB-INF/classes</code>, use the following configuration:</p>
- <p>
- <source><![CDATA[
+```
+
+<a name="attached"></a>
+
+#[[### How do I create a JAR containing the classes in my webapp?]]#
+
+If you would simply like to package the classes and resources as a JAR in
+`WEB-INF/lib` rather than as loose files under `WEB-INF/classes`, use the
+following configuration:
+
+```xml
<plugin>
<artifactId>maven-war-plugin</artifactId>
<version>${project.version}</version>
@@ -104,15 +119,18 @@ mvn help:describe -Dplugin=war -Dfull=true -Dversion=<your-plugin-version-here>
<archiveClasses>true</archiveClasses>
</configuration>
</plugin>
-]]></source>
- </p>
- <p>If you need to re-use this JAR in another project, the recommended approach is to move the classes to a
- separate module that builds a JAR, and then declare a dependency on that JAR from your webapp as well as from
- any other projects that need it.</p>
- <p>If you can't move the classes to another project, you can deploy the classes and resources included in
- your webapp as an "attached" artifact, with a classifier, by using the following configuration:</p>
- <p>
- <source><![CDATA[
+```
+
+If you need to re-use this JAR in another project, the recommended approach is
+to move the classes to a separate module that builds a JAR, and then declare a
+dependency on that JAR from your webapp as well as from any other projects that
+need it.
+
+If you can't move the classes to another project, you can deploy the classes and
+resources included in your webapp as an "attached" artifact, with a classifier,
+by using the following configuration:
+
+```xml
<project>
...
<artifactId>mywebapp</artifactId>
@@ -131,11 +149,7 @@ mvn help:describe -Dplugin=war -Dfull=true -Dversion=<your-plugin-version-here>
</build>
...
</project>
-]]></source>
- </p>
- <p>This will result in two artifacts being deployed: <code>mywebapp-1.0-SNAPSHOT.war</code>
- and <code>mywebapp-1.0-SNAPSHOT-classes.jar</code>.</p>
- </answer>
- </faq>
- </part>
-</faqs>
\ No newline at end of file
+```
+
+This will result in two artifacts being deployed:
+`mywebapp-1.0-SNAPSHOT.war` and `mywebapp-1.0-SNAPSHOT-classes.jar`.
(maven-war-plugin) 01/02: Rename the FAQ ahead of converting it
Posted by sl...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
slachiewicz pushed a commit to branch faq-to-markdown
in repository https://gitbox.apache.org/repos/asf/maven-war-plugin.git
commit 3ff74a083f3d15c4575112e770504df12b0a855b
Author: Sylwester Lachiewicz <sl...@apache.org>
AuthorDate: Mon Aug 10 01:44:35 2026 +0200
Rename the FAQ ahead of converting it
Git records a rename plus a rewrite in one commit as a delete and an
add, which stops 'git log --follow'. Splitting the rename out keeps the
history. Please merge or rebase rather than squash.
Generated-by: Claude Opus 5 (1M context)
---
src/site/{fml/faq.fml.vm => markdown/faq.md.vm} | 0
1 file changed, 0 insertions(+), 0 deletions(-)
diff --git a/src/site/fml/faq.fml.vm b/src/site/markdown/faq.md.vm
similarity index 100%
rename from src/site/fml/faq.fml.vm
rename to src/site/markdown/faq.md.vm