brett 2004/11/24 00:42:37
Modified: xdocs/using developing-plugins.xml
xdocs/reference 3rdparty.xml sharing-plugins.xml
xdocs/developers building-from-source.xml
Log:
documentation updates
Revision Changes Path
1.2 +35 -11 maven/xdocs/using/developing-plugins.xml
Index: developing-plugins.xml
===================================================================
RCS file: /home/cvs/maven/xdocs/using/developing-plugins.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- developing-plugins.xml 22 Nov 2004 11:52:59 -0000 1.1
+++ developing-plugins.xml 24 Nov 2004 08:42:37 -0000 1.2
@@ -23,6 +23,7 @@
<title>Developing Plugins</title>
<author email="[EMAIL PROTECTED]">Jason van Zyl</author>
<author email="[EMAIL PROTECTED]">Pete Kazmier</author>
+ <author email="[EMAIL PROTECTED]">Brett Porter</author>
</properties>
<body>
@@ -160,9 +161,9 @@
</p>
<source>hello.greeting=Hi</source>
<p>
- Edit the <code>plugin.jelly</code> file so that the
<code><echo></code> line reads:
+ Edit the <code>plugin.jelly</code> file so that the
<code><ant:echo></code> line reads:
</p>
- <source><![CDATA[<echo>${hello.greeting} from a Maven
Plug-in</echo>]]></source>
+ <source><![CDATA[<ant:echo>${hello.greeting} from a Maven
Plug-in</ant:echo>]]></source>
<p>
Now, install the new plugin and run it (<b>note</b>, you do not
need to run <code>maven plugin</code> first):
</p>
@@ -182,15 +183,28 @@
<p>
You can use plugin resources to be able to load external files
from inside a plugin.
Let's say you wanted to copy an image into every site. First, add
a file called
- <code>src/plugin-resources/hello.gif</code> to the source tree.
Then, you can add the following
- to your <code>hello:hello</code> goal in <code>plugin.jelly</code>.
+ <code>src/plugin-resources/hello-report.xml</code> to the source
tree that looks like this:
</p>
- <source><![CDATA[...
-<ant:copy todir="${maven.docs.dest}/images"
file="${plugin.resources}/hello.gif" />
+ <source><![CDATA[<document>
+ <body>
+ <section name="Hello">
+ <p>Hi!</p>
+ </section>
+ </body>
+</document>]]></source>
+ <p>
+ Next, you can create a new goal called <code>hello:report</code>
+ in <code>plugin.jelly</code>.
+ </p>
+ <source><![CDATA[...
+ <goal name="hello:report">
+ <ant:copy todir="${maven.gen.docs}"
file="${plugin.resources}/hello-report.xml" />
+ </goal>
...]]></source>
<p>
The plugin resources become most useful when you have templates
for generate site reports
- based on the project, which is discussed in the next section.
+ based on the project, which is discussed in the next section. This
report goal will be used
+ to "generate" the Hello Report.
</p>
</subsection>
<subsection name="Providing Reports in a Plugin">
@@ -214,7 +228,8 @@
<p>
To register a report withing your project, you should define three
goals (using hello as the example):
<ul>
- <li><code>hello:report</code> - generates the report
content.</li>
+ <li><code>hello:report</code> - generates the report content.
This was the goal we created in the
+ previous section.</li>
<li><code>hello:register</code> - registers the report with
Maven for inclusion on the site</li>
<li><code>hello:deregister</code> - disables the report so that
a project can override a previous
enabling command</li>
@@ -303,7 +318,7 @@
<p>
The <code>name</code> parameter should correspond to the original
registration <code>name</code> parameter.
</p>
- <source><![CDATA[<goal name="maven-javadoc-plugin:deregister">
+ <source><![CDATA[<goal name="hello:deregister">
<doc:deregisterReport name="Hello"/>
</goal>]]></source>
<p>
@@ -312,9 +327,18 @@
</p>
<source><![CDATA[<reports>
<report>hello</report>
-</reports>
- ]]></source>
+</reports>]]></source>
+ <p>
+ You can add this to any project, but for now we'll just reuse the
same plugin project to test the plugin on.
+ Add the above section to the <code>project.xml</code> you've
created, then run:
+ </p>
+ <source>maven site</source>
+ <p>
+ Notice the final result of a
<code>target/docs/hello-report.html</code> file. You can view this in your
+ browser. When doing so, you'll also see the "Hello" item under the
"Project Reports" menu in the navigation.
+ </p>
</subsection>
+ <!-- TODO: later, talk about how to write in Java and include via
Jellybean Tag -->
</section>
<section name="Sharing Your Plugin">
1.2 +1 -1 maven/xdocs/reference/3rdparty.xml
Index: 3rdparty.xml
===================================================================
RCS file: /home/cvs/maven/xdocs/reference/3rdparty.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- 3rdparty.xml 22 Nov 2004 11:52:58 -0000 1.1
+++ 3rdparty.xml 24 Nov 2004 08:42:37 -0000 1.2
@@ -35,7 +35,7 @@
<subsection name="Maven Plugins Project @ sf.net">
<p>
The <a href="http://maven-plugins.sf.net/";>Maven Plugins
Project</a> at SourceForge develops a series of
- plugins. <!-- TODO: examples, explain reason? -->
+ plugins.
</p>
</subsection>
<subsection name="Independant Plugins">
1.2 +100 -136 maven/xdocs/reference/sharing-plugins.xml
Index: sharing-plugins.xml
===================================================================
RCS file: /home/cvs/maven/xdocs/reference/sharing-plugins.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- sharing-plugins.xml 22 Nov 2004 11:52:58 -0000 1.1
+++ sharing-plugins.xml 24 Nov 2004 08:42:37 -0000 1.2
@@ -20,20 +20,19 @@
<document>
<properties>
- <author email="[EMAIL PROTECTED]">Tim Shadel</author>
<title>Sharing your plugin</title>
+ <author email="[EMAIL PROTECTED]">Tim Shadel</author>
+ <author email="[EMAIL PROTECTED]">Brett Porter</author>
</properties>
<body>
-<!-- TODO
- <section name="Overview">
+ <section name="Sharing Plugins">
<p>
- You've just created a killer Maven plugin. Now what?!
+ You've just created a killer Maven plugin. Now what?!
+ </p>
+ <p>
+ Where should plugins live? Who can update them? Does it really
make a difference?
</p>
- </section>
-
- <section name="Plugin Maintenance">
- <p>Where should plugins live? Who can update them? Does it really
make a difference?</p>
<subsection name="Can you put my plugin in the Maven distribution?">
<p>
The main Maven distribution includes many plugins, but the growing
trend is for plugin owners to host
@@ -43,151 +42,116 @@
</subsection>
<subsection name="Plugin owners are the best maintainers">
- <p>Since only Maven committers may update the
<code>maven-plugins</code> repository, changes you make to your
- plugin will take a while to make it into a Maven distribution.
Each plugin needs a committer willing to
- maintain it, and that plugin is not the only piece of Maven the
committer works on.</p>
-
- <p>Plugin owners are in a much better position to maintain the
plugin. They originally wrote the plugin.
- They have a vested interest in seeing it succeed. If they <a
href="#Step_1__How_do_I_host_my_Maven_plugin_">host</a>
- the plugin themselves, then updates can be incorporated quickly,
and users get the benefits of updated software
- quicker.</p>
-
- <p>This benefit is often maximized when a team that writes a
library, like the StatCvs group, also creates the Maven
- plugin. As the library changes, the plugin may be updated to
keep in sync. In fact, the
- <a
href="http://jakarta.apache.org/cactus/integration/maven/";>Cactus</a> and
- <a href="http://statcvs-xml.berlios.de/maven-plugin/";>StatCvs</a>
- plugins were among the first to voluntarily remove their plugins
from the Maven distribution and be hosted
- with their respective libraries.</p>
+ <p>
+ Since only Maven committers may update the
<code>maven-plugins</code> repository, changes you make to your
+ plugin will take a while to make it into a Maven distribution.
Each plugin needs a committer willing to
+ maintain it, and that plugin is not the only piece of Maven the
committer works on.
+ </p>
+ <p>
+ Plugin owners are in a much better position to maintain the
plugin. They originally wrote the plugin.
+ They have a vested interest in seeing it succeed. If they
+ <a href="#Step_1__How_do_I_host_my_Maven_plugin_">host</a> the
plugin themselves, then updates can be
+ incorporated quickly, and users get the benefits of updated
software quicker.
+ </p>
+ <p>
+ This benefit is often maximized when a team that writes a library,
like the StatCvs group, also creates the
+ Maven plugin. As the library changes, the plugin may be updated
to keep in sync. In fact, the
+ <a
href="http://jakarta.apache.org/cactus/integration/maven/";>Cactus</a> and
+ <a href="http://statcvs-xml.berlios.de/maven-plugin/";>StatCvs</a>
+ plugins were among the first to voluntarily remove their plugins
from the Maven distribution and be hosted
+ with their respective libraries.
+ </p>
</subsection>
-
</section>
<section name="Publishing Your Plugin">
<subsection name="Step 1. How do I host my Maven plugin?">
- <p>To "host" a Maven plugin, you require only two things:</p>
- <ul>
- <li>A place to keep your source code</li>
- <li>A website to deploy the following
- <ul>
- <li>Your plugin's site (<code>maven site</code>)
documentation</li>
- <li>Your plugin's JAR bundles for ibiblio upload requests</li>
- </ul>
- </li>
- </ul>
- <p>There are a variety of options available for each need. Your
source code may simply be kept on your hard
- drive, using a local installation of a version control tool like
<a href="http://www.cvshome.org/";>CVS</a> or
- <a href="http://subversion.tigris.org/";>Subversion</a> (you do
use version control, don't you?). If you'd like to
- share your plugin source with others, you can request a new
project at a service like <a href="http://sf.net";>SourceForge</a>
- or <a href="http://java.net";>Java.Net</a>, or request to join an
existing project like the
- <a href="http://maven-plugins.sourceforge.net/";>Maven-Plugins</a>
project on SourceForge.</p>
-
- <p>If you're creating a plugin for an existing open-source (or even
closed-source) library, the ideal situation is
- to approach the library maintainers about hosting your plugin
source and site. That way the plugin source is close to
- the people most likely to care about its success, and ensure it
works well far into the future. The plugin site
- is located close to the already well-known library site. In the
end, this cooperation means a better chance at happy
- users, and up-to-date plugins for everyone.</p>
+ <p>
+ To "host" a Maven plugin, you require only two things:
+ <ul>
+ <li>A place to keep your source code</li>
+ <li>A website to deploy the following
+ <ul>
+ <li>Your plugin's site (<code>maven site</code>)
documentation</li>
+ <li>Your plugin's JAR bundles for ibiblio upload
requests</li>
+ </ul>
+ </li>
+ </ul>
+ </p>
+ <p>
+ There are a variety of options available for each need. Your
source code may simply be kept on your hard
+ drive, using a local installation of a version control tool like
<a href="http://www.cvshome.org/";>CVS</a> or
+ <a href="http://subversion.tigris.org/";>Subversion</a> (you do use
version control, don't you?). If you'd
+ like to share your plugin source with others, you can request a
new project at a service like
+ <a href="http://sf.net";>SourceForge</a> or <a
href="http://java.net";>Java.Net</a>, or request to join an
+ existing project like the <a
href="http://maven-plugins.sourceforge.net/";>Maven-Plugins</a> project on
+ SourceForge.
+ </p>
+ <p>
+ If you're creating a plugin for an existing open-source (or even
closed-source) library, the ideal situation
+ is to approach the library maintainers about hosting your plugin
source and site. That way the plugin source
+ is close to the people most likely to care about its success, and
ensure it works well far into the future.
+ The plugin site is located close to the already well-known library
site. In the end, this cooperation means
+ a better chance at happy users, and up-to-date plugins for
everyone.
+ </p>
</subsection>
<subsection name="Step 2. OK. My plugin has a host, how can I put it
on ibiblio.org?" id="upload">
- <p>Please see the <a
href="../../repository-upload.html">instructions</a> for uploading a resource
to ibiblio.org.</p>
+ <p>
+ If the project is part of the repository mirroring program, such
as <code>maven-plugins.sf.net</code>,
+ publishing it at SourceForge will automatically mirror it to
ibiblio with further work.
+ </p>
- <p><strong>NOTE:</strong> If your plugin requires resources (JAR
files) that are not already at ibilio.org, you
- may need to make several separate upload requests.</p>
+ <p>
+ However, if the project is an independant, please see the
+ <a href="../reference/repository-upload.html">instructions</a> for
uploading a resource to ibiblio.org.
+ </p>
+
+ <p>
+ <strong>NOTE:</strong> If your plugin requires resources (JAR
files) that are not already at ibilio.org, you
+ may need to make several separate upload requests.
+ </p>
</subsection>
<subsection name="Step 3. My upload request was granted, but no one
knows my plugin exists!">
- <p>There are two ways to let your potential users know about your
plugin. The first is through sending an announcement
- to the <code>maven-user</code> mailing list. Here's a few
pointers on how to go about it:</p>
- <ul>
- <li>Read <a href="releasing-plugins.html">Releasing
Plugins</a>, concentrating on the announcement portion.</li>
- <li>Review an <a
href="http://www.mail-archive.com/users@maven.apache.org/msg09117.html";>excellent
announcement</a>
- sent by the StatCvs group, which includes
- <a
href="#Step_4_So_now_that_they_found_my_plugin_how_do_users_install_it_">plugin
installation instructions</a>.</li>
- <li>Combine the advice of the two parts to make your own
effective announcement.</li>
- <li>Make sure you've subscribed to the <code>maven-user</code>
mailing list.</li>
- <li>Send your annoucement to the <code>maven-user</code>
mailing list.</li>
- </ul>
- <p>The second way to publicize your plugin is on the Maven site
itself. The Maven project currently maintains a list of
- other sites that host plugins. The best way to get your link on
this page is to get the Maven source, and submit a
- patch to the list file itself. Here are the steps in a bit more
detail.</p>
- <ul>
- <li>Get the <code>maven-plugins</code> source as described <a
href="http://maven.apache.org/reference/plugins/cvs-usage.html";>here</a>.</li>
- <li>Open the file
<code>MAVEN_PLUGINS_SOURCE/xdocs/index.xml</code>.</li>
- <li>If your plugin host is not listed, add the following, so your
site's name falls <strong>in alphabetical order</strong>
- with the rest of the site list (except for the Maven site
itself).
- <source><![CDATA[
-<subsection name="Plugins on the [plugin host site name] site">
- <table>
- <tr>
- <td><a href="http://www.example.com/plugin";>Example plugin</a></td>
- <td>Plugin for Example Documentation</td>
- </tr>
- </table>
-</subsection>
- ]]></source>
- </li>
- <li>If your plugin host is already listed, add the table row
(<code><tr></code>) portion above to your
- host's section. Order your plugins appropriately within your
host section.</li>
- <li>Now follow the <a
href="http://wiki.codehaus.org/maven/SubmittingPatches";>guidelines for creating
a Maven patch</a>,
- and submit your patch to <a
href="http://jira.codehaus.org";>JIRA</a>. Use the project <code>maven</code>
- (<a
href="http://jira.codehaus.org/secure/BrowseProject.jspa?id=10030";>here</a>)
and the <code>documentation</code> component.
- Place a note in your JIRA issue telling the developer that your
patch is against the <code>maven-plugins</code> documentation.</li>
- <li>Once your patch is applied, and the Maven site is redeployed,
you'll have a link to your plugin's home page from the Maven site.</li>
- </ul>
+ <p>
+ There are two ways to let your potential users know about your
plugin. The first is through sending an
+ announcement to the <code>maven-user</code> mailing list. Here's
a few pointers on how to go about it:
+ <ul>
+<!-- TODO: fix link -->
+ <li>
+ Read <a href="releasing-plugins.html">Releasing Plugins</a>,
concentrating on the announcement portion.
+ </li>
+ <li>
+ Review an <a
href="http://www.mail-archive.com/users@maven.apache.org/msg09117.html";>excellent
+ announcement</a> sent by the StatCvs group, which includes
plugin installation instructions.
+ </li>
+ <li>
+ Combine the advice of the two parts to make your own effective
announcement. You may like to use
+ the <a href="../reference/plugins/announcement/">Announcement
Plugin</a> to generate and perhaps
+ mail the announcement.
+ </li>
+ <li>Make sure you've subscribed to the <code>maven-user</code>
mailing list.</li>
+ <li>Send your annoucement to the <code>maven-user</code> mailing
list.</li>
+ </ul>
+ </p>
+ <p>
+ The second way to publicize your plugin is on the Maven site
itself. The Maven project currently maintains a
+ list of other sites that host plugins. Simply raise a request in
JIRA to have a link added. Be sure to include
+ the relevant information, following an existing plugin's
description as an example.
+ </p>
</subsection>
<subsection name="Step 4. So now that they found my plugin, how do
users install it?">
- <p>Here's the general idea:</p>
- <source>maven plugin:download -DartifactId=[plugin-name]
-DgroupId=[plugin-group] -Dversion=[plugin-version]</source>
- <p>For example:</p>
+ <p>
+ Here's the general idea:
+ </p>
+ <source>maven plugin:download -DartifactId=[artifactId]
-DgroupId=[groupId] -Dversion=[version]</source>
+ <p>
+ For example:
+ </p>
<source>maven plugin:download -DartifactId=maven-statcvs-plugin
-DgroupId=statcvs -Dversion=2.4</source>
-
</subsection>
-
- <section name="Related Links">
- <subsection name="Official Maven Documentation">
- <p>Documentation maintained by Maven committers:</p>
- <ul>
- <li><a href="developer-guide.html">Developer Guide</a>: Start
here. This
- provides the most clear and comprehensive start to writing
Maven plugins.</li>
- <li><a href="releasing-plugins.html">Releasing Plugins</a>:
- Maven documentaion for contributors modifying a Maven plugin.
Look for ways to have your own project follow
- similar standards.</li>
- <li><a
href="http://maven.apache.org/reference/plugins/index.html";>Plugins</a>: Lists
sites that host Maven plugins.</li>
- <li><a href="../../repository-upload.html">Repository Upload
Instructions</a>: How to request your
- resources be uploaded to ibiblio.org. A must read. Watch it
for updates, and carefully follow the most recent
- instructions to give your resource the best chance of quick
processing.</li>
- <li><a href="../../faq.html">FAQ</a>: Read it. Use it. Love it.
Live it.</li>
- </ul>
- </subsection>
- <subsection name="Maven Wiki">
- <p>These links include collected documentation about Maven,
contributed from a variety of sources:</p>
- <ul>
- <li><a
href="http://wiki.codehaus.org/maven/HowToCreateYourFirstPlugIn";>A first</a> and
- <a
href="http://wiki.codehaus.org/maven/HowToCreateYourFirstPlugIn2";>second</a>
part of a tutorial for making
- a minimal Maven plugin.</li>
- <li><a
href="http://wiki.codehaus.org/maven/PluginCreation";>PluginCreation</a>: A more
comprehensive contributed
- tutorial for creating your own plugin.</li>
- <li><a
href="http://wiki.codehaus.org/maven/PluginModificationGuidelines";>PluginModificationGuidelines</a>
and
- <a
href="http://wiki.codehaus.org/maven/ReleasingPlugins";>ReleasingPlugins</a>:
- Contributed discussion of what Maven contributors or
developers do when modifying a Maven plugin in Maven CVS.
- Many things are duplicates of official docs now. Look for
ways to have your own project follow similar standards.</li>
- <li><a
href="http://wiki.codehaus.org/maven/PluginOwners";>PluginOwners</a>: Beginnings
of a list linking plugins
- and principal maintainers</li>
- </ul>
- </subsection>
- <subsection name="Mailing List Threads">
- <p>Discussions that occured on the Maven mailing lists:</p>
- <ul>
- <li><a
href="http://www.mail-archive.com/dev@maven.apache.org/msg10903.html";>StatCvs
Maintainership</a>: A discussion,
- initiated by the StatCvs group, about the benefits of moving
maintainership of the StatCvs plugin from the Maven
- team to the StatCvs team</li>
- <li><a
href="http://www.mail-archive.com/users@maven.apache.org/msg09117.html";>StatCvs
Plugin Announcement</a>:
- Example of how to properly announce releases of your
plugin.</li>
- </ul>
- </subsection>
- </section>
</section>
--->
</body>
</document>
1.2 +1 -1 maven/xdocs/developers/building-from-source.xml
Index: building-from-source.xml
===================================================================
RCS file: /home/cvs/maven/xdocs/developers/building-from-source.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- building-from-source.xml 22 Nov 2004 11:52:58 -0000 1.1
+++ building-from-source.xml 24 Nov 2004 08:42:37 -0000 1.2
@@ -33,7 +33,7 @@
to successfully build Maven from scratch, a bootstrapping process
is required to jumpstart the build. Alternatively, if you already
have Maven installed and would just like to build a newer version,
- you can follow <a href="#Building_Maven_With_Maven">these
instructions</a>.
+ you can follow <a href="#Building_Maven_with_Maven">these
instructions</a>.
</p>
</section>
<section name="Bootstrapping Maven with Ant">
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
