You are viewing a plain text version of this content. The canonical link for it is here.
Posted to log4j-dev@logging.apache.org by Curt Arnold <ca...@apache.org> on 2005/12/17 00:07:23 UTC
Exploration of use of Maven for site generation and build
Mark Womack, Ron Grabowski (from log4net) and I just recently
returned from ApacheCON US 2005. I expect that Mark will be
preparing a report on the Birds of a Feather on Monday night, our
discussions on a release plan for 1.3 and thoughts on 2.0.
One of my concerns had been the content and production of the project
documentation. The current documentation for log4j is generated
using the contents of the former logging-site CVS module (now http://
svn.apache.org/repos/asf/logging/site/trunk). The logging-site
module is not available for download, so someone who has downloaded a
log4j distribution and wants to regenerate the documentation has to
use Subversion to get the contents of logging-site. In addition,
logging-site has not been consistently tagged when log4j releases
have been made.
I had been interested in seeing if Apache Forrest (http://
forrest.apache.org) might be an better solution, however comments I
overheard at the Hackathon and the Forrest session, suggested that it
might be a bit of an overkill for our needs. In a discussion at the
BoF, one of the attendees (Mark has the contact info) mentioned that
Maven might be a better fit and helped Mark assemble an initial Maven
project description. In particular, Maven has extensive support for
generating code analysis and coverage reports which could be useful
for log4j development. For example, see http://db.apache.org/torque/
runtime/maven-reports.html for 18 different code analysis reports
performed on the Torque code.
Mark committed the initial pom.xml without referencing a bug report.
I continued work on it when I returned and logged a bug (http://
issues.apache.org/bugzilla/show_bug.cgi?id=37930) and committed my
changes. In the bug report, I described the current documentation
generation system as unmaintainable. The tools provided by logging-
site appear to be a development snapshot of Velocity 1.4. The jars
provided seem to be fairly dated and include Ant 1.4.1 (current is
1.6.5), log4j 1.1.3 (current is 1.2.14), commons-collections-2.0
(current is 3.1), velocity-1.4-dev.jar (current is 1.4), jdom-b8
(latest is 1.0), and xerces-1.4.4 (latest is 2.7.1). It may be just
the dependencies of the Velocity development build at the time of the
snapshot. Since Velocity 1.4 has apparently been released since the
snapshot has been made, it may be possible to eliminate the
dependency of log4j on logging-site and replace it with a dependency
on velocity 1.4, but I have not attempted that. However, if site
generation depends on stuff that was either eliminated or
significantly changed between the development snapshot and the final
release, then the initial characterization as "unmaintainable" might
be accurate.
Use of Maven was previously discussed in http://
marc.theaimsgroup.com/?t=112917760100003&r=1&w=2 and Yoav had a few
comments worth repeating:
On 2005-10-13:
-0.5 on using Maven. My experience with it has been that it's kind
of nice for
generating project documentation, but for most real-life (i.e. complex
dependencies, multiple builders on different environments) projects,
the setup
overhead is not worth the benefits.
On 2005-11-18:
If you want to come up with a Maven build file, have a blast. But
the key
thing is maintaining it afterwards: it won't replace the Ant file,
but you'd
still have to maintain it current as we change dependencies and stuff...
I'm definitely uncertain if we can effectively use Maven for the
total product build, but it seems to offer a lot of benefits for
project documentation. I think it is worth some experimentation to
see how far we can take it. If we don't migrate to Maven for
documentation, then we should at least try to migrate to Velocity 1.4
(or less likely Forrest).
Unfortunately, there is not a great solution regarding the
dependencies from Sun. The Maven guide on the topic (http://
maven.apache.org/guides/mini/guide-coping-with-sun-jars.html)
mentions that "When you add a Sun dependency ... then Maven 2.x can
help you locate the JARs by providing the site where they can be
retrieved." However, I haven't seen that actually work in practice.
The download site information is in the resources, however a simple
Maven invocation doesn't provide the link to the Sun site and
instructions on installing the Sun jars. Something I need to ask on
the Maven list, since maybe you only get that with a particular build
switch.
At some point, if things go well, we would need to consider
rearranging our source tree to align with the Maven Standard
Directory Layout (http://maven.apache.org/guides/introduction/
introduction-to-the-standard-directory-layout.html).
---------------------------------------------------------------------
To unsubscribe, e-mail: log4j-dev-unsubscribe@logging.apache.org
For additional commands, e-mail: log4j-dev-help@logging.apache.org
Re: Exploration of use of Maven for site generation and build
Posted by Mark Womack <mw...@apache.org>.
"Unmaintainable" may be a bit much, but I think it is fair to say that
moving to something more modern, like Maven2, could yield some benefits. As
Curt mentioned, there are some really nice features around documentation.
We need to figure out the options and settings, but I think it has greater
potential than trying to do the same things with our existing setup for site
generation. And I still like the automatic dependency determination and
download. If it weren't for the stupid Sun license for the jar files,
everything could be downloaded and generated with almost no configuration.
I think that Maven2 has really raised the bar. When Joakim was showing us
how to setup Maven2 and create the pom.xml file, I downloaded a tiny little
executable from the maven site, added one new env and path setting, created
a really simple pom.xml and we were off. The small Maven2 download
bootstrapped itself and started downloading the needed resources for the
log4j build. Of course, it helped to have an expert at hand, but I think
this could really help users generate the code on their desktop easier as
well. The Ant installation was never quite as easy, IMHO.
-Mark
----- Original Message -----
From: "Ceki Gülcü" <ce...@qos.ch>
To: <lo...@logging.apache.org>
Sent: Monday, December 19, 2005 8:02 AM
Subject: Re: Exploration of use of Maven for site generation and build
At 12:07 AM 12/17/2005, Curt Arnold wrote:
>Mark Womack, Ron Grabowski (from log4net) and I just recently
>returned from ApacheCON US 2005. I expect that Mark will be
>preparing a report on the Birds of a Feather on Monday night, our
>discussions on a release plan for 1.3 and thoughts on 2.0.
>
>One of my concerns had been the content and production of the project
>documentation. The current documentation for log4j is generated
>using the contents of the former logging-site CVS module (now http://
>svn.apache.org/repos/asf/logging/site/trunk). The logging-site
>module is not available for download, so someone who has downloaded a
>log4j distribution and wants to regenerate the documentation has to
>use Subversion to get the contents of logging-site. In addition,
>logging-site has not been consistently tagged when log4j releases
>have been made.
>
>I had been interested in seeing if Apache Forrest (http://
>forrest.apache.org) might be an better solution, however comments I
>overheard at the Hackathon and the Forrest session, suggested that it
>might be a bit of an overkill for our needs. In a discussion at the
>BoF, one of the attendees (Mark has the contact info) mentioned that
>Maven might be a better fit and helped Mark assemble an initial Maven
>project description. In particular, Maven has extensive support for
>generating code analysis and coverage reports which could be useful
>for log4j development. For example, see http://db.apache.org/torque/
>runtime/maven-reports.html for 18 different code analysis reports
>performed on the Torque code.
>
>Mark committed the initial pom.xml without referencing a bug report.
>I continued work on it when I returned and logged a bug (http://
>issues.apache.org/bugzilla/show_bug.cgi?id=37930) and committed my
>changes. In the bug report, I described the current documentation
>generation system as unmaintainable. The tools provided by logging- site
>appear to be a development snapshot of Velocity 1.4. The jars
>provided seem to be fairly dated and include Ant 1.4.1 (current is
>1.6.5), log4j 1.1.3 (current is 1.2.14), commons-collections-2.0
>(current is 3.1), velocity-1.4-dev.jar (current is 1.4), jdom-b8
>(latest is 1.0), and xerces-1.4.4 (latest is 2.7.1). It may be just
>the dependencies of the Velocity development build at the time of the
>snapshot. Since Velocity 1.4 has apparently been released since the
>snapshot has been made, it may be possible to eliminate the
>dependency of log4j on logging-site and replace it with a dependency
>on velocity 1.4, but I have not attempted that. However, if site
>generation depends on stuff that was either eliminated or
>significantly changed between the development snapshot and the final
>release, then the initial characterization as "unmaintainable" might
>be accurate.
The log4j site is build on top of Anakia which is itself based on Velocity.
By the way, the velocity site itself is built on top of Anakia. How
difficult would it be to upgrade to velocity-1.4 from velocity-1.4-dev? My
guess would be that it would not be difficult at all. In the unlikely case
of problems while upgrading, is there any reason the velocity-user list
could not be contacted? The characterization of the current system as
"unmaintainable" may be somewhat premature.
--
Ceki Gülcü
---------------------------------------------------------------------
To unsubscribe, e-mail: log4j-dev-unsubscribe@logging.apache.org
For additional commands, e-mail: log4j-dev-help@logging.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: log4j-dev-unsubscribe@logging.apache.org
For additional commands, e-mail: log4j-dev-help@logging.apache.org
Re: Exploration of use of Maven for site generation and build
Posted by Ceki Gülcü <ce...@qos.ch>.
At 12:07 AM 12/17/2005, Curt Arnold wrote:
>Mark Womack, Ron Grabowski (from log4net) and I just recently
>returned from ApacheCON US 2005. I expect that Mark will be
>preparing a report on the Birds of a Feather on Monday night, our
>discussions on a release plan for 1.3 and thoughts on 2.0.
>
>One of my concerns had been the content and production of the project
>documentation. The current documentation for log4j is generated
>using the contents of the former logging-site CVS module (now http://
>svn.apache.org/repos/asf/logging/site/trunk). The logging-site
>module is not available for download, so someone who has downloaded a
>log4j distribution and wants to regenerate the documentation has to
>use Subversion to get the contents of logging-site. In addition,
>logging-site has not been consistently tagged when log4j releases
>have been made.
>
>I had been interested in seeing if Apache Forrest (http://
>forrest.apache.org) might be an better solution, however comments I
>overheard at the Hackathon and the Forrest session, suggested that it
>might be a bit of an overkill for our needs. In a discussion at the
>BoF, one of the attendees (Mark has the contact info) mentioned that
>Maven might be a better fit and helped Mark assemble an initial Maven
>project description. In particular, Maven has extensive support for
>generating code analysis and coverage reports which could be useful
>for log4j development. For example, see http://db.apache.org/torque/
>runtime/maven-reports.html for 18 different code analysis reports
>performed on the Torque code.
>
>Mark committed the initial pom.xml without referencing a bug report.
>I continued work on it when I returned and logged a bug (http://
>issues.apache.org/bugzilla/show_bug.cgi?id=37930) and committed my
>changes. In the bug report, I described the current documentation
>generation system as unmaintainable. The tools provided by logging- site
>appear to be a development snapshot of Velocity 1.4. The jars
>provided seem to be fairly dated and include Ant 1.4.1 (current is
>1.6.5), log4j 1.1.3 (current is 1.2.14), commons-collections-2.0
>(current is 3.1), velocity-1.4-dev.jar (current is 1.4), jdom-b8
>(latest is 1.0), and xerces-1.4.4 (latest is 2.7.1). It may be just
>the dependencies of the Velocity development build at the time of the
>snapshot. Since Velocity 1.4 has apparently been released since the
>snapshot has been made, it may be possible to eliminate the
>dependency of log4j on logging-site and replace it with a dependency
>on velocity 1.4, but I have not attempted that. However, if site
>generation depends on stuff that was either eliminated or
>significantly changed between the development snapshot and the final
>release, then the initial characterization as "unmaintainable" might
>be accurate.
The log4j site is build on top of Anakia which is itself based on Velocity.
By the way, the velocity site itself is built on top of Anakia. How
difficult would it be to upgrade to velocity-1.4 from velocity-1.4-dev? My
guess would be that it would not be difficult at all. In the unlikely case
of problems while upgrading, is there any reason the velocity-user list
could not be contacted? The characterization of the current system as
"unmaintainable" may be somewhat premature.
--
Ceki Gülcü
---------------------------------------------------------------------
To unsubscribe, e-mail: log4j-dev-unsubscribe@logging.apache.org
For additional commands, e-mail: log4j-dev-help@logging.apache.org
Re: Exploration of use of Maven for site generation and build
Posted by Mark Womack <mw...@apache.org>.
Yeah, we are talking Maven2 here. It appears to be a really big improvement
over Maven1.
-Mark
----- Original Message -----
From: "Scott Heaberlin" <he...@gmail.com>
To: "Log4J Developers List" <lo...@logging.apache.org>
Sent: Sunday, December 18, 2005 8:01 AM
Subject: Re: Exploration of use of Maven for site generation and build
There is one thing I haven't seen mentioned in this thread yet that I
wasn't going to offer up but after seeing this comment, perhaps I
should...
<quote>
> namely the maintenance effort to keep an up to date pom.xml (or
> project.xml, which may be the more standard name IIRC, but it doesn't
> matter much).
</quote>
At first pass reading this I thought "you're right, the maven project
file name doesn't matter much." However, the mroe I think about it
may be beneficial to point out that I believe I hear Curt discussing
usage of Maven2 while others have shared anecdotes and experiences
from past usage of Maven1 (M2 standardizes on "pom.xml" while M1
primarily used "project.xml"). I suggest a look at the Maven2 "for
maven1 users" page for a discussion of what has changed (lots!) and
why in the Maven project.
http://maven.apache.org/maven1.html
Just two-cents from a list lurker and log4j user,
Scott Heaberlin
On 12/16/05, Yoav Shapira <yo...@apache.org> wrote:
> Hi,
> My take on it is same as before: it's a nice tool, has some cool
> features. But it's only worth pursuing if the benefits outweigh the
> costs, namely the maintenance effort to keep an up to date pom.xml (or
> project.xml, which may be the more standard name IIRC, but it doesn't
> matter much).
>
> I don't think it can replace Ant is the primary build mechanism for
> log4j, because so many more people use Ant when compared to Maven. I
> also think, as you pointed out, that logging-site should be tagged
> with every release: be it a CVS or SVN tag, that's a separate to-do
> item not related to the Ant or Maven discussion. But for
> documentation, sure, maybe it's nice: FWIW, I like Forrest at least as
> much as Maven.
>
> One good thing to ask ourselves is: is this really the itch to
> scratch? Have users been complaining about the current documentation?
> Or is our time better spent on getting log4j 1.3 backwards-compatible
> and out-the-door already?
>
> Yoav
>
> On 12/16/05, Curt Arnold <ca...@apache.org> wrote:
> > Explored a little more and committed some additional enhancements. A
> > sample of the generated documentation from Maven can be viewed at
> > http://people.apache.org/~carnold/log4j_mvn/maven-reports.html.
> > There are many known issues: several of the links point to non-
> > existent documents, the checkstyle report throws an exception so it
> > is suppressed and while the Javadocs are generated, the apidocs/
> > index.html page is empty (apidocs/overview-summary.html can be used
> > to see the generated Javadocs). However, it looks pretty good for
> > the amount of time put into it. Will post a message on maven-users
> > to see if I can get any help in extending it.
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: log4j-dev-unsubscribe@logging.apache.org
> > For additional commands, e-mail: log4j-dev-help@logging.apache.org
> >
> >
>
>
> --
> Yoav Shapira
> System Design and Management Fellow
> MIT Sloan School of Management
> Cambridge, MA, USA
> yoavs@computer.org / www.yoavshapira.com
>
---------------------------------------------------------------------
To unsubscribe, e-mail: log4j-dev-unsubscribe@logging.apache.org
For additional commands, e-mail: log4j-dev-help@logging.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: log4j-dev-unsubscribe@logging.apache.org
For additional commands, e-mail: log4j-dev-help@logging.apache.org
Re: Exploration of use of Maven for site generation and build
Posted by Scott Heaberlin <he...@gmail.com>.
There is one thing I haven't seen mentioned in this thread yet that I
wasn't going to offer up but after seeing this comment, perhaps I
should...
<quote>
> namely the maintenance effort to keep an up to date pom.xml (or
> project.xml, which may be the more standard name IIRC, but it doesn't
> matter much).
</quote>
At first pass reading this I thought "you're right, the maven project
file name doesn't matter much." However, the mroe I think about it
may be beneficial to point out that I believe I hear Curt discussing
usage of Maven2 while others have shared anecdotes and experiences
from past usage of Maven1 (M2 standardizes on "pom.xml" while M1
primarily used "project.xml"). I suggest a look at the Maven2 "for
maven1 users" page for a discussion of what has changed (lots!) and
why in the Maven project.
http://maven.apache.org/maven1.html
Just two-cents from a list lurker and log4j user,
Scott Heaberlin
On 12/16/05, Yoav Shapira <yo...@apache.org> wrote:
> Hi,
> My take on it is same as before: it's a nice tool, has some cool
> features. But it's only worth pursuing if the benefits outweigh the
> costs, namely the maintenance effort to keep an up to date pom.xml (or
> project.xml, which may be the more standard name IIRC, but it doesn't
> matter much).
>
> I don't think it can replace Ant is the primary build mechanism for
> log4j, because so many more people use Ant when compared to Maven. I
> also think, as you pointed out, that logging-site should be tagged
> with every release: be it a CVS or SVN tag, that's a separate to-do
> item not related to the Ant or Maven discussion. But for
> documentation, sure, maybe it's nice: FWIW, I like Forrest at least as
> much as Maven.
>
> One good thing to ask ourselves is: is this really the itch to
> scratch? Have users been complaining about the current documentation?
> Or is our time better spent on getting log4j 1.3 backwards-compatible
> and out-the-door already?
>
> Yoav
>
> On 12/16/05, Curt Arnold <ca...@apache.org> wrote:
> > Explored a little more and committed some additional enhancements. A
> > sample of the generated documentation from Maven can be viewed at
> > http://people.apache.org/~carnold/log4j_mvn/maven-reports.html.
> > There are many known issues: several of the links point to non-
> > existent documents, the checkstyle report throws an exception so it
> > is suppressed and while the Javadocs are generated, the apidocs/
> > index.html page is empty (apidocs/overview-summary.html can be used
> > to see the generated Javadocs). However, it looks pretty good for
> > the amount of time put into it. Will post a message on maven-users
> > to see if I can get any help in extending it.
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: log4j-dev-unsubscribe@logging.apache.org
> > For additional commands, e-mail: log4j-dev-help@logging.apache.org
> >
> >
>
>
> --
> Yoav Shapira
> System Design and Management Fellow
> MIT Sloan School of Management
> Cambridge, MA, USA
> yoavs@computer.org / www.yoavshapira.com
>
---------------------------------------------------------------------
To unsubscribe, e-mail: log4j-dev-unsubscribe@logging.apache.org
For additional commands, e-mail: log4j-dev-help@logging.apache.org
Re: Exploration of use of Maven for site generation and build
Posted by Curt Arnold <ca...@apache.org>.
On Dec 16, 2005, at 9:55 PM, Yoav Shapira wrote:
>
> One good thing to ask ourselves is: is this really the itch to
> scratch? Have users been complaining about the current documentation?
> Or is our time better spent on getting log4j 1.3 backwards-compatible
> and out-the-door already?
I think documentation is a concern, but I would agree it is not the
most pressing. It was something that we made some progress on during
ApacheCON since we had an interested user and experts handy.
I did spend almost a full day during the Hackathon working up a
process for generating a compatibility report (http://
issues.apache.org/bugzilla/show_bug.cgi?id=37864) and expect to spend
a significant part of the holiday season working on those issues.
Sometimes you just want to scratch something else for variety.
---------------------------------------------------------------------
To unsubscribe, e-mail: log4j-dev-unsubscribe@logging.apache.org
For additional commands, e-mail: log4j-dev-help@logging.apache.org
Re: Exploration of use of Maven for site generation and build
Posted by Mark Womack <mw...@apache.org>.
I think, but need to prove, that a Maven2 build will be easier than the Ant
version.
I agree that getting 1.3 out the door is a higher priority, but updating our
documentation is a pretty high item for 1.3 (IMO) and if Maven2 makes this
better/easier, then I am willing to make it happen.
-Mark
----- Original Message -----
From: "Yoav Shapira" <yo...@apache.org>
To: "Log4J Developers List" <lo...@logging.apache.org>
Sent: Friday, December 16, 2005 7:55 PM
Subject: Re: Exploration of use of Maven for site generation and build
Hi,
My take on it is same as before: it's a nice tool, has some cool
features. But it's only worth pursuing if the benefits outweigh the
costs, namely the maintenance effort to keep an up to date pom.xml (or
project.xml, which may be the more standard name IIRC, but it doesn't
matter much).
I don't think it can replace Ant is the primary build mechanism for
log4j, because so many more people use Ant when compared to Maven. I
also think, as you pointed out, that logging-site should be tagged
with every release: be it a CVS or SVN tag, that's a separate to-do
item not related to the Ant or Maven discussion. But for
documentation, sure, maybe it's nice: FWIW, I like Forrest at least as
much as Maven.
One good thing to ask ourselves is: is this really the itch to
scratch? Have users been complaining about the current documentation?
Or is our time better spent on getting log4j 1.3 backwards-compatible
and out-the-door already?
Yoav
On 12/16/05, Curt Arnold <ca...@apache.org> wrote:
> Explored a little more and committed some additional enhancements. A
> sample of the generated documentation from Maven can be viewed at
> http://people.apache.org/~carnold/log4j_mvn/maven-reports.html.
> There are many known issues: several of the links point to non-
> existent documents, the checkstyle report throws an exception so it
> is suppressed and while the Javadocs are generated, the apidocs/
> index.html page is empty (apidocs/overview-summary.html can be used
> to see the generated Javadocs). However, it looks pretty good for
> the amount of time put into it. Will post a message on maven-users
> to see if I can get any help in extending it.
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: log4j-dev-unsubscribe@logging.apache.org
> For additional commands, e-mail: log4j-dev-help@logging.apache.org
>
>
--
Yoav Shapira
System Design and Management Fellow
MIT Sloan School of Management
Cambridge, MA, USA
yoavs@computer.org / www.yoavshapira.com
---------------------------------------------------------------------
To unsubscribe, e-mail: log4j-dev-unsubscribe@logging.apache.org
For additional commands, e-mail: log4j-dev-help@logging.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: log4j-dev-unsubscribe@logging.apache.org
For additional commands, e-mail: log4j-dev-help@logging.apache.org
Re: Exploration of use of Maven for site generation and build
Posted by Yoav Shapira <yo...@apache.org>.
Hi,
My take on it is same as before: it's a nice tool, has some cool
features. But it's only worth pursuing if the benefits outweigh the
costs, namely the maintenance effort to keep an up to date pom.xml (or
project.xml, which may be the more standard name IIRC, but it doesn't
matter much).
I don't think it can replace Ant is the primary build mechanism for
log4j, because so many more people use Ant when compared to Maven. I
also think, as you pointed out, that logging-site should be tagged
with every release: be it a CVS or SVN tag, that's a separate to-do
item not related to the Ant or Maven discussion. But for
documentation, sure, maybe it's nice: FWIW, I like Forrest at least as
much as Maven.
One good thing to ask ourselves is: is this really the itch to
scratch? Have users been complaining about the current documentation?
Or is our time better spent on getting log4j 1.3 backwards-compatible
and out-the-door already?
Yoav
On 12/16/05, Curt Arnold <ca...@apache.org> wrote:
> Explored a little more and committed some additional enhancements. A
> sample of the generated documentation from Maven can be viewed at
> http://people.apache.org/~carnold/log4j_mvn/maven-reports.html.
> There are many known issues: several of the links point to non-
> existent documents, the checkstyle report throws an exception so it
> is suppressed and while the Javadocs are generated, the apidocs/
> index.html page is empty (apidocs/overview-summary.html can be used
> to see the generated Javadocs). However, it looks pretty good for
> the amount of time put into it. Will post a message on maven-users
> to see if I can get any help in extending it.
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: log4j-dev-unsubscribe@logging.apache.org
> For additional commands, e-mail: log4j-dev-help@logging.apache.org
>
>
--
Yoav Shapira
System Design and Management Fellow
MIT Sloan School of Management
Cambridge, MA, USA
yoavs@computer.org / www.yoavshapira.com
---------------------------------------------------------------------
To unsubscribe, e-mail: log4j-dev-unsubscribe@logging.apache.org
For additional commands, e-mail: log4j-dev-help@logging.apache.org
Re: Exploration of use of Maven for site generation and build
Posted by Curt Arnold <ca...@apache.org>.
Explored a little more and committed some additional enhancements. A
sample of the generated documentation from Maven can be viewed at
http://people.apache.org/~carnold/log4j_mvn/maven-reports.html.
There are many known issues: several of the links point to non-
existent documents, the checkstyle report throws an exception so it
is suppressed and while the Javadocs are generated, the apidocs/
index.html page is empty (apidocs/overview-summary.html can be used
to see the generated Javadocs). However, it looks pretty good for
the amount of time put into it. Will post a message on maven-users
to see if I can get any help in extending it.
---------------------------------------------------------------------
To unsubscribe, e-mail: log4j-dev-unsubscribe@logging.apache.org
For additional commands, e-mail: log4j-dev-help@logging.apache.org
Re: Exploration of use of Maven for site generation and build
Posted by Paul Glezen <pg...@us.ibm.com>.
My limited experiences with Maven and Forrest have yielded observations
very much in line with your comments.
Curt Arnold <ca...@apache.org> wrote on 12/16/2005 03:07:23 PM:
> ...
> I had been interested in seeing if Apache Forrest (http://
> forrest.apache.org) might be an better solution, however comments I
> overheard at the Hackathon and the Forrest session, suggested that it
> might be a bit of an overkill for our needs.
>
I've been excited about prospect of a tool like Forrest that easily
generates project documentation. But whenever I've tried it, I found that
the allowed tags within the XML source are very restrictive. It's nothing
like free-form XML. The Maven doc plug-in also has restrictions, but they
are far less severe.
It seems that you can customize anything you want with Forrest, but not
easily. It seems to require Cocoon knowledge among other things. The
documentation of a project starts becoming more work than the project
itself.
The last version of Forrest split many capabilities into plug-ins. That's
cool. But the plug-in documentation is not well maintained. You can find
the name of a plug-in and what it's suppose to do for you, but steps for
getting it working are lacking. In fact, I found the Forrest documentation
somewhat disorganized (ironic for a tool that generates docs). I'd find
one thing in the User's Guide, another in one sample, some other item in
another sample. When I wanted to go back and review, I could never
remember where I saw it. They need a more centralized doc.
Maven's docs are quite impressive. But their demands on project structure
seem rather oppresive. The idea is that their recommended project
structure is soooooo good that everyone should be using it and molding
their projects to fit it (rather than molding Maven to their own misguided
project structure). Certainly there is a benefit to a uniform project
structure across an organization. But whether it should be the one Maven
recommends is not so apparent.
Naturally, Maven can be customized. But like Forrest, beyond the simplest
customizations, you quickly start running into other technologies like
Jelly for scripting. Ugh, I was hoping a property file could do most
things, not learn another language.
So I too have backed away from using Maven for total build management. But
the notion of using it just for the doc generation is tempting.
> ... In particular, Maven has extensive support for
> generating code analysis and coverage reports which could be useful
> for log4j development.
>
They look really nice.
- Paul Glezen