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 [EMAIL PROTECTED] 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 [EMAIL PROTECTED] 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 [EMAIL PROTECTED] and one or two relevant ones to [EMAIL PROTECTED] [ 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: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
