(maven-rar-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-rar-plugin.git

commit 6f7dd53efee867687524bcec2d7fd1a73570141d
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.
    
    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, which FML rewrites whenever it is not a
    valid XML name.
    
    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: question, top, bodyColumn
      after:  the same three, plus two 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 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. 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 | 61 +++++++++++++++++++++++-------------------------
 1 file changed, 29 insertions(+), 32 deletions(-)

diff --git a/src/site/markdown/faq.md b/src/site/markdown/faq.md
index 80aed78..8011507 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,34 +21,29 @@ 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="question">
-     <question>Is the rar file generated by the maven-rar-plugin the same as the rar file(compressed file) of WinRar?</question>
-     <answer>
-       <p>
-            No. They are entirely different from each other.
-       </p>
-       <p>
-            A Resource Adapter Archive (RAR) file is a Java archive (JAR) file used to package a resource adapter for the Java 2 Connector (J2C) Architecture.
-            <br/>
-            <br/>
-            An RAR file can contain the following:
-       </p>
-      <ul>
-        <li>Enterprise information system (EIS) supplied resource adapter implementation code in the form of JAR files or other runnable components, such as dynamic link lists.</li>
-        <li>Utility classes.</li>
-        <li>Static documents, such as HTML files, images, and sound files.</li>
-      </ul>
-       <p>
-            RAR (Roshal ARchive) is the native format of WinRAR archiver. Like other archives, RAR files
-            are data containers. They store one or several files in the compressed form.
-            After you download an RAR file from Internet, you need to unpack its contents in order to use it.
-       </p>
-     </answer>
-   </faq>
- </part>
-</faqs>
+<a name="top"></a>
+
+# Frequently Asked Questions
+
+1. [Is the rar file generated by the maven-rar-plugin the same as the rar file(compressed file) of WinRar?](#question)
+
+<a name="question"></a>
+
+### Is the rar file generated by the maven-rar-plugin the same as the rar file(compressed file) of WinRar?
+
+No. They are entirely different from each other.
+
+A Resource Adapter Archive (RAR) file is a Java archive (JAR) file used to package a
+resource adapter for the Java 2 Connector (J2C) Architecture.
+
+An RAR file can contain the following:
+
+- Enterprise information system (EIS) supplied resource adapter implementation code
+  in the form of JAR files or other runnable components, such as dynamic link lists.
+- Utility classes.
+- Static documents, such as HTML files, images, and sound files.
+
+RAR (Roshal ARchive) is the native format of WinRAR archiver. Like other archives,
+RAR files are data containers. They store one or several files in the compressed
+form. After you download an RAR file from Internet, you need to unpack its contents
+in order to use it.