Convert the FAQ from FML to Markdown - #1009
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. Explicit anchors keep the existing deep links working. FML routes every <faq id> through DoxiaUtils.encodeId, which rewrites an id that is not a valid XML name: a space becomes '_' and any other character becomes its dot-prefixed UTF-8 bytes, so ',' becomes .2C and '?' becomes .3F. The <a name> elements emitted here reproduce that rendered form, not the raw attribute, so the live URLs still resolve. Prose double quotes are written as " entities: flexmark's smart punctuation would otherwise turn a straight quote into a typographic one and silently change the visible text. That matches the convention already used by the Markdown pages in this estate. Verified by building the site before and after and comparing the set of anchors the generated faq.html actually serves. All 3 anchors present before are still present after (5 after, the extra ones being the ids Doxia derives from the new headings): bodyColumn question top The <head> is byte-identical, so the title and metadata are unchanged. site.xml needs no edit - maven-enforcer-plugin/src/site/fml/faq.fml and maven-enforcer-plugin/src/site/markdown/faq.md both 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. 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, continuing the estate-wide
move off the Doxia FML format.
maven-enforcer-plugin/src/site/fml/faq.fmlbecomesmaven-enforcer-plugin/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 by hand rather than with doxia-converter
FML is a FAQ-specific Doxia format (
<faqs>/<part>/<faq id=…>) with noMarkdown counterpart, and doxia-converter cannot target it: the questions come
out as link-reference syntax rather than headings, the
[top]back-links turninto links to a nonexistent
toppage, and the contents links lose their#anchors. The page is written out by hand.
Every published URL still resolves
This page has been on maven.apache.org for years and is deep-linked from blog
posts and Stack Overflow, so no fragment may change.
FML routes every
<faq id>throughDoxiaUtils.encodeId, which rewrites any idthat is not a valid XML name — a space becomes
_, and any other characterbecomes its dot-prefixed UTF-8 bytes, so
,becomes.2Cand?becomes.3F. The<a name>elements added here reproduce that rendered anchor,not the raw
id=attribute, which for several entries is not the same string.Verified by generating the site before and after the change and comparing the
set of anchors the generated
faq.htmlactually serves —id=on any elementplus
name=on any<a>. The requirement is that the before-set is a subset ofthe after-set:
The anchors carried over are:
The
<head>is byte-identical, so the page title and metadata are unchanged.site.xmlneeds no edit — both source paths render tofaq.html.Accepted rendering losses
[top]back-link after every answer; those are dropped ratherthan hand-written.
h3heading rather than a definition term, sothe answers are no longer wrapped in a
<dl>.Generated-by: Claude Opus 5 (1M context)