Port the last APT documents to Markdown - #1632
Open
slachiewicz wants to merge 2 commits into
Open
Conversation
Kept as its own commit so that git log --follow and git blame still reach each page's history once the content changes.
Six guides and the fragment one of them parses. Four keep their .vm suffix because
they interpolate a version or a path; guides/index.md.vm and guides/mini/index.md.vm
keep theirs for the #set and #parse directives that build the mini-guide list.
Three things the conversion needed by hand:
* Velocity reads ## as a line comment, so level two headings use a setext underline
and deeper ones are wrapped in an unparsed block.
* APT writes $\{foo\} for a reference it means to display, and its parser strips
the backslashes, so the converted page carried a live ${prefix}, ${groupId},
${user.home} and friends. Those are now ${esc.d}{foo}.
* mini/index.txt is parsed into a Markdown page, so its APT comments and link
syntax had to become Markdown too, and it moves with the page that parses it.
Verified by building the site before and after and comparing all 265 generated
pages: 264 are identical in title, author and date metadata, visible text and every
link target. The one difference is that a Markdown table must have a header row
where the APT table had none, so two tables in the Java plugin guide gain an empty
one.
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.
The six remaining APT pages on maven.apache.org, plus the fragment one of them parses. After this the site is entirely Markdown, FML and XDoc.
Four pages keep their
.vmsuffix because they interpolate a version or a path;guides/index.md.vmandguides/mini/index.md.vmkeep theirs for the#setand#parsedirectives that build the mini-guide list.Three things needed doing by hand, and each is worth knowing for anyone doing the same elsewhere:
##as a line comment, so every heading below level one would be deleted before Doxia saw the page. Level two uses a setext underline; deeper ones are wrapped in#[[ ]]#.$\{foo\}for a reference it means to display, and the APT parser strips the backslashes — so the converted pages carried live${prefix},${groupId},${user.home}and${project.version}references. Those are now${esc.d}{foo}.mini/index.txtis#parsed into what is now a Markdown page, so its APT comments and link syntax had to become Markdown too. It moves with the page that parses it, since#parseresolves relative to the file.Two commits: a pure
git mvsogit log --followandgit blamestill reach each page history, then the conversion. Please merge or rebase rather than squash — squashing collapses the rename.Verified by building the site before and after and comparing all 265 generated pages: 264 are identical in their title, author and date metadata, their visible text and every link target.
The one difference: a Markdown table must have a header row where the APT table had none, so the two definition tables in the Java plugin guide gain an empty header. I left them empty rather than invent column headings; say the word if you would rather have "Element / Description" there.