You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@avalon.apache.org by Nicola Ken Barozzi <ni...@apache.org> on 2002/11/26 11:59:37 UTC
[PROPOSAL] Use Forrest for all Avalon docs
This proposal should mark the end to our doc discussions.
Forrest has grown since the start, and the Phoenix guys have accepted to
convert the documentation format to Forrest format.
Forrest is being actively developed and maintained, and projects like
incubator.apache.org and commons.apache.org are using/going to use it.
I want to propose that all projects in Avalon-land have documentation in
Forrest format.
As for the skin, it's (again) to be decided, and it must be the same one
for all.
Avaliable are the forrest skin, the new avalon-site one similar to the
current one, and the new krysalis one
(http://www.krysalis.org/centipede/beta3/).
All can be customized in font sizes and color schemes, and the Forrest
one will (soon) be changed to a CSS-only version.
Please let me know what you prefer.
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: [PROPOSAL] Use Forrest for all Avalon docs
Posted by Stefano Mazzocchi <st...@apache.org>.
Peter Donald wrote:
> On Wed, 27 Nov 2002 09:28, Stefano Mazzocchi wrote:
>
>>Uh, don't you find it interesting that you didn't feel like there was
>>any need to discuss about this in public?
>
>
> Actually it was discussed except for the "database" stuff.
Can you please point me to the email messages where this happened?
>>3 Mb of DTDs? where is this?
>
>
> there was a few copies of docbook DTDs - each weighing in at just under 1 MB.
> Thats not even including the 10 different copies of the document.dtd and so
> forth.
I repeat my question: where is this?
--
Stefano Mazzocchi <st...@apache.org>
--------------------------------------------------------------------
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: [PROPOSAL] Use Forrest for all Avalon docs
Posted by Peter Donald <pe...@realityforge.org>.
On Wed, 27 Nov 2002 09:28, Stefano Mazzocchi wrote:
> Uh, don't you find it interesting that you didn't feel like there was
> any need to discuss about this in public?
Actually it was discussed except for the "database" stuff. And that is just
something that is sitting in my head and may never be implemented. If it does
get implemented it will be discussed aswell.
> 3 Mb of DTDs? where is this?
there was a few copies of docbook DTDs - each weighing in at just under 1 MB.
Thats not even including the 10 different copies of the document.dtd and so
forth.
--
Cheers,
Peter Donald
----------------------------------------
"Liberty means responsibility. That is
why most men dread it." - Locke
----------------------------------------
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: [PROPOSAL] Use Forrest for all Avalon docs
Posted by Stefano Mazzocchi <st...@apache.org>.
Peter Donald wrote:
> On Tue, 26 Nov 2002 22:33, Nicola Ken Barozzi wrote:
>
>>>Anakia does it's job fine, is easier to use
>>>and much more lightweight. No need to ditch a tool that works.
>>
>>Then I'm confused.
>>Why did you consent for the change in Phoenix docs?
>
>
> Because I want to move to more advanced documentation generation features that
> cocoon provides. In particular generating single pdfs for guides but multiple
> html pages and being able to "suck" docs from other codebases into the
> phoenix docs (ie suck loader docs in as loader is used by phoenix etc).
> Integrate with javadocs and generate specific documentation from java/config
> source files. Also have a single "uber" pdf guide that encompases all phoenix
> docs. I also eventually want to move to "database" generated website.
Uh, don't you find it interesting that you didn't feel like there was
any need to discuss about this in public?
> By "database" I mean sucking in data from multiple sources such as
> /etc/passwd, /etc/groups, /home/cvs etc and then processing it with something
> like http://xineo.sourceforge.net/xil/
>
> Essentially I wanted to be able to do multi-format/channel publishing. While
> possible with anakia is no where as easy as it is in cocoon.
I'm glad to hear that but here you are showing your 'one-man show'ness
evidently and even more you expressed so with a simple '-1' and people
had to ask you 'explicitly' to share your thoughts with us in order to
be able to plans things together.
Do you start seeing why this community perceives you as working alone on
"your" stuff and 'tollerate' the presence of others?
I'll tell you: this is *very* annoying and frustrating, no matter how
impressive your end results are. And you know why? because this model of
yours is against the notion of software darwinism. Your mutations in the
code are huge steps and the community feedback is received only after
big steps are taken. This 'reduces' the ability of the environment (the
community and the users) to influence the evolution of the project in an
incremental way.
Do you realize that by making such big plans and actually implementing
them without early feedback you are actually 'hurting' the long term
technical evolution of this project?
>>Why did you create a framework Forrest branch?
>
>
> Because I was sick of hearing users complain. I get on average 6-7 complaints
> a month about the size of our CVS download or the size of our distributions
> or whatever. About 90% of that size is due to Cocoon jars and excess unused
> cruft in documentation tree (like 3 MB of DTDs).
3 Mb of DTDs? where is this?
--
Stefano Mazzocchi <st...@apache.org>
--------------------------------------------------------------------
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: [PROPOSAL] Use Forrest for all Avalon docs
Posted by Peter Donald <pe...@realityforge.org>.
On Tue, 26 Nov 2002 22:33, Nicola Ken Barozzi wrote:
> > Anakia does it's job fine, is easier to use
> > and much more lightweight. No need to ditch a tool that works.
>
> Then I'm confused.
> Why did you consent for the change in Phoenix docs?
Because I want to move to more advanced documentation generation features that
cocoon provides. In particular generating single pdfs for guides but multiple
html pages and being able to "suck" docs from other codebases into the
phoenix docs (ie suck loader docs in as loader is used by phoenix etc).
Integrate with javadocs and generate specific documentation from java/config
source files. Also have a single "uber" pdf guide that encompases all phoenix
docs. I also eventually want to move to "database" generated website.
By "database" I mean sucking in data from multiple sources such as
/etc/passwd, /etc/groups, /home/cvs etc and then processing it with something
like http://xineo.sourceforge.net/xil/
Essentially I wanted to be able to do multi-format/channel publishing. While
possible with anakia is no where as easy as it is in cocoon.
> Why did you create a framework Forrest branch?
Because I was sick of hearing users complain. I get on average 6-7 complaints
a month about the size of our CVS download or the size of our distributions
or whatever. About 90% of that size is due to Cocoon jars and excess unused
cruft in documentation tree (like 3 MB of DTDs).
Moving to using forrest means we get to remove a bunch of jars from CVS which
means less complaints hopefully. (Besides our site was not actually building
prior to my starting due to malformed docbook docs).
> >>About the skin, what are your comments?
> >
> > The skin we have seems to work.
>
> The skin we have is incompatible with Forrest; or are you talking about
> the new avalon-tigris one? I don't know if others have seen it yet.
The avalon-tigris one is meant to be the same as our current site which is why
I originally created it.
--
Cheers,
Peter Donald
---------------------------------------------------
"Wise men don't need advice. Fools don't take it."
-Benjamin Franklin
---------------------------------------------------
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: [PROPOSAL] Use Forrest for all Avalon docs
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Peter Donald wrote:
> On Tue, 26 Nov 2002 22:23, Nicola Ken Barozzi wrote:
>
>>Peter Donald wrote:
>>
>>>-1 mandating it everywhere.
>>>+1 for using it in framework cvs
>>
>>Please explain why.
>
> Theres no reason to mandate it.
Consistency, DTD validation, easier for users-developers to learn only
one tool, instant page changes via the embedded local webserver (thus
it's faster than any static generation system for editing).
> Anakia does it's job fine, is easier to use
> and much more lightweight. No need to ditch a tool that works.
Then I'm confused.
Why did you consent for the change in Phoenix docs?
Why did you create a framework Forrest branch?
>>About the skin, what are your comments?
>
> The skin we have seems to work.
The skin we have is incompatible with Forrest; or are you talking about
the new avalon-tigris one? I don't know if others have seen it yet.
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: [PROPOSAL] Use Forrest for all Avalon docs
Posted by Peter Donald <pe...@realityforge.org>.
On Tue, 26 Nov 2002 22:23, Nicola Ken Barozzi wrote:
> Peter Donald wrote:
> > -1 mandating it everywhere.
> > +1 for using it in framework cvs
>
> Please explain why.
Theres no reason to mandate it. Anakia does it's job fine, is easier to use
and much more lightweight. No need to ditch a tool that works.
> About the skin, what are your comments?
The skin we have seems to work.
--
Cheers,
Peter Donald
*------------------------------------------------------*
| "Nearly all men can stand adversity, but if you want |
| to test a man's character, give him power." |
| -Abraham Lincoln |
*------------------------------------------------------*
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: [PROPOSAL] Use Forrest for all Avalon docs
Posted by Stefano Mazzocchi <st...@apache.org>.
Nicola Ken Barozzi wrote:
>
>
> Peter Donald wrote:
>
>> -1 mandating it everywhere. +1 for using it in framework cvs
>
>
> Please explain why.
Yes, Peter. A -1 without a reasonable explaination is equivalent of a
slap in a face.
Think about it: what if you proposed something and then I came to you
and say '-1'. Period. How could you possible understand how to fix your
proposal to match my needs if I didn't express them?
--
Stefano Mazzocchi <st...@apache.org>
--------------------------------------------------------------------
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: [PROPOSAL] Use Forrest for all Avalon docs
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Peter Donald wrote:
> -1 mandating it everywhere.
> +1 for using it in framework cvs
Please explain why.
About the skin, what are your comments?
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: [PROPOSAL] Use Forrest for all Avalon docs
Posted by Peter Donald <pe...@realityforge.org>.
-1 mandating it everywhere.
+1 for using it in framework cvs
--
Cheers,
Peter Donald
Duct tape is like the force. It has a light side, and a dark side, and
it binds the universe together ...
-- Carl Zwanzig
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: [PROPOSAL] Use Forrest for all Avalon docs
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Leo Simons wrote:
> On Wed, 2002-11-27 at 12:08, Leo Simons wrote:
>
>>I think it would be real good to make this move, but I don't want to put
>>in the effort to make these changes right now. As for skins, I can live
>>with any of them; the krysalis looks real nice :D
>
> on a related note, the avalon excalibur front page has a <warn> tag for
> the sources but no red flagging of any kind shows up on the generated
> docs. I can't really figure out where/how to fix this?
The current forrest document11 DTD is here
http://xml.apache.org/forrest/document-v11.dtdx.html
Since the Cocoon in the jakarta-avalon repo is no more to remain, we
should port at least all docs currently done by Cocoon (it was
effectively a modified Forrest) to Forrest.
I've merged the old skin with the new one in Forrest-CVS, so that with
latest Forrest CVS (which also has better error reporting), the pages
render exactly like the ones on the main site now. This is to prevent us
to get tangled again in skin decisions ATM.
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: [PROPOSAL] Use Forrest for all Avalon docs
Posted by Leo Simons <le...@apache.org>.
On Wed, 2002-11-27 at 12:08, Leo Simons wrote:
> I think it would be real good to make this move, but I don't want to put
> in the effort to make these changes right now. As for skins, I can live
> with any of them; the krysalis looks real nice :D
on a related note, the avalon excalibur front page has a <warn> tag for
the sources but no red flagging of any kind shows up on the generated
docs. I can't really figure out where/how to fix this?
cheers,
- Leo
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: [PROPOSAL] Use Forrest for all Avalon docs
Posted by Leo Simons <le...@apache.org>.
I'm +0.
I think it would be real good to make this move, but I don't want to put
in the effort to make these changes right now. As for skins, I can live
with any of them; the krysalis looks real nice :D
cheers,
- Leo
On Tue, 2002-11-26 at 11:59, Nicola Ken Barozzi wrote:
> This proposal should mark the end to our doc discussions.
>
> Forrest has grown since the start, and the Phoenix guys have accepted to
> convert the documentation format to Forrest format.
> Forrest is being actively developed and maintained, and projects like
> incubator.apache.org and commons.apache.org are using/going to use it.
>
> I want to propose that all projects in Avalon-land have documentation in
> Forrest format.
>
> As for the skin, it's (again) to be decided, and it must be the same one
> for all.
>
> Avaliable are the forrest skin, the new avalon-site one similar to the
> current one, and the new krysalis one
> (http://www.krysalis.org/centipede/beta3/).
>
> All can be customized in font sizes and color schemes, and the Forrest
> one will (soon) be changed to a CSS-only version.
>
> Please let me know what you prefer.
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>