You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@maven.apache.org by "JackPGreen (via GitHub)" <gi...@apache.org> on 2026/10/22 11:49:24 UTC
[PR] Wrap `<`/`>` Modello `description`s in CDATA block [maven]
JackPGreen opened a new pull request, #13678:
URL: https://github.com/apache/maven/pull/13678
For angle braces (`<`/`>`) to be rendered correctly by Modello, they must be escaped by their HTML equivalents and then places inside a CDATA block, e.g.: https://github.com/apache/maven/blob/f6a012024f53177374f35a86f337b0e6e8e57bb4/maven-settings/src/main/mdo/settings.mdo#L424-L427
However, not all are like this - which causes them to be rendered incorrectly:
<img width="999" height="258" alt="Image" src="https://github.com/user-attachments/assets/04e64a6a-7a3e-4e3b-80fe-2ab38a1063c6" />
Updated all `<`/`>` Modello usages to resolve:
<img width="979" height="219" alt="image" src="https://github.com/user-attachments/assets/b168c216-7582-4734-9383-0a5bfcbeb911" />
Fixes: https://github.com/apache/maven/issues/13675
- [x] I hereby declare this contribution to be licensed under the [Apache License Version 2.0, January 2004](https://www.apache.org/licenses/LICENSE-2.0)
- [ ] I hereby declare that I have filed an [Apache Individual Contributor License Agreement](https://www.apache.org/licenses/icla.pdf).
--
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: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Docs: Wrap `<`/`>` Modello `description`s in CDATA block [maven]
Posted by "JackPGreen (via GitHub)" <gi...@apache.org>.
JackPGreen commented on PR #13678:
URL: https://github.com/apache/maven/pull/13678#issuecomment-6361540706
> I was _not_ able to reproduce this failure locally (e.g. `mvn package site -DskipTests` completes unexceptionally) to validate further, so 🤞 for CI result.
CI failed, maybe this is the wrong solution after all.
> maybe this shoudl be fixed in Modello?
I wasn't able to validate if it was a bug or a misconfiguration.
--
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: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Docs: Wrap `<`/`>` Modello `description`s in CDATA block [maven]
Posted by "elharo (via GitHub)" <gi...@apache.org>.
elharo commented on code in PR #13678:
URL: https://github.com/apache/maven/pull/13678#discussion_r4359866391
##########
api/maven-api-model/src/main/mdo/maven.mdo:
##########
@@ -70,8 +70,10 @@
<name>Model</name>
<superClass>ModelBase</superClass>
<description>
- The {@code <project>} element is the root of the descriptor.
+ <![CDATA[
+ The {@code <project>} element is the root of the descriptor.
Review Comment:
Something's seriously off here, maybe Modello? The greater than sign can be but DOES NOT HAVE TO BE escaped in XML.
##########
api/maven-api-model/src/main/mdo/maven.mdo:
##########
@@ -579,9 +581,11 @@
<name>properties</name>
<version>4.0.0+</version>
<description>
+ <![CDATA[
Properties that can be used throughout the POM as a substitution, and
are used as filters in resources if enabled.
- The format is {@code <name>value</name>}.
+ The format is {@code <name>value</name>}.
Review Comment:
Something is absolutely broken. The way this is structured It is requesting literal amspersands in the output, not less than and greater than signs.
--
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: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Docs: Wrap `<`/`>` Modello `description`s in CDATA block [maven]
Posted by "slachiewicz (via GitHub)" <gi...@apache.org>.
slachiewicz commented on PR #13678:
URL: https://github.com/apache/maven/pull/13678#issuecomment-6351190211
maybe this shoudl be fixed in Modello?
--
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: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Docs: Wrap `<`/`>` Modello `description`s in CDATA block [maven]
Posted by "gnodet (via GitHub)" <gi...@apache.org>.
gnodet commented on PR #13678:
URL: https://github.com/apache/maven/pull/13678#issuecomment-6368888857
Closing in favour of the upstream Modello fix: https://github.com/codehaus-plexus/modello/pull/619
--
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: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Docs: Wrap `<`/`>` Modello `description`s in CDATA block [maven]
Posted by "JackPGreen (via GitHub)" <gi...@apache.org>.
JackPGreen commented on PR #13678:
URL: https://github.com/apache/maven/pull/13678#issuecomment-6345931128
> Nit: `maven.mdo` now has inconsistent `>` escaping — this new line uses `<project>` (both brackets HTML-escaped), while several existing descriptions in the same file use only `<` with a raw `>` (e.g. `<build>`, `<scm>`, `<plugin>`, `<groupId>:<artifactId>:<version>`).
This isn't new, e.g.:
https://github.com/apache/maven/blob/f387510e08e77e82994fbff6f2bfbf793600a16a/api/maven-api-model/src/main/mdo/maven.mdo#L3151
But I think this change just exposes the issue.
> Please audit every `<...>` (where `>` is unescaped) within the newly added CDATA blocks and fix the escaping consistently.
Audited using AI-generated command:
```
% find . -type f -name '*.mdo' -exec perl -0777 -ne '
while (/<!\[CDATA\[(.*?)\]\]>/sg) {
$block = $1;
$start = $-[0];
$line = 1 + (substr($_, 0, $start) =~ tr/\n/\n/);
@lines = split /\n/, $block, -1;
for ($i = 0; $i < @lines; $i++) {
print "$ARGV:" . ($line + $i) . ": $lines[$i]\n"
if $lines[$i] =~ /[<>]/ && $lines[$i] =~ /&(?:lt|gt);/;
}
}
' {} +
```
Fixed in fcbc1eb2272e34d96c11bb6cd896fedd01a8455c.
I was _not_ able to reproduce this failure locally (e.g. `mvn package site -DskipTests` completes unexceptionally) to validate further, so 🤞 for CI result.
--
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: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Docs: Wrap `<`/`>` Modello `description`s in CDATA block [maven]
Posted by "gnodet-bot (via GitHub)" <gi...@apache.org>.
gnodet-bot commented on code in PR #13678:
URL: https://github.com/apache/maven/pull/13678#discussion_r4348064557
##########
api/maven-api-model/src/main/mdo/maven.mdo:
##########
@@ -70,8 +70,10 @@
<name>Model</name>
<superClass>ModelBase</superClass>
<description>
- The {@code <project>} element is the root of the descriptor.
+ <![CDATA[
+ The {@code <project>} element is the root of the descriptor.
Review Comment:
💡 **Nit:** This line uses `<project>` (both angle brackets HTML-escaped), but other descriptions in this file use `<build>`, `<scm>`, `<plugin>`, etc. — only `<` is escaped, `>` is raw. Worth picking one convention and applying it consistently across all `description` blocks.
--
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: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Docs: Wrap `<`/`>` Modello `description`s in CDATA block [maven]
Posted by "gnodet (via GitHub)" <gi...@apache.org>.
gnodet commented on PR #13678:
URL: https://github.com/apache/maven/pull/13678#issuecomment-6368887185
Thanks for the investigation! After tracing the full rendering pipeline I've found that the root cause is in Modello's xdoc generator, not in the `.mdo` descriptions. The `.mdo` files are correct as written.
**Root cause trace:**
1. MXParser reads `<description>` outside CDATA and XML-decodes `<` → `<`, so `{@code <activation>}` becomes the string `{@code <activation>}`.
2. `XdocGenerator.rewrite()` passes this to the `chhorz` javadoc-parser which wraps `{@code X}` in `<code>X</code>` **without HTML-escaping `X`** → produces `<code><activation></code>`.
3. Jsoup (XML output mode) treats `<activation>` as an unknown HTML element and silently drops it.
**Fix:** I've opened a PR against Modello to pre-process `{@code}` / `{@literal}` tags and HTML-escape their content before the parser+Jsoup pipeline: https://github.com/codehaus-plexus/modello/pull/619
This PR (wrapping in CDATA + double-escaping) is not the right approach — it adds complexity and changes the semantics of the descriptions without addressing the underlying Modello bug. Once Modello 2.8.2 ships with the fix, the Maven site will render correctly without any changes here.
I'll close this PR in favour of the upstream Modello fix.
--
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: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Docs: Wrap `<`/`>` Modello `description`s in CDATA block [maven]
Posted by "gnodet (via GitHub)" <gi...@apache.org>.
gnodet closed pull request #13678: Docs: Wrap `<`/`>` Modello `description`s in CDATA block
URL: https://github.com/apache/maven/pull/13678
--
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: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org