Convert the FAQ from FML to Markdown and fix its dead links - #577
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.
doxia-converter's FML output was not usable: the questions came out as link-reference syntax rather than headings, the [top] back-links became links to a nonexistent 'top' page, the contents links lost their # anchors, and '=' was escaped inside query strings. The page is written out by hand instead. Explicit anchors keep the existing deep links working: #question1 and #question2 still resolve. All four svn.apache.org viewvc links were dead - they return 401 since Apache retired public viewvc - and now point at the models on GitHub. maven.mdo gained a note distinguishing the Maven 4 and Maven 3.9.x versions. The assembly plugin's descriptor.mdo and component.mdo are now assembly.mdo and assembly-component.mdo, and Doxia's decoration model is now the site model. The four live links moved from http to https. FML generates a [top] back-link after each answer; those are dropped rather than hand-written, which is the only rendering loss. Part of codehaus-plexus/.github#58
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 codehaus-plexus/.github#58.
modello-maven-plugin/src/site/fml/faq.fmlis the only.fmlleft in the organisation.Two commits — please merge or rebase, don't squash.
The converter output was unusable
doxia-converter -from fml -to markdownproduced a page with four separate breakages:<question>[Where can I find…][top]back-link[\[top\]](top)top, which doesn't exist[…](question1)#, so they point at a page not an anchor?view=markup?view\=markup=inside the query stringSo this one is hand-written rather than machine-converted.
Deep links still work
FML generates
#question1/#question2anchors, and those are linkable from outside. Explicit anchors keep them resolving:Verified in the built HTML.
All four svn links were dead
Not a format problem, but I wasn't going to migrate a page and leave them:
Apache retired public viewvc, and these pointed at Maven 2.0.9 tags and
trunkregardless. Replacements, each checked to return 200:maven.mdo→ the Maven 4 model, with a note pointing at themaven-3.9.xbranch for the Maven 3 onesettings.mdo→ the Maven 4 settings modeldescriptor.mdo/component.mdo→assembly.mdo/assembly-component.mdo(both were renamed)decoration.mdo→doxia-site-model/…/site.mdo(the decoration model became the site model)The four live links also moved
http→https.One rendering loss, deliberate
FML emits a
[top]back-link after each answer. Those are gone rather than hand-written — for a two-question FAQ they were noise. Everything else diffs clean.Worth asking
FML is a format built for FAQs: it generates the contents list, the anchors and the back-links for free, and Markdown gives none of that. For a page this small the trade is fine, but if this FAQ ever grows, the hand-maintained contents list at the top becomes a thing someone has to remember to update. Happy to close this and leave it as FML if you'd rather.