slachiewicz opened a new pull request, #280:
URL: https://github.com/apache/maven-plugin-testing/pull/280
Converts this project's FAQ from FML to Markdown, completing the estate-wide
move
off the Doxia FML format.
`maven-plugin-testing-harness/src/site/fml/faq.fml` becomes
`maven-plugin-testing-harness/src/site/markdown/faq.md`, in two commits:
1. a pure `git mv`, no content change, so `git log --follow` keeps working;
2. the hand-written rewrite.
**Please merge or rebase rather than squash**, so the rename commit survives.
### Why this targets 3.x rather than master
This FAQ **exists only on this branch**. `master` was frozen and its FML
deleted, so
the copy here is the only source for the published page — which is why the
PR is based
on `maven-plugin-testing-3.x`.
### Why by hand rather than with doxia-converter
FML is a FAQ-specific Doxia format (`<faqs>` / `<part>` / `<faq id=…>`) with
no Markdown
counterpart, and doxia-converter cannot target it: the questions come out as
link-reference syntax rather than headings, the `[top]` back-links turn into
links to a
nonexistent `top` page, and the contents links lose their `#` anchors.
### Every published URL still resolves
Both anchors on this page are load-bearing, and neither could have been
produced by
letting Doxia derive an id from the heading:
| published anchor | what a heading alone would give |
|---|---|
| `What_is_a_Mojo_Testing_Harness` | `What_is_a_Mojo_Testing_Harness.3F` |
| `What_kinds_of_unit_tests_are_supported` |
`What_kind_of_unit_tests_are_supported.3F` |
The ids omit the question mark, so there is no trailing `.3F`; and the
second is
**plural** (`kinds`) while the question reads "What **kind** of unit tests
are
supported?". Both are therefore written out explicitly, reproducing the
*rendered*
anchor rather than the raw `id=` attribute.
Verified by generating the site before and after and comparing the set of
anchors the
generated `faq.html` actually serves:
```
before: 4 anchors after: 7 anchors missing: none
```
```
What_is_a_Mojo_Testing_Harness
What_kinds_of_unit_tests_are_supported
bodyColumn
top
```
The `<head>` is byte-identical. `site.xml` needs no edit — both source paths
render to
`faq.html`.
### Two branch-specific details
**Anchor form.** Written as `<a id>`, not `<a name>`. maven-site-plugin
3.21.0 drops the
`name` attribute from inline HTML anchors while 3.22.0 keeps it. This branch
resolves to
**3.22.0** (via `maven-parent:49`), so `name` would have worked here — but
`id` is the
primary path in `Xhtml5BaseParser`, is the correct HTML5 form, and keeps the
page safe if
it is ever built with an older toolchain. The build emits no
duplicate-anchor warning.
**Metadata.** The unfenced MultiMarkdown block, matching every other
markdown page on this
branch, and carrying **only** the title — because the FML declared only a
title. Adding
`author`/`date` like the sibling pages would have introduced `meta` elements
the published
page does not currently have and broken the byte-identical `<head>`. The
effective
`doxia-module-markdown` here is **2.1.0**, which accepts either form, so
this is a
consistency choice rather than a constraint; it was confirmed against the
generated page,
where `index.md`'s unfenced block parses into `<head>` correctly.
### Accepted rendering losses
- FML emits a `[top]` back-link after every answer; those are dropped rather
than
hand-written.
- Each question renders as an `h3` heading rather than a definition term.
The definition list inside the second answer is genuine, and is kept as real
`<dl>` markup
rather than flattened into prose.
Generated-by: Claude Opus 5 (1M context)
--
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]
