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 01:15:58 UTC
(maven-project-info-reports-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-project-info-reports-plugin.git
commit b3862809bd1372bd7c8dc5aebb41fbdca42d340d
Author: Sylwester Lachiewicz <sl...@apache.org>
AuthorDate: Mon Aug 10 01:45:45 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.
All four anchors are forms Doxia rewrites at render time: none of the
<faq id=...> values is a valid XML name, so DoxiaUtils.encodeId turns
'How to use developer/contributor time zone' into
#How_to_use_developer.2Fcontributor_time_zone, and drops the question
marks the questions carry but the ids do not. The <a id> elements
written here reproduce those rendered forms, not the raw attributes, so
the live deep links still resolve.
Two of them are worth pointing out because the anchor does not match the
question text: 'How to exclude SCM access info?' is served as
#How_to_exclude_SCM_anonymous_access_info, and the two 'Is it possible
to customize...' anchors end without a '.3F'.
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, and 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, so the menu entry and
the link from index.md keep working.
FML generates a [top] back-link after each answer; those are dropped
rather than hand-written. The question becomes an h3 heading instead of
a definition term. Nothing else on the page changes.
The anchors are written as <a id="...">, not <a name="...">.
maven-site-plugin 3.21.0 strips the name attribute from inline HTML, which
would silently delete every anchor on the page while the build stays green;
3.22.0 keeps it. Xhtml5BaseParser reads Attribute.ID first and only falls
back to NAME, so id= is the primary path rather than a workaround, and name
on <a> is obsolete in HTML5. Each anchor is kept on its own line: folding one
into the heading text suppresses the section's own generated id.
Generated-by: Claude Opus 5 (1M context)
---
src/site/markdown/faq.md | 77 ++++++++++++++++++++++--------------------------
1 file changed, 36 insertions(+), 41 deletions(-)
diff --git a/src/site/markdown/faq.md b/src/site/markdown/faq.md
index fe2af18..303cd11 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,43 +21,36 @@ specific language governing permissions and limitations
under the License.
-->
-<faqs xmlns="http://maven.apache.org/FML/1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/FML/1.0 http://maven.apache.org/xsd/fml-1.0.xsd" id="FAQ" title="Frequently Asked Questions">
- <part id="General">
- <faq id="Is it possible to customize the labels of the Project Reports Menu">
- <question>Is it possible to customize the labels of the Project Reports Menu?</question>
- <answer>
- <p>
- Not yet. See the related issue: <a href="https://issues.apache.org/jira/browse/MPIR-35">MPIR-35</a>
- </p>
- </answer>
- </faq>
-
- <faq id="How to exclude SCM anonymous access info">
- <question>How to exclude SCM access info?</question>
- <answer>
- <p>
- See the <a href="examples/scm-report.html#How_to_exclude_SCM_anonymous_access_info">SCM report documentation</a>.
- </p>
- </answer>
- </faq>
-
- <faq id="How to use developer/contributor time zone">
- <question>How to use developer/contributor time zone?</question>
- <answer>
- <p>
- Please refer to the <a href="http://maven.apache.org/pom.html#Developers">developer section</a> of the POM reference.
- </p>
- </answer>
- </faq>
-
- <faq id="Is it possible to customize the reports rendering">
- <question>Is it possible to customize the reports rendering?</question>
- <answer>
- <p>
- Not yet, but <a href="https://github.com/apache/maven-project-info-reports-plugin/issues/">patches</a> are always welcome!
- You could only <a href="./examples/custom-report.html">customize</a> the texts in the reports.
- </p>
- </answer>
- </faq>
- </part>
-</faqs>
+<a id="top"></a>
+
+# Frequently Asked Questions
+
+1. [Is it possible to customize the labels of the Project Reports Menu?](#Is_it_possible_to_customize_the_labels_of_the_Project_Reports_Menu)
+2. [How to exclude SCM access info?](#How_to_exclude_SCM_anonymous_access_info)
+3. [How to use developer/contributor time zone?](#How_to_use_developer.2Fcontributor_time_zone)
+4. [Is it possible to customize the reports rendering?](#Is_it_possible_to_customize_the_reports_rendering)
+
+<a id="Is_it_possible_to_customize_the_labels_of_the_Project_Reports_Menu"></a>
+
+### Is it possible to customize the labels of the Project Reports Menu?
+
+Not yet. See the related issue: [MPIR-35](https://issues.apache.org/jira/browse/MPIR-35)
+
+<a id="How_to_exclude_SCM_anonymous_access_info"></a>
+
+### How to exclude SCM access info?
+
+See the [SCM report documentation](examples/scm-report.html#How_to_exclude_SCM_anonymous_access_info).
+
+<a id="How_to_use_developer.2Fcontributor_time_zone"></a>
+
+### How to use developer/contributor time zone?
+
+Please refer to the [developer section](http://maven.apache.org/pom.html#Developers) of the POM reference.
+
+<a id="Is_it_possible_to_customize_the_reports_rendering"></a>
+
+### Is it possible to customize the reports rendering?
+
+Not yet, but [patches](https://github.com/apache/maven-project-info-reports-plugin/issues/) are always welcome!
+You could only [customize](./examples/custom-report.html) the texts in the reports.