You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs@cocoon.apache.org by Stephan Michels <st...@apache.org> on 2003/03/20 21:53:20 UTC
Migration to Forrest
Hi,
I tried to solve some issue for releasing 2.1. So I took some time
to integrate Forrest into the current build system. I create
successfully the docs, except some links.
See http://vern.chem.tu-berlin.de/~stephan/cocoon/index.html
But for me there are some issue unresolved:
1. Should Cocoon any longer produce his own docs? This mean
that we must include stuff from forrest.
2. Which skin should be used?
3. Can we use something like a forrest cent?
4. I cut the build.xml into several fragments to increase the clearness.
It's okay? And then where should I put the fragments: tools/targets, or
src/targets?
Thoughts?
_______________________________________________________________________
Stephan Michels EMail: stephan@apache.org
ICQ: 115535699 Tel: +49-030-314-21583
----+----|----+----|----+----|----+----|----+----|----+----|----+----|-|
Re: Migration to Forrest
Posted by David Crossley <cr...@indexgeo.com.au>.
Stephan Michels wrote:
> I tried to solve some issue for releasing 2.1. So I took some time
> to integrate Forrest into the current build system. I create
> successfully the docs, except some links.
>
> See http://vern.chem.tu-berlin.de/~stephan/cocoon/index.html
Great, thanks for diving in and helping. It sounds
like we might now have enough people interested to
conduct the transition to document-v11
I presume that you have seen the Wiki page where we
have been trying to outline some issues.
http://wiki.cocoondev.org/Wiki.jsp?page=ForrestProposal
> But for me there are some issue unresolved:
>
> 1. Should Cocoon any longer produce his own docs? This mean
> that we must include stuff from forrest.
That is one of the big problems that we have been grappling with.
Yes, Cocoon must be able to produce its own docs when it
runs via a webapp. So therefore it does need DTDs, stylesheets,
sitemap changes to match the new document-v11 DTD from Forrest.
> 2. Which skin should be used?
>
> 3. Can we use something like a forrest cent?
>
> 4. I cut the build.xml into several fragments to increase the clearness.
> It's okay? And then where should I put the fragments: tools/targets, or
> src/targets?
Please explain what you mean here.
--David
Re: Migration to Forrest
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Steven Noels wrote, On 21/03/2003 9.05:
> On 21/03/2003 4:16 Jeff Turner wrote:
>
>> IMHO the ideal solution would be for Cocoon to build its own
>> documentation, using the Forrest DTDs and a skin checked into Cocoon CVS.
>
> Agree. I consider this to be a nice unit test.
As suggested above not really.
Gump-like tests suppose that you have the latest of everything, and here
the DTDs and skins are not the latest. Furthermore Forrest is nore than
that, think about the build scripts.
I'd leave integration tests like these to Gump and have the docs be
generated by pure Forrest. It will also make more downloads of Forrest
happen, which is the best test Forrest can have ;-)
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: Migration to Forrest
Posted by Steven Noels <st...@outerthought.org>.
On 21/03/2003 4:16 Jeff Turner wrote:
> IMHO the ideal solution would be for Cocoon to build its own
> documentation, using the Forrest DTDs and a skin checked into Cocoon CVS.
Agree. I consider this to be a nice unit test.
</Steven>
--
Steven Noels http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
Read my weblog at http://blogs.cocoondev.org/stevenn/
stevenn at outerthought.org stevenn at apache.org
Re: Migration to Forrest
Posted by Bertrand Delacretaz <bd...@codeconsult.ch>.
Le Vendredi, 21 mars 2003, à 07:31 Europe/Zurich, David Crossley a
écrit :
> ....Actually, i do not see any alternative. Cocoon needs to
> generate its own docs from the webapp, so yes it needs all
> that stuff.
ok, see my reply to Jeff, I see your points.
> ...Would it be possible for people to use Forrest if they
> have it installed to build the Cocoon docs, otherwise
> they just use the Cocoon webapp to build and test the xdocs?
This is what I'd like to avoid: having two ways of generating the docs
would be confusing for users and a waste of time for contributors IMHO.
I think we must settle on One Right Way here.
-Bertrand
Re: Migration to Forrest
Posted by David Crossley <cr...@indexgeo.com.au>.
Jeff Turner wrote:
> Stephan Michels wrote:
<snip/>
> > But for me there are some issue unresolved:
> >
> > 1. Should Cocoon any longer produce his own docs? This mean
> > that we must include stuff from forrest.
>
> +1
>
> IMHO the ideal solution would be for Cocoon to build its own
> documentation, using the Forrest DTDs and a skin checked into
> Cocoon CVS.
Actually, i do not see any alternative. Cocoon needs to
generate its own docs from the webapp, so yes it needs all
that stuff.
> Advantages:
>
> - Cocoon developers don't need to download another 12mb of
> mostly-identical jars to build the docs. That would be a major
> disincentive to anyone wanting to contribute a 5-line doc patch.
> - From Forrest's POV, this is great; no more "big bang" integration
> efforts, trying to synch with Cocoon. Cocoon gets to eat its own
> dogfood. Whoever broke the cocoon.xconf reloading gets to experience
> first-hand the pain it causes. When Berin runs './build.sh docs' and
> it doesn't exit, he'll remember his half-finished TCPThreadManager
> patch ;)
Would it be possible for people to use Forrest if they
have it installed to build the Cocoon docs, otherwise
they just use the Cocoon webapp to build and test the xdocs?
--David
Re: Migration to Forrest
Posted by Stephan Michels <st...@apache.org>.
On Fri, 21 Mar 2003, Bertrand Delacretaz wrote:
> Le Vendredi, 21 mars 2003, à 04:16 Europe/Zurich, Jeff Turner a écrit :
>
> > ...IMHO the ideal solution would be for Cocoon to build its own
> > documentation, using the Forrest DTDs and a skin checked into Cocoon
> > CVS....
>
> Ok - I agree with the advantages you mention, makes sense and this is
> probably simpler than using Forrest in binary form as I was suggesting.
>
> If I got it right though, this will require some duplication of stuff
> between Cocoon and Forrest?
> What exactly, DTDs, skin files, anything else?
> Can this stuff be *moved* into Cocoon instead of being duplicated?
Duplicate files produce always dependencies, which are poorly to
maintain :-/
I will be lucky, if we can throw out all of the documentation generating
stuff, so that Cocoon loose some of his 'fatness' ;-) SoC etc.
How is the status of the Forrest binary version? Is there anything I
can work with?
Stephan.
Re: Migration to Forrest
Posted by Bertrand Delacretaz <bd...@codeconsult.ch>.
Le Vendredi, 21 mars 2003, à 04:16 Europe/Zurich, Jeff Turner a écrit :
> ...IMHO the ideal solution would be for Cocoon to build its own
> documentation, using the Forrest DTDs and a skin checked into Cocoon
> CVS....
Ok - I agree with the advantages you mention, makes sense and this is
probably simpler than using Forrest in binary form as I was suggesting.
If I got it right though, this will require some duplication of stuff
between Cocoon and Forrest?
What exactly, DTDs, skin files, anything else?
Can this stuff be *moved* into Cocoon instead of being duplicated?
-Bertrand
Re: Migration to Forrest
Posted by Jeff Turner <je...@apache.org>.
On Thu, Mar 20, 2003 at 09:53:20PM +0100, Stephan Michels wrote:
> Hi,
>
> I tried to solve some issue for releasing 2.1. So I took some time
> to integrate Forrest into the current build system. I create
> successfully the docs, except some links.
>
> See http://vern.chem.tu-berlin.de/~stephan/cocoon/index.html
Excellent!
> But for me there are some issue unresolved:
>
> 1. Should Cocoon any longer produce his own docs? This mean
> that we must include stuff from forrest.
+1
IMHO the ideal solution would be for Cocoon to build its own
documentation, using the Forrest DTDs and a skin checked into Cocoon CVS.
Advantages:
- Cocoon developers don't need to download another 12mb of
mostly-identical jars to build the docs. That would be a major
disincentive to anyone wanting to contribute a 5-line doc patch.
- From Forrest's POV, this is great; no more "big bang" integration
efforts, trying to synch with Cocoon. Cocoon gets to eat its own
dogfood. Whoever broke the cocoon.xconf reloading gets to experience
first-hand the pain it causes. When Berin runs './build.sh docs' and
it doesn't exit, he'll remember his half-finished TCPThreadManager
patch ;)
> 2. Which skin should be used?
I'd say forrest-site or krysalis-site.
--Jeff
...
Re: Migration to Forrest
Posted by Bertrand Delacretaz <bd...@codeconsult.ch>.
Le Vendredi, 21 mars 2003, à 09:41 Europe/Zurich, Stephan Michels a
écrit :
>
> ...BTW, how is the status of the roadmap for 2.1. Is the migration
> part of the transition to 2.1?
If the docs are migrated soon enough, we can probably include them in
the release, but I don't think there is a set date for this release
yet. Maybe someone knows better.
-Bertrand
Re: Migration to Forrest
Posted by Stephan Michels <st...@apache.org>.
On Thu, 20 Mar 2003, Bertrand Delacretaz wrote:
> Hi Stephan,
>
> > ...See http://vern.chem.tu-berlin.de/~stephan/cocoon/index.html
>
> Looks good!
>
> There seems to be a problem with images however, for example in
> http://vern.chem.tu-berlin.de/~stephan/cocoon/userdocs/concepts/
> index.html
> I found images references like <img
> src="images/pyramid-model.gif.html">, which do not work.
>
Hmm, yes. These are the links, which I don't get all to work ;-)
BTW, how is the status of the roadmap for 2.1. Is the migration
part of the transition to 2.1?
Stephan.
Re: Migration to Forrest
Posted by Bertrand Delacretaz <bd...@codeconsult.ch>.
Hi Stephan,
> ...See http://vern.chem.tu-berlin.de/~stephan/cocoon/index.html
Looks good!
There seems to be a problem with images however, for example in
http://vern.chem.tu-berlin.de/~stephan/cocoon/userdocs/concepts/
index.html
I found images references like <img
src="images/pyramid-model.gif.html">, which do not work.
> ....1. Should Cocoon any longer produce his own docs? This mean
> that we must include stuff from forrest....
I think the original idea was to keep both the existing docs generation
mechanism *and* Forrest, but this would be a pain IMHO. See
http://marc.theaimsgroup.com/?l=xml-cocoon-docs&m=104563976028968&w=2.
Other projects use Forrest in binary form to generate their docs, I
think that's what we should do to avoid the circular references problem
between cocoon and forrest.
In order for everyone to use the same version of Forrest when
generating the docs, I'd suggest creating a new "cocoon-tools" CVS
module and check in there the version of Forrest that is currently
used. In this way our main CVS won't get bigger and we'd have a
well-known version of Forrest to build on.
> ...2. Which skin should be used?
As Forrest is based on Cocoon it makes sense IMHO to use the same skin
for the Cocoon site as Forrest is using for its site, to show that
they're part of the same family.
> ...3. Can we use something like a forrest cent?
I should go to bed and I have no idea what a Forrest cent is so I'll
pass on this one ;-)
> ...4. I cut the build.xml into several fragments to increase the
> clearness.
> It's okay? ...
Talking of the main cocoon build.xml, right?
Splitting it makes sense IMHO but I think you should ask on cocoon-dev.
thanks for your work!
-Bertrand
Re: Migration to Forrest
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Diana Shannon wrote, On 21/03/2003 5.31:
>
> On Thursday, March 20, 2003, at 03:53 PM, Stephan Michels wrote:
...
>> 3. Can we use something like a forrest cent?
>
> I'll defer to Nicola Ken on this.
IMHO the ant entity that Forrest has is good enough. There is not
consensus wether to switch to Centipede, so we'll have to go plain Ant.
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: Migration to Forrest
Posted by Diana Shannon <sh...@apache.org>.
On Thursday, March 20, 2003, at 03:53 PM, Stephan Michels wrote:
> I tried to solve some issue for releasing 2.1. So I took some time
> to integrate Forrest into the current build system. I create
> successfully the docs, except some links.
Fabulous! Thanks for taking the time to help on this!
> See http://vern.chem.tu-berlin.de/~stephan/cocoon/index.html
>
> But for me there are some issue unresolved:
>
> 1. Should Cocoon any longer produce his own docs? This mean
> that we must include stuff from forrest.
I don't think the repos need build capability. Perhaps we should
consider making pre-built html docs snapshots available? Not sure about
including the prebuilt docs in each cvs, but that's probably what users
would expect.
> 2. Which skin should be used?
I'd vote for Forrest. We can always make our own down the road.
> 3. Can we use something like a forrest cent?
I'll defer to Nicola Ken on this.
> 4. I cut the build.xml into several fragments to increase the clearness.
I'm not sure what you mean here, but I'll check it out, once you commit
it somewhere.
Diana