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 00:26:17 UTC
(maven-jxr) branch master updated (42d0a70 -> 3b03104)
This is an automated email from the ASF dual-hosted git repository.
slachiewicz pushed a change to branch master
in repository https://gitbox.apache.org/repos/asf/maven-jxr.git
from 42d0a70 Restore the document metadata dropped when the pages were ported
new 47ffa50 Rename the FAQs ahead of converting them
new 3b03104 Convert the FAQs from FML to Markdown
The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
maven-jxr-plugin/src/site/fml/faq.fml | 38 -------------------
.../aggregate/p2/pom.xml => site/markdown/faq.md} | 31 +++++++--------
src/site/fml/faq.fml | 44 ----------------------
.../p2/pom.xml => src/site/markdown/faq.md | 39 ++++++++++---------
4 files changed, 36 insertions(+), 116 deletions(-)
delete mode 100644 maven-jxr-plugin/src/site/fml/faq.fml
copy maven-jxr-plugin/src/{it/aggregate/p2/pom.xml => site/markdown/faq.md} (57%)
delete mode 100644 src/site/fml/faq.fml
copy maven-jxr-plugin/src/it/aggregate/p2/pom.xml => src/site/markdown/faq.md (57%)
(maven-jxr) 02/02: Convert the FAQs from FML to Markdown
Posted by 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-jxr.git
commit 3b0310484d052310e9c692245a1f19489f6c407a
Author: Sylwester Lachiewicz <sl...@apache.org>
AuthorDate: Mon Aug 10 02:08:13 2026 +0200
Convert the FAQs from FML to Markdown
This repository carries two separate FAQ pages, one for the library and
one for the plugin. Both are converted; they are independent pages with
independent anchor sets and were verified separately.
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 pages are 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 .3F. The <a name> elements
emitted here reproduce that rendered form, not the raw attribute, so the
live URLs still resolve. maven-jxr-plugin's single entry is one of those
cases: the id ends in a question mark and is served as
Is_there_a_way_to_run_JXR_with_an_Ant_build.3F, not as the raw string.
Verified by building the site before and after and comparing the set of
anchors each generated faq.html actually serves.
src/site/fml/faq.fml -> src/site/markdown/faq.md
all 4 anchors present before are still present after (7 after):
Is_an_Ant_task_available
Is_it_possible_to_convert_other_source_files_than_Java_to_HTML
bodyColumn
top
maven-jxr-plugin/src/site/fml/faq.fml -> maven-jxr-plugin/src/site/markdown/faq.md
all 3 anchors present before are still present after (4 after):
Is_there_a_way_to_run_JXR_with_an_Ant_build.3F
bodyColumn
top
Both <head> elements are byte-identical, so titles and metadata are
unchanged. Neither site.xml needs an edit - the fml and markdown source
paths 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.
Anchors are written as <a id>, not <a name>: maven-site-plugin 3.21.0 drops
the name attribute from inline HTML anchors while 3.22.0 keeps it, and
Xhtml5BaseParser reads Attribute.ID first and only falls back to NAME. id is
the primary path and the correct HTML5 form; name on <a> is obsolete.
An explicit anchor is emitted only where it is actually needed. Doxia already
derives an id for each heading, and where that derived id is byte-identical to
the anchor the site serves today, a second explicit anchor would only produce a
duplicate id and a "used more than once" warning. Those are omitted; the
heading serves the URL. That is the case for the plugin FAQ's single entry,
whose FML id already ends in the question mark; the library FAQ's two entries
keep their explicit anchors because their ids drop it.
Generated-by: Claude Opus 5 (1M context)
---
maven-jxr-plugin/src/site/markdown/faq.md | 29 +++++++++-----------
src/site/markdown/faq.md | 45 +++++++++++++++----------------
2 files changed, 33 insertions(+), 41 deletions(-)
diff --git a/maven-jxr-plugin/src/site/markdown/faq.md b/maven-jxr-plugin/src/site/markdown/faq.md
index b6335bd..4b7be61 100644
--- a/maven-jxr-plugin/src/site/markdown/faq.md
+++ b/maven-jxr-plugin/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,13 @@ specific language governing permissions and limitations
under the License.
-->
+<a id="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="Is there a way to run JXR with an Ant build?">
- <question>Is there a way to run JXR with an Ant build?</question>
- <answer>
- <p>
- There isn't currently an Ant task, but it is a separate library so it
- wouldn't be hard to write one if someone was willing to contribute it.
- </p>
- </answer>
- </faq>
- </part>
-</faqs>
\ No newline at end of file
+# Frequently Asked Questions
+
+1. [Is there a way to run JXR with an Ant build?](#Is_there_a_way_to_run_JXR_with_an_Ant_build.3F)
+
+### Is there a way to run JXR with an Ant build?
+
+There isn't currently an Ant task, but it is a separate library so it
+wouldn't be hard to write one if someone was willing to contribute it.
diff --git a/src/site/markdown/faq.md b/src/site/markdown/faq.md
index 11d2e70..6042a7b 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,26 +21,21 @@ 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="Is it possible to convert other source files than Java to HTML">
- <question>Is it possible to convert other source files than Java to HTML?</question>
- <answer>
- <p>
- Not yet but it is on the roadmap.
- </p>
- </answer>
- </faq>
- <faq id="Is an Ant task available">
- <question>Is an Ant task available?</question>
- <answer>
- <p>
- Not yet. Patches are always welcome!
- </p>
- </answer>
- </faq>
- </part>
-</faqs>
\ No newline at end of file
+<a id="top"></a>
+
+# Frequently Asked Questions
+
+1. [Is it possible to convert other source files than Java to HTML?](#Is_it_possible_to_convert_other_source_files_than_Java_to_HTML)
+2. [Is an Ant task available?](#Is_an_Ant_task_available)
+
+<a id="Is_it_possible_to_convert_other_source_files_than_Java_to_HTML"></a>
+
+### Is it possible to convert other source files than Java to HTML?
+
+Not yet but it is on the roadmap.
+
+<a id="Is_an_Ant_task_available"></a>
+
+### Is an Ant task available?
+
+Not yet. Patches are always welcome!
(maven-jxr) 01/02: Rename the FAQs ahead of converting them
Posted by 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-jxr.git
commit 47ffa5031cfd79ef25ac8bf15e659a171c5a285e
Author: Sylwester Lachiewicz <sl...@apache.org>
AuthorDate: Mon Aug 10 01:57:40 2026 +0200
Rename the FAQs ahead of converting them
Git records a rename plus a rewrite in one commit as a delete and an
add, which stops 'git log --follow'. Splitting the rename out keeps the
history. Please merge or rebase rather than squash.
Generated-by: Claude Opus 5 (1M context)
---
maven-jxr-plugin/src/site/{fml/faq.fml => markdown/faq.md} | 0
src/site/{fml/faq.fml => markdown/faq.md} | 0
2 files changed, 0 insertions(+), 0 deletions(-)
diff --git a/maven-jxr-plugin/src/site/fml/faq.fml b/maven-jxr-plugin/src/site/markdown/faq.md
similarity index 100%
rename from maven-jxr-plugin/src/site/fml/faq.fml
rename to maven-jxr-plugin/src/site/markdown/faq.md
diff --git a/src/site/fml/faq.fml b/src/site/markdown/faq.md
similarity index 100%
rename from src/site/fml/faq.fml
rename to src/site/markdown/faq.md