You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@forrest.apache.org by Nicola Ken Barozzi <ni...@apache.org> on 2004/09/02 08:41:38 UTC
[RT] Forrest user impedence
I feel that the Incubator 'incident' has definately highlighted me a
failing for Forrest: it's at least one step too complicated to use.
Look at the Forrest sites *I* want to update: Depot, Incubator,
Xml.Apache, Krysalis. They are all stale mainly because the developers
and *I* feel it a step too much to do it. No wonder other users also
feel this way.
Change the docs - remembering the format -, validate, run Forrest - and
which version? -, copy over the built docs, commit to CVS, log on the
shell and update from CVS...
...compare this with just an update of the docs written in html and
their commit to CVS: unbelievably simpler.
IMHO an ideal setting would not have the users generate the site. This
means having a live Cocoon webapp installed or having the ForrestBot
run. In both cases, SourceForge users would not be able to benefit from
this.
Damn.
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: [RT] Forrest user impedence
Posted by David Crossley <cr...@apache.org>.
Fabio Rinaldi wrote:
> David Crossley writes:
> > Steven Noels wrote:
> > >
> > > From the peanut gallery: I would focus on a single input format and
> > > treat other formats just as binaries. That would be something (X)HTML-
> > > or xdocs-like - *not* the cwiki format.
> >
> > I too worry about having too many input formats,
> > especially the really loose ones like *wiki and
> > the half-supported ones like our docbook subset.
>
> I personally find the support of multiple input formats a very nice
> feature of Forrest. Clearly, users need to be aware of the fact that
> there are some limits in their functionality, ...
This is the trouble - they are not aware or they forget
that there are limitations, and Forrest is then blamed.
> ...but then, nobody is
> forced to actually use them. Users who do not wish to use wiki or
> docbook can stick to the Forrest XML format.
>
> In particular, I find wiki a very useful "entry" format. E.g. I want
> to quickly add a new page to my site out of some notes I took during
> the day: then wiki is perfect for this purpose, as I do not need to
> bother with XML markup.
Why is xml difficult? There are plenty of good editors.
Sure. We will continue to provide various input formats.
Is there a way to validate *wiki documents? I know that Chaperon
will issue an error in some cases, but that is hard to interpret.
--David
> Later, if I want to expand that page, I can
> either keep it in wiki, or replace it with the generated XML (if I
> want to do more sophisticated things).
>
> Btw, as previously mentioned, I spent some time trying to add support
> for "MoinMoin" wiki. I can post what I have so far, if there is any
> interest.
>
> Best,
> Fabio
Re: [RT] Forrest user impedence
Posted by Fabio Rinaldi <ri...@ifi.unizh.ch>.
David Crossley writes:
> Steven Noels wrote:
> >
> > From the peanut gallery: I would focus on a single input format and
> > treat other formats just as binaries. That would be something (X)HTML-
> > or xdocs-like - *not* the cwiki format.
>
> I too worry about having too many input formats,
> especially the really loose ones like *wiki and
> the half-supported ones like our docbook subset.
>
I personally find the support of multiple input formats a very nice
feature of Forrest. Clearly, users need to be aware of the fact that
there are some limits in their functionality, but then, nobody is
forced to actually use them. Users who do not wish to use wiki or
docbook can stick to the Forrest XML format.
In particular, I find wiki a very useful "entry" format. E.g. I want
to quickly add a new page to my site out of some notes I took during
the day: then wiki is perfect for this purpose, as I do not need to
bother with XML markup. Later, if I want to expand that page, I can
either keep it in wiki, or replace it with the generated XML (if I
want to do more sophisticated things).
Btw, as previously mentioned, I spent some time trying to add support
for "MoinMoin" wiki. I can post what I have so far, if there is any
interest.
Best,
Fabio
Re: [RT] Forrest user impedence
Posted by David Crossley <cr...@apache.org>.
Steven Noels wrote:
>
> From the peanut gallery: I would focus on a single input format and
> treat other formats just as binaries. That would be something (X)HTML-
> or xdocs-like - *not* the cwiki format.
I too worry about having too many input formats,
especially the really loose ones like *wiki and
the half-supported ones like our docbook subset.
I get concerned that if we get too lax, then people
will blame Forrest for poor production.
> Provide people with a clear
> migration path, but don't carry the burden of backwards-compatibility
> for too many releases. Don't release too often, but make it x.0
> releases.
:-) we will try.
> Make sure Forrest users don't know that Cocoon is underneath.
A certain class of users, then yes. For other users we
should trumpet Cocoon. There are untapped powers.
> Throw away the live webapp idea.
Nah.
> Slim down Cocoon to its bare essentials.
We could certainly do some slimming. Perhaps Cocoon itself
will do some slimming and we get the benefit.
--
David Crossley
Re: [RT] Forrest user impedence
Posted by David Crossley <cr...@apache.org>.
Nicola Ken Barozzi wrote:
> Steven Noels wrote:
> >
> > So what is it? Honestly, I've lost track myself, which must be largely
> > because of my lack of time in tracking progress. :-|
>
> Actually you should go back more, rather than seen the latest progress ;-)
>
> Forrest's initial vision was to be a sort of a project portal, not
> simply site generation like Anakia (remember the comments about a better
> SF?). The CLI mode of operation was deemed to be a necessary
> intermediate step. We still have a long way to go, but IMHO the concrete
> project plans we have in JIRA about 0.7 and 0.8 lay the foundation for
> starting to add features to Forrest.
>
> http://forrest.apache.org/docs/dreams.html
Thanks for popping in again Steven.
You ask "what is it" ... same as it ever was.
We do anything that encourages documentation.
Recently we had to come up with concise words
for a mission statement ...
"The generation of aggregated multi-channel documentation,
maintaining a separation of content and presentation."
Nice and broad, isn't it.
We still firmly believe in all modes of Forrest:
command-line, webapp, and forrestbot. We also are doing
logo generation with SVG. Also as Nicola Ken said,
those portal dreams are still on the list.
--
David Crossley
Re: [RT] Forrest user impedence
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Steven Noels wrote:
> On 02 Sep 2004, at 10:14, Nicola Ken Barozzi wrote:
>
>> It seems you see Forrest as Anakia2.
>
> ATM, frankly: yes. And a good one at that.
>
>> This is exactly what I *don't* want. IMO users see Forrest as too big
>> because they think it's like Anakia, which is wrong.
>
> So what is it? Honestly, I've lost track myself, which must be largely
> because of my lack of time in tracking progress. :-|
Actually you should go back more, rather than seen the latest progress ;-)
Forrest's initial vision was to be a sort of a project portal, not
simply site generation like Anakia (remember the comments about a better
SF?). The CLI mode of operation was deemed to be a necessary
intermediate step. We still have a long way to go, but IMHO the concrete
project plans we have in JIRA about 0.7 and 0.8 lay the foundation for
starting to add features to Forrest.
http://forrest.apache.org/docs/dreams.html
>> The main problem with the Incubator has been that I've moved them to
>> using a dev version, along with the fact that I have not put Forrest
>> in CVS as Anakia is, which is what they expected.
>
> Also, the fact that they want a tool which only processes updated files.
Correct.
> But as said: these were reflections from the peanut gallery. You're free
> to do with them whatever you want. No harm intended.
I appreciate your comments, it helps me get focused.
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: [RT] Forrest user impedence
Posted by Steven Noels <st...@outerthought.org>.
On 02 Sep 2004, at 10:14, Nicola Ken Barozzi wrote:
> It seems you see Forrest as Anakia2.
ATM, frankly: yes. And a good one at that.
> This is exactly what I *don't* want. IMO users see Forrest as too big
> because they think it's like Anakia, which is wrong.
So what is it? Honestly, I've lost track myself, which must be largely
because of my lack of time in tracking progress. :-|
> The main problem with the Incubator has been that I've moved them to
> using a dev version, along with the fact that I have not put Forrest
> in CVS as Anakia is, which is what they expected.
Also, the fact that they want a tool which only processes updated files.
But as said: these were reflections from the peanut gallery. You're
free to do with them whatever you want. No harm intended.
</Steven>
--
Steven Noels http://outerthought.org/
Outerthought - Open Source Java & XML An Orixo Member
Read my weblog at http://blogs.cocoondev.org/stevenn/
stevenn at outerthought.org stevenn at apache.org
Re: [RT] Forrest user impedence
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Steven Noels wrote:
> On 02 Sep 2004, at 08:41, Nicola Ken Barozzi wrote:
>
>> Change the docs - remembering the format -, validate, run Forrest -
>> and which version? -, copy over the built docs, commit to CVS, log on
>> the shell and update from CVS...
>
> From the peanut gallery: I would focus on a single input format and
> treat other formats just as binaries. That would be something (X)HTML-
> or xdocs-like - *not* the cwiki format. Provide people with a clear
> migration path, but don't carry the burden of backwards-compatibility
> for too many releases. Don't release too often, but make it x.0
> releases. Make sure Forrest users don't know that Cocoon is underneath.
> Throw away the live webapp idea. Slim down Cocoon to its bare essentials.
It seems you see Forrest as Anakia2. This is exactly what I *don't*
want. IMO users see Forrest as too big because they think it's like
Anakia, which is wrong.
>> IMHO an ideal setting would not have the users generate the site. This
>> means having a live Cocoon webapp installed or having the ForrestBot
>> run. In both cases, SourceForge users would not be able to benefit
>> from this.
>
> I'm convinced more tools & trickery won't help - quite the contrary.
>
>> Damn.
>
> Look at Gump. Sometimes, it's better to not add to something, but tear
> things down and provide yourself with the freedom of a blank sheet of
> paper.
>
> Anyway, these are my ideas when looking at the Incubator story. One must
> be careful not to push people towards a tool which can't deliver, hoping
> that "if they'll come, it will get built". Anakia is very small and
> focussed, and delivers. It delivers less than what Forrest is capable
> of, but people don't mind since it just works. "maven site": same story.
The main problem with the Incubator has been that I've moved them to
using a dev version, along with the fact that I have not put Forrest in
CVS as Anakia is, which is what they expected.
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: [RT] Forrest user impedence
Posted by David Crossley <cr...@apache.org>.
thorsten wrote:
> Steven Noels wrote:
> > Nicola Ken Barozzi wrote:
> >
> >> Change the docs - remembering the format -, validate, run Forrest -
> >> and which version? -, copy over the built docs, commit to CVS, log on
> >> the shell and update from CVS...
> >
> > From the peanut gallery: I would focus on a single input format and
> > treat other formats just as binaries. That would be something (X)HTML-
> > or xdocs-like - *not* the cwiki format. Provide people with a clear
> > migration path, but don't carry the burden of backwards-compatibility
> > for too many releases. Don't release too often, but make it x.0
> > releases. Make sure Forrest users don't know that Cocoon is underneath.
> > Throw away the live webapp idea. Slim down Cocoon to its bare essentials.
>
> What you said makes perfect sense, but:
>
> "Throw away the live webapp idea"
> IMO that would be the wrong way!
Don't Panic. We are not going to throw it away.
It is too cool. Recently i grabbed an email post
of Nicola Ken, saved it as text, stripped the headers
with vi, merged it into a shell xml document, linked it
in site.xml, viewed it via 'forrest run', tweaked it,
and committed it. I had to save his words fast.
It was enjoyable and productive.
> I would suggest to extend the webapp
> with "lenya" functionality.
Please do. In fact please start a Jira issue for this
so that we can make links to email threads like this.
Too often the words get lost. We just need links, not
copy all the text.
I feel that we are not going to be able to discuss
it properly at this stage, as we need to get our
Forrest release out.
> The problem that we see with the incubator
> and that Nicola mentioned is that the process to actually deploy a
> forrest-documentation is to long and pain in the a##!
>
> I thought about something like this:
>
> forrest
> |
> +-forrest seed
> |
> +-forrestskinbot -> skining, customising
> |
> +-lenya -> editing, workflow
> |
> +-forrestbot -> publishing, deployment
>
> Besides the forrest seed everything should be done by a webinterface or
> other GUI (python/java/...). User do not want to write in tags and they
> should not have to!
>
> The +-forrestskinbot is yet just an idea to edit the skinconf.xml with a
> GUI. I would like to do that in a webinterface where I then can hit the
> refresh button and see the changes. That is very important if you change
> layout because it is a try&error process. Besides the layout the basic
> project infos should be customisable as well.
>
> +-lenya should be integrated into forrest or vice versa. That makes it
> possible to edit the content in a WYSWYG editor! Again writing in tags
> can not be our aim! Lenya should take care of creating new, editing and
> archiving existing content. Namly site.xml, tab.xml and all other xdocs.
> With lenya we have as well workflow!
>
> If a ressource should be published and deployed +-forrestbot should take
> over. He should not only deploy the site but
> >> copy over the built docs, commit to CVS, log on
> >> the shell and update from CVS
This is where things get tricky. Security and procedural
issues come into play. The design discussion on infrastructure
helps in this regard.
> >> IMHO an ideal setting would not have the users generate the site. This
> >> means having a live Cocoon webapp installed or having the ForrestBot
> >> run. In both cases, SourceForge users would not be able to benefit
> >> from this.
>
> That leads us straight to DOCO! IMO it would be time to get together ASF
> wide and make it happen!
It is way past time. As i said elsewhere in this thread,
there have been genuine holdups which are now starting to clear.
Anyway, it is great to see that you are keen to integrate
Forrest and Lenya. Keep on.
--
David Crossley
Re: [RT] Forrest user impedence
Posted by thorsten <th...@apache.org>.
Steven Noels wrote:
> On 02 Sep 2004, at 08:41, Nicola Ken Barozzi wrote:
>
>> Change the docs - remembering the format -, validate, run Forrest -
>> and which version? -, copy over the built docs, commit to CVS, log on
>> the shell and update from CVS...
>
>
> From the peanut gallery: I would focus on a single input format and
> treat other formats just as binaries. That would be something (X)HTML-
> or xdocs-like - *not* the cwiki format. Provide people with a clear
> migration path, but don't carry the burden of backwards-compatibility
> for too many releases. Don't release too often, but make it x.0
> releases. Make sure Forrest users don't know that Cocoon is underneath.
> Throw away the live webapp idea. Slim down Cocoon to its bare essentials.
>
What you said makes perfect sense, but:
"Throw away the live webapp idea"
IMO that would be the wrong way! I would suggest to extend the webapp
with "lenya" functionality. The problem that we see with the incubator
and that Nicola mentioned is that the process to actually deploy a
forrest-documentation is to long and pain in the a##!
I thought about something like this:
forrest
|
+-forrest seed
|
+-forrestskinbot -> skining, customising
|
+-lenya -> editing, workflow
|
+-forrestbot -> publishing, deployment
Besides the forrest seed everything should be done by a webinterface or
other GUI (python/java/...). User do not want to write in tags and they
should not have to!
The +-forrestskinbot is yet just an idea to edit the skinconf.xml with a
GUI. I would like to do that in a webinterface where I then can hit the
refresh button and see the changes. That is very important if you change
layout because it is a try&error process. Besides the layout the basic
project infos should be customisable as well.
+-lenya should be integrated into forrest or vice versa. That makes it
possible to edit the content in a WYSWYG editor! Again writing in tags
can not be our aim! Lenya should take care of creating new, editing and
archiving existing content. Namly site.xml, tab.xml and all other xdocs.
With lenya we have as well workflow!
If a ressource should be published and deployed +-forrestbot should take
over. He should not only deploy the site but
>> copy over the built docs, commit to CVS, log on
>> the shell and update from CVS
>> IMHO an ideal setting would not have the users generate the site. This
>> means having a live Cocoon webapp installed or having the ForrestBot
>> run. In both cases, SourceForge users would not be able to benefit
>> from this.
>
That leads us straight to DOCO! IMO it would be time to get together ASF
wide and make it happen!
>
>
> Look at Gump. Sometimes, it's better to not add to something, but tear
> things down and provide yourself with the freedom of a blank sheet of
> paper.
>
Yeah, we are planing that with the upcoming /forrest seed-basic/. A
blank forrest project ;-).
King regards
thorsten
Re: [RT] Forrest user impedence
Posted by Steven Noels <st...@outerthought.org>.
On 02 Sep 2004, at 08:41, Nicola Ken Barozzi wrote:
> Change the docs - remembering the format -, validate, run Forrest -
> and which version? -, copy over the built docs, commit to CVS, log on
> the shell and update from CVS...
From the peanut gallery: I would focus on a single input format and
treat other formats just as binaries. That would be something (X)HTML-
or xdocs-like - *not* the cwiki format. Provide people with a clear
migration path, but don't carry the burden of backwards-compatibility
for too many releases. Don't release too often, but make it x.0
releases. Make sure Forrest users don't know that Cocoon is underneath.
Throw away the live webapp idea. Slim down Cocoon to its bare
essentials.
> IMHO an ideal setting would not have the users generate the site. This
> means having a live Cocoon webapp installed or having the ForrestBot
> run. In both cases, SourceForge users would not be able to benefit
> from this.
I'm convinced more tools & trickery won't help - quite the contrary.
> Damn.
Look at Gump. Sometimes, it's better to not add to something, but tear
things down and provide yourself with the freedom of a blank sheet of
paper.
Anyway, these are my ideas when looking at the Incubator story. One
must be careful not to push people towards a tool which can't deliver,
hoping that "if they'll come, it will get built". Anakia is very small
and focussed, and delivers. It delivers less than what Forrest is
capable of, but people don't mind since it just works. "maven site":
same story.
Anyway, these are just some loose ramblings.
</Steven>
--
Steven Noels http://outerthought.org/
Outerthought - Open Source Java & XML An Orixo Member
Read my weblog at http://blogs.cocoondev.org/stevenn/
stevenn at outerthought.org stevenn at apache.org
Re: [RT] Forrest user impedence
Posted by David Crossley <cr...@apache.org>.
Nicola Ken Barozzi wrote:
> IMHO an ideal setting would not have the users generate the site. This
> means having a live Cocoon webapp installed or having the ForrestBot
> run. ...
We are lots closer on that front. As we all know, there have
been holdups due to many reasons. Recently we had an excellent
discussion about this on infrastructure@a.o and even designed
the workflow and everything. It seemed that all issues were
resolved. Now we need the energy to put it into place.
(Subject: forrestbot Date: 2004-07-30)
One option was to wait for the new machines that are due soon.
The other option was to approach the Apache Gump project
to run it on their machine until the other ones are ready.
We started on the latter and all is favourable. However
i stopped because i reckon it is better to concentrate
on our release.
--
David Crossley