The author can't write too well, and so the title is a bit off - it ought to read: Doco that explains the protocols required to allow maven.xml or any plugin.jelly to inject values into or retrieve values from another plugin

explanation I gave Andy. To date I haven't been able to distill this into a user readable form:

Variables in a plugin are in its own, separate, jelly context.
However, this context is only created when the plugin is first loaded,
which is when it is first used.

Unfortunately, maven:set does not initialise the plugin context. It
was intended to, but caused some other problems that are documented in
the JIRA issue. So, you cannot use maven:set (or get) before the
plugin context is initialised.

When the plugin context is initialised, it uses the variables from the
current context, so anything set with j:set (no scope) is added. So
using this before the plugin gets used works, but not afterwards.
Using scope="parent" always works, as it puts it into the root
context, shared by all - as long as the plugin has not overridden the
variable in its own context.

The plugin is initialised when:
a) the goal you are in has a preGoal on a goal from that plugin
b) attainGoal has been called for that plugin
c) you have a namespace dependency on the plugin (This seems to have
been unreliable and only work if you actually use a tag from the
plugin though - hence the dependency handle)

It is much better to use a or b if possible, then use maven:set/get
exclusively. If you know the plugin has not been initialised and need
to set a var, you must use j:set without a scope. j:set with a scope
of parent is a last resort that will work in most but not all
situations.

It's a mess, and that's why m2 was a rewrite

OK! I've checked out the Maven 1 code. I've read through faq.fml and I have an idea about what I'd like to say and where I think that it ought to go.

I've looked at the code for the Maven Jelly tags, and I have a partial understanding about the mechanisms by which the Jelly tag documentaion pages are generated.

So, I've got a couple of questions.

I'm tempted to put some substantive comments into the GetTag.java and the SetTag.java files that explain the issues concerning the injection/retrival of values into/from maven plugins via Jelly scripts. At a minimum, I'd like to add a "see such and such reference", BUT either of those ideas seem to be BAD because it binds the documentation of the code to the larger issue of documenting Maven and Maven's use by its progammer customers. An improper separation of concerns if ever there was one.

I see, under the Codehaus Confluence pages, that there is an "Aiding Maven Adoption" page" I've got a bunch of suggestions concerning that topic, but I'll spare you for now. What I would like to know is, is there any intention of adding a "Why We Rewrote Maven" page to the Maven 1 site anytime soon? Putting the information about the differences between the 2 releases on the Maven 2 pages doesn't help the kind of Maven 1 users that I used to be, before I got religion, that is.

If there were a highlighted link on the Maven 1 page to such a discussion, and possibly a link from the Maven 1 faq to same, then I would feel comfortable leaving the code unmodified; because we would have discharged our documentation obligations to the community. In teh future when someone asks the inevitable ignorant questions on the user list, we could simply respond, "RTFM, look at the 'Why We Rewrote Maven pages.!"

So, after that multi paragraph "rant", I guess that I'm asking whether there is any interest in my writing the documentation about injection/retrieval in the context of a "Why We Rewrote Maven" piece that I would write. I'd be happy to submit it for proper vetting by the appropriate eyes.

I think that bound to the larger context, lets say in a "Tips and Tricks" section at the end of the piece, people would be more likely to read and remember it when it came time for them to make this sort of attempt.

Thanks, waiting for some feedback,

Andy

Andy, sorry I missed this from a while back. If you want a disucssion, it might be easier on te mailing list.

If you are still interested in doing the "Why we rewrote Maven" piece you'll find some material in my SJUG slides under the "Articles" part of the Maven 1.x site.

Hope this helps...

To be documented if it's not yet done