Re: [Fwd: [mail@leosimons.com: Re: [RT] Super Simple Site Generation Tool]]

[David Crossley <cr...@apache.org>]

Ross Gardler wrote:
> (Background:
> 
> Over on Infra there has been some very harsh criticism of Forrest 
> lately.

Ross means Apache Incubator.

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

That is the way i see it too, and have said so on
the general@incubator list. Think of it from the
point-of-view of the general public and those searching
the archives in the future. If incorrect statements are
left dangling then there is serious damage. They will
never touch Forrest and rumour will spread.

> Constructive criticism is good and we encourage it. So thanks for your 
> effort in writing this mail.
> 
> > 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.
> > [ snip list of old Avalon email ]

No. It was because you offered to write a
"Forrest plugin for Maven" and we wanted to ease
your way. This was before Forrest became a top-level
project and gained procedures for new committers.

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

Waiting until Cocooon move to Maven. Forrest
probably then doesn't need to, as most of the
jars that we use are direct from Cocoon.

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

Actually, sorry to say Ross, this time you are
spreading the mis-information. The Incubator docs
are very clear about using the current forrest_07_branch.
http://incubator.apache.org/guides/website.html

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

When doing 'forrest site' from a Terminal window
(i.e. a command-line shell window) the OS presents
a menu option for the Java process of Cocoon. 
You can use it to kill Cocoon, although i do not.

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

They are explicitly explained in the build output
and there is a nice FAQ about it. I find them
extremely useful and would like them to remain.

> 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 the generated incubation-process.png perhaps
because the asciiart source was missing the last EOL marker.
Perhaps different OSs treat it differently.
Need more info about the PDF issue. I checked and its
SVN properties are correct.

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

This is because Cocoon crawls the site looking for
links to build. Perhaps the navigation has changed
to add other menu items to this page. Perhaps the
skin has changed. So perhaps Cocoon needs to re-build
every page. I cannot see how or why we would change this.

There are FAQs about generating single pages.
It is not hard. However this is a dangerous thing
to do. It would be easy to end up with a site
that is out-of-sync.

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

Wrong. There *are* critical fixes in the forrest_07_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

Only the old "deprecated" skins use html tables.
Use the recommended "pelt" skin or wait for the new
Dispatcher.

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

Welcome to open-source. If we had more people helping
then we could progress more quickly.

[ snip the rest, i don't yet understand the feedback. ]

-David

Re: Cocoon status messages (Was: [RT] Super Simple Site Generation Tool)

[Ross Gardler <rg...@apache.org>]

David Crossley wrote:
> Hmmm... It has said "See FAQ" since the early days
> of Forrest.

I see a common theme emerging ;-)

Ross

Cocoon status messages (Was: [RT] Super Simple Site Generation Tool)

[David Crossley <cr...@apache.org>]

David Crossley wrote:
> Ross Gardler wrote:
> > David Crossley wrote:
> > >Ross Gardler wrote:
> > >>Leo Simons wrote:
> 
> > >>>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.
> > >
> > >They are explicitly explained in the build output
> > >and there is a nice FAQ about it. I find them
> > >extremely useful and would like them to remain.
> > 
> > They are explained in the FAQ, but not in the build output:
> > 
> > # Column 2 is the page count - the number of pages processed and the 
> > number remaining. The latter will change because during processing one 
> > page, Cocoon will discover more.
> > # Column 3 is the number of links that were gathered from that page.
> > 
> > (I'm guessing Leo was actually referring to the second two columns since 
> > he refers to numbers and the first is indeed explained in the build output)
> 
> Ah yeah, sorry they are only fully-explained via the
> build output in 0.8-dev (damn our holdups between releases).

Gak. Now it is me spreading the mis-information.
Thankfully easily corrected via mail archives.

I remember now ... tried to explain it better in
the build output, but it became too verbose.

Hmmm... It has said "See FAQ" since the early days
of Forrest.

-David

Re: [Fwd: [mail@leosimons.com: Re: [RT] Super Simple Site Generation Tool]]

[David Crossley <cr...@apache.org>]

Ross Gardler wrote:
> David Crossley wrote:
> >Ross Gardler wrote:
> >>Leo Simons wrote:
> 
> >>>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.
> >
> >Actually, sorry to say Ross, this time you are
> >spreading the mis-information. The Incubator docs
> >are very clear about using the current forrest_07_branch.
> >http://incubator.apache.org/guides/website.html
> 
> OK, sorry, I didn't realise there were bug fixes in the branch. If they 
> are critical we should consider a 0.7.1 release. If they are only for 
> Incubator (and they stay with Forrest) we should consider providing 
> "stable snapshots" (see thread on dev).

The trouble is that we might need even more modifications.
We would already probably be up to 0.7.2 if we took
that approach. Forrest project is too small to cope
with that. Perhaps your "stable snapshots" idea will work.
More on dev.

> >>>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.
> >
> >They are explicitly explained in the build output
> >and there is a nice FAQ about it. I find them
> >extremely useful and would like them to remain.
> 
> They are explained in the FAQ, but not in the build output:
> 
> # Column 2 is the page count - the number of pages processed and the 
> number remaining. The latter will change because during processing one 
> page, Cocoon will discover more.
> # Column 3 is the number of links that were gathered from that page.
> 
> (I'm guessing Leo was actually referring to the second two columns since 
> he refers to numbers and the first is indeed explained in the build output)

Ah yeah, sorry they are only fully-explained via the
build output in 0.8-dev (damn our holdups between releases).

> >>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.
> >
> >This is because Cocoon crawls the site looking for
> >links to build. Perhaps the navigation has changed
> >to add other menu items to this page. Perhaps the
> >skin has changed. So perhaps Cocoon needs to re-build
> >every page. I cannot see how or why we would change this.
> 
> One has to be very careful about this. If I fix a spelling error in a 
> single page of a 500 page site, I really don't want to generate all 500 
> pages. It would be good to just generate that single page...
> 
> >There are FAQs about generating single pages.
> >It is not hard. However this is a dangerous thing
> >to do. It would be easy to end up with a site
> >that is out-of-sync.
> 
> Yes, there are FAQs. But we know people don't read docs, our discussions 
> on the Incubator list prove it.

Well i am not sure what that Incubator discussion proves.
If they had asked questions, then we could have pointed
to FAQs about techniques.

> For me, the question is can we make it even simpler than it already is? 
> I think we can, see proposal on dev list.

Thanks for trying.

-David

Re: [Fwd: [mail@leosimons.com: Re: [RT] Super Simple Site Generation Tool]]

[Ross Gardler <rg...@apache.org>]

David Crossley wrote:
> Ross Gardler wrote:
> 

...

>>Leo Simons wrote:

...

>>>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, ...
> 
> 
> Waiting until Cocooon move to Maven. Forrest
> probably then doesn't need to, as most of the
> jars that we use are direct from Cocoon.

True, although some plugins provide jars as well. I agree we should be 
waiting for Cocoon to finish the move as 95% of the benefit is in Cocoon 
not the plugins.

>>>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.
> 
> 
> Actually, sorry to say Ross, this time you are
> spreading the mis-information. The Incubator docs
> are very clear about using the current forrest_07_branch.
> http://incubator.apache.org/guides/website.html

OK, sorry, I didn't realise there were bug fixes in the branch. If they 
are critical we should consider a 0.7.1 release. If they are only for 
Incubator (and they stay with Forrest) we should consider providing 
"stable snapshots" (see thread on dev).

>>>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.
> 
> 
> They are explicitly explained in the build output
> and there is a nice FAQ about it. I find them
> extremely useful and would like them to remain.

They are explained in the FAQ, but not in the build output:

# Column 2 is the page count - the number of pages processed and the 
number remaining. The latter will change because during processing one 
page, Cocoon will discover more.
# Column 3 is the number of links that were gathered from that page.

(I'm guessing Leo was actually referring to the second two columns since 
he refers to numbers and the first is indeed explained in the build output)

>>> Moreoever, why on earth did
>>>it spend 5 minutes generating files that are now exactly the same as
>>>before?? Abort, abort, abort.

...

>>With respect to the need to generate changed pages,

That should read "to generate *unchanged* 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.
> 
> 
> This is because Cocoon crawls the site looking for
> links to build. Perhaps the navigation has changed
> to add other menu items to this page. Perhaps the
> skin has changed. So perhaps Cocoon needs to re-build
> every page. I cannot see how or why we would change this.

One has to be very careful about this. If I fix a spelling error in a 
single page of a 500 page site, I really don't want to generate all 500 
pages. It would be good to just generate that single page...

> There are FAQs about generating single pages.
> It is not hard. However this is a dangerous thing
> to do. It would be easy to end up with a site
> that is out-of-sync.

Yes, there are FAQs. But we know people don't read docs, our discussions 
on the Incubator list prove it.

For me, the question is can we make it even simpler than it already is? 
I think we can, see proposal on dev list.

>>>  - heavy HTML using spacer GIFs and complex tables
> 
> 
> Only the old "deprecated" skins use html tables.
> Use the recommended "pelt" skin or wait for the new
> Dispatcher.

Yes, that is correct. The pelt skin is 100% CSS and has been for some 
time. Interestingly that is what the Incubator is using, so I have no 
idea when the last time Leo looked at the generated sources were.

Furthermore, I just created a new skin which is somewhat cleaner in its 
output. It is  intended to be a the equivalent of http://www.apache.org. 
It's not perfect yet, but it is pretty close. See dev list.

The Dispatcher improves things even more (again a dev topic).

Ross