Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions maven-plugin-plugin/src/it/help-basic-jdk11/expected-help.txt
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,15 @@ help-jdk11:test

Available parameters:

codeExample
A parameter with a preformatted example.
<binary>
<url>https://example.test/plugin.exe</url>
</binary>

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.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,20 @@ public class MyMojo extends AbstractMojo {
@Parameter(defaultValue = "escape\\backslash")
private String defaultParam;

/**
* A parameter with a preformatted example.
*
* <pre>{@code
* <binary>
* <url>https://example.test/plugin.exe</url>
* </binary>
* }</pre>
* <pre>unindented code spaces
* tabbed code spaces</pre>
*/
@Parameter
private String codeExample;

/**
* This parameter is deprecated.
*
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,15 @@
* MOJO-DESCRIPTION. Some "quotation" marks and backslashes '\\', some <strong>important</strong> javadoc<br> and an
* inline link to {@link test.AnotherMojo}.
*
* Nested list:
* <ul>
* <li>Outer<ul><li>A nested item with enough words to exceed the help line width and preserve its indentation when rendered.</li></ul></li>
* </ul>
* <pre>
* first line
* second line
* </pre>
*
* @since 2.1
*/
@Deprecated
Expand Down
6 changes: 5 additions & 1 deletion maven-plugin-plugin/src/it/help-basic/help/expected-help.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,15 @@
* MOJO-DESCRIPTION. Some "quotation" marks and backslashes '\\', some <strong>important</strong> javadoc<br> and an
* inline link to {@link test.AnotherMojo}.
*
* Nested list:
* <ul>
* <li>Outer<ul><li>A nested item with enough words to exceed the help line width and preserve its indentation when rendered.</li></ul></li>
* </ul>
* <pre>
* first line
* second line
* </pre>
*
* @deprecated As of 1.0, use the "quoted" goal instead.
* @since 2.1
*/
Expand Down
2 changes: 2 additions & 0 deletions maven-plugin-plugin/src/it/v4api-4x/invoker.properties
Original file line number Diff line number Diff line change
Expand Up @@ -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
Original file line number Diff line number Diff line change
Expand Up @@ -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
*
* <pre>unindented code spaces
* tabbed code spaces</pre>
*
* @since 1.2
*/
@Mojo(name = "first", defaultPhase = "integration-test")
Expand Down
3 changes: 3 additions & 0 deletions maven-plugin-plugin/src/it/v4api-4x/verify.groovy
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Original file line number Diff line number Diff line change
Expand Up @@ -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 <pre>} 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.
*
* <p>{@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) {
Comment thread
gnodet marked this conversation as resolved.
Resolved
if (StringUtils.isBlank(text)) {
return text;
}
Document document = Jsoup.parse(text);
return getPlainText(document);
return getPlainText(document, preserveHelpWhitespace);
}

/**
Expand All @@ -50,27 +68,40 @@ 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();
}

// 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 <li> 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 <ul>/<ol>, used to indent nested <li> items

// Nested <pre> 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) {
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');
for (int i = 1; i < listDepth; i++) {
Expand All @@ -81,6 +112,12 @@ public void head(Node node, int depth) {
listDepth++;
} 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");
}
Expand All @@ -89,10 +126,22 @@ 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 (name.equals("ul") || name.equals("ol")) {
boolean preformattedEndsWithNewline = false;
if (name.equals("pre")) {
preformatted--;
preformattedEndsWithNewline = accum.length() > 0 && accum.charAt(accum.length() - 1) == '\n';
accum.append(PRE_END);
if (!preformattedEndsWithNewline) {
accum.append('\n');
}
Comment thread
gnodet marked this conversation as resolved.
Resolved
} 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");
}
} else 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
String link = node.absUrl("href");
Expand All @@ -104,12 +153,31 @@ public void tail(Node node, int depth) {

@Override
public String toString() {
// 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), " ");
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();
}
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));
return result.toString();
}

private static void appendNormalText(StringBuilder result, String text) {
String normalText =
text.replaceAll(" +", " ").replace("\n ", "\n").replace(String.valueOf(INDENT_MARKER), " ");
result.append(normalText.replaceAll(" +(?=\\n|$)", ""));
}
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -400,6 +418,30 @@ public class HelpMojo
int lineIndent = getIndentLevel( line );
StringBuilder buf = new StringBuilder( 256 );

// Preserve nested-list indentation (spaces) and preformatted indentation (NBSPs) instead of wrapping them.
if ( lineIndent < line.length()
&& ( line.charAt( lineIndent ) == ' ' || line.charAt( lineIndent ) == '\u00A0' ) )
{
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 )
Expand Down
Loading