You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs@cocoon.apache.org by Nicola Ken Barozzi <ni...@apache.org> on 2002/10/27 23:56:36 UTC
[VOTE] Use Forrest to build Cocoon docs
It's time we move the Cocoon docs to Forrest.
There is still a problem to solve though.
How are we going to generate the documentation?
Currently Cocoon uses itself to generate the documentation, but now we
want to use Forrest, which has an indipendent distribution.
I would propose that we remove the current "docs" target from Cocoon
altogether, and use the Forrest distro for it.
This way we move the concern of the docs system to Forrest and don't
have to cut-n-paste and keep in synch the Forrest build system with the
Cocoon one.
The "docs" target in Cocoon will thus become just a call to the Forrest
build process, and the docs will be included in the distributions
generated statically.
I think this will make things simpler to manage and update.
What do you think?
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: [VOTE] Use Forrest to build Cocoon docs
Posted by Vadim Gritsenko <va...@verizon.net>.
David Crossley wrote:
>Nicola Ken Barozzi wrote:
>
>
>>David Crossley wrote:
>>
>>
...
>>>Also, why is this being copied to cocoon-dev. We agreed
>>>that documentation stuff would get discussed only on
>>>cocoon-docs working under the assumption that all Cocoon
>>>developers are subscribed there.
>>>
>>>
>>This is a VOTE for a structural decision in the Cocoon
>>distribution, so it should always happen in the cocoon-dev
>>list IMHO.
>>
>>
>
>When it is time for a vote, then maybe.
>
>
>
>>Also, lately there have been some crosspost by other developers
>>here to cocoon-dev.
>>
>>
>
>Please do not just follow the bad habits of others. When we
>set up cocoon-docs, we agreed that all docs-related stuff
>would get discussed here. I again stress this part:
>"working under the assumption that all Cocoon developers
>are subscribed to cocoon-docs". Therefore no need to create
>a Cc mess which is impossible to follow and to sensibly
>reply across multiple lists.
>
I took the pain subscribing to this list (thanks god it's quiet there ;)
so now I totally agree with you, no need for mess.
>That is what we decided at list inception. If we are not
>going to do it that way, then we should dump cocoon-docs
>now and go back to cocoon-dev.
>
+1 in a sense "Let's discuss here."
>>I'll stick to discussing here then, but I still think that
>>the VOTE needs to go to both lists.
>>
>>
>
>Conducting a vote on two lists is ridiculous. Perhaps we
>should discuss the PROPOSAL here, then decide where the
>actual VOTE should happen.
>
How about making a proposal and then vote about where the VOTE should
happen? :-P
Vadim
>--David
>
>
Re: [VOTE] Use Forrest to build Cocoon docs
Posted by David Crossley <cr...@indexgeo.com.au>.
Nicola Ken Barozzi wrote:
>
> David Crossley wrote:
> > STOP !!
> > This is not ready for a "vote" we need to discuss the
> > "proposal" first.
>
> Ok.
>
> > There are many issues. Some we have discussed on Forrest
> > and we even have scratchpad builds to help transform the
> > Cocoon xdocs. However, it needs careful consideration.
> > http://marc.theaimsgroup.com/?l=forrest-dev&m=102456379811908
> > (Work with Forrest in general has progressed since then and
> > the demo transformation now needs to catch up.)
> >
> > Also, why is this being copied to cocoon-dev. We agreed
> > that documentation stuff would get discussed only on
> > cocoon-docs working under the assumption that all Cocoon
> > developers are subscribed there.
>
> This is a VOTE for a structural decision in the Cocoon
> distribution, so it should always happen in the cocoon-dev
> list IMHO.
When it is time for a vote, then maybe.
> Also, lately there have been some crosspost by other developers
> here to cocoon-dev.
Please do not just follow the bad habits of others. When we
set up cocoon-docs, we agreed that all docs-related stuff
would get discussed here. I again stress this part:
"working under the assumption that all Cocoon developers
are subscribed to cocoon-docs". Therefore no need to create
a Cc mess which is impossible to follow and to sensibly
reply across multiple lists.
That is what we decided at list inception. If we are not
going to do it that way, then we should dump cocoon-docs
now and go back to cocoon-dev.
> I'll stick to discussing here then, but I still think that
> the VOTE needs to go to both lists.
Conducting a vote on two lists is ridiculous. Perhaps we
should discuss the PROPOSAL here, then decide where the
actual VOTE should happen.
--David
Re: [VOTE] Use Forrest to build Cocoon docs
Posted by Nicola Ken Barozzi <ni...@apache.org>.
David Crossley wrote:
> STOP !!
> This is not ready for a "vote" we need to discuss the
> "proposal" first.
Ok.
> There are many issues. Some we have discussed on Forrest
> and we even have scratchpad builds to help transform the
> Cocoon xdocs. However, it needs careful consideration.
> http://marc.theaimsgroup.com/?l=forrest-dev&m=102456379811908
> (Work with Forrest in general has progressed since then and
> the demo transformation now needs to catch up.)
>
> Also, why is this being copied to cocoon-dev. We agreed
> that documentation stuff would get discussed only on
> cocoon-docs working under the assumption that all Cocoon
> developers are subscribed there.
This is a VOTE for a structural decision in the Cocoon distribution, so
it should always happen in the cocoon-dev list IMHO.
Also, lately there have been some crosspost by other developers here to
cocoon-dev.
I'll stick to discussing here then, but I still think that the VOTE
needs to go to both lists.
> More below ...
>
> Nicola Ken Barozzi wrote:
>
>>It's time we move the Cocoon docs to Forrest.
>>
>>There is still a problem to solve though.
>>How are we going to generate the documentation?
>>
>>Currently Cocoon uses itself to generate the documentation, but now we
>>want to use Forrest, which has an indipendent distribution.
>>
>>I would propose that we remove the current "docs" target from Cocoon
>>altogether, and use the Forrest distro for it.
>
>
> No, not remove docs target. Forrest can remotely build
> it as well as Cocoon being able to build its own docs
> in place.
>
> As a user, when i download Cocoon via my dial-up 56k modem
> (yes i am lucky, lots of Australia has 28.8k and twitchy)
> i expect to be able to build the core docs locally via
> Cocoon. I expect to just do "build docs" then start
> at index.html and become enlightened.
I disagree with this.
If an apache-incubator developer uses Forrest to build docs, it has to
download Forrest, no?
The same for any project that uses Forrest.
Cocoon just happens to be the project we use to make Forrest work, but
it always has a newer version of the core, different libraries, and I
honestly don't want to rely on the CVS Cocoon to be able to build the docs.
If the Cocoon in CVS is in alpha state, or simply slightly incompatible
with the Forrest one, why can't I be able to build the project docs?
IMNSHO the docs should compile at all times, or else the doc committers
will be at the mercy of the core committers.
If we use a separate installation we have stability of the docs build,
and overmore it's ready to help the write to use Forrest also for other
projects.
Anyway, the built docs *will* be included in distributions, so users
won't need Forrest at all.
>>This way we move the concern of the docs system to Forrest and don't
>>have to cut-n-paste and keep in synch the Forrest build system with the
>>Cocoon one.
>
> I do not know what you mean by "cut-n-paste" - we do
> not do that for the Cocoon-docs experiment in Forrest.
There have been changes IIUC, and now I have embedded Jetty working on
my version... I'm also working on in-place editing and stuff, and it
could become more complicated on the lib dependencies as time goes by.
We will maybe need libre libs too, and copy Forrest stuff to Cocoon that
will have to be maintained also in Cocoon.
I don't think it's a good idea.
>>The "docs" target in Cocoon will thus become just a call to the Forrest
>>build process, and the docs will be included in the distributions
>>generated statically.
>>
>>I think this will make things simpler to manage and update.
>>
>>What do you think?
>
> Discuss a proposal first.
The proposal is to use Forrest for Cocoon docs.
Not use a Forrest-based docs build system with the Cocoon distro, but to
use Forrest as any other projec tdoes..
There is not much to discuss about or propose /if/ we use Forrest, since
the shbat distro works well, and the project-howto is clear enough.
Of course, this is my view, I'd be happy to hear other opinions too.
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: [VOTE] Use Forrest to build Cocoon docs
Posted by Bertrand Delacretaz <bd...@codeconsult.ch>.
On Monday 28 October 2002 04:17, David Crossley wrote:
>. . .
> This is not ready for a "vote" we need to discuss the
> "proposal" first.
Agreed, the proposal needs to be fleshed out before voting.
I'm all +1 on moving to Forrest, but only after making sure all relevant docs
are published correctly by Forrest.
I also agree with David that downloading Forrest should not be required to
build the Cocoon docs, if we can avoid it (but I don't know much about the
issues, I'm still getting up to speed on Forrest).
-Bertrand
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [VOTE] Use Forrest to build Cocoon docs
Posted by Bertrand Delacretaz <bd...@codeconsult.ch>.
On Monday 28 October 2002 04:17, David Crossley wrote:
>. . .
> This is not ready for a "vote" we need to discuss the
> "proposal" first.
Agreed, the proposal needs to be fleshed out before voting.
I'm all +1 on moving to Forrest, but only after making sure all relevant docs
are published correctly by Forrest.
I also agree with David that downloading Forrest should not be required to
build the Cocoon docs, if we can avoid it (but I don't know much about the
issues, I'm still getting up to speed on Forrest).
-Bertrand
Re: [VOTE] Use Forrest to build Cocoon docs
Posted by Diana Shannon <sh...@apache.org>.
I'm generally in agreement with Ken (in fact I proposed a separate CVS
module for docs, powered by a Forrest webapp back in July on
forrest-dev), but I agree with David that we need to clarify a number of
key issues to make such a transition successful and efficient.
While I haven't posted much recently on forrest-dev, I do keep up with
the list. I'm also scrutinizing the latest cvs version and will have
more comments soon. Here's a few issues that I have at this moment.
1. Is Forrest Ready?
After all, it's still considered alpha, isn't it? I agree that docs need
a stable framework for reliable generation, but at this point in time,
I'd argue that the release branch of Cocoon is more stable than the
current Forrest distro. Still, all of us are Cocoon-proficient and could
most likely fix bugs caused by the use of the current alpha Forrest
distro. Nevertheless, I would argue that such a transition **may** be a
bit premature, unless we decide some kind of reliable update cycle for a
distro that's still alpha (and that lacks any known release schedule).
2. What kind of docs and doc building facilities should we provide users?
I agree with Ken that we it would be nice to move docs generation
facilities and doc source files out of the code-oriented cvs branches. I
think we should move them to a separate cvs module/branch that users can
also download if they want to build docs locally. However, if users just
want (prebuilt) docs, they should be able to download html files as they
do nightly snapshots -- or something similar. Moving the docs out of the
code branches does raise a few other issues. For example, we'd need to
distinguish in docs builds between a web site build and a local docs
build. Local docs can link to webapp samples (generated by the code cvs
branches build), while a live site build cannot.
3. What is Forrest?
Because Forrest is a Cocoon webapp, it's a bit unclear what
"distribution updates" mean. It's not a simple issue like a few updated
jars as is the case with most inter-project dependencies. The Forrest
distro contains so many other files! For example, in the early days of
Forrest, it wasn't clear if users were "allowed" to have their own
sitemaps and sub-sitemaps. I don't think that's the case anymore, but I
would like to get a better understanding of this. Still, even a few
months ago, you guys were discussing the prospect of abandoning
document-v11.dtd. How backwards-compatible can Forrest be at this early
alpha state, and how easy would it be to "fork" Forrest unintentionally,
like making some "inappropriate" edits to one of the distro files that
later gets overwritten by a distro/cvs update?
Diana
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [VOTE] Use Forrest to build Cocoon docs
Posted by David Crossley <cr...@indexgeo.com.au>.
STOP !!
This is not ready for a "vote" we need to discuss the
"proposal" first.
There are many issues. Some we have discussed on Forrest
and we even have scratchpad builds to help transform the
Cocoon xdocs. However, it needs careful consideration.
http://marc.theaimsgroup.com/?l=forrest-dev&m=102456379811908
(Work with Forrest in general has progressed since then and
the demo transformation now needs to catch up.)
Also, why is this being copied to cocoon-dev. We agreed
that documentation stuff would get discussed only on
cocoon-docs working under the assumption that all Cocoon
developers are subscribed there.
More below ...
Nicola Ken Barozzi wrote:
>
> It's time we move the Cocoon docs to Forrest.
>
> There is still a problem to solve though.
> How are we going to generate the documentation?
>
> Currently Cocoon uses itself to generate the documentation, but now we
> want to use Forrest, which has an indipendent distribution.
>
> I would propose that we remove the current "docs" target from Cocoon
> altogether, and use the Forrest distro for it.
No, not remove docs target. Forrest can remotely build
it as well as Cocoon being able to build its own docs
in place.
As a user, when i download Cocoon via my dial-up 56k modem
(yes i am lucky, lots of Australia has 28.8k and twitchy)
i expect to be able to build the core docs locally via
Cocoon. I expect to just do "build docs" then start
at index.html and become enlightened.
> This way we move the concern of the docs system to Forrest and don't
> have to cut-n-paste and keep in synch the Forrest build system with the
> Cocoon one.
I do not know what you mean by "cut-n-paste" - we do
not do that for the Cocoon-docs experiment in Forrest.
> The "docs" target in Cocoon will thus become just a call to the Forrest
> build process, and the docs will be included in the distributions
> generated statically.
>
> I think this will make things simpler to manage and update.
>
> What do you think?
Discuss a proposal first.
--David
Re: [VOTE] Use Forrest to build Cocoon docs
Posted by David Crossley <cr...@indexgeo.com.au>.
STOP !!
This is not ready for a "vote" we need to discuss the
"proposal" first.
There are many issues. Some we have discussed on Forrest
and we even have scratchpad builds to help transform the
Cocoon xdocs. However, it needs careful consideration.
http://marc.theaimsgroup.com/?l=forrest-dev&m=102456379811908
(Work with Forrest in general has progressed since then and
the demo transformation now needs to catch up.)
Also, why is this being copied to cocoon-dev. We agreed
that documentation stuff would get discussed only on
cocoon-docs working under the assumption that all Cocoon
developers are subscribed there.
More below ...
Nicola Ken Barozzi wrote:
>
> It's time we move the Cocoon docs to Forrest.
>
> There is still a problem to solve though.
> How are we going to generate the documentation?
>
> Currently Cocoon uses itself to generate the documentation, but now we
> want to use Forrest, which has an indipendent distribution.
>
> I would propose that we remove the current "docs" target from Cocoon
> altogether, and use the Forrest distro for it.
No, not remove docs target. Forrest can remotely build
it as well as Cocoon being able to build its own docs
in place.
As a user, when i download Cocoon via my dial-up 56k modem
(yes i am lucky, lots of Australia has 28.8k and twitchy)
i expect to be able to build the core docs locally via
Cocoon. I expect to just do "build docs" then start
at index.html and become enlightened.
> This way we move the concern of the docs system to Forrest and don't
> have to cut-n-paste and keep in synch the Forrest build system with the
> Cocoon one.
I do not know what you mean by "cut-n-paste" - we do
not do that for the Cocoon-docs experiment in Forrest.
> The "docs" target in Cocoon will thus become just a call to the Forrest
> build process, and the docs will be included in the distributions
> generated statically.
>
> I think this will make things simpler to manage and update.
>
> What do you think?
Discuss a proposal first.
--David
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org