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));
+ }
}