From 2515affa7fda2ec42c2d927b82d87a39a776be8c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Efe=20G=C3=B6kdemir?= Date: Wed, 23 Sep 2026 21:02:18 +0300 Subject: [PATCH 1/6] fix: preserve preformatted help descriptions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Efe Gökdemir --- .../src/it/help-basic-jdk11/expected-help.txt | 6 +++ .../src/main/java/test/MyMojo.java | 12 +++++ .../generator/HtmlToPlainTextConverter.java | 53 +++++++++++++++++-- .../main/resources/help-class-source-v4.vm | 23 ++++++++ .../src/main/resources/help-class-source.vm | 23 ++++++++ .../HtmlToPlainTextConverterTest.java | 9 ++++ 6 files changed, 121 insertions(+), 5 deletions(-) diff --git a/maven-plugin-plugin/src/it/help-basic-jdk11/expected-help.txt b/maven-plugin-plugin/src/it/help-basic-jdk11/expected-help.txt index 069f241b3..00577282b 100644 --- a/maven-plugin-plugin/src/it/help-basic-jdk11/expected-help.txt +++ b/maven-plugin-plugin/src/it/help-basic-jdk11/expected-help.txt @@ -10,6 +10,12 @@ help-jdk11:test Available parameters: + codeExample + A parameter with a preformatted example. + + https://example.test/plugin.exe + + defaultParam (Default: escape\backslash) This parameter uses "quotation" marks and backslashes '\\' in its description. Those characters must be escaped in Java string literals. diff --git a/maven-plugin-plugin/src/it/help-basic-jdk11/src/main/java/test/MyMojo.java b/maven-plugin-plugin/src/it/help-basic-jdk11/src/main/java/test/MyMojo.java index 480fdbc77..caae655b0 100644 --- a/maven-plugin-plugin/src/it/help-basic-jdk11/src/main/java/test/MyMojo.java +++ b/maven-plugin-plugin/src/it/help-basic-jdk11/src/main/java/test/MyMojo.java @@ -41,6 +41,18 @@ public class MyMojo extends AbstractMojo { @Parameter(defaultValue = "escape\\backslash") private String defaultParam; + /** + * A parameter with a preformatted example. + * + *
{@code
+     *   
+     *     https://example.test/plugin.exe
+     *   
+     * }
+ */ + @Parameter + private String codeExample; + /** * This parameter is deprecated. * diff --git a/maven-plugin-tools-generators/src/main/java/org/apache/maven/tools/plugin/generator/HtmlToPlainTextConverter.java b/maven-plugin-tools-generators/src/main/java/org/apache/maven/tools/plugin/generator/HtmlToPlainTextConverter.java index 6906c75cf..6ae47c866 100644 --- a/maven-plugin-tools-generators/src/main/java/org/apache/maven/tools/plugin/generator/HtmlToPlainTextConverter.java +++ b/maven-plugin-tools-generators/src/main/java/org/apache/maven/tools/plugin/generator/HtmlToPlainTextConverter.java @@ -59,17 +59,30 @@ private String getPlainText(Element element) { // the formatting rules, implemented in a breadth-first DOM traverse private static class FormattingVisitor implements NodeVisitor { + private static final char PRE_START = '\u0001'; + private static final char PRE_END = '\u0002'; + private StringBuilder accum = new StringBuilder(); // holds the accumulated text + private int preformatted; + // hit when the node is first seen public void head(Node node, int depth) { String name = node.nodeName(); if (node instanceof TextNode) { - accum.append(((TextNode) node).text()); // TextNodes carry all user-readable text in the DOM. + TextNode textNode = (TextNode) node; + // TextNode#text() normalizes whitespace. Keep the original text inside preformatted blocks. + accum.append(preformatted > 0 ? textNode.getWholeText() : textNode.text()); } else if (name.equals("li")) { accum.append("\n * "); } else if (name.equals("dt")) { accum.append(" "); + } else if (name.equals("pre")) { + if (accum.length() > 0 && accum.charAt(accum.length() - 1) != '\n') { + accum.append('\n'); + } + accum.append(PRE_START); + preformatted++; } else if (StringUtil.in(name, "p", "h1", "h2", "h3", "h4", "h5", "tr")) { accum.append("\n"); } @@ -78,8 +91,20 @@ public void head(Node node, int depth) { // hit when all of the node's children (if any) have been visited public void tail(Node node, int depth) { String name = node.nodeName(); - if (StringUtil.in(name, "br", "dd", "dt", "p", "h1", "h2", "h3", "h4", "h5")) { - accum.append("\n"); + boolean preformattedEndsWithNewline = false; + if (name.equals("pre")) { + preformatted--; + preformattedEndsWithNewline = accum.length() > 0 && accum.charAt(accum.length() - 1) == '\n'; + accum.append(PRE_END); + } + if (name.equals("pre")) { + if (!preformattedEndsWithNewline) { + accum.append('\n'); + } + } else if (StringUtil.in(name, "br", "dd", "dt", "p", "h1", "h2", "h3", "h4", "h5")) { + if (accum.length() == 0 || accum.charAt(accum.length() - 1) != '\n') { + accum.append("\n"); + } } else if (name.equals("a")) { // link is empty if it cannot be made absolute String link = node.absUrl("href"); @@ -91,8 +116,26 @@ public void tail(Node node, int depth) { @Override public String toString() { - // collate multiple consecutive spaces - return accum.toString().replaceAll(" +", " ").replace("\n ", "\n"); + String text = accum.toString(); + StringBuilder result = new StringBuilder(text.length()); + int start = 0; + int preStart; + while ((preStart = text.indexOf(PRE_START, start)) >= 0) { + appendNormalText(result, text.substring(start, preStart)); + int preEnd = text.indexOf(PRE_END, preStart); + if (preEnd < 0) { + appendNormalText(result, text.substring(preStart + 1)); + return result.toString(); + } + result.append(text, preStart + 1, preEnd); + start = preEnd + 1; + } + appendNormalText(result, text.substring(start)); + return result.toString(); + } + + private static void appendNormalText(StringBuilder result, String text) { + result.append(text.replaceAll(" +", " ").replace("\n ", "\n")); } } } diff --git a/maven-plugin-tools-generators/src/main/resources/help-class-source-v4.vm b/maven-plugin-tools-generators/src/main/resources/help-class-source-v4.vm index 5cb0bb170..9946e9c38 100644 --- a/maven-plugin-tools-generators/src/main/resources/help-class-source-v4.vm +++ b/maven-plugin-tools-generators/src/main/resources/help-class-source-v4.vm @@ -400,6 +400,29 @@ public class HelpMojo int lineIndent = getIndentLevel( line ); StringBuilder buf = new StringBuilder( 256 ); + // Preserve leading spaces in preformatted descriptions instead of treating them as word separators. + if ( lineIndent < line.length() && line.charAt( lineIndent ) == ' ' ) + { + for ( int j = 0; j < line.length(); j++ ) + { + char c = line.charAt( j ); + if ( c == '\t' ) + { + buf.append( repeat( " ", indentSize - buf.length() % indentSize ) ); + } + else if ( c == '\u00A0' ) + { + buf.append( ' ' ); + } + else + { + buf.append( c ); + } + } + lines.add( buf.toString() ); + return; + } + String[] tokens = line.split( " +" ); for ( String token : tokens ) diff --git a/maven-plugin-tools-generators/src/main/resources/help-class-source.vm b/maven-plugin-tools-generators/src/main/resources/help-class-source.vm index 794ed18a1..5c358ec53 100644 --- a/maven-plugin-tools-generators/src/main/resources/help-class-source.vm +++ b/maven-plugin-tools-generators/src/main/resources/help-class-source.vm @@ -390,6 +390,29 @@ public class HelpMojo int lineIndent = getIndentLevel( line ); StringBuilder buf = new StringBuilder( 256 ); + // Preserve leading spaces in preformatted descriptions instead of treating them as word separators. + if ( lineIndent < line.length() && line.charAt( lineIndent ) == ' ' ) + { + for ( int j = 0; j < line.length(); j++ ) + { + char c = line.charAt( j ); + if ( c == '\t' ) + { + buf.append( repeat( " ", indentSize - buf.length() % indentSize ) ); + } + else if ( c == '\u00A0' ) + { + buf.append( ' ' ); + } + else + { + buf.append( c ); + } + } + lines.add( buf.toString() ); + return; + } + String[] tokens = line.split( " +" ); for ( String token : tokens ) diff --git a/maven-plugin-tools-generators/src/test/java/org/apache/maven/tools/plugin/generator/HtmlToPlainTextConverterTest.java b/maven-plugin-tools-generators/src/test/java/org/apache/maven/tools/plugin/generator/HtmlToPlainTextConverterTest.java index 1cbe3e603..c9b155dcf 100644 --- a/maven-plugin-tools-generators/src/test/java/org/apache/maven/tools/plugin/generator/HtmlToPlainTextConverterTest.java +++ b/maven-plugin-tools-generators/src/test/java/org/apache/maven/tools/plugin/generator/HtmlToPlainTextConverterTest.java @@ -85,6 +85,15 @@ void explicitNewline() { converter.convert(test)); } + @Test + void preformattedTextPreservesWhitespace() { + String test = + "For example:
\n  <binary>\n    <url>https://example.test/plugin.exe</url>\n  </binary>\n
"; + assertEquals( + "For example:\n \n https://example.test/plugin.exe\n \n", + converter.convert(test)); + } + @ParameterizedTest(name = "{0} to {1}") // With JUnit 6.0.0 the non-printable chars will be kept in display, see // https://docs.junit.org/current/user-guide/#writing-tests-parameterized-tests-display-names-quoted-text @MethodSource("provideConvertParamsBreakLines") From d8ca673097adef5da4b6b78166be8ac98d28d7cf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Efe=20G=C3=B6kdemir?= Date: Sat, 17 Oct 2026 10:26:57 +0300 Subject: [PATCH 2/6] fix: omit whitespace separator before preformatted help --- .../main/resources/help-class-source-v4.vm | 22 +++++++++++++++++-- .../src/main/resources/help-class-source.vm | 22 +++++++++++++++++-- 2 files changed, 40 insertions(+), 4 deletions(-) diff --git a/maven-plugin-tools-generators/src/main/resources/help-class-source-v4.vm b/maven-plugin-tools-generators/src/main/resources/help-class-source-v4.vm index 9946e9c38..9db5cf8ac 100644 --- a/maven-plugin-tools-generators/src/main/resources/help-class-source-v4.vm +++ b/maven-plugin-tools-generators/src/main/resources/help-class-source-v4.vm @@ -379,9 +379,27 @@ public class HelpMojo String[] plainLines = text.split( "(\r\n)|(\r)|(\n)" ); - for ( String plainLine : plainLines ) + for ( int i = 0; i < plainLines.length; i++ ) { - toLines( lines, ind + plainLine, indentSize, lineLength ); + String plainLine = plainLines[i]; + if ( plainLine.trim().isEmpty() ) + { + boolean previousLineIsPreformatted = i > 0 + && !plainLines[i - 1].trim().isEmpty() + && plainLines[i - 1].startsWith( " " ); + boolean nextLineIsPreformatted = i + 1 < plainLines.length + && !plainLines[i + 1].trim().isEmpty() + && plainLines[i + 1].startsWith( " " ); + // The whitespace-only line before a preformatted block is a boundary, not displayed content. + if ( !nextLineIsPreformatted || previousLineIsPreformatted ) + { + lines.add( "" ); + } + } + else + { + toLines( lines, ind + plainLine, indentSize, lineLength ); + } } return lines; diff --git a/maven-plugin-tools-generators/src/main/resources/help-class-source.vm b/maven-plugin-tools-generators/src/main/resources/help-class-source.vm index 5c358ec53..da82a4095 100644 --- a/maven-plugin-tools-generators/src/main/resources/help-class-source.vm +++ b/maven-plugin-tools-generators/src/main/resources/help-class-source.vm @@ -369,9 +369,27 @@ public class HelpMojo String[] plainLines = text.split( "(\r\n)|(\r)|(\n)" ); - for ( String plainLine : plainLines ) + for ( int i = 0; i < plainLines.length; i++ ) { - toLines( lines, ind + plainLine, indentSize, lineLength ); + String plainLine = plainLines[i]; + if ( plainLine.trim().isEmpty() ) + { + boolean previousLineIsPreformatted = i > 0 + && !plainLines[i - 1].trim().isEmpty() + && plainLines[i - 1].startsWith( " " ); + boolean nextLineIsPreformatted = i + 1 < plainLines.length + && !plainLines[i + 1].trim().isEmpty() + && plainLines[i + 1].startsWith( " " ); + // The whitespace-only line before a preformatted block is a boundary, not displayed content. + if ( !nextLineIsPreformatted || previousLineIsPreformatted ) + { + lines.add( "" ); + } + } + else + { + toLines( lines, ind + plainLine, indentSize, lineLength ); + } } return lines; From 7d3d905ae261dee0e2e52ca8ecf1bed90226325b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Efe=20G=C3=B6kdemir?= Date: Sat, 17 Oct 2026 14:51:25 +0300 Subject: [PATCH 3/6] test: cover preformatted text boundaries --- .../plugin/generator/HtmlToPlainTextConverter.java | 3 +-- .../generator/HtmlToPlainTextConverterTest.java | 12 ++++++++++++ 2 files changed, 13 insertions(+), 2 deletions(-) diff --git a/maven-plugin-tools-generators/src/main/java/org/apache/maven/tools/plugin/generator/HtmlToPlainTextConverter.java b/maven-plugin-tools-generators/src/main/java/org/apache/maven/tools/plugin/generator/HtmlToPlainTextConverter.java index 6ae47c866..de840f8f7 100644 --- a/maven-plugin-tools-generators/src/main/java/org/apache/maven/tools/plugin/generator/HtmlToPlainTextConverter.java +++ b/maven-plugin-tools-generators/src/main/java/org/apache/maven/tools/plugin/generator/HtmlToPlainTextConverter.java @@ -64,6 +64,7 @@ private static class FormattingVisitor implements NodeVisitor { private StringBuilder accum = new StringBuilder(); // holds the accumulated text + // Nested
 elements are invalid HTML; Jsoup normalises them before traversal.
         private int preformatted;
 
         // hit when the node is first seen
@@ -96,8 +97,6 @@ public void tail(Node node, int depth) {
                 preformatted--;
                 preformattedEndsWithNewline = accum.length() > 0 && accum.charAt(accum.length() - 1) == '\n';
                 accum.append(PRE_END);
-            }
-            if (name.equals("pre")) {
                 if (!preformattedEndsWithNewline) {
                     accum.append('\n');
                 }
diff --git a/maven-plugin-tools-generators/src/test/java/org/apache/maven/tools/plugin/generator/HtmlToPlainTextConverterTest.java b/maven-plugin-tools-generators/src/test/java/org/apache/maven/tools/plugin/generator/HtmlToPlainTextConverterTest.java
index c9b155dcf..95584ce52 100644
--- a/maven-plugin-tools-generators/src/test/java/org/apache/maven/tools/plugin/generator/HtmlToPlainTextConverterTest.java
+++ b/maven-plugin-tools-generators/src/test/java/org/apache/maven/tools/plugin/generator/HtmlToPlainTextConverterTest.java
@@ -94,6 +94,18 @@ void preformattedTextPreservesWhitespace() {
                 converter.convert(test));
     }
 
+    @Test
+    void preformattedTextWithoutTrailingNewlinePreservesWhitespace() {
+        assertEquals("before\n  first\n  second\nafter", converter.convert("before
  first\n  second
after")); + } + + @Test + void multiplePreformattedBlocksPreserveTheirBoundaries() { + assertEquals( + "one\n first\nmiddle\nsecond \nend", + converter.convert("one
  first
middle
second  
end")); + } + @ParameterizedTest(name = "{0} to {1}") // With JUnit 6.0.0 the non-printable chars will be kept in display, see // https://docs.junit.org/current/user-guide/#writing-tests-parameterized-tests-display-names-quoted-text @MethodSource("provideConvertParamsBreakLines") From 34a54d9dc2ee582f56db4b23b522ec9f35ce7ec4 Mon Sep 17 00:00:00 2001 From: Efe Date: Tue, 3 Nov 2026 21:26:39 +0300 Subject: [PATCH 4/6] Preserve consecutive explicit breaks in help descriptions --- .../tools/plugin/generator/HtmlToPlainTextConverter.java | 4 +++- .../plugin/generator/HtmlToPlainTextConverterTest.java | 6 ++++++ 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/maven-plugin-tools-generators/src/main/java/org/apache/maven/tools/plugin/generator/HtmlToPlainTextConverter.java b/maven-plugin-tools-generators/src/main/java/org/apache/maven/tools/plugin/generator/HtmlToPlainTextConverter.java index de840f8f7..d4b50a5ce 100644 --- a/maven-plugin-tools-generators/src/main/java/org/apache/maven/tools/plugin/generator/HtmlToPlainTextConverter.java +++ b/maven-plugin-tools-generators/src/main/java/org/apache/maven/tools/plugin/generator/HtmlToPlainTextConverter.java @@ -100,7 +100,9 @@ public void tail(Node node, int depth) { if (!preformattedEndsWithNewline) { accum.append('\n'); } - } else if (StringUtil.in(name, "br", "dd", "dt", "p", "h1", "h2", "h3", "h4", "h5")) { + } else if (name.equals("br")) { + accum.append('\n'); + } else if (StringUtil.in(name, "dd", "dt", "p", "h1", "h2", "h3", "h4", "h5")) { if (accum.length() == 0 || accum.charAt(accum.length() - 1) != '\n') { accum.append("\n"); } diff --git a/maven-plugin-tools-generators/src/test/java/org/apache/maven/tools/plugin/generator/HtmlToPlainTextConverterTest.java b/maven-plugin-tools-generators/src/test/java/org/apache/maven/tools/plugin/generator/HtmlToPlainTextConverterTest.java index 95584ce52..405ed505d 100644 --- a/maven-plugin-tools-generators/src/test/java/org/apache/maven/tools/plugin/generator/HtmlToPlainTextConverterTest.java +++ b/maven-plugin-tools-generators/src/test/java/org/apache/maven/tools/plugin/generator/HtmlToPlainTextConverterTest.java @@ -85,6 +85,12 @@ void explicitNewline() { converter.convert(test)); } + @Test + void consecutiveExplicitLineBreaksArePreserved() { + assertEquals("before\n\nafter", converter.convert("before

after")); + assertEquals("before\n\nafter\n", converter.convert("
before

after
")); + } + @Test void preformattedTextPreservesWhitespace() { String test = From 42488cff4d3353773655076d814fdfcc812a7240 Mon Sep 17 00:00:00 2001 From: Efe Date: Wed, 4 Nov 2026 04:29:37 +0300 Subject: [PATCH 5/6] fix: preserve preformatted spacing through help generation Encode preformatted spaces only in the limited help descriptor so both help templates preserve them during wrapping. Keep the public converter and standard descriptors unchanged, and exercise generated Maven 3 and Maven 4 help output. --- .../src/it/help-basic-jdk11/expected-help.txt | 3 ++ .../src/main/java/test/MyMojo.java | 2 + .../src/it/v4api-4x/invoker.properties | 2 + .../org/apache/maven/its/v4api/FirstMojo.java | 3 ++ .../src/it/v4api-4x/verify.groovy | 3 ++ .../generator/HtmlToPlainTextConverter.java | 20 ++++++-- .../PluginDescriptorFilesGenerator.java | 2 +- .../PluginDescriptorFilesGeneratorTest.java | 48 +++++++++++++++++++ 8 files changed, 78 insertions(+), 5 deletions(-) diff --git a/maven-plugin-plugin/src/it/help-basic-jdk11/expected-help.txt b/maven-plugin-plugin/src/it/help-basic-jdk11/expected-help.txt index 00577282b..52f8aeba8 100644 --- a/maven-plugin-plugin/src/it/help-basic-jdk11/expected-help.txt +++ b/maven-plugin-plugin/src/it/help-basic-jdk11/expected-help.txt @@ -16,6 +16,9 @@ help-jdk11:test https://example.test/plugin.exe + unindented code spaces + tabbed code spaces + defaultParam (Default: escape\backslash) This parameter uses "quotation" marks and backslashes '\\' in its description. Those characters must be escaped in Java string literals. diff --git a/maven-plugin-plugin/src/it/help-basic-jdk11/src/main/java/test/MyMojo.java b/maven-plugin-plugin/src/it/help-basic-jdk11/src/main/java/test/MyMojo.java index caae655b0..f583bdbd1 100644 --- a/maven-plugin-plugin/src/it/help-basic-jdk11/src/main/java/test/MyMojo.java +++ b/maven-plugin-plugin/src/it/help-basic-jdk11/src/main/java/test/MyMojo.java @@ -49,6 +49,8 @@ public class MyMojo extends AbstractMojo { * https://example.test/plugin.exe * * }
+ *
unindented  code   spaces
+     * 	tabbed  code   spaces
*/ @Parameter private String codeExample; diff --git a/maven-plugin-plugin/src/it/v4api-4x/invoker.properties b/maven-plugin-plugin/src/it/v4api-4x/invoker.properties index 5a80f791c..a4d493058 100644 --- a/maven-plugin-plugin/src/it/v4api-4x/invoker.properties +++ b/maven-plugin-plugin/src/it/v4api-4x/invoker.properties @@ -19,3 +19,5 @@ invoker.java.version = 17+ invoker.goals.1 = clean install invoker.goals.2 = org.apache.maven.its:v4api:1.0-SNAPSHOT:first invoker.maven.version = 4+ + +invoker.goals.3 = --log-file help.log org.apache.maven.its:v4api:1.0-SNAPSHOT:help diff --git a/maven-plugin-plugin/src/it/v4api-4x/src/main/java/org/apache/maven/its/v4api/FirstMojo.java b/maven-plugin-plugin/src/it/v4api-4x/src/main/java/org/apache/maven/its/v4api/FirstMojo.java index d2c3e17eb..967d6ec6e 100644 --- a/maven-plugin-plugin/src/it/v4api-4x/src/main/java/org/apache/maven/its/v4api/FirstMojo.java +++ b/maven-plugin-plugin/src/it/v4api-4x/src/main/java/org/apache/maven/its/v4api/FirstMojo.java @@ -35,6 +35,9 @@ * - it's using a custom lifecycle which is not defined * - it has a @Inject dependency on ArtifactInstaller (hint=test) which does not exist * + *
unindented  code   spaces
+ * 	tabbed  code   spaces
+ * * @since 1.2 */ @Mojo(name = "first", defaultPhase = "integration-test") diff --git a/maven-plugin-plugin/src/it/v4api-4x/verify.groovy b/maven-plugin-plugin/src/it/v4api-4x/verify.groovy index 1fed69783..9471ff1e5 100644 --- a/maven-plugin-plugin/src/it/v4api-4x/verify.groovy +++ b/maven-plugin-plugin/src/it/v4api-4x/verify.groovy @@ -80,4 +80,7 @@ assert parameter.expression.isEmpty() assert new File( basedir, "target/classes/org/apache/maven/its/v4api/HelpMojo.class" ).isFile() assert new File( basedir, "target/generated-sources/plugin/org/apache/maven/its/v4api/HelpMojo.java" ).isFile() +def helpLog = new File(basedir, "help.log").text.replace("\r", "") +assert helpLog.contains(" unindented code spaces\n tabbed code spaces") + return true; diff --git a/maven-plugin-tools-generators/src/main/java/org/apache/maven/tools/plugin/generator/HtmlToPlainTextConverter.java b/maven-plugin-tools-generators/src/main/java/org/apache/maven/tools/plugin/generator/HtmlToPlainTextConverter.java index d4b50a5ce..50ae9feab 100644 --- a/maven-plugin-tools-generators/src/main/java/org/apache/maven/tools/plugin/generator/HtmlToPlainTextConverter.java +++ b/maven-plugin-tools-generators/src/main/java/org/apache/maven/tools/plugin/generator/HtmlToPlainTextConverter.java @@ -37,11 +37,15 @@ public class HtmlToPlainTextConverter implements Converter { @Override public String convert(String text) { + return convert(text, false); + } + + String convert(String text, boolean preserveHelpWhitespace) { if (StringUtils.isBlank(text)) { return text; } Document document = Jsoup.parse(text); - return getPlainText(document); + return getPlainText(document, preserveHelpWhitespace); } /** @@ -50,8 +54,8 @@ public String convert(String text) { * @param element the root element to format * @return formatted text */ - private String getPlainText(Element element) { - FormattingVisitor formatter = new FormattingVisitor(); + private String getPlainText(Element element, boolean preserveHelpWhitespace) { + FormattingVisitor formatter = new FormattingVisitor(preserveHelpWhitespace); NodeTraversor.traverse(formatter, element); // walk the DOM, and call .head() and .tail() for each node return formatter.toString(); @@ -66,6 +70,11 @@ private static class FormattingVisitor implements NodeVisitor { // Nested
 elements are invalid HTML; Jsoup normalises them before traversal.
         private int preformatted;
+        private final boolean preserveHelpWhitespace;
+
+        FormattingVisitor(boolean preserveHelpWhitespace) {
+            this.preserveHelpWhitespace = preserveHelpWhitespace;
+        }
 
         // hit when the node is first seen
         public void head(Node node, int depth) {
@@ -128,7 +137,10 @@ public String toString() {
                     appendNormalText(result, text.substring(preStart + 1));
                     return result.toString();
                 }
-                result.append(text, preStart + 1, preEnd);
+                String preformattedText = text.substring(preStart + 1, preEnd);
+                // Help templates already decode NBSP after word wrapping. Keep spaces inside
+                // preformatted blocks out of that wrapping without changing ordinary descriptors.
+                result.append(preserveHelpWhitespace ? preformattedText.replace(' ', '\u00a0') : preformattedText);
                 start = preEnd + 1;
             }
             appendNormalText(result, text.substring(start));
diff --git a/maven-plugin-tools-generators/src/main/java/org/apache/maven/tools/plugin/generator/PluginDescriptorFilesGenerator.java b/maven-plugin-tools-generators/src/main/java/org/apache/maven/tools/plugin/generator/PluginDescriptorFilesGenerator.java
index e1f6ffdc8..75e9ddfaf 100644
--- a/maven-plugin-tools-generators/src/main/java/org/apache/maven/tools/plugin/generator/PluginDescriptorFilesGenerator.java
+++ b/maven-plugin-tools-generators/src/main/java/org/apache/maven/tools/plugin/generator/PluginDescriptorFilesGenerator.java
@@ -216,7 +216,7 @@ private static String getTextValue(DescriptorType type, boolean containsXhtmlVal
             xhtmlText = text;
         }
         if (type != DescriptorType.XHTML) {
-            return new HtmlToPlainTextConverter().convert(text);
+            return new HtmlToPlainTextConverter().convert(text, type == DescriptorType.LIMITED_FOR_HELP_MOJO);
         } else {
             return xhtmlText;
         }
diff --git a/maven-plugin-tools-generators/src/test/java/org/apache/maven/tools/plugin/generator/PluginDescriptorFilesGeneratorTest.java b/maven-plugin-tools-generators/src/test/java/org/apache/maven/tools/plugin/generator/PluginDescriptorFilesGeneratorTest.java
index 30803fb40..e0463a3a2 100644
--- a/maven-plugin-tools-generators/src/test/java/org/apache/maven/tools/plugin/generator/PluginDescriptorFilesGeneratorTest.java
+++ b/maven-plugin-tools-generators/src/test/java/org/apache/maven/tools/plugin/generator/PluginDescriptorFilesGeneratorTest.java
@@ -18,6 +18,8 @@
  */
 package org.apache.maven.tools.plugin.generator;
 
+import javax.xml.parsers.DocumentBuilderFactory;
+
 import java.io.BufferedReader;
 import java.io.File;
 import java.io.IOException;
@@ -25,6 +27,7 @@
 import java.io.StringReader;
 import java.io.StringWriter;
 import java.net.URI;
+import java.nio.file.Path;
 import java.util.List;
 
 import org.apache.maven.plugin.descriptor.DuplicateParameterException;
@@ -32,11 +35,17 @@
 import org.apache.maven.plugin.descriptor.Parameter;
 import org.apache.maven.plugin.descriptor.PluginDescriptor;
 import org.apache.maven.plugin.descriptor.PluginDescriptorBuilder;
+import org.apache.maven.project.MavenProject;
+import org.apache.maven.tools.plugin.DefaultPluginToolsRequest;
+import org.apache.maven.tools.plugin.ExtendedMojoDescriptor;
 import org.apache.maven.tools.plugin.javadoc.JavadocLinkGenerator;
 import org.codehaus.plexus.component.repository.ComponentDependency;
 import org.codehaus.plexus.configuration.PlexusConfiguration;
 import org.codehaus.plexus.util.ReaderFactory;
 import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.EnumSource;
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertNotNull;
@@ -46,6 +55,45 @@
  * @author Jason van Zyl 
  */
 class PluginDescriptorFilesGeneratorTest extends AbstractGeneratorTestCase {
+    @ParameterizedTest
+    @EnumSource(PluginDescriptorFilesGenerator.DescriptorType.class)
+    void preformattedWhitespaceIsEncodedOnlyForHelp(
+            PluginDescriptorFilesGenerator.DescriptorType type, @TempDir Path directory) throws Exception {
+        String description = "ordinary   prose
unindented  spaces\n\t tabbed  spaces  \n"
+                + "a  long  preformatted  line  that  must  not  lose  its  spaces\n"
+                + "
after prose"; + ExtendedMojoDescriptor mojo = new ExtendedMojoDescriptor(true); + mojo.setGoal("example"); + mojo.setImplementation("ExampleMojo"); + mojo.setDescription(description); + PluginDescriptor plugin = new PluginDescriptor(); + mojo.setPluginDescriptor(plugin); + plugin.addMojo(mojo); + File output = directory.resolve("plugin.xml").toFile(); + new PluginDescriptorFilesGenerator() + .writeDescriptor(output, new DefaultPluginToolsRequest(new MavenProject(), plugin), type); + String actual = ((org.w3c.dom.Element) DocumentBuilderFactory.newInstance() + .newDocumentBuilder() + .parse(output) + .getElementsByTagName("mojo") + .item(0)) + .getElementsByTagName("description") + .item(0) + .getTextContent(); + String plain = new HtmlToPlainTextConverter().convert(description); + if (type == PluginDescriptorFilesGenerator.DescriptorType.XHTML) { + assertEquals(description, actual); + } else if (type == PluginDescriptorFilesGenerator.DescriptorType.STANDARD) { + assertEquals(plain, actual); + } else { + assertEquals( + "ordinary prose\nunindented\u00a0\u00a0spaces\n\t\u00a0tabbed\u00a0\u00a0spaces\u00a0\u00a0\n" + + "a\u00a0\u00a0long\u00a0\u00a0preformatted\u00a0\u00a0line\u00a0\u00a0that\u00a0\u00a0must\u00a0\u00a0not\u00a0\u00a0lose\u00a0\u00a0its\u00a0\u00a0spaces\nafter prose", + actual); + assertEquals(plain, actual.replace('\u00a0', ' ')); + } + } + @Override protected void extendPluginDescriptor(PluginDescriptor pluginDescriptor) throws DuplicateParameterException { Parameter parameterWithGenerics = new Parameter(); From 5ab8e98761f8bdfb394c5975a9eb07613d94c1c7 Mon Sep 17 00:00:00 2001 From: Efe Date: Wed, 4 Nov 2026 04:58:19 +0300 Subject: [PATCH 6/6] docs: explain help whitespace encoding contract Document the limited help descriptor's NBSP transport and generated help decoding while distinguishing the ordinary converter behavior. --- .../plugin/generator/HtmlToPlainTextConverter.java | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/maven-plugin-tools-generators/src/main/java/org/apache/maven/tools/plugin/generator/HtmlToPlainTextConverter.java b/maven-plugin-tools-generators/src/main/java/org/apache/maven/tools/plugin/generator/HtmlToPlainTextConverter.java index 50ae9feab..69caa344a 100644 --- a/maven-plugin-tools-generators/src/main/java/org/apache/maven/tools/plugin/generator/HtmlToPlainTextConverter.java +++ b/maven-plugin-tools-generators/src/main/java/org/apache/maven/tools/plugin/generator/HtmlToPlainTextConverter.java @@ -40,6 +40,20 @@ public String convert(String text) { return convert(text, false); } + /** + * Converts (X)HTML to plain text, optionally encoding spaces inside {@code
} blocks
+     * as XML-safe non-breaking spaces (U+00A0) for the limited help descriptor.
+     * The generated help templates preserve these spaces during word wrapping and decode
+     * them to ordinary spaces on output. Ordinary prose keeps its existing wrapping behavior.
+     *
+     * 

{@link PluginDescriptorFilesGenerator} enables this only for + * {@code LIMITED_FOR_HELP_MOJO}; {@link #convert(String)} and standard descriptors + * retain ordinary spaces. + * + * @param text the (X)HTML to convert + * @param preserveHelpWhitespace whether to encode preformatted spaces for generated help + * @return the plain-text equivalent, with encoded preformatted spaces when requested + */ String convert(String text, boolean preserveHelpWhitespace) { if (StringUtils.isBlank(text)) { return text;