forrest-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ross Gardler <rgard...@apache.org>
Subject Re: [Fwd: [mail@leosimons.com: Re: [RT] Super Simple Site Generation Tool]]
Date Sat, 31 Dec 2005 12:40:10 GMT
(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


Mime
View raw message