forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jeff Turner <je...@apache.org>
Subject Re: latest updates
Date Sat, 12 Oct 2002 06:04:00 GMT
On Thu, Oct 10, 2002 at 09:59:05PM -0700, Vladimir R. Bossicard wrote:
> I've updated the tree for the latest version (btw thanks for putting the 
> logos in the ressource dir) and I continue my exploration of forrest.
> 
> - major frustration: when I define a panel, I put all the xml files into 
> one folder.  I discovered that the index.xml file is only transformed 
> into an html file _if_:
>   1) it is referenced by a menuitem (like Overview -> index.html)
>   2) another menuitem is defined (?!?) and reference another file (B)
>   If you have errors in the file (B) the file index.html won't be 
> generated. So you try to find the error in the index.xml file.  Well no 
> luck! Boy I lost time on this one!

I don't understand. The HTML files are generated by the 'crawler', which
starts from one file, and recursively renders all files it is linked to.
The starting file is defined by ${project.start-uri}, and is 'index.html'
by default. Thus index.html will _always_ be rendered, if it is
well-formed.

If index.xml is invalid, then the crawler will be unable to extract links
from it, and no further pages will be processed.

Here is the crawler algorithm in pseudocode:

Add ${project.start-uri} to {links}
For page $P in {links}:
  Take xml file P.xml
  Combine P.xml with book.xml and tabs.xml (to create Px.xml)
  Render this combined file Px.xml to P.html
  Extract links from Px.xml and add them to {links}

> - it is quite difficult to figure out what went wrong when a page is not 
>  correctly generated.  Are informations logged somewhere?

Um. Yes it should be going to build/tmp/forrest.log, but that file isn't
being created. Quite a major bug :(

I don't think Forrest tries to validate XML docs before rendering, so the
only error you'd get would be from the XSLT processor. Another large
omission.

I have always validated content as I edit it. If you have an editor that
support XML Catalogs, it's easy to set up. On Linux, there's 'xmllint'
which supports them, and I can show you how to set it up.

> - is it possible to generate only one page?  Even on my machine (1.8GHz, 
> 512MB) it takes 1 minute to generate the whole site.  It would be useful 
> if I could just generate the document I'm currently working on.

I think it may be technically possible, but it wouldn't be as easy as
tools like Anakia make it.

I personally consider the Cocoon crawler a terrible tool for developing a
website. It's _far_ too slow. It takes 9 minutes to render the Forrest
site. Imagine doing an edit, and waiting that long to see the result!
Even rendering a single page, the crawler is many times slower than tools
like Anakia.

To develop a real site, I'd suggest the following strategy:

 - Run 'forrest webapp', and configure a Tomcat server to run the site as
   a webapp.
 - Symlink src/documentation/content/xdocs to
   build/webapp/content/xdocs
 - Edit away, and see updates almost instantaneously in your browser
 - Only use 'forrest site' (the crawler) when you need a static HTML
   snapshot to upload 

This way, one experiences Cocoon's strengths, rather than it's
weaknesses. I developed aft.sourceforge.net in this way. I think this is
the direction Forrest should be heading in.

> - (personal taste) I would prefer "<enable-search>true</enable-search" 
> to "<disable-search>false</disable-search>" (double negation is 
> sometimes hard to quickly figure out)

You're right. I think I'll change it.

> - why do you copy the files to be processed into the build/tmp directory?

Because we need to filter-copy some Ant @tokens@. However I'd really like
to eliminate this copy step, because then when generating a webapp, one
wouldn't need to symlink files.

> Thank you for supporting my complains.  Forrest is really a great tool 
> don't get me wrong!

:) Well, usability is pretty terrible now, but the major problems can be
worked around, and we're working on eliminating them. Your feedback is
very valuable.


--Jeff

> Best regards
> 
> -Vladimir
> 
> -- 
> Vladimir R. Bossicard
> www.bossicard.com
> 

Mime
View raw message