Convert the FAQ from FML to Markdown - #418
Closed
slachiewicz wants to merge 2 commits into
Closed
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. Neither <faq id=...> value is a valid XML name, so DoxiaUtils.encodeId rewrites both at render time: 'What is a Mojo' survives as #What_is_a_Mojo, and the second becomes #Why_mvn_help.3Aactive-profiles_won.27t_show_the_active_profiles_under_Maven_2.1 - note that it ends at '2.1' with no '.3F', because the id carries no question mark even though the question does. The <a name> elements written here reproduce those rendered forms, not the raw attributes, so the live deep links still resolve. The first question needs no explicit <a name>: the h3 it becomes already generates #What_is_a_Mojo from the same encodeId rule, so writing one as well would emit the id twice and Doxia warns about it. The second does need one, because the heading would generate a trailing '.3F' the live anchor does not have. 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 keeps working. 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 on the page changes. Generated-by: Claude Opus 5 (1M context)
Member
Author
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.
Part of an estate-wide move of the remaining FAQ pages from FML to Markdown.
Two commits, deliberately
src/site/fml/faq.fml->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
FML derives its anchor from the
<faq id=…>attribute, and where that attribute is not a valid XML nameDoxiaUtils.encodeIdrewrites it at render time. Neither id here is a valid XML name. The second one is worth a look::became.3A,'became.27, and it ends at2.1with no.3F— theidnever carried the question mark the question does. The<a name>written here reproduces that rendered form, not the raw attribute.Verification
Built the site with
mvn sitebefore and after and compared the set of anchors the generatedfaq.htmlactually serves. Every anchor served before is still served after;<head>byte-identical, so title and metadata are unchanged.site.xmlneeds no edit — FML and Markdown both render tofaq.html, so the menu entry keeps working.What is lost
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. Nothing else changes.Drafted with Claude — please verify