This is an automated email from the ASF dual-hosted git repository. kwin pushed a commit to branch feature/clarify-plugin-descriptors in repository https://gitbox.apache.org/repos/asf/maven-plugin-tools.git
commit 6ec0c38fcca9d6c99899de9506596d1ac792a344 Author: Konrad Windszus <[email protected]> AuthorDate: Thu Aug 31 20:21:40 2023 +0200 Clarify different descriptor formats --- .../generator/PluginDescriptorFilesGenerator.java | 6 ++-- src/site/xdoc/index.xml | 34 ++++++++++++++++++++-- src/site/xdoc/plugin-descriptors.mmd | 4 +-- 3 files changed, 36 insertions(+), 8 deletions(-) diff --git a/maven-plugin-tools-generators/src/main/java/org/apache/maven/tools/plugin/generator/PluginDescriptorFilesGenerator.java b/maven-plugin-tools-generators/src/main/java/org/apache/maven/tools/plugin/generator/PluginDescriptorFilesGenerator.java index f0c485b8..7a0d9335 100644 --- a/maven-plugin-tools-generators/src/main/java/org/apache/maven/tools/plugin/generator/PluginDescriptorFilesGenerator.java +++ b/maven-plugin-tools-generators/src/main/java/org/apache/maven/tools/plugin/generator/PluginDescriptorFilesGenerator.java @@ -52,7 +52,7 @@ import static java.nio.charset.StandardCharsets.UTF_8; * Serializes * <ol> * <li>a standard <a href="/ref/current/maven-plugin-api/plugin.html">Maven Plugin Descriptor XML file</a></li> - * <li>a descriptor containing a limited set of attributes for {@link PluginHelpGenerator}</li> + * <li>a descriptor containing a limited set of elements for {@link PluginHelpGenerator}</li> * <li>an enhanced descriptor containing HTML values for some elements (instead of plain text as for the other two) * for {@link PluginXdocGenerator}</li> * </ol> @@ -116,10 +116,10 @@ public class PluginDescriptorFilesGenerator implements Generator { final String additionalInfo; switch (type) { case LIMITED_FOR_HELP_MOJO: - additionalInfo = " (for help'mojo with additional elements)"; + additionalInfo = " (for help mojo with limited elements)"; break; case XHTML: - additionalInfo = " (enhanced XHTML version with additional elements (used for plugin:report))"; + additionalInfo = " (enhanced XHTML version (used for plugin:report))"; break; default: additionalInfo = ""; diff --git a/src/site/xdoc/index.xml b/src/site/xdoc/index.xml index 008c1403..e62096ae 100644 --- a/src/site/xdoc/index.xml +++ b/src/site/xdoc/index.xml @@ -122,15 +122,43 @@ </table> <subsection name="Plugin Descriptors"> - <p>The plugin descriptor is first being generated in memory finally containing some values in HTML format before being persisted into three different formats. + <p>The plugin descriptor is first being generated in memory finally containing some values in HTML format before being persisted into three different XML files. The formats differ in <ul> - <li>whether they contain extended attributes (not part of the <a href="https://maven.apache.org/ref/current/maven-plugin-api/plugin.html";>Plugin Descriptor Spec</a></li> - <li>whether descriptive values contain HTML or plain text</li> + <li>whether they contain all elements or just a limited set of elements defined by the <a href="https://maven.apache.org/ref/current/maven-plugin-api/plugin.html";>Plugin Descriptor Spec</a></li> + <li>whether descriptive elements contain HTML or plain text values</li> + <li>whether they are packaged in the resulting JAR or not</li> </ul> Javadoc tags are in general being resolved and replaced by their XHTML value before they end up in the according plugin descriptor attributes <code>description</code> and <code>deprecated</code>. Also javadoc code links via <code>{@link}</code> or <code>@see</code> are replaced by links to the according Javadoc pages if configured accordingly. + Plaintext is afterwards being generated out of the XHTML (where most XHTML element are just stripped and links are emitted inside angle brackets). </p> + <table> + <tr> + <th>File name</th> + <th>Allows HTML</th> + <th>Limited Elements</th> + <th>Contained in JAR</th> + </tr> + <tr> + <td>plugin.xml</td> + <td>no</td> + <td>no</td> + <td>yes</td> + </tr> + <tr> + <td>plugin-help.xml</td> + <td>no</td> + <td>yes</td> + <td>yes</td> + </tr> + <tr> + <td>plugin-enhanced.xml</td> + <td>no</td> + <td>yes</td> + <td>no (volatile file)</td> + </tr> + </table> <p> <img src="images/plugin-descriptors.svg" width="759" border="0" /> </p> diff --git a/src/site/xdoc/plugin-descriptors.mmd b/src/site/xdoc/plugin-descriptors.mmd index 5a78273b..8a5e0f35 100644 --- a/src/site/xdoc/plugin-descriptors.mmd +++ b/src/site/xdoc/plugin-descriptors.mmd @@ -8,8 +8,8 @@ flowchart LR P3 --> |populates| P4 subgraph output["Plugin Descriptors Serializations"] O1(["plugin.xml (plain text)"]) - O2(["plugin-help.xml (plain text)"]) - O3(["plugin-enhanced.xml (html)"]) + O2(["plugin-help.xml (plain text with extended elements)"]) + O3(["plugin-enhanced.xml (html, transient, not part of final JAR)"]) end subgraph generators["maven-plugin-tools-generators"] G1["PluginXdocGenerator"] --> |generates| R2([XDoc])
