This is an automated email from the ASF dual-hosted git repository.

kwin pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-plugin-tools.git


The following commit(s) were added to refs/heads/master by this push:
     new 743fd6a6 Fix #807: helpmojo flattens nested lists in javadoc
743fd6a6 is described below

commit 743fd6a609ff90a1dba64dd7907ced09fd98ecd2
Author: Arturo Bernal <[email protected]>
AuthorDate: Thu Oct 29 14:24:23 2026 +0100

    Fix #807: helpmojo flattens nested lists in javadoc
    
    HtmlToPlainTextConverter.FormattingVisitor appended "\n * " for every
    <li> regardless of nesting depth, and its cleanup step collated any
    run of spaces -- including indentation meant to show nesting -- down
    to one. A nested <ul>/<li> structure in a Mojo's or parameter's
    javadoc always rendered as one flat bullet level in the plain-text
    output used by mvn <plugin>:help, losing the nesting the javadoc
    author intended.
    
    FormattingVisitor now tracks <ul>/<ol> nesting depth and indents each
    <li> accordingly, using a placeholder character for the indentation
    spaces so the existing space-collation cleanup doesn't erase it --
    the placeholder is only expanded to real spaces as the last step of
    toString(). Added tests for a single-level list (unchanged output), a
    nested list, and a doubly-nested list.
---
 .../plugin/generator/HtmlToPlainTextConverter.java | 25 ++++++++++++++++++----
 .../generator/HtmlToPlainTextConverterTest.java    | 18 ++++++++++++++++
 2 files changed, 39 insertions(+), 4 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 6906c75c..fd52e024 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,7 +59,12 @@ public class HtmlToPlainTextConverter implements Converter {
 
     // the formatting rules, implemented in a breadth-first DOM traverse
     private static class FormattingVisitor implements NodeVisitor {
+        // Placeholder for indentation spaces that must survive the whitespace 
cleanup in toString(), which
+        // otherwise collates any run of real spaces -- including nested <li> 
indentation -- down to one.
+        private static final char INDENT_MARKER = '\u0001';
+
         private StringBuilder accum = new StringBuilder(); // holds the 
accumulated text
+        private int listDepth = 0; // nesting depth of the current <ul>/<ol>, 
used to indent nested <li> items
 
         // hit when the node is first seen
         public void head(Node node, int depth) {
@@ -67,7 +72,13 @@ public class HtmlToPlainTextConverter implements Converter {
             if (node instanceof TextNode) {
                 accum.append(((TextNode) node).text()); // TextNodes carry all 
user-readable text in the DOM.
             } else if (name.equals("li")) {
-                accum.append("\n * ");
+                accum.append('\n');
+                for (int i = 1; i < listDepth; i++) {
+                    accum.append(INDENT_MARKER).append(INDENT_MARKER);
+                }
+                accum.append("* ");
+            } else if (name.equals("ul") || name.equals("ol")) {
+                listDepth++;
             } else if (name.equals("dt")) {
                 accum.append("  ");
             } else if (StringUtil.in(name, "p", "h1", "h2", "h3", "h4", "h5", 
"tr")) {
@@ -78,7 +89,9 @@ public class HtmlToPlainTextConverter implements Converter {
         // 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")) {
+            if (name.equals("ul") || name.equals("ol")) {
+                listDepth = Math.max(0, listDepth - 1);
+            } else if (StringUtil.in(name, "br", "dd", "dt", "p", "h1", "h2", 
"h3", "h4", "h5")) {
                 accum.append("\n");
             } else if (name.equals("a")) {
                 // link is empty if it cannot be made absolute
@@ -91,8 +104,12 @@ public class HtmlToPlainTextConverter implements Converter {
 
         @Override
         public String toString() {
-            // collate multiple consecutive spaces
-            return accum.toString().replaceAll(" +", " ").replace("\n ", "\n");
+            // collate multiple consecutive spaces, then turn the indentation 
placeholders -- untouched by the
+            // collation above since they aren't spaces -- into the real 
spaces they stand for.
+            return accum.toString()
+                    .replaceAll(" +", " ")
+                    .replace("\n ", "\n")
+                    .replace(String.valueOf(INDENT_MARKER), " ");
         }
     }
 }
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 1cbe3e60..a3a95de9 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
@@ -114,4 +114,22 @@ class HtmlToPlainTextConverterTest {
                 "Generates something for the project.",
                 converter.convert("Generates <i>something</i> <b>for the 
project."));
     }
+
+    @Test
+    void singleLevelList() {
+        String test = "<ul><li>Item one</li><li>Item two</li></ul>";
+        assertEquals("\n* Item one\n* Item two", converter.convert(test));
+    }
+
+    @Test
+    void nestedListIsIndented() {
+        String test = "<ul><li>Outer one<ul><li>Inner one</li><li>Inner 
two</li></ul></li><li>Outer two</li></ul>";
+        assertEquals("\n* Outer one\n  * Inner one\n  * Inner two\n* Outer 
two", converter.convert(test));
+    }
+
+    @Test
+    void doublyNestedListIndentsFurther() {
+        String test = "<ul><li>Level one<ul><li>Level two<ul><li>Level 
three</li></ul></li></ul></li></ul>";
+        assertEquals("\n* Level one\n  * Level two\n    * Level three", 
converter.convert(test));
+    }
 }

Reply via email to