slachiewicz opened a new pull request, #143:
URL: https://github.com/apache/maven-archetypes/pull/143
Converts the thirteen APT pages that are this project's own documentation:
the aggregator's
`index.apt` and one `index.apt.vm` per archetype module.
Two commits — the rename alone so `git log --follow` and the review diff
stay readable, then the
conversion. **Please merge or rebase rather than squash**; squashing
collapses the rename back
into the rewrite.
### Deliberately not converted
| files | why |
|---|---|
| 9 under `src/main/resources/archetype-resources/**` | template content
shipped into users' generated projects, not this project's docs |
|
`maven-archetype-site-simple/src/test/resources/.../reference/src/site/apt/index.apt`
| the expected-output fixture the archetype's own IT compares against |
That is 9 template files, not 8 —
`maven-archetype-site-skin/src/main/resources/archetype-resources/src/it/sample/src/site/apt/index.apt.vm`
is one too, and is doubly excluded as an `src/it` sample.
### The `.vm` heading trap fired on all twelve module pages
Each module page interpolates `${project.name}` and `${project.artifactId}`,
so it keeps its
`.vm` suffix — and each has a `Usage` section that converts to an ATX `##`,
which Velocity reads
as a line comment and deletes silently on a green build. All twelve are
setext underlines now.
### Two things the format cannot express, both on the two pages with tables
Flagging these rather than burying them, since they are visible changes:
* **A table with no header row.** APT rendered the quickstart parameter
table's first row as
ordinary cells; Markdown requires a header, so the converter emitted an
*empty* header row
above it, which renders as a blank row. I promoted `Name`/`Default` to the
header instead —
three rows as before, at the cost of those two cells becoming `<th>`
rather than `<td>`.
* **Grid borders and column alignment.** The aggregator table loses
`table-bordered`, and the
quickstart table's centring falls back to the default left. Content is
unchanged in both.
If a reviewer would rather keep either as raw HTML, say so and I will.
### Verification
Every module's site generated before and after and compared page by page:
* **all 184 pages identical** in visible text, link targets, `<title>`, and
the `author`/`date`
meta
* **all anchor ids identical** across all 184
* structural tag sequence identical except the four table facts above
Anchors use `id`, not `name`, throughout. Every fence the converter produced
was a bare fence —
APT's non-boxed `----` form — so nothing needed an info string and nothing
was over-boxed.
`maven-archetype-profiles` is commented out of the reactor and pins parent
`1.3-SNAPSHOT`
against the current `1.6-SNAPSHOT`, so it does not build. Its page is
converted for consistency,
and to verify it I re-enabled the module and corrected the parent **locally
only** — neither
change is in this branch. **That page is the one I could not verify against
the real build.**
`rat.skip` is `true` in this repo. Forced on, RAT fails on pre-existing
unlicensed
`archetype-resources` template content in **both** this branch and pristine
`master`; none of the
thirteen converted files is implicated. Local runs are JDK 21 / Maven 3.9.16
/ macOS only — CI is
the real check.
Generated with assistance from Claude Opus 5.
--
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]
