slachiewicz opened a new pull request, #12713:
URL: https://github.com/apache/maven/pull/12713
Ports the site documentation from APT to Markdown on `maven-3.9.x`,
following apache/maven#12682 on `master`.
All **24** pages converted; none left as APT. Three commits: a rename-only
commit so `git log --follow` survives, then the conversion, then four
readability edits kept separate for review. **Please merge or rebase rather
than squash.**
Unlike the 4.0.x port, these 24 are a different and smaller set than
master's 38, so this is a fresh conversion rather than a port of reviewed work.
### Three traps that produce a clean build and a wrong page
Each was found by comparing rendered output, not by the build failing:
1. **`${…}` in flow text became an anchor.** APT reads the braces as an
anchor *definition*, so the baseline HTML rendered a visible `$maven.home` plus
a stray `<a id="maven.home">`. The converter faithfully reproduced that
breakage. 8 references repaired to literal code spans, matching master. Note
the baseline was already wrong — this fixes it.
2. **Bare `file://` gets autolinked** into `<a href="file://">`, which APT
never produced. 8 occurrences in `offline-mode` escaped as `file\://`.
3. **Empty table cells must be `| |`, not `||`.** `String.split` drops
trailing empty fields, so a row ending in empty cells comes back short and
`ArtifactHandlerTest` reads past its array end.
A fourth of the same kind: APT read the angle brackets of
`<developerConnection/>` as *italic* markup and swallowed them, so the baseline
rendered `developerConnection/` italicised with no brackets. A code span
restores them. That one arrived as a "readability" edit and turned out to be a
fidelity fix.
### Front matter kept
Master's conversion commit dropped it and a follow-up (`096d59ec94`)
restored it; master carries it today. Keeping it from the outset preserves
`<meta name="author">`, `<meta name="date">` and the real page titles.
### Verification
Full reactor `mvn site` before and after. Not the build succeeding — **all
202 generated pages** compared through a normaliser covering visible text,
heading levels, table cells, list items, `<pre>` markers, link targets and page
metadata.
**202 compared, 0 missing, 2 differing** — `configuration-management` and
`getting-to-container-configured-mojos`, and the only differences are the
intended repairs above. `ArtifactHandlerTest` passes; it was checked to be the
only test in the branch that reads a site document.
**Limits:** the normaliser is text, structure markers and link targets, so a
purely visual change — CSS, spacing, `<b>` versus `<strong>` — would not show,
and no page was opened in a browser. Only `ArtifactHandlerTest` was run, not
the full suite.
### Two typos deliberately left alone
`configuration-management` reads "tweaking **the the** various files" and
"**analagous** to the repository". Both are already fixed on 4.0.x and master.
They are prose changes rather than conversion artefacts, so folding them in
would have muddied the verification — happy to fix separately if wanted.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
