slachiewicz opened a new pull request, #1294:
URL: https://github.com/apache/maven-site-plugin/pull/1294
Converts this project's FAQ from FML to Markdown, continuing the estate-wide
move off the Doxia FML format.
`src/site/fml/faq.fml` becomes `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 is the only FAQ in the estate whose `<part>` elements carry a `<title>`,
so it needs more than the usual treatment. `FmlParser.writeFaqs` gives a
titled
part three things: an anchor on the part id, the title rendered as a section
heading, and **its own numbered list restarting at 1**. So `General` and
`Specific_issues` are live anchors in their own right — both are in the
before-set below — and the contents is two lists of 5 and 3, not one list of
8.
Both are reproduced rather than flattened.
The one answer that genuinely is a definition list (`mvn site` vs
`mvn site:site`) is kept as literal `<dl>` markup.
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: 12 anchors
after: 20 anchors
missing: none
```
The anchors carried over are:
```
Can_I_use_entities
Can_I_validate_xml
General
How_do_I_integrate_static_.28X.29HTML_pages_into_my_Maven_site
How_to_include_a_custom_Doxia_module.2C_like_Twiki
Specific_issues
Use_of_url
What_is_the_difference_between_mvn_site_and_mvn_site.3Asite
Why_do_my_absolute_links_get_translated_into_relative_links
Why_don.27t_the_links_between_parent_and_child_modules_work_when_I_run_.22mvn_site.22.3F
bodyColumn
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]
