Conversation
elharo
marked this pull request as ready for review
August 9, 2026 12:15
Bukama
approved these changes
Aug 9, 2026
| The archive parameter is a class that resides outside of this plugin, | ||
| in the Maven Archiver component. You can find the documentation for | ||
| Maven Archiver | ||
| The `archive` parameter is a class outside of this plugin. It is |
Contributor
There was a problem hiding this comment.
maybe add "for" so "for a class and maybe "not provided, but only used by this plugin".?
Current it reads very weird that a parameter should be a class
Co-authored-by: Matthias Bünger <Bukama@users.noreply.github.com>
Member
|
Maybe convert to markdown before? |
Contributor
Author
|
Those are separate tasks, so please file issues. Meanwhile one thing at a time and this si ready to go now. It doesn't get in the way of doing markdown later. |
slachiewicz
added a commit
that referenced
this pull request
Aug 9, 2026
The FAQ answer was rewritten in #581 using Markdown backticks around `archive`. FML is not Markdown: an <answer> body is parsed by Doxia's XdocParser, which has no backtick handling, so the characters reach the generated page verbatim. maven.apache.org currently shows The `archive` parameter is defined by the Maven Archiver library. Use <code>, which is what the other 22 faq.fml files in the Maven estate use for the same purpose. The same sentence also gained a full stop in place of a comma, splitting "defined by the Maven Archiver library, not by the Maven JAR Plugin" into a sentence and a fragment. Fixed here since it is the same sentence and the same origin. Verified by building the site before and after: the only differences in the rendered page are `archive` -> archive and library. -> library,. The #question1 anchor is unchanged. Generated-by: Claude Opus 5 (1M context)
slachiewicz
added a commit
that referenced
this pull request
Aug 10, 2026
doxia-converter cannot target FML usefully - 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. The page is written out by hand instead. The single anchor, #question1, is a valid XML name, so Doxia serves it unchanged and the <a id> written here matches the live URL exactly. Verified by building the site before and after and comparing the set of anchors the generated faq.html actually serves. Every anchor present before is still present after, and the <head> is byte-identical, so the title and metadata are unchanged. This also fixes the backticks around 'archive'. FML hands an <answer> body to Doxia's XdocParser, which has no backtick handling, so the page has been serving the characters verbatim since the Simplified Technical English rewrite in #581. Now that the page is Markdown the backticks are correct and render as <code>, which is what PR #582 set out to achieve with <code> markup - that PR becomes unnecessary if this is merged. The full stop that split "defined by the Maven Archiver library, not by the Maven JAR Plugin" into a sentence and a fragment is corrected here too, since it came from the same rewrite. site.xml needs no edit: src/site/fml/faq.fml and src/site/markdown/faq.md both render to faq.html, so the menu entry and the link from index.md keep working. 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 on the page changes. The anchors are written as <a id="...">, not <a name="...">. maven-site-plugin 3.21.0 strips the name attribute from inline HTML, which would silently delete every anchor on the page while the build stays green; 3.22.0 keeps it. Xhtml5BaseParser reads Attribute.ID first and only falls back to NAME, so id= is the primary path rather than a workaround, and name on <a> is obsolete in HTML5. Each anchor is kept on its own line: folding one into the heading text suppresses the section's own generated id. Generated-by: Claude Opus 5 (1M context)
slachiewicz
added a commit
that referenced
this pull request
Aug 10, 2026
doxia-converter cannot target FML usefully - 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. The page is written out by hand instead. The single anchor, #question1, is a valid XML name, so Doxia serves it unchanged and the <a id> written here matches the live URL exactly. Verified by building the site before and after and comparing the set of anchors the generated faq.html actually serves. Every anchor present before is still present after, and the <head> is byte-identical, so the title and metadata are unchanged. This also fixes the backticks around 'archive'. FML hands an <answer> body to Doxia's XdocParser, which has no backtick handling, so the page has been serving the characters verbatim since the Simplified Technical English rewrite in #581. Now that the page is Markdown the backticks are correct and render as <code>, which is what PR #582 set out to achieve with <code> markup - that PR becomes unnecessary if this is merged. The full stop that split "defined by the Maven Archiver library, not by the Maven JAR Plugin" into a sentence and a fragment is corrected here too, since it came from the same rewrite. site.xml needs no edit: src/site/fml/faq.fml and src/site/markdown/faq.md both render to faq.html, so the menu entry and the link from index.md keep working. 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 on the page changes. The anchors are written as <a id="...">, not <a name="...">. maven-site-plugin 3.21.0 strips the name attribute from inline HTML, which would silently delete every anchor on the page while the build stays green; 3.22.0 keeps it. Xhtml5BaseParser reads Attribute.ID first and only falls back to NAME, so id= is the primary path rather than a workaround, and name on <a> is obsolete in HTML5. Each anchor is kept on its own line: folding one into the heading text suppresses the section's own generated id. Generated-by: Claude Opus 5 (1M context)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.