Re: Build process: was http://james.apache.org]

[Jason van Zyl <ja...@zenplex.com>]

On Mon, 2003-01-27 at 17:46, Noel J. Bergman wrote:
> I do recall a "shoot-out" between Maven and Forrest for the web site, and we
> seemed to prefer Forrest.  In discussions with Dion, he noted that Maven's
> primary benefit was process and build related, and that we could seamlessly
> use Forrest with Maven, getting what appeared to be the best of both worlds.

What I was going to point out was that you have a maven POM and the
reports generated from the POM alone are very useful. You'll be
duplicating HTML docs for:

- mailing lists
- project team
- dependencies
- sources repository and instructions for retrieval
- issue tracking
- changelogs
- developer activity
- file activity
- tasklists (taken from @todo in javadocs)

> Dion has been working on a project file for James so that we can see the
> benefits of Maven.  As Danny says on our list (which is where this should be
> discussed), we'd like to hear more about our build and web publishing
> options so that we can make the informed selection.

Well you quite a bit from Maven with simply the POM. You do nothing.
Even if you have zero content aside from the POM people can find the
sources with basic instructions. All what I've listed above for free.
All you have to do is install Maven and with your POM you get loads of
useful info for your users.

And plugins are being added to Maven at pretty quick and you can now
control the reports you want presented on your site from the POM itself.
So again all you do is select the reports you want by editing the POM
and you get what you want.

> For example, if we have james-site, james-mailet and james-server, and we
> want james-site to be populated with HTML generated from javadocs in
> james-mailet and james-server, is Maven able to handle such a thing?  Is
> Forrest?

Sure, there is a vdoclet plugin that I use for passing over the source
of a project to find the @todos. I also use it to create JMX code. You
would add something like:

      <vdoclet:vdoclet
        srcDir="${pom.build.sourceDirectory}"
        destDir="${genDocs}"
        template="james-mailet.vm"
        outputFile="james-mailet.xml"
      />

And then it could be later transformed and pushed onto your site. You
can do whatever you like with with vdoclet and your sources.


> Unlike Jakarta, our sub-projects are related.  Is Maven's report generator
> capable of giving us integrated reports across our sub-projects, or is it
> only capable of separate reports?  

The sample commmons reactor build I made 6 months ago built each of the
commons components, generated the docs for them and then aggregated them
together in what you see here:

http://www.apache.org/~jvanzyl/jakarta-commons/

I also use it to produce docs for the Plexus components. The reactor
walks over each of projects performing the specified task, in this case
generating site docs, and then gives you a list of processed projects
that you can subsequently process in any desired fashion.

So for example, you could walk over all your james-mailets, process the
docs for them and then generate a front-end site with links to all the
individual james-mailets by extracting information from each of the POMs
processed by the reactor. Same process used to make the commons site
above.

> We will have dependencies such that
> james-mailet will produce one or more jar files that james-server depends
> upon.  Will Maven handle that?  How?

For this we can group your mailets under the james 'groupId' and each
mailet would have an artifactId. Then for james itself you can declare
dependencies on each of these mailets. Not a problem. Maven's build
itself uses this when one plugin depends on another.

> Right now, everytime I generate the build, every javadoc page is regenerated
> for publication, even though the javadoc hasn't changed.  Will Maven clean
> up that idiotic process?  Will Forrest?

I'm sure both could fix that with a check. There is a tool in
CruiseControl which checks the timestamps on a set of files. It uses it
to detect whether or not to update the source repository before doing
another build. I'm sure that tool could be snagged and employed for
documentation as well.

> 
> 	--- Noel
-- 
jvz.

Jason van Zyl
jason@zenplex.com
http://tambora.zenplex.org

In short, man creates for himself a new religion of a rational
and technical order to justify his work and to be justified in it.
  
  -- Jacques Ellul, The Technological Society
-- 
jvz.

Jason van Zyl
jason@zenplex.com
http://tambora.zenplex.org

In short, man creates for himself a new religion of a rational
and technical order to justify his work and to be justified in it.
  
  -- Jacques Ellul, The Technological Society


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

Re: Build process: was http://james.apache.org]

[Nicola Ken Barozzi <ni...@apache.org>]

Jason van Zyl wrote:
> On Mon, 2003-01-27 at 17:46, Noel J. Bergman wrote:
> 
>>I do recall a "shoot-out" between Maven and Forrest for the web site, and we
>>seemed to prefer Forrest.  In discussions with Dion, he noted that Maven's
>>primary benefit was process and build related, and that we could seamlessly
>>use Forrest with Maven, getting what appeared to be the best of both worlds.
> 
> What I was going to point out was that you have a maven POM and the
> reports generated from the POM alone are very useful. You'll be
> duplicating HTML docs for:
> 
> - mailing lists
> - project team
> - dependencies
> - sources repository and instructions for retrieval
> - issue tracking
> - changelogs
> - developer activity
> - file activity
> - tasklists (taken from @todo in javadocs)

Nope. Forrest is more than capable to use Maven-generated docs in the 
documentation.

- Maven is a build tool that also has site-generation capabilities that 
uses JSL as a primary generation tool.

- Forrest is a site generation system.

- Centipede is a build tool that also has site-generation capabilities 
that uses Forrest as a primary generation tool.

There is no technological reason why Forrest cannot include 
Maven-generated docs in the site.

As for centipede, yes, we have what you call POM, and yes, it's the 
standard Gump descriptor, and yes, Centipede projects do work natively 
under Gump with the same descriptor, and yes, we also have all the above 
reports Maven gives using the Gump descriptor.
At one point, I even had the Maven site feature generate the site from 
Centipede docs http://www.krysalis.org/alt/.

On reports and builds, it's Maven VS Centipede, not Maven VS Forrest.

On his side, Forrest has instant page editing with the integrated 
webserver, multiple actively maintained skins, a linkmap for semantic 
linking, can use plain html documents as source (both cleaned and 
embedded as-is), an use wiki format sources for pages, a status file 
with all todos and changes with RSS feed, transparent usage of svg files 
rendered as png, DTD validation for sourcefiles... these are the few 
things that come to mind now.

-- 
Nicola Ken Barozzi                   nicolaken@apache.org
             - verba volant, scripta manent -
    (discussions get forgotten, just code remains)
---------------------------------------------------------------------


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>