forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Nicola Ken Barozzi <nicola...@apache.org>
Subject Re: [PATCH] customizable skins, greater configurability, image di r fixes, miscellanea
Date Fri, 13 Sep 2002 12:20:13 GMT

Jeff Turner wrote:
> On Fri, Sep 13, 2002 at 01:35:36PM +0400, Piroumian Konstantin wrote:
> 
>>>From: Jeff Turner [mailto:jefft@apache.org] 
>>
> ...
> 
>>>These changes were made while producing the site at
>>>http://aft.sourceforge.net/
>>
>>Seems that Forrest's skin is the favourite one. We already have at least 3
>>sites with the same skin.
> 
> I like the Krysalis one (avalon-site) though. I think this patch would
> allow the krysalis skin mods to be rolled back into avalon-site.

Cool :-)
Well, we have changed the skin at Avalon, as you can see 
http://jakarta.apache.org/avalon/ , and I've done some minor 
enhancements for the text of the krysalis one.

Many people have asked me to decouple the skin repository from Forrest 
itself, do you have any ideas on how this can be done well?

>>>The patch does the following:
>>>
>>> - Allows users to have a custom sitemap, overriding the
>>> forrest-provided one. Default location is
>>> src/documentation/sitemap.xmap, though it is configurable.
>>
>>Why not the src/resources/conf?
> 
> That's where it lives in Forrest's CVS module, where it is indeed a
> "resource". But inside a live Forrest-using project, it's not a static
> "resource", but the active controller. It specifies how resources
> (images, xdocs) are mapped to URIs, so it's not a resource itself. Thus I
> followed the Cocoon example of putting it at
> src/documentation/sitemap.xmap. It's configurable of course.

I have been thinking about the dir layout we ask our users to have...
Since we have decided that we put all in the same dir, with the 
possibility of having also them in indipendent dirs, what about this 
default layout:

  */documentation/fdocs (forrest docs)
  */documentation/fdocs/images
  */documentation/fdocs/innerdir
  */documentation/fdocs/innerdir/images

  */documentation/resources/images
  */documentation/resources/scripts
  */documentation/resources/...

?

>>> - Allows users to add jars to the webapp, by default from
>>>   src/documentation/lib (configurable). This is useful for 
>>>adding custom
>>>   sitemap components, or testing hacked versions of Cocoon. 
>>
>>Why not the /lib directory (or /lib/optional or /lib/endorsed)?
> 
> 
> Putting them in lib/ might interfere with other jars there, and might
> cause unforseen interactions with either Cocoon or the user's app.
> lib/optional and lib/endorsed are Centipede specific. How about lib/doc/?
> Hmm.. if your project doesn't have a lib/ directory anyway, it would look
> a bit silly. The intention with src/documentation/lib is that all doc
> stuff (xdocs, stylesheets, images, jars) are in one directory.

We should decouple the doc dir from the doc-generation enhancements dir.

What about

  */documentation/fdocs (forrest docs)
  */documentation/fdocs/images
  ...
  */documentation/resources/images
  ...
  */ext/sitemap.xmap
  */ext/lib/
  ...

?

In this way it can be easier to decuple the exts later on and make a 
specific forrst enhancement plugin. (mayby plugin instead of ext?)

>>I don't like having JARs inside of the documentation folder. Custom jars can
>>be used not only for the documentation, but also for custom Ant tasks or
>>other java source that is placed in the src/java directory.
> 
> ...
> 
>>Maybe the search box can be made more configurable? I've noticed that you
>>have a label 'Search AFT site' instead. Did you changed the stylesheet for
>>that?
> 
> 
> It's "Search the <xsl:value-of select="$config/project-name"/> site"
> 
> skinconf.xml is intended to contain declarative, reusable information
> about one's project, reusable in multiple locations, like here.

+1

I like it.

>>>  <group-name>Apache XML</group-name>
>>>  <group-url>http://xml.apache.org/</group-url>
>>>  <group-logo>images/group-logo.gif</group-logo>
>>
>>I wonder how can be the XML.apache.org site itself be configured. Am I
>>correct saying that it'll be like this:
>> <project-name>Apache XML</project-name>
>>...
>><group-name>Apache</group-name>
> 
> 
> That's right. See src/resources/conf/skinconf.xml, which contains the
> Forrest defaults.
> 
> ...
> 
>>>  <trail>
>>>    <link1 name="apache" href="http://www.apache.org/"/>
>>>    <link2 name="xml.apache" href="http://xml.apache.org/"/>
>>>    <link3 name="" href=""/>
>>
>><link4/><link5/>...<linkN/>?
>>
>>Maybe simply:
>>	<link ...>
>>	<link ...>
>>and process them in the order of appearance?
> 
> 
> Yes it would be nice. However the 'processor' is the <xmlproperty> task,
> and unfortunately it provides no way for accessing the n'th link.

We can get round this quite easily with two ways:
  1) I patched the xmlproperty task (@see Ant Bugzilla) to make multiple 
entries result in a comma-separated list on which the for-each task can 
iterate
  2) We update to the latest Ant embed proposal and use JXPath
     http://www.krysalis.org/cgi-bin/krywiki.pl?AntJXPath

> ...
> 
>>>This file can be then read by the skin stylesheets:
>>>
>>><xsl:param name="config-file" select="'../../../../skinconf.xml'"/>
>>
>>Maybe something like a base-dir can be used instead of relative links? E.g.:
>><xsl:param name="config-file" select="'{$base-dir}/skinconf.xml'"/>
> 
> 
> That's just a default, which assumes that skinconf.xml is alongside the
> sitemap. If that's not true, then the sitemap could configure the stylesheet as
> follows:
> 
> <map:transform src="skins/@skin@/xslt/html/{type}.xsl">
>   ...
>   <map:parameter name="config-file" value="../../../../skinconf.xml"/>
> 
> So it is quite flexible.
> 
> ...
> 
>>>However, we also do need tokens to "passively" configure 
>>>other parts of a skin,
>>>like CSS and Javascript pages. Eg, the breadcrumbs.js script 
>>>is configured with
>>>tokens like @link1.href@.
>>
>>Hm... Is it really needed?
> 
> 
> ?? Yes, tokens are needed.. how else do you customize a .js file?
> 
> 
>> Can't we stick to a single configuration location?
> 
> 
> Everything is configured from skinconf.xml. Stylesheets access it directly, and
> everything else gets filters applied, where filters correspond directly to
> skinconf.xml elements. There's no duplication of config info anywhere.
>  
> ...
> 
>>>Also, I have written no docs other than this email, pending 
>>>the list's approval
>>>of the general ideas in this patch.
>>
>>It's Ok. 
>>But as we settle the things, we will need some User's docs for all the
>>configurations and an entry in the changes.xml with a summary.
> 
> 
> I don't know. Isn't it more fun when users have to figure stuff out themselves?
> Brings some excitement to their dull pointless little lives..
> 
> ;) Yes of course.

hehehe

-- 
Nicola Ken Barozzi                   nicolaken@apache.org
             - verba volant, scripta manent -
    (discussions get forgotten, just code remains)
---------------------------------------------------------------------


Mime
View raw message