You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs@cocoon.apache.org by Jeff Turner <je...@apache.org> on 2003/03/26 16:30:58 UTC
Re: [vote] Forrestizing Cocoon and more
(moved to cocoon-docs)
On Wed, Mar 26, 2003 at 11:30:09AM +0100, Stephan Michels wrote:
>
> On Wed, 26 Mar 2003, Jeff Turner wrote:
>
> > On Wed, Mar 26, 2003 at 11:08:39AM +0100, Stefano Mazzocchi wrote:
> > ...
> > > Moreover, to be honest, I think that we should aim to improve
> > > forrest/lenya and make it a structured wiki and setup a CMS and point
> > > users to that for editing.
> >
> > Getting the latest Chaperon updates was a major impetus for the recent
> > Cocoon upgrade. Wiki parsing is just waiting for a volunteer.
>
> ;-) First we make the transition, then I will help you on this topic.
> deal?
:) Thanks, help would be very welcome.
As for Forrest transition, the easy part is done. The site currently
built at:
http://forrestbot.cocoondev.org/sites/cocoon-site/
should now contain all the content of the Cocoon-built site.
To get the CVS version of Forrest known to work with Cocoon, run 'cvs
update -r stable' in xml-forrest.
Remaining issues:
- There are lots of untranslated @tokens@ in the xdocs. A short-term
solution would be to do a filter-copy in forrest-build.xml before
Forrest is invoked. Nicer long-term solution is to write a
FilterTransformer, using input modules much like
LinkRewriterTransformer does. If there's no better ideas I'll get
around to this eventually.
- jars.xml isn't generated. Could be fixed
with another forrest-build.xml pre-generation hack. Perhaps in
Forrest we should allow hooks for calling targets in external Ant
scripts.
- doclist.html isn't used. doclist.html isn't referred to anywhere, and
the mechanism of aggregating all book.xml's looks kinda brittle, so I
didn't port it to the Forrest sitemap.xmap. If we still want this,
it's easy to do.
- Someone needs to decide how to use the tabs. How about:
| Home | User docs | Dev docs | Wiki |
I certainly wouldn't ditch the 'docs' target. CVS Forrest is horribly
(unusably?) slow by comparison. 3 mins vs. 15 mins. I hope this mostly
due to the new CLI. If it is the speed/generality tradeoffs Forrest has
made, we'll have to reconsider them.
--Jeff
>
> Stephan.
>
Re: [vote] Forrestizing Cocoon and more
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Jeff Turner wrote, On 27/03/2003 2.25:
...
> Comparing 'build docs' (Cocoon's skin) with 'forrest'. Just tried
> it again: 2:05 vs. 13:26.
Oh my... terrible.
No Jeff, it's not the CLI, it's still set by default to use the old
method. In fact if you use the new method (that has still some bugs, we
are working on it), time goes down by 30% still IIRC.
Try it without PDFs though, that makes things much worse... anyway it's
our Forrest sitemap that needs to get faster. :-/
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: [vote] Forrestizing Cocoon and more
Posted by Jeff Turner <je...@apache.org>.
On Wed, Mar 26, 2003 at 04:38:12PM +0100, Nicola Ken Barozzi wrote:
>
>
> Jeff Turner wrote, On 26/03/2003 16.30:
> >(moved to cocoon-docs)
> ...
> >I certainly wouldn't ditch the 'docs' target. CVS Forrest is horribly
> >(unusably?) slow by comparison. 3 mins vs. 15 mins. I hope this mostly
> >due to the new CLI. If it is the speed/generality tradeoffs Forrest has
> >made, we'll have to reconsider them.
>
> Sorry Jeff, I don't understand... you mean that CVS Forrest is 5 times
> slower than the same thing done with Cocoon docs target using the same
> skin? :-O
Comparing 'build docs' (Cocoon's skin) with 'forrest'. Just tried
it again: 2:05 vs. 13:26.
--Jeff
>
> What's the difference? Why? I'm confused and curious...
>
> --
> Nicola Ken Barozzi nicolaken@apache.org
> - verba volant, scripta manent -
> (discussions get forgotten, just code remains)
> ---------------------------------------------------------------------
>
Re: [vote] Forrestizing Cocoon and more
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Jeff Turner wrote, On 26/03/2003 16.30:
> (moved to cocoon-docs)
...
> I certainly wouldn't ditch the 'docs' target. CVS Forrest is horribly
> (unusably?) slow by comparison. 3 mins vs. 15 mins. I hope this mostly
> due to the new CLI. If it is the speed/generality tradeoffs Forrest has
> made, we'll have to reconsider them.
Sorry Jeff, I don't understand... you mean that CVS Forrest is 5 times
slower than the same thing done with Cocoon docs target using the same
skin? :-O
What's the difference? Why? I'm confused and curious...
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: [vote] Forrestizing Cocoon and more
Posted by Bertrand Delacretaz <bd...@codeconsult.ch>.
Le Mercredi, 26 mars 2003, à 16:30 Europe/Zurich, Jeff Turner a écrit :
> ...As for Forrest transition, the easy part is done. The site
> currently
> built at:
>
> http://forrestbot.cocoondev.org/sites/cocoon-site/
> ...
Looks good, thanks for your work!
> ...
> - Someone needs to decide how to use the tabs. How about:
>
> | Home | User docs | Dev docs | Wiki |
Ok for a first shot, but I think the terms "users" and "developers" can
be confusing.
As users of Cocoon are developers of their own stuff, they might
wrongly jump to "Developers" although what they need to look at is the
"users" stuff.
In the future we might want to base the navigation on the docs plan
that was discussed a while ago
(http://wiki.cocoondev.org/Wiki.jsp?page=CocoonDocsPlan). But that's
another story.
-Bertrand
Re: [vote] Forrestizing Cocoon and more
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Diana Shannon wrote, On 26/03/2003 21.08:
>
> On Wednesday, March 26, 2003, at 10:30 AM, Jeff Turner wrote:
...
>> CVS Forrest is horribly
>> (unusably?) slow by comparison. 3 mins vs. 15 mins. I hope this mostly
>> due to the new CLI. If it is the speed/generality tradeoffs Forrest has
>> made, we'll have to reconsider them.
>
>
> Did anyone ever follow up on Berni's suggestion to my same concern
> (voiced last November on Forrest)?
>
> http://marc.theaimsgroup.com/?l=forrest-dev&m=103782712902758&w=2
Yes, and it has already been committed, along with other changes, and
other bugs are being fixed... we are still working on it.
But still I'm confused by the above comment of 15 VS 3 minutes... what
do they compare?
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: Forrest documentation tabs (was [vote] Forrestizing Cocoon...)
Posted by Diana Shannon <sh...@apache.org>.
On Thursday, March 27, 2003, at 07:08 AM, Stefano Mazzocchi wrote:
> Consensus is cool, turning it into a UN security council decision for
> everything is only going to slow things down.
So then how would you have handled the cocoon-docs question differently?
I didn't call for a vote. Yet a vote was called, and now we don't have a
100% agreement, so we do "nothing" new, which means a minority of people
are deciding what's going to happen. Is that community? Is that a
do-acracy?
People may equate docs == inertia, but it's really not fair. Remember,
we've been stuck in the mud with a static site limitations until only
very recently. We've deliberately held back on new approaches until
Forrest transition occurred. Sometimes discussions may have predominated
but that was simply because our options were limited.
Going forward, what's the best approach for the seeming majority of us
who want a sandbox for docs? Prototype a poor man's wiki-cms system on
cocooondev (with Steven's good wishes, of course). Show how it works,
figure out what it needs, and then reapproach this list for "approval".
Diana
Re: Forrest documentation tabs (was [vote] Forrestizing Cocoon...)
Posted by Stefano Mazzocchi <st...@apache.org>.
Bertrand Delacretaz wrote:
> Le Mercredi, 26 mars 2003, à 21:08 Europe/Zurich, Diana Shannon a écrit :
>
>> On Wednesday, March 26, 2003, at 10:30 AM, Jeff Turner wrote:
>>
>>>
>>> - Someone needs to decide how to use the tabs. How about:
>>>
>>> | Home | User docs | Dev docs | Wiki |
>>
>>
>> I think the community needs to decide this, not any individual. Again,
>> it's been discussed by some of us already across different threads....
>
>
> IMHO waiting for community consensus on such things often slows things
> down.
> I don't think it's such a big thing as to require a vote.
>
> Having visible changes in the docs makes it easier to get feedback, much
> more efficient than long discussions that often send people back to
> waiting mode.
>
> Don't get me wrong, I'm not against community decisions, it's just that
> we have to find a balance and there is a big need for *action* in the
> docs department right now, there is some momentum and we have to do our
> best to keep it.
>
> Release early, release often - I think this should apply to the docs as
> well as the code, CVS is here to fix things when needed.
>
> My 2 swiss centimes.
Big +1.
Consensus is cool, turning it into a UN security council decision for
everything is only going to slow things down.
Do-ocracy. At last.
Stefano.
Re: Forrest documentation tabs
Posted by David Crossley <cr...@indexgeo.com.au>.
Bertrand Delacretaz wrote:
> Diana Shannon a écrit:
> > Jeff Turner wrote:
> >
> >>
> >> - Someone needs to decide how to use the tabs. ...
> >
> > I think the community needs to decide this, not any individual.
> > Again, it's been discussed by some of us already across
> > different threads....
>
> IMHO waiting for community consensus on such things often slows
> things down.
> I don't think it's such a big thing as to require a vote.
>
> Having visible changes in the docs makes it easier to get feedback,
> much more efficient than long discussions that often send people back
> to waiting mode.
>
> Don't get me wrong, I'm not against community decisions, it's just that
> we have to find a balance and there is a big need for *action* in the
> docs department right now, there is some momentum and we have to do our
> best to keep it.
We can also consider "action and fix later" to be a
community decision. The changes in cvs can be enhanced
or rolled back if the community does not like it.
Just vote when big disruptive changes are needed.
> Release early, release often - I think this should apply to the docs as
> well as the code, CVS is here to fix things when needed.
>
> My 2 swiss centimes.
Plus my 2 Australian cents ... if that registers against
your valuable expenditure :-)
--David
Re: Forrest documentation tabs (was [vote] Forrestizing Cocoon...)
Posted by Jeff Turner <je...@apache.org>.
On Thu, Mar 27, 2003 at 07:47:26AM -0500, Diana Shannon wrote:
...
> Maybe I'm overcomplicating this, and I sincerely apologize if I am, but
> I see tabs as intimately connected to decisions related to URI space and
> docs reorganization. I think deciding tabs before a docs reorganization,
> is premature -- IMHO. Anyone ready to reorganize docs? Or is this a
> one-person job?
Technically, Forrest tabs are completely passive things that simply react
based on the current path. Specifically, changes in tabs.xml can *never*
affect the URI space. Tabs are purely a navigational aid. Changing tabs
is like changing a set of bookmarks in a physical book.
As such, I think a bit of tinkering won't hurt, especially as the
Forrest-generated site is far from going live.
> I also am against maintaining the artificial distinction between user
> and developer docs.
+1
--Jeff
> So I could live with
>
> | Cocoon (project related) | Docs (all docs) | Samples (all samples,
> may not exist on web site) | Wiki
>
> for now.
>
> Diana
>
>
Re: Forrest documentation tabs (was [vote] Forrestizing Cocoon...)
Posted by Andrew Savory <an...@luminas.co.uk>.
On Thu, 27 Mar 2003, Diana Shannon wrote:
> Maybe I'm overcomplicating this, and I sincerely apologize if I am, but
> I see tabs as intimately connected to decisions related to URI space and
> docs reorganization. I think deciding tabs before a docs reorganization,
> is premature -- IMHO. Anyone ready to reorganize docs? Or is this a
> one-person job?
I'm waiting on the final decision for cocoon-docs CVS before ploughing in
with suggestions and help on reorganising the docs. But it's not a
one-person job; you are not alone!
> I also am against maintaining the artificial distinction between user
> and developer docs.
Ditto. I think a more natural distinction (if, indeed, a distinction needs
to be made) is between "reference" and "user guide/howto" ...
> | Cocoon (project related) | Docs (all docs) | Samples (all samples,
> may not exist on web site) | Wiki
or that ;-)
Andrew.
--
Andrew Savory Email: andrew@luminas.co.uk
Managing Director Tel: +44 (0)870 741 6658
Luminas Internet Applications Fax: +44 (0)700 598 1135
This is not an official statement or order. Web: www.luminas.co.uk
Re: Forrest documentation tabs (was [vote] Forrestizing Cocoon...)
Posted by Diana Shannon <sh...@apache.org>.
On Thursday, March 27, 2003, at 07:41 AM, Bertrand Delacretaz wrote:
> But if no one has the time or will to come up with alternate proposals
> for tabs, I think Jeff should go ahead and implement his tabs proposal,
> without waiting too long for answers.
I guess don't see why we need tabs yet because we can use Forrest with a
single tab.
Maybe I'm overcomplicating this, and I sincerely apologize if I am, but
I see tabs as intimately connected to decisions related to URI space and
docs reorganization. I think deciding tabs before a docs reorganization,
is premature -- IMHO. Anyone ready to reorganize docs? Or is this a
one-person job?
I also am against maintaining the artificial distinction between user
and developer docs.
So I could live with
| Cocoon (project related) | Docs (all docs) | Samples (all samples,
may not exist on web site) | Wiki
for now.
Diana
Re: Forrest documentation tabs (was [vote] Forrestizing Cocoon...)
Posted by Bertrand Delacretaz <bd...@codeconsult.ch>.
Le Jeudi, 27 mars 2003, à 13:24 Europe/Zurich, Diana Shannon a écrit :
> ...I wasn't asking for a vote, just hoping to bring back some very
> good ideas about tabs, lacking the time ATM to make a proposal about
> tabs myself.
ok, no problem.
But if no one has the time or will to come up with alternate proposals
for tabs, I think Jeff should go ahead and implement his tabs proposal,
without waiting too long for answers.
-Bertrand
Re: Forrest documentation tabs (was [vote] Forrestizing Cocoon...)
Posted by Diana Shannon <sh...@apache.org>.
On Thursday, March 27, 2003, at 01:03 AM, Bertrand Delacretaz wrote:
>>
>>>
>>> - Someone needs to decide how to use the tabs. How about:
>>>
>>> | Home | User docs | Dev docs | Wiki |
>>
>> I think the community needs to decide this, not any individual. Again,
>> it's been discussed by some of us already across different threads....
>
> IMHO waiting for community consensus on such things often slows things
> down.
> I don't think it's such a big thing as to require a vote.
I wasn't asking for a vote, just hoping to bring back some very good
ideas about tabs, lacking the time ATM to make a proposal about tabs
myself.
Diana
Forrest documentation tabs (was [vote] Forrestizing Cocoon...)
Posted by Bertrand Delacretaz <bd...@codeconsult.ch>.
Le Mercredi, 26 mars 2003, à 21:08 Europe/Zurich, Diana Shannon a écrit
:
> On Wednesday, March 26, 2003, at 10:30 AM, Jeff Turner wrote:
>
>>
>> - Someone needs to decide how to use the tabs. How about:
>>
>> | Home | User docs | Dev docs | Wiki |
>
> I think the community needs to decide this, not any individual. Again,
> it's been discussed by some of us already across different threads....
IMHO waiting for community consensus on such things often slows things
down.
I don't think it's such a big thing as to require a vote.
Having visible changes in the docs makes it easier to get feedback,
much more efficient than long discussions that often send people back
to waiting mode.
Don't get me wrong, I'm not against community decisions, it's just that
we have to find a balance and there is a big need for *action* in the
docs department right now, there is some momentum and we have to do our
best to keep it.
Release early, release often - I think this should apply to the docs as
well as the code, CVS is here to fix things when needed.
My 2 swiss centimes.
-Bertrand
Re: [vote] Forrestizing Cocoon and more
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Stephan Michels wrote, On 27/03/2003 10.42:
>
> On Wed, 26 Mar 2003, Diana Shannon wrote:
>
>>On Wednesday, March 26, 2003, at 10:30 AM, Jeff Turner wrote:
>>
>>> - Someone needs to decide how to use the tabs. How about:
>>>
>>> | Home | User docs | Dev docs | Wiki |
>>
>>I think the community needs to decide this, not any individual. Again,
>>it's been discussed by some of us already across different threads.
>>
>>>I certainly wouldn't ditch the 'docs' target.
>>
>>Please not yet!
>
> Can you explain why you adhere to the docs targets. Please, I want
> to kow ;-) Perhaps we can help. Is Forrest too slow?
BTW, please let's keep it for now side by side. Call it old-docs,
whatever, but it's needed ATM to easily test the CLI changes we are
doing and having comparable results.
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: [vote] Forrestizing Cocoon and more
Posted by Bertrand Delacretaz <bd...@codeconsult.ch>.
Le Jeudi, 27 mars 2003, à 13:20 Europe/Zurich, Diana Shannon a écrit :
> ...As a matter of respect for our users, and to avoid broken links on
> the web site, I see know reason why we should drop the old docs target
> until the new one works 100%....
+1 (although I'd put it bar slightly lower than 100%)
-Bertrand
Re: [vote] Forrestizing Cocoon and more
Posted by Diana Shannon <sh...@apache.org>.
On Thursday, March 27, 2003, at 04:42 AM, Stephan Michels wrote:
>>
>>> I certainly wouldn't ditch the 'docs' target.
>>
>> Please not yet!
>>
>
> Can you explain why you adhere to the docs targets.
I think I'm being misunderstood here.
As a matter of respect for our users, and to avoid broken links on the
web site, I see know reason why we should drop the old docs target until
the new one works 100%. We have a few remaining problems, outlined by
Jeff. Sylvain recently voiced the same thing, that old docs build should
work until the transition is complete.
> Please, I want
> to kow ;-) Perhaps we can help. Is Forrest too slow?
I'm not against Forrest. I have supported it's adoption since the first
day it was formed. I hate the old documentation system. I have
****zero**** interest in maintaining the old way. I just am 100% against
disruption for our users and the cvs when we can avoid it, which we can
and are doing in this case.
Ok?
Diana
Re: [vote] Forrestizing Cocoon and more
Posted by Stephan Michels <st...@apache.org>.
On Wed, 26 Mar 2003, Diana Shannon wrote:
>
> On Wednesday, March 26, 2003, at 10:30 AM, Jeff Turner wrote:
>
> >
> > - Someone needs to decide how to use the tabs. How about:
> >
> > | Home | User docs | Dev docs | Wiki |
>
> I think the community needs to decide this, not any individual. Again,
> it's been discussed by some of us already across different threads.
>
> > I certainly wouldn't ditch the 'docs' target.
>
> Please not yet!
>
Can you explain why you adhere to the docs targets. Please, I want
to kow ;-) Perhaps we can help. Is Forrest too slow?
Stephan.
Re: [vote] Forrestizing Cocoon and more
Posted by Diana Shannon <sh...@apache.org>.
On Wednesday, March 26, 2003, at 10:30 AM, Jeff Turner wrote:
>
> - Someone needs to decide how to use the tabs. How about:
>
> | Home | User docs | Dev docs | Wiki |
I think the community needs to decide this, not any individual. Again,
it's been discussed by some of us already across different threads.
> I certainly wouldn't ditch the 'docs' target.
Please not yet!
> CVS Forrest is horribly
> (unusably?) slow by comparison. 3 mins vs. 15 mins. I hope this mostly
> due to the new CLI. If it is the speed/generality tradeoffs Forrest has
> made, we'll have to reconsider them.
Did anyone ever follow up on Berni's suggestion to my same concern
(voiced last November on Forrest)?
http://marc.theaimsgroup.com/?l=forrest-dev&m=103782712902758&w=2
Diana
Re: [vote] Forrestizing Cocoon and more
Posted by Stephan Michels <st...@apache.org>.
On Thu, 27 Mar 2003, Jeff Turner wrote:
> (moved to cocoon-docs)
>
> On Wed, Mar 26, 2003 at 11:30:09AM +0100, Stephan Michels wrote:
> >
> > On Wed, 26 Mar 2003, Jeff Turner wrote:
> >
> > > On Wed, Mar 26, 2003 at 11:08:39AM +0100, Stefano Mazzocchi wrote:
> > > ...
> > > > Moreover, to be honest, I think that we should aim to improve
> > > > forrest/lenya and make it a structured wiki and setup a CMS and point
> > > > users to that for editing.
> > >
> > > Getting the latest Chaperon updates was a major impetus for the recent
> > > Cocoon upgrade. Wiki parsing is just waiting for a volunteer.
> >
> > ;-) First we make the transition, then I will help you on this topic.
> > deal?
>
> :) Thanks, help would be very welcome.
>
> As for Forrest transition, the easy part is done. The site currently
> built at:
>
> http://forrestbot.cocoondev.org/sites/cocoon-site/
>
> should now contain all the content of the Cocoon-built site.
Great! We can finally see the light at the end of the road ;-)
> To get the CVS version of Forrest known to work with Cocoon, run 'cvs
> update -r stable' in xml-forrest.
>
> Remaining issues:
>
> - There are lots of untranslated @tokens@ in the xdocs. A short-term
> solution would be to do a filter-copy in forrest-build.xml before
> Forrest is invoked. Nicer long-term solution is to write a
> FilterTransformer, using input modules much like
> LinkRewriterTransformer does. If there's no better ideas I'll get
> around to this eventually.
Perhaps we do something like prepare-docs, copying(filtering) the docs
into the build dir, add some others like jars.xml, and then generate the
docs from this dir. But perhaps there is a problem with forrestbot?
> - jars.xml isn't generated. Could be fixed
> with another forrest-build.xml pre-generation hack. Perhaps in
> Forrest we should allow hooks for calling targets in external Ant
> scripts.
>
> - doclist.html isn't used. doclist.html isn't referred to anywhere, and
> the mechanism of aggregating all book.xml's looks kinda brittle, so I
> didn't port it to the Forrest sitemap.xmap. If we still want this,
> it's easy to do.
>
> - Someone needs to decide how to use the tabs. How about:
>
> | Home | User docs | Dev docs | Wiki |
cocoondev.org?
> I certainly wouldn't ditch the 'docs' target. CVS Forrest is horribly
> (unusably?) slow by comparison. 3 mins vs. 15 mins. I hope this mostly
> due to the new CLI. If it is the speed/generality tradeoffs Forrest has
> made, we'll have to reconsider them.
:-( Yes.
Is Forrest using a <uptodate> task like the docs_check target?
Stephan.