Re: Packaging plugin docs

[Dennis Lundberg <de...@apache.org>]

Jeff Jensen wrote:
> Hi Dennis, Your email below was exactly what I needed.  It also makes me ask
> this question "how do users know to look at the archiver plugin options for
> the packaging-type plugins?".  E.g. my recent escapade into making a war
> (converting an M1 build to M2) - I was in the middle of trying to determine
> how to use an existing manifest file vs having Maven generate one when I
> read your below email.  There are a number of nice examples of manifest file
> manipulation in the war plugin docs, but nothing on using a file.  Same is
> true for the "Guide to Working with Manifests" page.  So I visited the
> archiver docs, and there was my answer!
> 
> Nothing I found on the war plugin's docs leads the user to look at the
> archiver info (and with a quick glance at the EAR one I did not see anything
> on other packaging plugins; my guess is I will have similar questions on the
> EAR plugin).

This is a maintenance issue. The site for the archiver was created in 
the process of releasing maven-jar-plugin 2.2. We took the best docs we 
could find on the subject and put it in a single place (archiver). The 
site for the jar plugin was updated accordingly, referring to the 
archiver docs when appropriate. Any duplicate docs was removed from the 
jar plugin site.

> Assuming all of these packaging plugins use archiver (could be a wrong
> assumption!), I am thinking we should add to each of the packaging plugins a
> simple sentence or two stating to also refer to the Archiver docs for
> further configuration examples and a link to it.  Otherwise, it takes
> "preexisting knowledge" to know to look there.  WDYT? 

The other archive-ish plugins (war and ear) should get the same 
treatment for their respective next release.

> Additionally, the archiver plugin is not listed on the
> http://maven.apache.org/plugins/ page.  This also leads me to wonder if
> different doc page(s) exist for a plugin list.  I think probably not, and
> this is just a "doc maintenance issue", which hints to auto-generating a
> plugin list page with description and link to its page.  That's a different
> issue of course! :-)

The archiver isn't a plugin in itself, but something we call a shared 
component. There are other shared components as well, but they are 
somewhat lacking in the documentation area. But creating a starting page 
for them, similar to the plugins page, is a good idea.

> <generalThought>Besides these specifics on archiver, the <configuration>
> element options per plugin seem a little bit elusive - we rely on examples
> on the plugin doc page, which I think the existing ones are good, just
> incomplete at times [cite above case].  Not knowing what would be the answer
> other than something like the M1 properties list pages (properties could
> still get overlooked, of course).

There is an auto-generated page for every plugin, describing the 
configuration elements for each goal. Click the Goals link in the menu 
and then on a specific goal. The page relies on annotations in the 
Javadoc of the plugin.

> One thing I miss with the <configuration>
> elements that we have with most of the POM is what XML schema provides for
> IDE smart completion.</generalThought>
> 
> 
> -----Original Message-----
> From: Dennis Lundberg [mailto:dennisl@apache.org] 
> Sent: Sunday, February 24, 2008 4:44 AM
> To: Maven Users List
> Subject: Re: manifest problem Please help
> 
> Did you try following the documentation to the letter:
> 
> http://maven.apache.org/shared/maven-archiver/examples/manifestFile.html
> http://maven.apache.org/shared/maven-archiver/examples/manifestEntries.html
> http://maven.apache.org/shared/maven-archiver/examples/classpath.html
> 
> 
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
> For additional commands, e-mail: users-help@maven.apache.org
> 
> 


-- 
Dennis Lundberg

---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org