*FORREST SITE CONF* Currently, configuration and extension of Forrest is done with these files relative to the current directory:

[Nicola Ken Barozzi <ni...@apache.org>]

 [PROPOSAL] Forrest site configuration
Content-Type: text/plain; charset=us-ascii; format=flowed
Content-Transfer-Encoding: 7bit


Currently, configuration and extension of Forrest is done with these 
files relative to the current directory:

  a - *.xmaps
  b - forrest.properties
  c - skinconf.xml

Point (a) IMHO has only one way of making it better: not *having* to 
extend xmaps to be able to do the most used extension features.

The most common extensions I see that are done in xmaps are:
  - addition of DTDs
  - insertion of extra sources

Point (b) is about validation, source dirs, and other dirs places. In 
common with (a) there is the source dirs stuff: define the default ones, 
another to add to them.

Finally (c) is about the configuration of the skin, so that it is 
customized. This has proven to be succesful, so I regard it as a 
reference about how to do the rest.

Note that I want to make it possible for a single Forrest webapp to 
serve different sites, and so to make it also possible for projects that 
have subprojects to share the same skinconf and infos.

  Proposal
----------

custom *.xmaps     -> dtdpack.zip
forrest.properties -> srcconf.xml
                    -> gump.xml (optional)
skinconf.xml       == skinconf.xml


In essence, each project would have two descriptors:

   srcconf.xml  (content)
   skinconf.xml (style)

Forrest would find them in a predefined location in the directory, and 
srcconf is not compulsory, so the default Forrest would be exactly like 
now. :-)

If a user wants to change the location of the sources or add to them, he 
would have to add a srcconf.xml file next to skinconf.xml.

If he wants to change the location where Forrest looks for these 
descriptors, he would have to add the information to its project 
descriptor, that can be the Gump one *or* the Maven one. The skinconf 
logic should be intelligent enough to look for the usual project 
descriptor names and locations and extract these two pieces of 
information regardless the descriptor (using // xpaths for example).

As for DTDpacks, they would be extensions exactly like the skins. Hence 
I will change skins.xml to extensions.xml and also add the possibility 
of adding extra DTDs there. We will thus have a single way of adding 
extensions; the only extra thing to do is to add the downloaded DTDs to 
the resolver file in the installed Forrest, but that's easy enough.

I think that this is the best solution to date to the 
descriptor-sources-extensions stuff that Forrest needs. It makes it also 
possible for example to make a webapp out of many sites, by simply 
feeding forrest a descriptor with all the sites it has to render, and at 
which relative URI.

Finally, here is the proposal of an initial srcconf.xml:

<srcconf xmlns="http://apache.org/forrest/srcconf/1.0"
          xmlns:map="http://apache.org/cocoon/sitemap/1.0">

   <map:components>
     <map:matchers default="wildcard">
       <map:matcher name="wildcard" src="o.a.c.m.WildcardURIMatcher"/>
       <map:matcher name="regexp" src="o.a.c.m.RegexpURIMatcher"/>
     </map:matchers>
     <map:selectors>
      <map:selector name="exists" src="o.a.c.s.ResourceExistsSelector" />
     </map:selectors>
   </map:components>

   <matches>
     <map:match type="wildcard" pattern="**.gif">
        <location src="content/xdocs/{1}.gif">
     </map:match>

     <map:match type="wildcard" pattern="**.xml">
       <map:select type="exists">
         <map:when test="content/xdocs/{1}.ihtml">
            <location src="content/xdocs/{1}.ihtml">
         </map:when>
         <map:when test="content/xdocs/{1}.txt">
           <location src="content/xdocs/{1}{2}.txt">
         </map:when>
         <map:otherwise>
           <!-- there is a default srcconf that handles other sources -->
           <location src="{default}">
         </map:otherwise>
      </map:select>
    </map:match>

   </matches>
</srcconf>

Does it look like sitemap.xmap?

Before anyone starts asking why not use xmaps instead, which I have done 
with myself a lot too, here are the answers:

1 - external xmaps constrain our ability to refactor the sitemaps,
     also for speed, as the cocoon:// protocol is not a speed daemon
2 - if does not enable us to deploy multiple forrest sites in a single
     Forrest instance
3 - with DTD extensions we don't need transformations in this file, and
     this will also add the benefit of separating source and view

The upside of the above is also that it looks like sitemap.xmap, which 
could help users dwelve into cocoon if they ever really need extra 
functionality. Also it uses the Cocoon matchers, which is a nice reuse 
of powerful finctionality.

Blocks? When they will come, we will se iff-how to change this. It will 
take some time before they are done, even more before they become solid 
and 2.2 is our of the door.

Thoughts?

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