slachiewicz opened a new pull request, #1009:
URL: https://github.com/apache/maven-enforcer/pull/1009
Converts this project's FAQ from FML to Markdown, continuing the estate-wide
move off the Doxia FML format.
`maven-enforcer-plugin/src/site/fml/faq.fml` becomes
`maven-enforcer-plugin/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 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. The page is written out by hand.
### Every published URL still resolves
This page has been on maven.apache.org for years and is deep-linked from blog
posts and Stack Overflow, so no fragment may change.
FML routes every `<faq id>` through `DoxiaUtils.encodeId`, which rewrites
any id
that is not a valid XML name — a space becomes `_`, and any other character
becomes its dot-prefixed UTF-8 bytes, so `,` becomes `.2C` and `?` becomes
`.3F`. The `<a name>` elements added here reproduce that **rendered** anchor,
not the raw `id=` attribute, which for several entries is not the same
string.
Verified by generating the site before and after the change and comparing the
set of anchors the generated `faq.html` actually serves — `id=` on any
element
plus `name=` on any `<a>`. The requirement is that the before-set is a
subset of
the after-set:
```
before: 3 anchors
after: 5 anchors
missing: none
```
The anchors carried over are:
```
bodyColumn
question
top
```
The `<head>` is byte-identical, so the page title and metadata are unchanged.
`site.xml` needs no edit — both source paths render to `faq.html`.
### 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, so
the answers are no longer wrapped in a `<dl>`.
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]
