forrest-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ross Gardler <rgard...@apache.org>
Subject [Fwd: [mail@leosimons.com: Re: [RT] Super Simple Site Generation Tool]]
Date Sat, 31 Dec 2005 12:36:05 GMT


The following message from Leo Simons seems to have got lost. He asked 
me to forward it to the list as he is not a subscriber.


----- Forwarded message from Leo Simons <mail@leosimons.com> -----

From: Leo Simons <mail@leosimons.com>
Date: Wed, 28 Dec 2005 06:31:11 -0800
Subject: Re: [RT] Super Simple Site Generation Tool
To: user@forrest.apache.org

(this carried over from general@incubator.apache.org. Note I don't
subscribe to user@forrest so CC me if you want me to read the reply)

Ross, David, guys,

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.

But since you asked. Here's feedback. This is really long. You're going to
have to do some digesting to figure out what I mean I'm afraid.

History
-------
First of...no-one is perfect. Most brilliant hackers are lousy at
writing bug reports. Feature requests are worse. But I've really been a
Forrest user for over 3 years yet it has never worked well for me. At
several times during that period I've gotten in touch with the forrest
community, heck at some point I think I wrote so many patches I got
commit access. For example, Avalon was one of the first projects to want
to replace anakia with something else...

   http://www.mail-archive.com/avalon-dev@jakarta.apache.org/msg07101.html
   http://www.mail-archive.com/avalon-dev@jakarta.apache.org/msg07669.html
   http://www.mail-archive.com/avalon-dev@jakarta.apache.org/msg08378.html
   http://www.mail-archive.com/avalon-dev@jakarta.apache.org/msg08784.html
   http://www.mail-archive.com/avalon-dev@jakarta.apache.org/msg10148.html
   http://www.mail-archive.com/avalon-dev@jakarta.apache.org/msg10523.html
   http://www.mail-archive.com/avalon-dev@jakarta.apache.org/msg10527.html
   http://www.mail-archive.com/avalon-dev@jakarta.apache.org/msg10718.html
   http://www.mail-archive.com/avalon-dev@jakarta.apache.org/msg11202.html

...then at some point I spent quite a bit of time with forrest since it
    basically promised once more to solve all the problems we had had for a
    year or so using cocoon...

   http://www.mail-archive.com/avalon-dev@jakarta.apache.org/msg11628.html
   http://www.mail-archive.com/avalon-dev@jakarta.apache.org/msg11360.html
   http://www.mail-archive.com/avalon-dev@jakarta.apache.org/msg11496.html

...then there's a few months of flamewars not related to docs...
    nevertheless forrest is getting more and more use...

   http://www.mail-archive.com/avalon-dev@jakarta.apache.org/msg15659.html

...then there's more flamewars...but every now and then a little more
    forrest is put to use...

   http://www.mail-archive.com/avalon-dev@jakarta.apache.org/msg16982.html

...after more flamewars avalon becomes a TLP, which involves a lot more
    website work...

   http://www.mail-archive.com/avalon-dev@jakarta.apache.org/msg21236.html

...*lots of work*...after about a year of fiddling maven will eventually
    be "stable enough" to mean "less fiddling"...

   http://www.mail-archive.com/avalon-dev@jakarta.apache.org/msg21393.html

...so that when avalon dies and a site needs to be set up for excalibur,
    this is now finally something relatively simple and automated...

 
http://mail-archives.apache.org/mod_mbox/excalibur-dev/200406.mbox/raw/%3C40CCB91E.80402@jicarilla.org%3E

After trying from early 2002 through to mid 2004 to work with Forrest (heck,
we worked with cocoon before forrest existed), I finally got to a state of
affairs where stuff "just worked". "just worked" didn't include Forrest. I
have since stayed away from using forrest on xdocs stuff, except that 
some of
the projects I participate in (like the incubator) still use it, and every
time I hear someone talking about the incubator site I hear them being
frustrated.

I seem to remember someone (I think Berin Loritsch) writing a lengthy and
solid comparison somewhere in 2004 comparing the various approaches but I
can't find it right now.

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). Even if it works once I get forrest built
(why do I need to build anything?) it doesn't satisfy my requirement for
"simple" since getting the tool up on my machine involves a 30 minute SVN
checkout. 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?
Grr. I feel silly now. `cd .. && forrest run`. And here it goes off 
fetching a
bunch of plugins again! Gaah! In any case, now when I hit refresh in the
browser something happens at least (my computer locks for about 30 seconds).

Then it displays the incubator site. Victory! (hmm, apachecon logo 
really ought
to go).

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?). 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? I try "view source" but the HTML in there
sort-of scares me away from even trying. 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". 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 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. 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.
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...

$ 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.

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.
   - documentation organisation that doesn't match my expectations (I
     expect something like incubator/trunk/xdocs or incubator/trunk/site)

   Not incubator specific
   - having to check out lots of stuff I already have on my machine
   - having to check out lots of stuff I am never going to use
   - having to check out lots of stuff, period
   - having lots of manual installation steps that I would've never
     figured out without reading docs
   - having lots of manual installation steps, period
   - 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)
   - context switching between console and web browser all the time
   - forrest eating up my HTML without warning or complaining
   - lots of console output I don't understand
   - no "fail early" mechanism so I feel stupid when I make a mistake
     and waste time
   - cryptic error messages no-one understands
   - heavy HTML using spacer GIFs and complex tables
   - rendering everything

You know what, these are the exact same things I didn't like 3 years ago,
and the exact same comments I've made about cocoon, centipede, forrest 3
years ago. The frustration is exactly the same one.

I want *simple* and *predictable* and *trustable*.

Say again?
----------
Phrasing the above in terms of a bug report...the following command 
sequence...

   ssh people.apache.org
   svn co 
https://svn.apache.org/repos/asf/infrastructure/site-tools/trunk/xdok
   cd xdok
   # get rid of xdok itself, just keep the tests 'n stuff
   rm -Rf target xdok lib *.py

   # you're up
   $something_to_install_forrest
   echo "$something_that_runs_forrest_as_appropriate" > xdok
   chmod +x xdok

   # tests
   time ./selftest
   vi xdocs/index.html
   time ./xdok
   vi templates/site.kid.html
   ./xdok --force

...currently...

   * is probably just not possible since java doesn't work too well on
     FreeBSD
   * takes over half an hour
   * results in unacceptable resource consumption
   * $somemthing_to_install_forrest is too complex
   * provides way too much output
   * does a bunch of stuff I don't understand or that doesn't make sense
     to me
   * fails the test cases provided and doesn't come close
   * doesn't show enough difference between the first 'time' and the second
    'time'

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).

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).

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.

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.)

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.

---

I hope this helps. If it doesn't just throw it away and go have a beer.


cheers,


Leo


----- End forwarded message -----



Mime
View raw message