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:25 UTC
(maven-war-plugin) 02/02: Convert the FAQ from FML to Markdown
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`.