slachiewicz opened a new pull request, #365:
URL: https://github.com/apache/maven-jxr/pull/365
Converts this repository's FAQs from FML to Markdown, continuing the
estate-wide
move off the Doxia FML format.
**This repository carries two FAQ pages, and both are converted here:**
| source | becomes | published as |
|---|---|---|
| `src/site/fml/faq.fml` | `src/site/markdown/faq.md` |
maven.apache.org/jxr/faq.html |
| `maven-jxr-plugin/src/site/fml/faq.fml` |
`maven-jxr-plugin/src/site/markdown/faq.md` |
maven.apache.org/jxr/maven-jxr-plugin/faq.html |
They are independent pages with independent anchor sets, and each was
verified
on its own.
Two commits: a pure `git mv` of both files, no content change, so
`git log --follow` keeps working; then 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 pages are written out by hand.
### Every published URL still resolves
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. The `<a name>` elements added here
reproduce that **rendered** anchor, not the raw `id=` attribute.
That distinction is load-bearing for the plugin page: its single entry is
`<faq id="Is there a way to run JXR with an Ant build?">`, and the site
serves
it as `#Is_there_a_way_to_run_JXR_with_an_Ant_build.3F` — note the trailing
`.3F` for the question mark. Copying the raw attribute would have broken it.
Verified by generating the site before and after and comparing the set of
anchors each generated `faq.html` actually serves — `id=` on any element plus
`name=` on any `<a>`. The requirement is that each before-set is a subset of
its
after-set:
```
src/site/faq.html before: 4 after: 7 missing: none
maven-jxr-plugin/faq.html before: 3 after: 4 missing: none
```
Anchors carried over, library page:
```
Is_an_Ant_task_available
Is_it_possible_to_convert_other_source_files_than_Java_to_HTML
bodyColumn
top
```
Anchors carried over, plugin page:
```
Is_there_a_way_to_run_JXR_with_an_Ant_build.3F
bodyColumn
top
```
Both `<head>` elements are byte-identical, so titles and metadata are
unchanged.
Neither `site.xml` needs an 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]
