You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@forrest.apache.org by Peter Donald <pe...@apache.org> on 2002/11/03 23:55:28 UTC
Newbie Feedback
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 ;)
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.
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.
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.
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!
No XSLT comments:
-----------------
The XSLT also lack all comments in generated form and can be difficult to
figure out. I would highly suggest that you add things like the following all
the way through your xslt sheets
<xsl:comment>===== start BreadCrumb =====</xsl:comment>
...
<xsl:comment>===== end BreadCrumb =====</xsl:comment>
If there is a concern over size of generated file then you should add an extra
transformer in production docs such that the comments are stripped, uneeded
whitespace is removed and normalization occurs.
Thats another thing that I found irritiating - some of the xslt sheets don't
use whitespace to make them easier to understand. Some of the lines were
pushing 400 characters!!!! It would be soo much easier if they broke them
down into smaller more easily understood by people like me ;)
Call XSLT Templates:
--------------------
Large chunks of the stylesheets could be turned into parametrized templates
that are called from another section. Several places through the forrest skin
I saw the same bit of code repeated - sometimes with slight modifications.
For example, the render an image or text if image not present (ie rendering
group logo, project logo, credits logos, host logo) is one such example. Only
some of them printed out the text when the image was not present, some of
them would not print logo if defined as empty string, some required image
while others didn't. So I made a parameterized template that took
displayString, logo, url and treated all of them identically. It seemed to
work well. I would love it if the rest of xslt sheets worked that way.
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.
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.
--
Cheers,
Peter Donald
--------------------------------
My opinions may have changed,
but not the fact that I am right
--------------------------------
Re: Newbie Feedback
Posted by Peter Donald <pe...@apache.org>.
And I just thought of another thing that bugged me for a bit :)
The directory structure in the skins/content/resource directories do not
necessarily matchg the output directory structure. It would be much easier
for users if there was no such difference.
I kinda like the idea that things are separated by type in skin/resources but
according to function in the end app but I am not sure the split is going to
be appreciated by many ;)
--
Cheers,
Peter Donald
----------------------------------------
Whatever you do will be insignificant,
but it is very important that you do it.
--Gandhi
----------------------------------------
Re: Newbie Feedback
Posted by Jeff Turner <je...@apache.org>.
On Mon, Nov 04, 2002 at 10:15:49AM +1100, Peter Donald wrote:
> One more thing I didn't like was the way the skinconf was defined. The first
> thing I did was change
>
> <trail>
> <link1 name="RealityForge" href="http://www.realityforge.org/"/>
> <link2 name="ThinkTank" href="http://www.realityforge.org/thinktank"/>
> </trail>
>
> to
>
> <trail>
> <link name="RealityForge" href="http://www.realityforge.org/"/>
> <link name="ThinkTank" href="http://www.realityforge.org/thinktank"/>
> </trail>
IIRC, the reason for link1, link2 etc was that <xmlproperty> needs
uniquely named elements. We use <xmlproperty> to convert the link hrefs
to @skin.blah@ tokens.
Since we need Ant 1.6 for XML validation anyway, probably we could use
${jxpath:...} syntax instead of <xmlproperty>.
> I was also consider changing all the image/icon defs to use a standard format
> but have a "role" element that could define their role. ie Look something
> like
>
> <logo>
> <name>ThinkTank</name>
> <role>project</role>
> <url>http://www.realityforge.org/thinktank</url>
> <image>skin/images/thinktank-logo.gif</image>
> <width>88</width>
> <height>31</height>
> </logo>
> <logo>
> <name>RealityForge</name>
> <role>group</role>
> <url>http://www.realityforge.org/</url>
> <image>skin/images/rf.gif</image>
> <width>88</width>
> <height>31</height>
> </logo>
> <logo>
> <name>Built with Cocoon</name>
> <role>credit</role>
> <url>http://xml.apache.org/cocoon/</url>
> <image>skin/images/built-with-cocoon.gif</image>
> <width>88</width>
> <height>31</height>
> </logo>
Sounds good.
--Jeff
> Thoughts?
>
> --
> Cheers,
>
> Peter Donald
> *------------------------------------------------*
> | You can't wake a person who is pretending |
> | to be asleep. -Navajo Proverb. |
> *------------------------------------------------*
>
>
Re: changes to skinconf.xml (Was: Newbie Feedback)
Posted by Peter Donald <pe...@apache.org>.
On Mon, 4 Nov 2002 18:11, David Crossley wrote:
> We would need stylesheet mods to accompany this.
> Have you already done that for your local build?
> If so, please send patches.
Unfortunately I use a different stylesheet. You should be able to extract it
from the style I just sent though. I don't feel game enough to touch the
forrest skin :)
> We also need "alt" as one of the logo parameters,
> probably required.
I think I just put "{$name} logo". But it could be nice to put taglines with
em. ie "Ant - the only bug you want near your code" or similar.
--
Cheers,
Peter Donald
"All my life I wanted to be someone; I guess I should have been more
specific."
-- Jane Wagner
changes to skinconf.xml (Was: Newbie Feedback)
Posted by David Crossley <cr...@indexgeo.com.au>.
Peter Donald wrote:
> One more thing I didn't like was the way the skinconf was defined.
> The first thing I did was change
>
> <trail>
> <link1 name="RealityForge" href="http://www.realityforge.org/"/>
> <link2 name="ThinkTank" href="http://www.realityforge.org/thinktank"/>
> </trail>
>
> to
>
> <trail>
> <link name="RealityForge" href="http://www.realityforge.org/"/>
> <link name="ThinkTank" href="http://www.realityforge.org/thinktank"/>
> </trail>
>
> I was also consider changing all the image/icon defs to use a standard format
> but have a "role" element that could define their role. ie Look something
> like
>
> <logo>
> <name>ThinkTank</name>
> <role>project</role>
> <url>http://www.realityforge.org/thinktank</url>
> <image>skin/images/thinktank-logo.gif</image>
> <width>88</width>
> <height>31</height>
> </logo>
> <logo>
> <name>RealityForge</name>
> <role>group</role>
> <url>http://www.realityforge.org/</url>
> <image>skin/images/rf.gif</image>
> <width>88</width>
> <height>31</height>
> </logo>
> <logo>
> <name>Built with Cocoon</name>
> <role>credit</role>
> <url>http://xml.apache.org/cocoon/</url>
> <image>skin/images/built-with-cocoon.gif</image>
> <width>88</width>
> <height>31</height>
> </logo>
>
> Thoughts?
>
> --
> Cheers,
>
> Peter Donald
Thanks Peter, these are things that worried me too.
We would need stylesheet mods to accompany this.
Have you already done that for your local build?
If so, please send patches.
We also need "alt" as one of the logo parameters,
probably required.
--David
Re: Newbie Feedback
Posted by Peter Donald <pe...@apache.org>.
One more thing I didn't like was the way the skinconf was defined. The first
thing I did was change
<trail>
<link1 name="RealityForge" href="http://www.realityforge.org/"/>
<link2 name="ThinkTank" href="http://www.realityforge.org/thinktank"/>
</trail>
to
<trail>
<link name="RealityForge" href="http://www.realityforge.org/"/>
<link name="ThinkTank" href="http://www.realityforge.org/thinktank"/>
</trail>
I was also consider changing all the image/icon defs to use a standard format
but have a "role" element that could define their role. ie Look something
like
<logo>
<name>ThinkTank</name>
<role>project</role>
<url>http://www.realityforge.org/thinktank</url>
<image>skin/images/thinktank-logo.gif</image>
<width>88</width>
<height>31</height>
</logo>
<logo>
<name>RealityForge</name>
<role>group</role>
<url>http://www.realityforge.org/</url>
<image>skin/images/rf.gif</image>
<width>88</width>
<height>31</height>
</logo>
<logo>
<name>Built with Cocoon</name>
<role>credit</role>
<url>http://xml.apache.org/cocoon/</url>
<image>skin/images/built-with-cocoon.gif</image>
<width>88</width>
<height>31</height>
</logo>
Thoughts?
--
Cheers,
Peter Donald
*------------------------------------------------*
| You can't wake a person who is pretending |
| to be asleep. -Navajo Proverb. |
*------------------------------------------------*
Re: Newbie Feedback
Posted by Rodent of Unusual Size <Ke...@Golux.Com>.
Jeff Turner wrote:
>
> Avoid Cocoon CLI yuckiness by developing docs and skins as a webapp:
>
> forrest webapp
> cd build/webapp
> ... symlink stuff back to src/documentation/* ...
i keep reading this and keep wondering about it. where is this 'webapp'
aspect documented, and what does it require? tomcat? cocoon? ???
Re: Newbie Feedback
Posted by Jeff Turner <je...@apache.org>.
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