slachiewicz opened a new pull request, #547:
URL: https://github.com/apache/maven-ear-plugin/pull/547
Part of an estate-wide move of the remaining FAQ pages from FML to Markdown.
### Two commits, deliberately
1. **A pure rename**, `src/site/fml/faq.fml` -> `src/site/markdown/faq.md`,
no content change.
2. **The rewrite**, written by hand.
Git records a rename plus a rewrite in a single commit as a delete and an
add, which stops `git log --follow`. Splitting them keeps the history. **Please
merge or rebase rather than squash.**
### Why by hand
doxia-converter cannot target FML: the questions come out as link-reference
syntax rather than headings, the `[top]` back-links become links to a
nonexistent `top` page, and the contents links lose their `#` anchors.
### Anchors are preserved, and that is the point
This page has been on maven.apache.org for years and is linked from outside.
All four `<faq id=…>` values here are valid XML names, so Doxia serves them
unchanged and the `<a name>` elements written here match the live URLs exactly:
`#what-is-ear`, `#har-files`, `#avoid-display-name`,
`#when-should-one-use-the-modules`.
### One link spelled differently in the source, identically in the output
The `har-files` answer links to `modules.html#Custom Artifact Types` in the
FML — fragment with spaces. Doxia encodes a fragment on the way out, so the
live page has always served `#Custom_Artifact_Types`, which is also the anchor
`modules.md.vm` generates. The Markdown writes the encoded form directly, so
the rendered `href` is byte-identical.
### `${null}` is still literal
`src/site/markdown/faq.md` is not a `.vm` file, so Velocity does not run
over it — exactly as it did not run over the FML. The `${null}` in the
display-name answer renders verbatim, as before.
### Verification
Built the site with `mvn site` before and after and compared the set of
anchors the generated `faq.html` actually serves. Every anchor served before is
still served after; `<head>` byte-identical, so title and metadata are
unchanged. `site.xml` needs no edit — FML and Markdown both render to
`faq.html`, so the menu entry and the `./faq.html` link in `index.md` keep
working.
### What is lost
FML generates a `[top]` back-link after each answer. Those are dropped
rather than hand-written. The question becomes an `h3` heading instead of a
definition term. Nothing else changes.
<sub>Drafted with Claude — please verify</sub>
--
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]
