incubator-general mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Crossley <cross...@apache.org>
Subject Re: [RT] Super Simple Site Generation Tool
Date Wed, 28 Dec 2005 02:12:52 GMT
I am not trying to defend Forrest. We already acknowledge
that there are some inadequacies for the situation where
people do not want to learn and enhance the tool, and rather
they just want to use it to generate some quick doco.
Forrest is overkill for that. Why are people using it
and then criticising it for being overkill?

There are some misguided comments below, so i attempt
to correct them. We cannot afford to leave public
comments hanging.

Leo Simons wrote:
> Hi gang,
> 
> It pains me to say this (Forrest is a cool project and I
> consider at least some of its active developers and community
> members my friends) but we've muddled around long enough.

Interesting that you don't acknowledge my recent posting
to general@incubator on this topic.
http://marc.theaimsgroup.com/?t=113108607500002
Re: simplifying the generation of Incubator website

We got very little feedback on that. I had put in an incredible
amount of effort and it hurts to have it ignored. (Thanks
to the sole responder.)

If people have issues with Forrest, then please take them
to the user@forrest mailing list. It is totally unfair
to a new project to just criticise it from afar. We get
very few emails to the user mailing list about any issues
with Forrest. This seems to be especially the case with
committers from Apache projects that decided to use Forrest.

> I think that, for the incubator website, Apache Forrest
> 
>   * is too unstable as a codebase
>   * is way too complex
>   * has too many features we don't need and solves
>     too many problems we don't have
>   * has a learning curve that is too big
>   * does not work well with the SVN-based publishing
>     process we want to use

Would you please explain what you mean by that SVN point.

>   * is not well-understood by enough of the current
>     Incubator volunteers
>   * has caused frustration for too many of the current
>     Incubator volunteers
> 
> I think this needs solving. I think this needs solving in
> general, not just for the Incubator (I have the exact same
> problem over at Gump, which also has a horrendously outdated
> website which also uses Apache Forrest).

At Gump i hope that you are using a recent version
of Forrest and have configured it properly. Remember
that it is in a 0.x series of releases. If you tell
us your problems, then we will try to help.

There are zero postings from Leo to user@forrest and
one or two relevant ones to dev@forrest.

[ snip ]
> Given the above, fixing forrest seems like a lot of work. I think its a
> fundamentally bad fit, being built on top of many many layers of java code
> and several frameworks makes it too heavy by definition. However, since
> it is very easy to customize forrest to output the source format for
> another tool, and we have ready access to forrest experts, migrating away
> from forrest is probably not very painful (I think it involves writing some
> XSLT).

There is already one alternative skin called "plain-dev".
Set that in your forrest.properties and you will get
plain html output. The "-dev" on the end means "in development".
Send a patch if you can fix something.

> As long as the source format stays XML, moving back to forrest later
> is also not painful. Standards-based. Lack of lock-in. Good.

The format of the source content is not a concern of Forrest.
Forrest is only about drawing together various source content
and generating consistent output.

Have you looked at the source format for the Incubator site.
Plain html. It seemed that people could not cope with xml,
so the Incubator site was switched a couple of years ago.

It is interesting to note that even though people have the
option at Incubator to just edit the source html content
and leave it for someone else to generate the site, that this
does not really happen.

It always amazes me that when people see a documentation
blockage, then they blame the tools and go off inventing
new ones.

I predict that the problem has nothing to do with the
particular doc generation tools. It is mostly about content
editing and about people having enough urge to even bother
with that task. Consider the top-level apache.org website
(e.g. /dev/). It uses the wonderfully simple Anakia. However,
people still don't do much enhancement of those docs.

> I think I'll call it xdok.
>
> I'll send another email once I have something working and ready for a
> demo.
> 
> From there, we'll see where it goes.

I sure hope that it doesn't turn into a one-person show.

-David

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org


Mime
View raw message