slachiewicz opened a new pull request, #148: URL: https://github.com/apache/maven-doxia-converter/pull/148
`src/site/apt/index.apt` and `src/site/apt/usage.apt.vm` were the last two APT pages in this repository — the reference implementation of the tool that converts APT to Markdown, still written in APT, right next to the [page this repository just added][pr] telling other projects how to migrate. This converts them, following that page. [pr]: https://github.com/apache/maven-doxia-converter/pull/146 Two commits: the rename on its own 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. ### `usage.md.vm` hits the trap the new page warns about It keeps its `.vm` suffix, because `${project.version}` in the sample command lines is meant to resolve. So the conversion runs straight into the failure mode documented in *Velocity and Markdown disagree about `#`*: all four section headings convert to ATX `##`, Velocity reads that as a line comment, and every one of them disappears from the rendered page — silently, with a green build. The `%{toc}` macro that lists them then renders as an empty list. The before/after comparison is what caught it: ``` < [ITEM] < [LINK:#Command_Line_Help] < Command < Line < Help ... < [h2] < Command < Line < Help ``` Fixed with setext underlines, which need no `#` at all. ### Two other things worth a look * The Ant example's `${tdi.apt}`, `${doxia.out.format}` and `${doxia.out.extension}` are Ant properties the page means to *display*. They render literally today only because Velocity happens to leave an unresolvable reference alone — nothing guarantees that. Written as `${esc.d}{...}` now. * The converter emits ` ```unknown ` for a boxed (`+-----+`) APT block. That info string is load-bearing: the Markdown parser reads a non-empty info string as "boxed", so stripping it as cosmetic noise would silently unbox the block. Kept, but named the languages the blocks actually are — `java` and `xml` — which also gets them real syntax highlighting. ### Verification `mvn site` before and after, then every generated page compared with `tools/normalize-site-page.py`: * all 18 pages compare identical, including `<title>` and the `author`/`date` `<meta>` * the four section anchors (`#Command_Line_Help` etc.) and the toc links are unchanged * `${project.version}` still resolves; the Ant properties still render literally * no non-ASCII bytes in either source (the `-outEncoding UTF-8` trap) `mvn verify` locally: BUILD SUCCESS, RAT 0 unapproved, 23/23 tests pass — on JDK 21, Maven 3.9.16, macOS only. CI on this push is the real check. `src/site/xdoc/download.xml.vm` and the `.fml` files are deliberately untouched. 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]
