Convert the FAQ from FML to Markdown - #280
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)
This FAQ exists only on this branch: master was frozen and its FML deleted, so maven-plugin-testing-harness/src/site/fml/faq.fml here is the only source for the published page. 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. Explicit anchors keep the existing deep links working. FML routes every <faq id> through DoxiaUtils.encodeId, and the rendered anchor is not the question text: both entries here differ from what a heading alone would produce. The published anchors have no trailing .3F because the ids omit the question mark, and the second is What_kinds_of_unit_tests_are_supported - plural - while the question reads "What kind of unit tests are supported?". Neither could have been reproduced by relying on the id Doxia derives from the heading, so both are written out explicitly. They are written as <a id> rather than <a name>. maven-site-plugin 3.21.0 drops the name attribute from inline HTML anchors while 3.22.0 keeps it; this branch resolves to 3.22.0, so name would have worked here, but id is the primary path in Xhtml5BaseParser, is the correct HTML5 form, and keeps the page safe if it is ever built with an older toolchain. The metadata is the unfenced MultiMarkdown block used by every other markdown page on this branch, and carries only the title, because the FML declared only a title. Adding author or date would have introduced meta elements the published page does not currently have. Verified by building the site before and after and comparing the set of anchors the generated faq.html actually serves. All 4 anchors present before are still present after (7 after, the extra 3 being the ids Doxia derives from the new headings): What_is_a_Mojo_Testing_Harness What_kinds_of_unit_tests_are_supported bodyColumn top The <head> is byte-identical, which also confirms the metadata was parsed rather than rendered into the page. site.xml needs no edit - both source paths 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; the definition list inside the second answer is kept as real <dl> markup. 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
1 participant
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.
Converts this project's FAQ from FML to Markdown, completing the estate-wide move
off the Doxia FML format.
maven-plugin-testing-harness/src/site/fml/faq.fmlbecomesmaven-plugin-testing-harness/src/site/markdown/faq.md, in two commits:git mv, no content change, sogit log --followkeeps working;Please merge or rebase rather than squash, so the rename commit survives.
Why this targets 3.x rather than master
This FAQ exists only on this branch.
masterwas frozen and its FML deleted, sothe copy here is the only source for the published page — which is why the PR is based
on
maven-plugin-testing-3.x.Why by hand rather than with doxia-converter
FML is a FAQ-specific Doxia format (
<faqs>/<part>/<faq id=…>) with no Markdowncounterpart, and doxia-converter cannot target it: the questions come out as
link-reference syntax rather than headings, the
[top]back-links turn into links to anonexistent
toppage, and the contents links lose their#anchors.Every published URL still resolves
Both anchors on this page are load-bearing, and neither could have been produced by
letting Doxia derive an id from the heading:
What_is_a_Mojo_Testing_HarnessWhat_is_a_Mojo_Testing_Harness.3FWhat_kinds_of_unit_tests_are_supportedWhat_kind_of_unit_tests_are_supported.3FThe ids omit the question mark, so there is no trailing
.3F; and the second isplural (
kinds) while the question reads "What kind of unit tests aresupported?". Both are therefore written out explicitly, reproducing the rendered
anchor rather than the raw
id=attribute.Verified by generating the site before and after and comparing the set of anchors the
generated
faq.htmlactually serves:The
<head>is byte-identical.site.xmlneeds no edit — both source paths render tofaq.html.Two branch-specific details
Anchor form. Written as
<a id>, not<a name>. maven-site-plugin 3.21.0 drops thenameattribute from inline HTML anchors while 3.22.0 keeps it. This branch resolves to3.22.0 (via
maven-parent:49), sonamewould have worked here — butidis theprimary path in
Xhtml5BaseParser, is the correct HTML5 form, and keeps the page safe ifit is ever built with an older toolchain. The build emits no duplicate-anchor warning.
Metadata. The unfenced MultiMarkdown block, matching every other markdown page on this
branch, and carrying only the title — because the FML declared only a title. Adding
author/datelike the sibling pages would have introducedmetaelements the publishedpage does not currently have and broken the byte-identical
<head>. The effectivedoxia-module-markdownhere is 2.1.0, which accepts either form, so this is aconsistency choice rather than a constraint; it was confirmed against the generated page,
where
index.md's unfenced block parses into<head>correctly.Accepted rendering losses
[top]back-link after every answer; those are dropped rather thanhand-written.
h3heading rather than a definition term.The definition list inside the second answer is genuine, and is kept as real
<dl>markuprather than flattened into prose.
Generated-by: Claude Opus 5 (1M context)