slachiewicz opened a new pull request, #3423: URL: https://github.com/apache/maven-surefire/pull/3423
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 1. **A pure rename**, `maven-surefire-plugin/src/site/fml/faq.fml` -> `maven-surefire-plugin/src/site/markdown/faq.md`, no content change. 2. **The rewrite**, written by hand. 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 nonexistent `top` page, 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. `#dumpfiles` also has an in-repo caller: `examples/shutdown.apt.vm` links to `../faq.html#dumpfiles`. ### Two answers were already Markdown, and were being served verbatim 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/)` 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 site` before and after and compared the set of anchors the generated `faq.html` actually serves. All ten plus `#top` are still served; `<head>` byte-identical, so title and metadata are unchanged. `site.xml` needs no edit — FML and Markdown both render to `faq.html`, so the menu entry and the `./faq.html` link in `index.apt.vm` keep working. `${...}` 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. ### 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 an `h3` heading instead of a definition term. Two answers change shape for the better rather than being transcribed literally: * the GWT configuration snippet and the dump-file name list were `<code>` runs separated by `<br/>` inside CDATA; they become fenced code blocks; * the two `<pre>${...}</pre>` fragments in the `late-property-evaluation` answer were breaking one sentence into three blocks; they become inline code. <sub>Drafted with Claude — please verify</sub> -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
