Convert two site documents from xdoc to Markdown - #576
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.
Converts the Modello overview and the modello-plugin-velocity page. The other nine xdoc pages are deliberately left as they are. They depend on inline HTML that Markdown cannot express - constructs like <code><i>my.model.package</i><b>.io.sax.</b><i>ModelName</i></code>, and <br/> inside list items. Converting them means embedding the same HTML in a Markdown file, which is more fragile than the xdoc it replaces, so there is nothing to gain. Two converter defects needed repairing by hand: The overview page has a clickable image map over modello-deps.png, and doxia-converter silently dropped the entire <map> element with all 20 <area> hotspots, keeping only a bare <img>. The original HTML block is restored verbatim. The velocity page's table came out with each row split across lines and blank lines between them, so it did not render as a table at all, and braces inside code spans were backslash-escaped. Verified by building the site before and after and diffing the normalised pages, head included. Both are identical. Part of codehaus-plexus/.github#58
|
Update: the "nine pages stay as xdoc" reasoning in this PR is superseded by #578. I argued here that those nine plugin pages couldn't be converted because they depend on inline HTML Markdown can't express. That was true of a faithful conversion, but it was the wrong conclusion — those #578 converts all nine that way, and also fixes three genuine errors that only surfaced from reading the sources closely (a missing This PR still stands on its own for the two pages it converts — the Modello overview and modello-plugin-velocity — including the image map The two touch different files, so they can merge in either order. |
1 participant
Part of codehaus-plexus/.github#58. Now unblocked: modello is on parent 26, which excludes
**/src/site/markdown/**from Spotless, so no local workaround is needed here.Two commits — please merge or rebase, don't squash, so
git log --followsurvives the rename.Two converted, nine deliberately not
I started out converting all 11 xdoc pages. Nine of them are going back unchanged, and I think that's the right answer rather than a shortfall.
Those pages lean on inline HTML that Markdown genuinely cannot express:
There is no Markdown for italic-and-bold inside a code span, or for
<br/>inside a list item.doxia-converterproduced`_RootClass_`— which renders those underscores literally — and turned each<br/>into a backslash plus a blank line, which closed the list and dumped the rest as plain text.The only faithful conversion is to paste the same HTML into the
.mdfile. That is strictly more fragile than the xdoc it replaces (flexmark closes a list when it meets a multi-line raw HTML block inside one), for no benefit. Sosax,xpp3,stax,jackson,snakeyaml,dom4j,jdom,convertersandxdocstay as they are — verified byte-identical to their pre-rename state.The two that convert cleanly are the Modello overview and modello-plugin-velocity.
Two converter defects I had to repair
The overview page has a clickable image map, and the converter silently dropped it —
<map>and all 20<area>hotspots gone, leaving a bare<img>. Themodello-deps.pngarchitecture diagram would have become a flat picture, with every link tomodello-core/,modello-plugin-java/and the rest lost. Original HTML block restored verbatim.The velocity page's table came out with each row split over two lines and blank lines between them, so it didn't render as a table at all — the cells appeared as literal
|parameters configured in the plugin|. Rebuilt from the original. It also backslash-escaped braces inside code spans, so`${project.basedir}`rendered as`$\{project.basedir\}`.Neither is visible in the Markdown. Both are obvious in the HTML.
Verified
Built the site before and after, diffed the normalised pages — title, author, visible text and every link target,
<head>included:The image map is worth stressing: a body-text comparison alone would have passed the version that had lost all 20 hotspots. The
[LINK:...]targets in the normaliser are what caught it.Noticed, not fixed
modello-plugin-velocityhas a typo — "rfelative tovelocityBasedir". It's in the original xdoc, so I've left it; a format migration shouldn't smuggle in copy edits. Happy to send it separately.