From afaa0d9cc8a3d03b8848b22df8267784f40722c4 Mon Sep 17 00:00:00 2001 From: Sylwester Lachiewicz Date: Mon, 10 Aug 2026 01:39:27 +0200 Subject: [PATCH 1/2] Rename the FAQ ahead of converting it 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) --- src/site/{fml/faq.fml => markdown/faq.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename src/site/{fml/faq.fml => markdown/faq.md} (100%) 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 From df43d0e2c5a94effb6f5afdd58b475398417a89c Mon Sep 17 00:00:00 2001 From: Sylwester Lachiewicz Date: Mon, 10 Aug 2026 01:39:44 +0200 Subject: [PATCH 2/2] 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 one anchor on this page is a form Doxia rewrites at render time: is not a valid XML name, so DoxiaUtils.encodeId serves it as #Why_use_antrun_and_not_the_Ant_program_itself.3F. The written here reproduces that rendered form, not the raw attribute, so the live deep link still resolves. No explicit is written for that anchor, because the h3 the question becomes already generates exactly that id from the same encodeId rule - adding one as well would emit the id twice and Doxia warns about it. The rendered page carries the anchor once, from the heading. 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 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 , not . 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 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 | 35 ++++++++++++++++------------------- 1 file changed, 16 insertions(+), 19 deletions(-) diff --git a/src/site/markdown/faq.md b/src/site/markdown/faq.md index 7aff8aa..171ff4a 100644 --- a/src/site/markdown/faq.md +++ b/src/site/markdown/faq.md @@ -1,4 +1,6 @@ - +--- +title: Frequently Asked Questions +--- - - - - Why use antrun and not the Ant program itself? - -

Maven has benefits over Ant. You can use Maven as your project - management tool. Use its maven-antrun-plugin to build your Ant - projects.

-

If you want to migrate from Ant to Maven, use this plugin first. - Then convert your Ant expressions into their Maven counterparts one by - one.

- - - - + + +# Frequently Asked Questions + +1. [Why use antrun and not the Ant program itself?](#Why_use_antrun_and_not_the_Ant_program_itself.3F) + +### Why use antrun and not the Ant program itself? + +Maven has benefits over Ant. You can use Maven as your project management tool. Use its maven-antrun-plugin to +build your Ant projects. + +If you want to migrate from Ant to Maven, use this plugin first. Then convert your Ant expressions into their +Maven counterparts one by one.