slachiewicz opened a new pull request, #232:
URL: https://github.com/apache/maven-ejb-plugin/pull/232
Part of an estate-wide move of the remaining FAQ pages from FML to Markdown.
FML is a
FAQ-specific Doxia format with no Markdown counterpart and doxia-converter
cannot target
it, so the page is hand-written rather than converted.
### Two commits, deliberately
1. **A pure rename**, `src/site/fml/faq.fml.vm` →
`src/site/markdown/faq.md.vm`, no content change.
2. **The rewrite.**
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**, since squashing collapses the
rename again.
### It stays a Velocity template
The sample POM interpolates `${project.version}` — the rendered page really
does show the
current plugin version — so the target is `faq.md.vm`, not `faq.md`.
That has one non-obvious consequence: **in a `.vm` file an ATX heading
starting `##` is
swallowed as a Velocity line comment**, which silently deletes the heading
on a green
build. So the page title uses a setext underline and each question is
wrapped in
`#[[### … ]]#` (Velocity's unparsed-content block) to reach the Markdown
parser intact.
The verification below confirms both headings survive.
### Anchors are preserved, and that is the point
This page has been on maven.apache.org for years and is linked from outside,
so no URL may
change. FML derives its anchor from the `<faq id=…>` attribute — and where
that attribute
is not a valid XML name, `DoxiaUtils.encodeId` rewrites it at render time.
Here
`id="How can I specify a Class-Path: entry in the manifest of an EJB jar?"`
is served as
`#How_can_I_specify_a_Class-Path.3A_entry_in_the_manifest_of_an_EJB_jar.3F`.
Note that the question text says *EJB JAR* where the id says *EJB jar*, so
the anchor a
Markdown heading derives is genuinely a different string from the one the
site serves. The
`<a name>` written here reproduces the served one.
### Verification
Built the site before and after and compared the set of anchors the
generated `faq.html`
actually serves:
| | anchors served |
|---|---|
| before |
`How_can_I_specify_a_Class-Path.3A_entry_in_the_manifest_of_an_EJB_jar.3F`,
`classifieruse`, `top`, `bodyColumn` |
| after | the same four, plus three heading-derived ids |
Every anchor present before is still present after — the set only grows. The
`<head>` is
byte-identical, so the title and metadata are unchanged. `site.xml` needs no
edit:
`src/site/fml/faq.fml.vm` and `src/site/markdown/faq.md.vm` both render to
`faq.html`.
### What is lost
FML generates a `[top]` back-link after each answer; those are dropped
rather than
hand-written. The question now renders as an `h3` heading instead of a
definition term.
Those are the only rendering differences.
<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]
