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/10 00:24:44 UTC
(maven-remote-resources-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 master
in repository https://gitbox.apache.org/repos/asf/maven-remote-resources-plugin.git
commit 330445cc00a7bfc94484538c3231afdde0b3761d
Author: Sylwester Lachiewicz <sl...@apache.org>
AuthorDate: Mon Aug 10 02:11:32 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.
Explicit <a id> anchors keep the existing deep links working. All 2
still resolve. Where an id was not a valid XML name, Doxia rewrote it at
render time via DoxiaUtils.encodeId; the anchors written here reproduce
that rendered form, not the raw 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, the <head> is byte-identical, and every
link target on the page is unchanged.
site.xml needs no edit: src/site/fml/faq.fml and
src/site/markdown/faq.md both render to faq.html.
FML generates a [top] back-link after each answer; those are dropped
rather than hand-written, which is the only rendering loss.
Generated-by: Claude Opus 5 (1M context)
---
src/site/markdown/faq.md | 116 ++++++++++++++++++++++-------------------------
1 file changed, 54 insertions(+), 62 deletions(-)
diff --git a/src/site/markdown/faq.md b/src/site/markdown/faq.md
index 1580344..103ba9c 100644
--- a/src/site/markdown/faq.md
+++ b/src/site/markdown/faq.md
@@ -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,64 +21,54 @@ specific language governing permissions and limitations
under the License.
-->
-<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 https://maven.apache.org/xsd/fml-1.0.1.xsd"
- id="FAQ" title="Frequently Asked Questions">
- <part id="General">
- <faq id="question1">
- <question>Why do I need to use this plugin?</question>
- <answer>
- <p>
- This plugin greatly reduces the pain associated with consistent packaging concerns across
- a large set of projects, or an entire organization. Any project can specify the use of a
- remote resource bundle and have the resources incorporated into their packaging. This means
- that you can create standard settings in a parent POM somewhere in the project hierarchy and
- have all projects use packaged common resources in a standard way like licenses, other legal
- notices and disclaimers, or anything else that may be common.
- </p>
- </answer>
- </faq>
- <faq id="question2">
- <question>The generated files have a lot of missing information. Looking at the POMs from
- the dependencies, the information isn't there either. What can I do?</question>
- <answer>
- <p>
- There are two solutions:
- </p>
- <ol>
- <li>
- File bugs with the projects that produced those artifacts to get them to fix them.
- </li>
- <li>
- Use a supplemental data file. You can create a file that contains the missing metadata.
- For example:
- <source><![CDATA[
- <supplementalDataModels>
- <supplement>
- <project>
- <groupId>com.sun.xml.bind</groupId>
- <artifactId>jaxb-impl</artifactId>
- <name>Sun JAXB Reference Implementation Runtime</name>
- <organization>
- <name>Sun Microsystems</name>
- <url>http://www.sun.com/</url>
- </organization>
- <licenses>
- <license>
- <name>COMMON DEVELOPMENT AND DISTRIBUTION LICENSE (CDDL) Version 1.0</name>
- <url>https://oss.oracle.com/licenses/CDDL</url>
- </license>
- </licenses>
- </project>
- </supplement>
- </supplementalDataModels>]]>
- </source>
- That location of that file can then be configured with the
- <code>supplementalModels</code> configuration element for the <code>process</code> goal. The
- supplemental information is merged with the information provided from the repository.
- </li>
- </ol>
- </answer>
- </faq>
- </part>
-</faqs>
+<a id="top"></a>
+
+# Frequently Asked Questions
+
+1. [Why do I need to use this plugin?](#question1)
+2. [The generated files have a lot of missing information. Looking at the POMs from the dependencies, the information isn't there either. What can I do?](#question2)
+
+<a id="question1"></a>
+
+### Why do I need to use this plugin?
+
+This plugin greatly reduces the pain associated with consistent packaging concerns across a large set of
+projects, or an entire organization. Any project can specify the use of a remote resource bundle and have the
+resources incorporated into their packaging. This means that you can create standard settings in a parent POM
+somewhere in the project hierarchy and have all projects use packaged common resources in a standard way like
+licenses, other legal notices and disclaimers, or anything else that may be common.
+
+<a id="question2"></a>
+
+### The generated files have a lot of missing information. Looking at the POMs from the dependencies, the information isn't there either. What can I do?
+
+There are two solutions:
+
+1. File bugs with the projects that produced those artifacts to get them to fix them.
+2. Use a supplemental data file. You can create a file that contains the missing metadata. For example:
+
+ ```xml
+ <supplementalDataModels>
+ <supplement>
+ <project>
+ <groupId>com.sun.xml.bind</groupId>
+ <artifactId>jaxb-impl</artifactId>
+ <name>Sun JAXB Reference Implementation Runtime</name>
+ <organization>
+ <name>Sun Microsystems</name>
+ <url>http://www.sun.com/</url>
+ </organization>
+ <licenses>
+ <license>
+ <name>COMMON DEVELOPMENT AND DISTRIBUTION LICENSE (CDDL) Version 1.0</name>
+ <url>https://oss.oracle.com/licenses/CDDL</url>
+ </license>
+ </licenses>
+ </project>
+ </supplement>
+ </supplementalDataModels>
+ ```
+
+ That location of that file can then be configured with the `supplementalModels` configuration element for
+ the `process` goal. The supplemental information is merged with the information provided from the
+ repository.