Repository navigation
Convert the FAQ from FML to Markdown - #3423
Merged
Merged
Conversation
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)
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 ten <faq id=...> values are valid XML names, so Doxia serves them unchanged and the <a name> elements written here match the live URLs exactly. #dumpfiles matters beyond the live site: examples/shutdown.apt.vm links to ../faq.html#dumpfiles from inside this module. 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.apt.vm keep working. Two answers were already written in Markdown inside the FML and were being served verbatim, because FML hands an <answer> body to Doxia's XdocParser, which has no Markdown handling. The GWT answer's [gwt-maven-plugin](https://gwt-maven-plugin.github.io/gwt-maven-plugin/) now renders as the link it was always meant to be. 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. The GWT answer's CDATA-wrapped configuration snippet and the dump-file name list become fenced code blocks rather than <code> runs separated by <br/>, and the two <pre>${...}</pre> fragments in the late-property-evaluation answer become inline code so they no longer break the sentence into three blocks. ${...} and @{...} stay literal: src/site/markdown/faq.md is not a .vm file, so Velocity does not run over it, exactly as it did not run over the FML. Generated-by: Claude Opus 5 (1M context)
slachiewicz
marked this pull request as ready for review
August 10, 2026 00:07
slachiewicz
added a commit
that referenced
this pull request
Aug 10, 2026
Follow-up to #3423, which converted the FAQ from FML to Markdown and is already merged. Two defects in that page, one visible to readers. flexmark enables smart-punctuation, so a straight double quote in Markdown prose is rendered as a typographic quote. FML went through XdocParser, which does no such rewriting, so the page had straight quotes for years. Twenty-two of them changed appearance when the page became Markdown: the forked-VM message, "extraordinary", "jar", "classesDirectory", "${project.build.outputDirectory}", the corrupted-channel warning and both occurrences of "enableProcessChecker". They are written as " here, which is the convention the already-converted maven-site-plugin pages use for the same reason. Quotes inside code spans and fenced blocks are untouched; smart-punctuation never applied to those. The anchors also move from <a name="..."> to <a id="...">. This module is safe either way today, because the root pom pins maven-site-plugin 3.22.0 explicitly rather than inheriting it from maven-parent 47, and 3.22.0 preserves the name attribute. 3.21.0 strips it, which would delete every anchor on the page while the build stayed green. Since the pin is the only thing standing between this page and that outcome, and since Xhtml5BaseParser reads Attribute.ID first and only falls back to NAME - and name on <a> is obsolete in HTML5 - id is the form to be holding. Verified by building maven-surefire-plugin's site and comparing the rendered page against the FML original from before #3423. All ten anchors plus #top still served, <head> byte-identical, no duplicate-id warnings, and no typographic quotes left in the visible text. Note for anyone rebuilding this locally: the reactor does not build on JDK 26. sisu-maven-plugin 0.9.0.M4 fails on maven-surefire-common with "Unsupported class file major version 70". JDK 21 works. Generated-by: Claude Opus 5 (1M context)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Part of an estate-wide move of the remaining FAQ pages from FML to Markdown. Touches only
maven-surefire-plugin/src/site/fml/faq.fml; no overlap with the APT→Markdown work in #3422.Two commits, deliberately
maven-surefire-plugin/src/site/fml/faq.fml->maven-surefire-plugin/src/site/markdown/faq.md, no content change.Git records a rename plus a rewrite in a single commit as a delete and an add, which stops
git log --follow. Splitting them keeps the history. Please merge or rebase rather than squash.Why by hand
doxia-converter cannot target FML: the questions come out as link-reference syntax rather than headings, the
[top]back-links become links to a nonexistenttoppage, and the contents links lose their#anchors.Anchors are preserved, and that is the point
This page has been on maven.apache.org for years and is linked from outside. All ten
<faq id=…>values are valid XML names, so Doxia serves them unchanged and the<a name>elements written here match the live URLs exactly.#dumpfilesalso has an in-repo caller:examples/shutdown.apt.vmlinks to../faq.html#dumpfiles.Two answers were already Markdown, and were being served verbatim
FML hands an
<answer>body to Doxia'sXdocParser, which has no Markdown handling. The GWT answer's[gwt-maven-plugin](https://gwt-maven-plugin.github.io/gwt-maven-plugin/)has been rendering as literal square brackets on the live page. Now that the page is Markdown it becomes the link it was always meant to be.Verification
Built the site with
mvn sitebefore and after and compared the set of anchors the generatedfaq.htmlactually serves. All ten plus#topare still served;<head>byte-identical, so title and metadata are unchanged.site.xmlneeds no edit — FML and Markdown both render tofaq.html, so the menu entry and the./faq.htmllink inindex.apt.vmkeep working.${...}and@{...}stay literal:src/site/markdown/faq.mdis not a.vmfile, so Velocity does not run over it — exactly as it did not run over the FML.What is lost, and what changes shape
FML generates a
[top]back-link after each answer. Those are dropped rather than hand-written. The question becomes anh3heading instead of a definition term.Two answers change shape for the better rather than being transcribed literally:
<code>runs separated by<br/>inside CDATA; they become fenced code blocks;<pre>${...}</pre>fragments in thelate-property-evaluationanswer were breaking one sentence into three blocks; they become inline code.Drafted with Claude — please verify