From beface70acb283703436eca2bf4d9e35e164637b Mon Sep 17 00:00:00 2001
From: Arturo Bernal <abernal@apache.org>
Date: Thu, 29 Oct 2026 14:24:23 +0100
Subject: [PATCH] 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.
---
 .../generator/HtmlToPlainTextConverter.java   | 25 ++++++++++++++++---
 .../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 6906c75cf..fd52e0249 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 @@ private String getPlainText(Element element) {
 
     // 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 void head(Node node, int depth) {
             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 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")) {
+            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 void tail(Node node, int depth) {
 
         @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 1cbe3e603..a3a95de9b 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 @@ void wrongHtml() {
                 "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));
+    }
 }