(Background:
Over on Infra there has been some very harsh criticism of Forrest
lately. Some of it is just plain ill-informed, some of it is very valid.
We asked that the feedback be placed somewhere where Forrest users and
developers could see it and therefore contribute to the discussion. We
have much to learn from these views.
Leo kindly put lots of effort into this for us, here's my response
)
Leo Simons wrote:
> First of, please don't get or feel upset. Please feel free to
completely ignore
> all comments/questions/criticism which you've seen on the Incubator list
> or elsewhere that have anything to do with Forrest and go and do fun
stuff
> rather than spend time arguing with people.
The problem is when people make incorrect statements about a product we
have to correct those misinterpretations because they are damaging to
the potential user impression of an excellent tool (excellent in the
right use case).
Constructive criticism is good and we encourage it. So thanks for your
effort in writing this mail.
> History
> -------
An impressive list of mails, but none of them are on the Forrest lists.
Not sure how Forrest devs can learn from or contribute to such
discussion if they are not on our lists.
Speaking personally I have considerable experience of Forrest in a
variety of environments and use cases. I have about 400 sites ranging
from just a few pages to tens of thousands. I have single sites
generating content from up to ten different sources (database, CSS, SVN,
multiple CMS's etc.) I even have a site that is generating real time
monitoring information from electronic machinery in tabulated data and
graph form. Forrest is an amazing tool.
With all this experience I think I have a pretty deep understanding of
what Forrest can and can't do, and most (not all) of the criticism of
Forrest in you incubator proposal is simply incorrect. Not that this
means you shouldn't build a simple tool for your use case. My point is
that it is a shame I have *never* seen any of these mails, or useful
summaries of them or even feature requests within Forrest.
Had I seen some of that I may have been able to help before you.
(I've not read them now either, although I will certainly do so since
you took the time to collate it all)
> Present day
> -----------
> Typing up as I go along.
>
> Right now I'm following the incubator website howto guide. It takes
quite a
> while since it has to check out things such as a servlet engine, a whole
> website, lots of skins I don't need, dozens of jars I already have on my
> system (in my maven repository).
Yes, we should consider moving to Maven, we should also consider
integrating the doc generation stuff with Mavens cool Java documentation
generation stuff. Somebody did this once, but unfortunately it has not
been maintained.
As for checking out servlet engines etc. There is no need. Just download
a binary distribution which comes with a minimal Jetty installation.
This is the kind of misinformation that is damaging. To a potential user
it makes it sound like Forrest has too high a hurdle to get going with.
> Even if it works once I get forrest built
> (why do I need to build anything?)
You don't have to build anything, just download a binary distribution,
this is more misinformation.
You stated it takes way longer than a few seconds to install Forrest. It
doesn't (apart from download time), there is no manual configuration to
do at all, just download and run. You may want to set FORREST_HOME and
add it to your path, but that is a convenience not a requirement.
> I made a mistake and typed `forrest run` in the wrong directory.
> After a few screens of output and a minute or two later I get to visit a
> website which tells me (among other things).
>
>
/Users/lsimons/dev/asf/incubator-public-trunk/forrest_07_branch/forrest.properties
(No such file or directory)
>
> why on earth didn't it tell me that before running lots of ant build
stuff?
Yes, that's a known issue. I fixed it once, but it seems to have slipped
back in again. It should detect there is no source and fail gracefully
> Grr. I feel silly now. `cd .. && forrest run`. And here it goes off
fetching a
> bunch of plugins again! Gaah!
This is a one off activity. Just as when you install something like
maven the first time it retrieves any needed stuff.
The purpose of the plugin infrastructure is that we can now trim Forrest
down so that simple sites don't have all the extra stuff in there that
is not needed. This trimming down is a "work in progress". In other
words this step is a result of hearing complaints about Forrest having
too many functions within it that are not needed for use case X or Y.
With SVN head the plugins are automatically built from local sources
rather than downloading them. If you get a binary version of the next
release there will be a separate distribution of the plugins for those
wanting to avoid this step. We may even release different default
configurations of Forrest for various common use cases, each version
including the required plugins for that use case.
So you see, some of your complaints are about things that are in place
to satisfy some of your other complaints. This is a no-win situation.
> Ok, in terms of making this a useful experience, lets try to add "the
> incubator is closed for renovations" to the front page. I switch to
console,
> hit CTRL+Z, then run `edit site-author/index.html` (why is it called
> site-author?).
It is called site-author because whoever set it up decided to call it
that. It is completely configurable. The default is
src/documentation/content, so this has nothing to do with Forrest, but
instead with the incubator as a user.
> I add this:
>
> <h1 style="color: red; font-weight: bold">The Incubator Is Closed
> For Renovation</h1>
>
> <p>Apache is not accepting any new code donations at the moment.
> Thank you.</p>
>
> Save, type 'fg', switch to the browser, hit refresh. Grr. After
waiting for
> about 5 seconds I find that my CSS information didn't make it into
the final
> page. Or is something else wrong?
No you are not missing anything. That is by design, putting style
information in the source is not allowed since it goes against best
practice. The idea of Forrest is that you get consistent output
regardless of the rubbish that is put in, we therefore ignore local
style information since users tend to do all sorts of weird and
wonderful things with it and thus break the standard look and feel of a
site.
What you should do is:
<h1 class="notice">...</h1>
then add the notice CSS class to the <extra-css> in skinconf.xml This
will then result in the same class being usable in multiple locations,
whilst still being managed from a single location (which is the point of
CSS of course).
Sure the overhead is slightly higher the first time you use a class, but
it makes the maintenance of the site much easier in the long term.
If you were using XDoc rather than html you could also do:
<warning>...</warning>
> I try "view source" but the HTML in there
> sort-of scares me away from even trying.
Yes, HTML output become too verbose and confusing. The trunk work on our
new "skinning" system (called dispatcher) improves this considerably,
it's a work in progress.
> I get rid of the CSS but in my haste
> I manage to cut out one '>' too much. The page still manages to
render. There
> is no error message, and...I'll be damned...the entire title line is
gone,
> even when I "view source".
This is a problem of using HTML as the source and would not occur if you
were using XDoc. We use JTidy to preprocess the HTML (we must have valid
XML to work with). I guess JTidy is just removing the invalid content.
I'll look into whether this can be configured in JTidy and make it fail
if such an error exists.
However, it is worth noting that if you try and build a site with
"forrest site" a pre-processing validation step would detect it and
report it.
> Okay, I give up. Lets just get rid of the custom
> HTML and commit the critter. I type 'forrest site'. An icon pops up on my
> Dock (I use mac os x). Interesting. I click on it. It identifies
itself as
> "org.apache.cocoon.Main" but ignores me. Meanwhile forrest is
running, taking
> about 2.5 to 3.5 seconds per web page to render (it looks like its
rendering
> everything, even though I changed 3 lines of a single file). The
output is
> something like
>
> * [81/67] [18/65] 3.697s 24.8Kb projects/index.html
I can't comment on the dock icon I don't use Mac so I have no idea what
that means.
The time for page generation seems way too long. I'm running a fairly
modest Intel machine and it takes milliseconds to generate each page
(after the first). Perhaps another Mac user can investigate.
> I have no idea what the first two columns mean. They don't seem to
correspond
> to anything, since the numbers change at random between pages. Ugh.
You know I don't know what they mean either. I never bothered to find
out because I never needed to know and I never saw a user question that
involved them.
It would be nice to have a cleaner output, but for a 0.8-dev I think
this is just fine. In the event of broken links we do provide a nice XML
file that lists what they are and where they can be found.
Besides if you use the forrestbot, there is no need to view this output
at all. In other words, we are addressing this issue.
> Now its
> generating a boatload of PDFs too. Surprisingly, those take less time
than the
> corresponding HTML pages! Sheesh, its been running for more than 5
minutes now.
That's because you have asked it to. Don't want them? Turn of the PDF
link by editing skinconf.xml.
They take less time because Cocoon has cached much of the processing for
the pages when it generated the HTML. The PDF is generated from the
cached content. I'm guessing you are not objecting to this ;-)
> Finally its done:
>
> Logging Error: Writing event to closed stream.
> Total time: 6 minutes 21 seconds, Site size: 2,844,977 Site pages: 173
> ------------------------------
> Static site was successfully generated at:
> /Users/lsimons/dev/asf/incubator-public-trunk/site-publish
> ------------------------------
>
> Hmm. I'm a little worried. Did I miss an important error message?
Better not
> commit this...but I'll see what happened...
This was a Cocoon problem and is gone in SVN trunk. Being a 0.8-dev
version we use Cocoon trunk (or near as damn it) so we occasionally fall
foul of issues like this one.
> $ svn status
> ? forrest_07_branch
> M site-author/index.html
> M site-publish/index.pdf
> M site-publish/projects/axion.pdf
> M site-publish/incubation/incubation-process.png
> M site-publish/index.html
> $ svn diff site-publish/index.html
> ...
> -<a name="N1002D"></a><a name="ApacheCon+US+2005"></a>
> +<a name="N10033"></a><a name="ApacheCon+US+2005"></a>
> ...
>
> Huh? Why such a big diff? I can sort-of understand why the index.* files
> have been modified (though this isn't exactly a pretty diff to look at)
> but what's with the image or the axion.pdf? Moreoever, why on earth did
> it spend 5 minutes generating files that are now exactly the same as
> before?? Abort, abort, abort.
I can't explain the axion and png differences. Perhaps this is a badly
configured SVN setup since both of these are binary files.
With respect to the need to generate changed pages, this is an often
requested feature. We are a little limited by Cocoon here, but it is
possible to manually edit a config file that will restrict the
generation to a limited number of pages. Problem there is the need to
manually edit the file - too complex.
The solution? I have an idea that may work, it just came to me now
whilst typing the above para. Other devs have been playing around with
other options too. In other words, it is something we are looking into
and will address before a 1.0 release.
In the meantime, use the ForrestBot. Don't even bother building locally,
Just use "forrest run" for local validation and commit the changes. Let
the ForrestBot take care of the rest.
> Grmbl
> -----
> Here's just a few of the things I don't like:
>
> Incubator-specific
> - actually being discouraged from using the tool. I want to be able
> to fulfill all the steps end-to-end. I'm not exactly a newbie here.
I'm not sure what this refers to, I've only just joined the incubator
list so maybe something from before I arrived.
> - documentation organisation that doesn't match my expectations (I
> expect something like incubator/trunk/xdocs or incubator/trunk/site)
Like I said above, it is totally configurable. Whoever set up the
incubator site has changed the default settings (which are much closer
to what you want). You can change them to whatever you want to have, see
forrest.properties.
> Not incubator specific
> - having to check out lots of stuff I already have on my machine
Agreed, Maven will help here, but will require the installation of Maven
before one can build from source. Not sure which is the worst -
certainly there are projects I have avoided getting the source for
because I didn't have Maven.
> - having to check out lots of stuff I am never going to use
> - having to check out lots of stuff, period
Agreed. We need to split the tools stuff from the core svn checkout.
Plugins are taking none core Forrest functionality out of core and
should be moved into a separate SVN repository. This is a work in progress.
These actions will trim the SVN checkout size considerably. It will also
reduce the binarty distribution size a fair bit (although not enough, we
need real Coocoon blocks for that).
> - having lots of manual installation steps that I would've never
> figured out without reading docs
> - having lots of manual installation steps, period
There should be none if you use a binary distribution (and we have
nightly builds if you are using svn trunk).
I note from [1] that you are using an SVN version, not sure why since
you are on the stable 0.7 release and there are no critical fixes in
that branch.
Even so, the instrcutions for installing Forrest on that page are:
cd /usr/local/svn
svn co
http://svn.apache.org/repos/asf/forrest/branches/forrest_07_branch
forrest_07_branch
cd forrest_07_branch/main
./build.sh
If you used the binary distrubtion then it would be:
Download the tar
unpack
> - some tool taking a long time to do anything or using up a lot of
> resources when its basic task is simple (eg taking minutes for a
> step in the workflow when it should be less than a second)
Use "forrest run" for local QA and the forrestbot for publishing.
Everything is a very fast turnaround. a few seconds to generate the very
first page, a few milliseconds to generate (or regenerate) subsequent pages.
Publishing the full site is a different issue, it can be safely hidden
from the user by using a ForrestBot, but this doesn't solve the
resources issue.
As mentioned above we have this on our radar for a 1.0 release.
> - context switching between console and web browser all the time
There are lots of options here:
Use the HTMLEdit plugin, you can edit your source files in a WYSIWYG
environemnt from within the browser (warning this is a whiteboard plugin
and not been actively developed for some time).
or
Use the Daisy plugin to edit your content in a web based CMS (this is
also a whiteboard plugin but is working very well for Cocoon and
production installations).
and/or
Use the Eclipse plugin that allows you to edit, build and deploy from
within the Eclipse GUI (again this is a fairly early stage product, but
again it is in use in production environments)
and/or
Install the forrestbot locally and use that to build and deploy the site
via a web interface (this does reguire some manual installation, as the
forestbot is only just starting to mature)
> - forrest eating up my HTML without warning or complaining
As mentioned above, it doesn't do it on a "forrest site". Will look into
the JTidy config to see if we can stop it doing it on "forrest run"
> - lots of console output I don't understand
If it really bothers you use the forrestbot which can be configured to
pipe the output to a log file and report only success or failure.
The eclipse plugin intercepts that output and provides more meaningful
information. For the 1.0 release we will, no doubt, move that filtering
to the console output too, but for a 0.8-dev product I think the current
situation is just fine.
> - no "fail early" mechanism so I feel stupid when I make a mistake
> and waste time
Yes, I must find out why my fix for this has been broken again.
> - cryptic error messages no-one understands
Yes, this is a problem. We need to provide decent error handling. It's
actually easy to do, it's just one of those things where a developer
understands what is happening so doesn't do the work to make it clearer.
A must for a 1.0 release.
> - heavy HTML using spacer GIFs and complex tables
The new Dispatcher work is 100% CSS with much lighter HTML and much
easier configuration of the output HTML and skins. It's currently
starting to mature and should be officially in the release after next.
In the meantime, there are at least three active sites using it.
> - rendering everything
Yes, common issue, must be addressed.
> I want *simple* and *predictable* and *trustable*.
Since I am familiar with Forrest I have predictable and trustable.
However, there can certainly be simpler tools that tackle less than
Forrest does.
> ...currently...
>
> * is probably just not possible since java doesn't work too well on
> FreeBSD
That's obviously something we can't fix, but if zones become a permanent
thing then it should be less of an issue.
> * takes over half an hour
> * results in unacceptable resource consumption
Agreed and on the radar
> * $somemthing_to_install_forrest is too complex
We can't really simplify the binary installation (download, unpack). For
svn install it is:
svn co ...
cd forest/main
./build.sh
Not sure how simple we can make it.
> * provides way too much output
Agreed and on the radar for a 1.0 release, even when using the
forrestbot the output is only hidden, we need more concise reporting
like our broken-links file that provides a readable report of any broken
links in the site.
> * does a bunch of stuff I don't understand or that doesn't make sense
> to me
Not sure what this is referring to, perhaps my response above will cover
this.
> * fails the test cases provided and doesn't come close
Eh?
Our tests are run hourly on our zone and report failures to the dev
list. They pass each time.
cd FORREST_HOME/main
./build.sh test
The tests are also run against release candidates and passed with
respect to the binary releases.
> * doesn't show enough difference between the first 'time' and the
second
> 'time'
Agreed (asuuming you mean time to build)
> Note I also want some other "features", such as not having a web
connection
> not being a problem (eg the ssh command above is not acceptable, its just
> that I tested these commands on minotaur so you can see what I mean
without
> installing python).
Forrest 0.7 requires a web connection to download the plugins the
*first* time it finds it needs that plugin. Not after that.
Forrest trunk no longer requires a web connection if you have the src
version or have downloaded a separate plugins bundle (we've not actually
built that bundle yet, will do for the 0.8 release when it makes sense
to do so)
> End The Discussion
> ------------------
> It doesn't help you guys to keep asking "so what's the problem" over
and over
> again. I've talked about the above over and over again the last few
years,
> and the message just hasn't come across (otherwise the above would be
totally
> wrong by now and I'd have nothing left to complain about).
Many of the issues you raise above *are* being or have been solved. One
or two of them are still "on the radar", but we are a 0.8-dev project,
that means we haven't done everything yet.
We do try and listen (when people speak in areas populate), we do act on
what we hear. Howver, not everything is said in earshot (not your long
list of links to discussions you've had, not one of which was on the
Forrest lists.
> Endless navel-staring can hurt communities. Both your development
community
> and that of your users. Accept that some people disagree with you and
move
> on.
It doesn't help when users refuse to keep up with the developments of
the product they are using, *sometimes* they are disagreeing when they
should be agreeing.
Of course, we are not perfect. I'm sure some things have slipped through
the net, but this is Open Source. We scratch the itches that we have as
individuals.
>
> For example, some things I feel are usually a bad idea
> * frameworks
> * XML
> * XSLT
> * SOAP
> * J2EE (esp EJB)
> * "AJAX"
> * fancy HTML
> * classloader magic
> * logging frameworks
> * storing binaries such as jars in version control systems
> * client-server applications for dealing with content
> (note my day job tends to involve all of these. Irony.)
I can agree with some of those, even more in the "simple site
generation" use case you have.
> This makes me "biased" against forrest (except its not bias, since I
sort-of
> know why I don't like this stuff). Either you can accept you're not
going to
> convince me and work together productively on other stuff, or you can
chase
> me away by asking me to explain myself over and over again.
Well, I'v not tried to convince you of anything about your proposal to
create a simple site tool, in fact on the site-dev list I have
*supported* your cause. Nor have I asked you to explain yourself more
than once (sure you may have said it all before, but not on the Forrest
lists which is where I hear things).
All I ask is that if you want to criticise a project you at least ensure
that you criticise it from an informed and current understanding *or*
qualify your statements by making it clear that you have not kept up to
date with the current developements of that project and therefore your
observations may be outdated.
> I hope this helps. If it doesn't just throw it away and go have a beer.
Thank you for taking the time to write this up. I hear you load and
clear and despite my previous paragraph there is stuff in here that is
very valuable.
Ross
[1] http://incubator.apache.org/guides/website.html
