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

commit 08e628d98a656995e6878511faa81542cf021388
Author: Sylwester Lachiewicz <sl...@apache.org>
AuthorDate: Mon Aug 10 02:03:00 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. FML routes every
    <faq id> through DoxiaUtils.encodeId, which rewrites an id that is not a
    valid XML name: a space becomes '_' and any other character becomes its
    dot-prefixed UTF-8 bytes, so ',' becomes .2C and '?' becomes .3F. The
    <a name> elements emitted here reproduce that rendered form, not the raw
    attribute, so the live URLs still resolve.
    
    Verified by building the site before and after and comparing the set of
    anchors the generated faq.html actually serves. All 3 anchors present
    before are still present after (5 after, the extra ones being the ids
    Doxia derives from the new headings):
    
      bodyColumn
      question
      top
    
    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 renders as an h3 heading rather
    than a definition term. Those are the only rendering losses.
    
    Generated-by: Claude Opus 5 (1M context)
---
 src/site/markdown/faq.md | 31 ++++++++++++++-----------------
 1 file changed, 14 insertions(+), 17 deletions(-)

diff --git a/src/site/markdown/faq.md b/src/site/markdown/faq.md
index e94afa9..a32002a 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,20 +21,15 @@ 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="question">
-     <question>Can I use the <i>install:install-file</i> goal to install artifacts to my remote repository?</question>
-     <answer>
-       <p>
-            No. You need to use
-            <a href="http://maven.apache.org/plugins/maven-deploy-plugin/"><i>deploy:deploy-file</i></a> instead.
-       </p>
-     </answer>
-   </faq>
- </part>
-</faqs>
+# Frequently Asked Questions
+
+1. [Can I use the *install:install-file* goal to install artifacts to my remote repository?](#question)
+
+<a name="question"></a>
+
+### Can I use the *install:install-file* goal to install artifacts to my remote repository?
+
+No. You need to use
+[*deploy:deploy-file*](http://maven.apache.org/plugins/maven-deploy-plugin/) instead.