(maven-ejb-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 faq-to-markdown
in repository https://gitbox.apache.org/repos/asf/maven-ejb-plugin.git

commit 90025ff53f000c9ddc21016dc51dd992f3e7035d
Author: Sylwester Lachiewicz <sl...@apache.org>
AuthorDate: Mon Aug 10 01:58:43 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 sample POM interpolates
    ${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. FML renders
    <faq id="How can I specify a Class-Path: entry in the manifest of an EJB
    jar?"> as #How_can_I_specify_a_Class-Path.3A_entry_in_the_manifest_of_
    an_EJB_jar.3F, because DoxiaUtils.encodeId rewrites an id that is not a
    valid XML name. The <a name> emitted here reproduces that rendered form,
    not the raw attribute, so the live URL still resolves - note the
    question text says "EJB JAR" where the id says "EJB jar", so the
    heading-derived anchor is not the same string.
    
    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: How_can_I_specify_a_Class-Path.3A_entry_in_the_manifest_of_
              an_EJB_jar.3F, classifieruse, top, bodyColumn
      after:  the same four, plus three 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 | 60 +++++++++++++++++++++++----------------------
 1 file changed, 31 insertions(+), 29 deletions(-)

diff --git a/src/site/markdown/faq.md.vm b/src/site/markdown/faq.md.vm
index 8ae9d02..6e82885 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,19 +21,22 @@ 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="How can I specify a Class-Path: entry in the manifest of an EJB jar?">
-      <question>How can I specify a Class-Path: entry in the manifest of an EJB JAR?</question>
-      <answer>
-        <p>
-          You just have to configure it:
-          <source>
-<![CDATA[<project>
+Frequently Asked Questions
+==========================
+
+1. [How can I specify a Class-Path: entry in the manifest of an EJB JAR?](#How_can_I_specify_a_Class-Path.3A_entry_in_the_manifest_of_an_EJB_jar.3F)
+1. [How does the classifier affect artifacts in my EJB project?](#classifieruse)
+
+<a name="How_can_I_specify_a_Class-Path.3A_entry_in_the_manifest_of_an_EJB_jar.3F"></a>
+
+#[[### How can I specify a Class-Path: entry in the manifest of an EJB JAR?]]#
+
+You just have to configure it:
+
+```xml
+<project>
   ...
   <build>
     <plugins>
@@ -52,19 +57,16 @@ under the License.
     </plugins>
   </build>
   ...
-</project>]]>
-          </source>
-Please see the <a href="/shared/maven-archiver/examples/classpath.html">Maven Archiver Reference</a>
-for more information about controlling the exact format of the generated class path entries.
-        </p>
-      </answer>
-    </faq>
-   <faq id="classifieruse">
-     <question>How does the classifier affect artifacts in my EJB project?</question>
-     <answer>
-       <p>When used, the copy of the artifact in your project will have the classifier appended to its
-       filename. This can be used to differentiate multiple artifacts.</p>
-     </answer>
-   </faq>
-  </part>
-</faqs>
\ No newline at end of file
+</project>
+```
+
+Please see the [Maven Archiver Reference](/shared/maven-archiver/examples/classpath.html)
+for more information about controlling the exact format of the generated class path
+entries.
+
+<a name="classifieruse"></a>
+
+#[[### How does the classifier affect artifacts in my EJB project?]]#
+
+When used, the copy of the artifact in your project will have the classifier appended
+to its filename. This can be used to differentiate multiple artifacts.