Clarify different descriptor formats (#224)

Author: kwin

maven-plugin-tools-generators/src/main/java/org/apache/maven/tools/plugin/generator/PluginDescriptorFilesGenerator.java

@@ -52,7 +52,7 @@
  * 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 void writeDescriptor(File destinationFile, PluginToolsRequest request, De
             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 = "";

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>

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])