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..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 @@ -10,6 +10,15 @@ help-jdk11:test Available parameters: + codeExample + A parameter with a preformatted example. + + 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 480fdbc77..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 @@ -41,6 +41,20 @@ public class MyMojo extends AbstractMojo { @Parameter(defaultValue = "escape\\backslash") private String defaultParam; + /** + * A parameter with a preformatted example. + * + *
{@code
+     *   
+     *     https://example.test/plugin.exe
+     *   
+     * }
+ *
unindented  code   spaces
+     * 	tabbed  code   spaces
+ */ + @Parameter + private String codeExample; + /** * This parameter is deprecated. * diff --git a/maven-plugin-plugin/src/it/help-basic/help-deprecated-annotation-only/expected-help.txt b/maven-plugin-plugin/src/it/help-basic/help-deprecated-annotation-only/expected-help.txt index c3aeb824a..53559d209 100644 --- a/maven-plugin-plugin/src/it/help-basic/help-deprecated-annotation-only/expected-help.txt +++ b/maven-plugin-plugin/src/it/help-basic/help-deprecated-annotation-only/expected-help.txt @@ -6,7 +6,11 @@ help-deprecated-annotation-only:test MOJO-DESCRIPTION. Some "quotation" marks and backslashes '\\', some important javadoc - and an inline link to test.AnotherMojo . + and an inline link to test.AnotherMojo . Nested list: + * Outer + * A nested item with enough words to exceed the help line width and preserve its indentation when rendered. + first line + second line Available parameters: diff --git a/maven-plugin-plugin/src/it/help-basic/help-deprecated-annotation-only/src/main/java/test/MyMojo.java b/maven-plugin-plugin/src/it/help-basic/help-deprecated-annotation-only/src/main/java/test/MyMojo.java index 73ea59107..e8d82be62 100644 --- a/maven-plugin-plugin/src/it/help-basic/help-deprecated-annotation-only/src/main/java/test/MyMojo.java +++ b/maven-plugin-plugin/src/it/help-basic/help-deprecated-annotation-only/src/main/java/test/MyMojo.java @@ -26,6 +26,15 @@ * MOJO-DESCRIPTION. Some "quotation" marks and backslashes '\\', some important javadoc
and an * inline link to {@link test.AnotherMojo}. * + * Nested list: + * + *
+ *   first  line
+ *     second  line
+ * 
+ * * @since 2.1 */ @Deprecated diff --git a/maven-plugin-plugin/src/it/help-basic/help/expected-help.txt b/maven-plugin-plugin/src/it/help-basic/help/expected-help.txt index 2bed0f0d1..b59187f78 100644 --- a/maven-plugin-plugin/src/it/help-basic/help/expected-help.txt +++ b/maven-plugin-plugin/src/it/help-basic/help/expected-help.txt @@ -6,7 +6,11 @@ help:test MOJO-DESCRIPTION. Some "quotation" marks and backslashes '\\', some important javadoc - and an inline link to test.AnotherMojo . + and an inline link to test.AnotherMojo . Nested list: + * Outer + * A nested item with enough words to exceed the help line width and preserve its indentation when rendered. + first line + second line Available parameters: diff --git a/maven-plugin-plugin/src/it/help-basic/help/src/main/java/test/MyMojo.java b/maven-plugin-plugin/src/it/help-basic/help/src/main/java/test/MyMojo.java index 480fdbc77..1051c7a93 100644 --- a/maven-plugin-plugin/src/it/help-basic/help/src/main/java/test/MyMojo.java +++ b/maven-plugin-plugin/src/it/help-basic/help/src/main/java/test/MyMojo.java @@ -26,6 +26,15 @@ * MOJO-DESCRIPTION. Some "quotation" marks and backslashes '\\', some important javadoc
and an * inline link to {@link test.AnotherMojo}. * + * Nested list: + * + *
+ *   first  line
+ *     second  line
+ * 
+ * * @deprecated As of 1.0, use the "quoted" goal instead. * @since 2.1 */ 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 fd52e0249..919e793e2 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,29 @@ public class HtmlToPlainTextConverter implements Converter { @Override 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; } Document document = Jsoup.parse(text); - return getPlainText(document); + return getPlainText(document, preserveHelpWhitespace); } /** @@ -50,8 +68,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(); @@ -59,18 +77,31 @@ 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'; + // Placeholder for indentation spaces that must survive the whitespace cleanup in toString(), which // otherwise collates any run of real spaces -- including nested

  • indentation -- down to one. - private static final char INDENT_MARKER = '\u0001'; + private static final char INDENT_MARKER = '\u0003'; private StringBuilder accum = new StringBuilder(); // holds the accumulated text private int listDepth = 0; // nesting depth of the current