Skip to content

Commit

Permalink
Clarify different descriptor formats (#224)
Browse files Browse the repository at this point in the history
  • Loading branch information
kwin authored Sep 4, 2023
1 parent 0f837b5 commit 511d287
Show file tree
Hide file tree
Showing 3 changed files with 36 additions and 8 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down Expand Up @@ -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 = "";
Expand Down
34 changes: 31 additions & 3 deletions src/site/xdoc/index.xml
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
4 changes: 2 additions & 2 deletions src/site/xdoc/plugin-descriptors.mmd
Original file line number Diff line number Diff line change
Expand Up @@ -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])
Expand Down

0 comments on commit 511d287

Please sign in to comment.