slachiewicz opened a new pull request, #584: URL: https://github.com/apache/maven-jar-plugin/pull/584
Part of an estate-wide move of the remaining FAQ pages from FML to Markdown. ### Two commits, deliberately 1. **A pure rename**, `src/site/fml/faq.fml` -> `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. ### This supersedes #582 `faq.fml` currently writes the parameter name with Markdown backticks. FML hands an `<answer>` body to Doxia's `XdocParser`, which has no backtick handling, so the live page has been serving `` `archive` `` verbatim since the Simplified Technical English rewrite in #581. #582 fixes that by switching to `<code>`. Once the page **is** Markdown, the backticks are correct and render as `<code>` — which is the outcome #582 was after. So this PR keeps `` `archive` `` deliberately, and #582 becomes unnecessary if this is merged. The full stop that split "defined by the Maven Archiver library, not by the Maven JAR Plugin" into a sentence and a fragment is corrected here too, since it came from the same rewrite. ### Anchors are preserved `#question1` is a valid XML name, so Doxia serves it unchanged; the `<a name="question1">` written here matches the live URL exactly. ### Verification Built the site with `mvn site` before and after and compared the set of anchors the generated `faq.html` actually serves. Every anchor served before is still served after (`question1`, `top`, `bodyColumn`), plus two new heading-derived ids. `<head>` byte-identical, so title and metadata are unchanged. No link target on the page changed. `site.xml` needs no edit — FML and Markdown both render to `faq.html`, so the menu entry and the `./faq.html` link in `index.md` keep working. The one visible difference beyond markup, as intended: ``` -The `archive` parameter is defined by the Maven Archiver library. not by … +The <code>archive</code> parameter is defined by the Maven Archiver library, not by … ``` ### What is lost 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 changes. <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]
