forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jeff Turner <je...@apache.org>
Subject Re: Newbie Feedback
Date Mon, 04 Nov 2002 05:48:33 GMT
On Mon, Nov 04, 2002 at 09:55:28AM +1100, Peter Donald wrote:
> Hi,
> 
> I have been slowly adapting forrest with a different skin and using my
> own DTDs and I figured I would give you feedback because I am still
> pretty much a newbie ;)

Appreciated, thanks.

> Error Reporting:
> ----------------
> 
> First off the error reporting sucks badly. If I forget to close a tag in an 
> xsl sheet then the error is not reported and I just end up with a broken 
> index.html (presumably the initial crawl point?). I ended up having to resort 
> to commenting out parts to locate the error... Painful in the extreme.

Ew..

> I would so much prefer that there was an error pointed out if a problem 
> occured in a particular pipeline stage. Then at least I would know where to 
> look and how to go about fixing the problem.

Yes, error reporting sucks.

Solutions:

Short term:

  Avoid Cocoon CLI yuckiness by developing docs and skins as a webapp:

  forrest webapp
  cd build/webapp
  ... symlink stuff back to src/documentation/* ...

Medium term:

  Forrest should validate everything with pointy brackets, including
  users' skin XSLTs, before letting Cocoon at it.  So far, I have my
  local Forrest validating XSLTs in ${project.stylesheets-dir} and
  ${project.skins-dir}.  I need to make this more flexible before
  checking in.

Long term:

  Abandon CLI for everything except generating static site snapshots.


> Skinning:
> ---------
> 
> The directions for creating a skin at 
> 
> http://xml.apache.org/forrest/your-project.html#N1026A
> 
> don't seem to work. Or at least I don't seem to be able to make them work. 
> They don't get copied to correct place and thus it fails (though it took me a 
> while to figure this out - see above). I had to resort to placing the skin in 
> xml-forrest and rebuilding forrest every time I changed the skin.

Oops, there is one stupid mistake in your-project.html:

  "and add project.skin=myskin to default.properties"

should be

  "and add project.skin=myskin to forrest.properties"

Was this the problem?

Skins seem to work fine for me.  Here's a test:

mkdir /tmp/testsite
cd /tmp/testsite
forrest seed
cp -r $HOME/apache/xml/xml-forrest/src/resources/skins/forrest-site \
  src/documentation/skins/blueness
vim src/documentation/skins/blueness/css/page.css
# Make some visible changes

cat >> forrest.properties << EOF
project.skin=blueness
EOF
forrest site


> XSLT Sheets:
> ------------
> 
> The XSLT sheets don't separate out concerns and are not exactly easy to reuse 
> parts of. I wanted to create my own skin but I found myself pretty much 
> rewriting large chunks of the xslt to work with what I wanted to do.
> 
> What I would like to see is that visual style and visual structure are 
> separated out. Visual style could be placed in css sheets and visual 
> structure would be generated in xslt sheets. Essentially the XSLT would 
> create a document with lots of <span/>s and <div/>s that each had their style

> and id marked out. Then all the styling would occur via css.
> 
> The advantage of that? Well then I could reuse large parts of forrest skins 
> xslt in the tigris skin. For example consider something where we have a 
> simple menu. We could have xslt generate something like
> 
> <div id="mainMenu" class="menuBar">
>   <div id="menu1" class="menu">
>     <div class="menuLabel">MyMenuGroup</div>
>     <div class="menuItem"><a href="..">MyMenuItem</a></div>
>   </div>
> </div>
> 
> See the above only gives the structure. With CSS you could color, position, 
> indent, add icons and generally make pretty. And by just changing the css I 
> could use the same xslt in either the tigris or forrest skins. Yea!

Another excellent reason for the development of CSS-intense skins..

Stefano had an excellent prototype that Konstantin or Bert or someone
posted earlier.. I can't find the link :/


[snip good XSLT comments]

> XSLT library:
> -------------
> 
> It would be great if chunks of common xslt behaviour were placed in a library 
> area where they could be reused without fuss. I vaguely recall some sort of 
> cascading ability for xslt sheets (import at lower priority or something?). 
> So using that you could just overide the behaviour you needed to change. 
> Combine this with css/xslt separation and skins become soooo much easier to 
> create.

Yes, there's a couple of utility XSLTs (pathutils.xsl, dotdots.xsl) that
should be made available to all skins.  I'll add this and the other XSLT
points to the TODO list.

> Conclusion:
> -----------
> 
> It is sooooo much easier than raw Cocoon and bugs seem to get fixed faster 
> than I can report them (several I had to report had already been fixed). So 
> this is definetly encouraging ;)
> 
> Anyways this is the initial thoughts from an XSLT weenie/hater who is 
> incredibly lazy ;) Maybe useful. If any of these things were "fixed" then I 
> would be very happy. 

Useful feedback, thanks.


--Jeff

Mime
View raw message