forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jeff Turner <je...@apache.org>
Subject In-place editing (Re: [RT] Forrest source directory layout and resolving)
Date Wed, 24 Sep 2003 12:49:57 GMT
On Wed, Sep 24, 2003 at 11:30:10AM +0200, Nicola Ken Barozzi wrote:
> 
> We need to tackle the Forrest source directory layout and how to resolve 
> additional source dirs.
....
> 
> 2 no more source copying
> --------------------------

This is the one I'm personally interested in tackling right now.
Actually I've prototyped much of this locally.  It works (XML can be
edited in-place) but isn't complete yet.  I've placed my experiments
online at:

http://www.apache.org/~jefft/forrest/samples/xml-forrest-vfs.tgz

> Why do we have to copy the sources?

Because:

1) We let users define their site structure however they want, yet our
sitemap expects a certain format.  So we make the project structure
conform to what the sitemap wants.  See the 'copy-xdocs' target and
friends in forrest.build.xml

The obvious solution is to make the sitemap adapt to the user's project
structure.  We need a layer of abstraction between the rendering
pipelines and the filesystem.  A Virtual Filesystem that can mask
whatever the user's real filesystem is.

Actually, in 0.5 we already have this.  The *.xml matchers constitute the
VFS, on which all other pipelines are built

  <map:match pattern="**body-*.html">
    <map:generate src="cocoon:/{1}{2}.xml"/>
    ...

This is why you can slip in a RSS feed (defining
'cocoon://forrest-issues.xml'), and transparently have its content
rendered with everything else.  Cool stuff.

The *.xml matchers (VFS layer) are defined in various *.xmap files, but
mostly in forrest.xmap.

So if we simply replaced every occurrence of 'content/xdocs' in that file
with {defaults:content-dir}, I think we'd have a good VFS layer to build
on.


                           --oOo--


2) We allow projects to override Forrest files:

2.1) If I have src/documentation/skins/forrest-site/css/page.css, it
overrides that from the Forrest skin.  This applies to *any* skin file.

The only solution I can see is to do a resource-exists test to see if a
skin file has been overridden, and if so, use the overridden version.

We can hide this ugliness in a pipeline:

<map:transform src="cocoon://skin/xslt/html/document2html.xsl">

(see skin.xmap in my prototype)

In effect, creating another 'virtual filesystem' for skin files (XSLTs
and stuff).  Does this sound like Cocoon blocks to anyone? :)


2.2) Sitemaps can be overridden.  If my project has a
src/documentation/conf/sitemap.xmap, I want it to be used instead of the
default.

Two options for solving this:

1) We keep the existing solution of physically copying and overwriting
xmap files.

2) We apply the 'virtual filesystem' pattern, and mount dynamically
chosen sitemaps:

<map:mount uri-prefix="" src="cocoon://forrest.xmap" check-reload="yes" />

We have a bootstrap problem with sitemap.xmap itself, although looking in
cocoon.xconf, I see it is located with 'context://sitemap.xmap', so
perhaps there's room for abstracting the location.


                           --oOo--


3) We rely on @tokens@ in breadcrumbs.js

breadcrumbs.js isn't XML, and a <map:read> doesn't leave us much
opportunity for transforms.  But I suppose we could solve the problem
with:

<map:generators>
  <map:generator name="text2xml" src="org.apache.cocoon.generation.TextGenerator" />
  <map:generator name="xml2text" src="org.apache.cocoon.generation.TextSerializer" />
</map:generators>
...
<map:match pattern="**.js">
  <map:generate type="text2xml" src="cocoon://skin/javascript/{1}.js"/>
  <map:transform src="replacetokens.xsl"/>
  <map:serialize type="xml2text"/>
</map:match>

I didn't get around to implementing this in the prototype.


                           --oOo--

Thoughts?  Ideas?

If it all sounds decent, I'd like to clean up and check this stuff
into a branch some time over the next week.


--Jeff


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

Mime
View raw message