(maven-invoker-plugin) 02/02: Convert the FAQ from FML to Markdown

[sl...@apache.org]

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-invoker-plugin.git

commit 9dbee164803169be729c3a68069cf957b5e202e6
Author: Sylwester Lachiewicz <sl...@apache.org>
AuthorDate: Mon Aug 10 02:13:16 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 4
    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 | 104 ++++++++++++++++++++++-------------------------
 1 file changed, 48 insertions(+), 56 deletions(-)

diff --git a/src/site/markdown/faq.md b/src/site/markdown/faq.md
index a8f0935..2b389b8 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,58 +21,48 @@ 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 http://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>
-         It is essential that you provide some form of integration testing for your projects and the Invoker Plugin
-         tries to make is easy for you to create integration tests for your Maven Plugins, new Lifecycles, or any other
-         type of Maven component that you've created. Currently the Invoker Plugin forks Maven to execute the specified
-         projects, but it is hoped that soon we will integrate the Maven Embedder into the mix to allow you run your
-         projects in process for great speed.
-       </p>
-     </answer>
-   </faq>
-   <faq id="question2">
-     <question>How can I assert that the build of an IT project fails?</question>
-     <answer>
-       <p>
-         Sometimes you might want to test that error conditions are properly dealt with, i.e. fail a build. To assert
-         a failure for a particular IT project, put the following setting into the properties file denoted by the
-         plugin's <a href="run-mojo.html#invokerPropertiesFile"><code>invokerPropertiesFile</code></a> parameter:
-         <i>invoker.buildResult=failure</i>.
-         Now, the failure of the IT build will be interpreted as a test success. Likewise, a successful IT build will
-         be considered a test failure.
-       </p>
-     </answer>
-   </faq>
-   <faq id="question3">
-     <question>How can I share common code between the pre-/post-build scripts?</question>
-     <answer>
-       <p>
-         If you want to avoid copy&amp;paste of lengthy code snippets within the hook scripts, you can move this code
-         into a regular Java class. More precisely, you would place this utility code somewhere in your test source
-         tree and set the plugin parameter <a href="run-mojo.html#addTestClassPath"><code>addTestClassPath</code></a>
-         to <code>true</code>. For more details, please see the example
-         <a href="examples/access-test-classes.html">Accessing Test Classes</a>.
-       </p>
-     </answer>
-   </faq>
-   <faq id="question4">
-     <question>How can I invoke multiple Maven builds on the same IT project?</question>
-     <answer>
-       <p>
-         This is not supported in the plugin configuration but rather on a per project basis by means of the invoker
-         properties. This way, you use properties like <code>invoker.goals.2</code> to configure the goals for a second
-         invocation of Maven. Have a look at the example about using
-         <a href="examples/invoker-properties.html">Invoker Properties</a>.
-       </p>
-     </answer>
-   </faq>
- </part>
-</faqs>
+<a id="top"></a>
+
+# Frequently Asked Questions
+
+1. [Why do I need to use this plugin?](#question1)
+2. [How can I assert that the build of an IT project fails?](#question2)
+3. [How can I share common code between the pre-/post-build scripts?](#question3)
+4. [How can I invoke multiple Maven builds on the same IT project?](#question4)
+
+<a id="question1"></a>
+
+### Why do I need to use this plugin?
+
+It is essential that you provide some form of integration testing for your projects and the Invoker Plugin
+tries to make is easy for you to create integration tests for your Maven Plugins, new Lifecycles, or any other
+type of Maven component that you've created. Currently the Invoker Plugin forks Maven to execute the specified
+projects, but it is hoped that soon we will integrate the Maven Embedder into the mix to allow you run your
+projects in process for great speed.
+
+<a id="question2"></a>
+
+### How can I assert that the build of an IT project fails?
+
+Sometimes you might want to test that error conditions are properly dealt with, i.e. fail a build. To assert a
+failure for a particular IT project, put the following setting into the properties file denoted by the
+plugin's [`invokerPropertiesFile`](run-mojo.html#invokerPropertiesFile) parameter:
+*invoker.buildResult=failure*. Now, the failure of the IT build will be interpreted as a test success.
+Likewise, a successful IT build will be considered a test failure.
+
+<a id="question3"></a>
+
+### How can I share common code between the pre-/post-build scripts?
+
+If you want to avoid copy&amp;paste of lengthy code snippets within the hook scripts, you can move this code
+into a regular Java class. More precisely, you would place this utility code somewhere in your test source
+tree and set the plugin parameter [`addTestClassPath`](run-mojo.html#addTestClassPath) to `true`. For more
+details, please see the example [Accessing Test Classes](examples/access-test-classes.html).
+
+<a id="question4"></a>
+
+### How can I invoke multiple Maven builds on the same IT project?
+
+This is not supported in the plugin configuration but rather on a per project basis by means of the invoker
+properties. This way, you use properties like `invoker.goals.2` to configure the goals for a second invocation
+of Maven. Have a look at the example about using [Invoker Properties](examples/invoker-properties.html).