You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cactus-dev@jakarta.apache.org by Vincent Massol <vm...@pivolis.com> on 2003/09/20 21:40:16 UTC
[Q] New structure for cactus documentations?
Hi,
I'd like to do some brainstorming on how we want to manage the Cactus
documentation in the future. ATM, we have a monolithic documentation/
project which contains the full documentation for all modules.
Note: The modules are: framework, samples/servlet, samples/jetty,
samples/ejb, integration/ant, integration/eclipse/*, etc
There is another way of doing this, by distributing the documentation to
the respective modules: the documentation related to the framework will
go in the framework module, etc. And the general documentation will go
in the master project (whatever we want to call it).
Something like:
jakarta-cactus
|_ framework
|_ xdocs
|_ [doc related to the framework module]
|_ [other modules]
|_ xdocs
|_ [general master docs]
The published website, would also mirror this:
/www/jakarta.apache.org/cactus/[version]
|_ [general master docs]
|_ framework
|_ [doc related to the framework module]
In my opinion, the advantages are:
- each module is self-contained and standalone (in term of artifacts it
generates, build, and in term of documentation), thus leading in a more
modular build (and more scalable)
- it will allow to easily move to a Maven build (which require this
structure to work as is - Otherwise, we won't be able to easily benefit
from a lot of the nice features related to documentation and reports)
- Cactus has moved from a single project to modules which are now
clearly identified. Moving the documentation is the last step in this
direction.
Any disadvantage?
What do you think?
Thanks
-Vincent
RE: [Q] New structure for cactus documentations?
Posted by Vincent Massol <vm...@pivolis.com>.
> -----Original Message-----
> From: Vincent Massol [mailto:vmassol@pivolis.com]
> Sent: 20 September 2003 22:29
> To: 'Cactus Developers List'
> Subject: RE: [Q] New structure for cactus documentations?
>
>
>
> > -----Original Message-----
> > From: Christopher Lenz [mailto:cmlenz@gmx.de]
> > Sent: 20 September 2003 22:21
> > To: Cactus Developers List
> > Subject: Re: [Q] New structure for cactus documentations?
> >
>
> [snip]
>
> > > What do you think?
> >
> > Sounds good. However, where would we put things like the skin (css,
> > images, etc)?
> >
>
> Good point Chris! We have several options:
>
> 1/ put it in the master project and make it an artifact of that
project.
> Subprojects will depend on it
>
> 2/ Create a build project containing custom stuff needed by our build.
> For example build-common.xml, any custom Ant task, skins, etc could go
> in there
>
> 3/ Duplicate it... arg!
>
Actually there is a 4th option (it's a variation of 2/)
4/ All shared build stuff goes in the root directory. This is actually
what we've been doing so far:
- build-common.xml
- checkstyle.xml
- common properties
If we follow that we could add the XSL stylesheets.
Thinking about it, what we're doing is not really clean and having a
build/ directory with these shared build data would be an better option.
However with option 4/ it doesn't have to be a specific project, simply
a well-known location for shared build data. My option 2/ was a real
project.
All in all, I prefer option 4/ as it is more lightweight and does not
necessitate to build a project before being able to build the other
projects.
-Vincent
> I'm hesitating between 1/ and 2/. I think 2/ is cleaner. In maven
terms
> it means we would have custom Maven plugins for complex stuff which is
> probably the best way. So I would tend to prefer 2/.
>
> -Vincent
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: cactus-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: cactus-dev-help@jakarta.apache.org
RE: [Q] New structure for cactus documentations?
Posted by Vincent Massol <vm...@pivolis.com>.
> -----Original Message-----
> From: Vincent Massol [mailto:vmassol@pivolis.com]
> Sent: 20 September 2003 22:29
> To: 'Cactus Developers List'
> Subject: RE: [Q] New structure for cactus documentations?
>
>
>
> > -----Original Message-----
> > From: Christopher Lenz [mailto:cmlenz@gmx.de]
> > Sent: 20 September 2003 22:21
> > To: Cactus Developers List
> > Subject: Re: [Q] New structure for cactus documentations?
> >
>
> [snip]
>
> > > What do you think?
> >
> > Sounds good. However, where would we put things like the skin (css,
> > images, etc)?
> >
>
> Good point Chris! We have several options:
>
> 1/ put it in the master project and make it an artifact of that
project.
> Subprojects will depend on it
>
> 2/ Create a build project containing custom stuff needed by our build.
> For example build-common.xml, any custom Ant task, skins, etc could go
> in there
>
> 3/ Duplicate it... arg!
>
Actually there is a 4th option (it's a variation of 2/)
4/ All shared build stuff goes in the root directory. This is actually
what we've been doing so far:
- build-common.xml
- checkstyle.xml
- common properties
If we follow that we could add the XSL stylesheets.
Thinking about it, what we're doing is not really clean and having a
build/ directory with these shared build data would be an better option.
However with option 4/ it doesn't have to be a specific project, simply
a well-known location for shared build data. My option 2/ was a real
project.
All in all, I prefer option 4/ as it is more lightweight and does not
necessitate to build a project before being able to build the other
projects.
-Vincent
> I'm hesitating between 1/ and 2/. I think 2/ is cleaner. In maven
terms
> it means we would have custom Maven plugins for complex stuff which is
> probably the best way. So I would tend to prefer 2/.
>
> -Vincent
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: cactus-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: cactus-dev-help@jakarta.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: cactus-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: cactus-dev-help@jakarta.apache.org
RE: [Q] New structure for cactus documentations?
Posted by Vincent Massol <vm...@pivolis.com>.
> -----Original Message-----
> From: Christopher Lenz [mailto:cmlenz@gmx.de]
> Sent: 20 September 2003 22:21
> To: Cactus Developers List
> Subject: Re: [Q] New structure for cactus documentations?
>
[snip]
> > What do you think?
>
> Sounds good. However, where would we put things like the skin (css,
> images, etc)?
>
Good point Chris! We have several options:
1/ put it in the master project and make it an artifact of that project.
Subprojects will depend on it
2/ Create a build project containing custom stuff needed by our build.
For example build-common.xml, any custom Ant task, skins, etc could go
in there
3/ Duplicate it... arg!
I'm hesitating between 1/ and 2/. I think 2/ is cleaner. In maven terms
it means we would have custom Maven plugins for complex stuff which is
probably the best way. So I would tend to prefer 2/.
-Vincent
RE: [Q] New structure for cactus documentations?
Posted by Vincent Massol <vm...@pivolis.com>.
> -----Original Message-----
> From: Christopher Lenz [mailto:cmlenz@gmx.de]
> Sent: 20 September 2003 22:21
> To: Cactus Developers List
> Subject: Re: [Q] New structure for cactus documentations?
>
[snip]
> > What do you think?
>
> Sounds good. However, where would we put things like the skin (css,
> images, etc)?
>
Good point Chris! We have several options:
1/ put it in the master project and make it an artifact of that project.
Subprojects will depend on it
2/ Create a build project containing custom stuff needed by our build.
For example build-common.xml, any custom Ant task, skins, etc could go
in there
3/ Duplicate it... arg!
I'm hesitating between 1/ and 2/. I think 2/ is cleaner. In maven terms
it means we would have custom Maven plugins for complex stuff which is
probably the best way. So I would tend to prefer 2/.
-Vincent
---------------------------------------------------------------------
To unsubscribe, e-mail: cactus-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: cactus-dev-help@jakarta.apache.org
Re: [Q] New structure for cactus documentations?
Posted by Christopher Lenz <cm...@gmx.de>.
Vincent Massol wrote:
> Hi,
>
> I'd like to do some brainstorming on how we want to manage the Cactus
> documentation in the future. ATM, we have a monolithic documentation/
> project which contains the full documentation for all modules.
>
> Note: The modules are: framework, samples/servlet, samples/jetty,
> samples/ejb, integration/ant, integration/eclipse/*, etc
>
> There is another way of doing this, by distributing the documentation to
> the respective modules: the documentation related to the framework will
> go in the framework module, etc. And the general documentation will go
> in the master project (whatever we want to call it).
>
> Something like:
>
> jakarta-cactus
> |_ framework
> |_ xdocs
> |_ [doc related to the framework module]
> |_ [other modules]
> |_ xdocs
> |_ [general master docs]
>
> The published website, would also mirror this:
>
> /www/jakarta.apache.org/cactus/[version]
> |_ [general master docs]
> |_ framework
> |_ [doc related to the framework module]
>
> In my opinion, the advantages are:
>
> - each module is self-contained and standalone (in term of artifacts it
> generates, build, and in term of documentation), thus leading in a more
> modular build (and more scalable)
>
> - it will allow to easily move to a Maven build (which require this
> structure to work as is - Otherwise, we won't be able to easily benefit
> from a lot of the nice features related to documentation and reports)
>
> - Cactus has moved from a single project to modules which are now
> clearly identified. Moving the documentation is the last step in this
> direction.
>
> Any disadvantage?
>
> What do you think?
Sounds good. However, where would we put things like the skin (css,
images, etc)?
-chris
--
Christopher Lenz
/=/ cmlenz at gmx.de
Re: [Q] New structure for cactus documentations?
Posted by Christopher Lenz <cm...@gmx.de>.
Vincent Massol wrote:
> Hi,
>
> I'd like to do some brainstorming on how we want to manage the Cactus
> documentation in the future. ATM, we have a monolithic documentation/
> project which contains the full documentation for all modules.
>
> Note: The modules are: framework, samples/servlet, samples/jetty,
> samples/ejb, integration/ant, integration/eclipse/*, etc
>
> There is another way of doing this, by distributing the documentation to
> the respective modules: the documentation related to the framework will
> go in the framework module, etc. And the general documentation will go
> in the master project (whatever we want to call it).
>
> Something like:
>
> jakarta-cactus
> |_ framework
> |_ xdocs
> |_ [doc related to the framework module]
> |_ [other modules]
> |_ xdocs
> |_ [general master docs]
>
> The published website, would also mirror this:
>
> /www/jakarta.apache.org/cactus/[version]
> |_ [general master docs]
> |_ framework
> |_ [doc related to the framework module]
>
> In my opinion, the advantages are:
>
> - each module is self-contained and standalone (in term of artifacts it
> generates, build, and in term of documentation), thus leading in a more
> modular build (and more scalable)
>
> - it will allow to easily move to a Maven build (which require this
> structure to work as is - Otherwise, we won't be able to easily benefit
> from a lot of the nice features related to documentation and reports)
>
> - Cactus has moved from a single project to modules which are now
> clearly identified. Moving the documentation is the last step in this
> direction.
>
> Any disadvantage?
>
> What do you think?
Sounds good. However, where would we put things like the skin (css,
images, etc)?
-chris
--
Christopher Lenz
/=/ cmlenz at gmx.de
---------------------------------------------------------------------
To unsubscribe, e-mail: cactus-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: cactus-dev-help@jakarta.apache.org
Re: [Q] New structure for cactus documentations?
Posted by Julien Dubois <ju...@julien-dubois.com>.
This is going to ease my job *a lot*, so of course I'm in favor of it.
I think option 4 is better, but I'll first experiment it at work.
Oh yeah, since Friday I'm doing the same things for my projects at work, so
I'm getting paid to experiment what I'll put into Cactus :-))
Le Dimanche 21 Septembre 2003 02:19, Nicholas Lesiecki a écrit :
> I'm in favor of the distributed documentation. It should also make
> maintaining the docs a little more straightforward.
>
Re: [Q] New structure for cactus documentations?
Posted by Julien Dubois <ju...@julien-dubois.com>.
This is going to ease my job *a lot*, so of course I'm in favor of it.
I think option 4 is better, but I'll first experiment it at work.
Oh yeah, since Friday I'm doing the same things for my projects at work, so
I'm getting paid to experiment what I'll put into Cactus :-))
Le Dimanche 21 Septembre 2003 02:19, Nicholas Lesiecki a écrit :
> I'm in favor of the distributed documentation. It should also make
> maintaining the docs a little more straightforward.
>
---------------------------------------------------------------------
To unsubscribe, e-mail: cactus-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: cactus-dev-help@jakarta.apache.org
Re: [Q] New structure for cactus documentations?
Posted by Nicholas Lesiecki <nd...@yahoo.com>.
I'm in favor of the distributed documentation. It should also make
maintaining the docs a little more straightforward.
Cheers,
nick
On 9/20/03 3:40 PM, "Vincent Massol" <vm...@pivolis.com> wrote:
> Hi,
>
> I'd like to do some brainstorming on how we want to manage the Cactus
> documentation in the future. ATM, we have a monolithic documentation/
> project which contains the full documentation for all modules.
>
> Note: The modules are: framework, samples/servlet, samples/jetty,
> samples/ejb, integration/ant, integration/eclipse/*, etc
>
> There is another way of doing this, by distributing the documentation to
> the respective modules: the documentation related to the framework will
> go in the framework module, etc. And the general documentation will go
> in the master project (whatever we want to call it).
>
> Something like:
>
> jakarta-cactus
> |_ framework
> |_ xdocs
> |_ [doc related to the framework module]
> |_ [other modules]
> |_ xdocs
> |_ [general master docs]
>
> The published website, would also mirror this:
>
> /www/jakarta.apache.org/cactus/[version]
> |_ [general master docs]
> |_ framework
> |_ [doc related to the framework module]
>
> In my opinion, the advantages are:
>
> - each module is self-contained and standalone (in term of artifacts it
> generates, build, and in term of documentation), thus leading in a more
> modular build (and more scalable)
>
> - it will allow to easily move to a Maven build (which require this
> structure to work as is - Otherwise, we won't be able to easily benefit
> from a lot of the nice features related to documentation and reports)
>
> - Cactus has moved from a single project to modules which are now
> clearly identified. Moving the documentation is the last step in this
> direction.
>
> Any disadvantage?
>
> What do you think?
>
> Thanks
> -Vincent
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: cactus-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: cactus-dev-help@jakarta.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: cactus-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: cactus-dev-help@jakarta.apache.org
Re: [Q] New structure for cactus documentations?
Posted by Nicholas Lesiecki <nd...@yahoo.com>.
I'm in favor of the distributed documentation. It should also make
maintaining the docs a little more straightforward.
Cheers,
nick
On 9/20/03 3:40 PM, "Vincent Massol" <vm...@pivolis.com> wrote:
> Hi,
>
> I'd like to do some brainstorming on how we want to manage the Cactus
> documentation in the future. ATM, we have a monolithic documentation/
> project which contains the full documentation for all modules.
>
> Note: The modules are: framework, samples/servlet, samples/jetty,
> samples/ejb, integration/ant, integration/eclipse/*, etc
>
> There is another way of doing this, by distributing the documentation to
> the respective modules: the documentation related to the framework will
> go in the framework module, etc. And the general documentation will go
> in the master project (whatever we want to call it).
>
> Something like:
>
> jakarta-cactus
> |_ framework
> |_ xdocs
> |_ [doc related to the framework module]
> |_ [other modules]
> |_ xdocs
> |_ [general master docs]
>
> The published website, would also mirror this:
>
> /www/jakarta.apache.org/cactus/[version]
> |_ [general master docs]
> |_ framework
> |_ [doc related to the framework module]
>
> In my opinion, the advantages are:
>
> - each module is self-contained and standalone (in term of artifacts it
> generates, build, and in term of documentation), thus leading in a more
> modular build (and more scalable)
>
> - it will allow to easily move to a Maven build (which require this
> structure to work as is - Otherwise, we won't be able to easily benefit
> from a lot of the nice features related to documentation and reports)
>
> - Cactus has moved from a single project to modules which are now
> clearly identified. Moving the documentation is the last step in this
> direction.
>
> Any disadvantage?
>
> What do you think?
>
> Thanks
> -Vincent
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: cactus-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: cactus-dev-help@jakarta.apache.org