Mailing-List: contact forrest-dev-help@xml.apache.org; run by ezmlm
Precedence: bulk
Reply-To: forrest-dev@xml.apache.org
Message-ID: <3DD02AE3.3000904@apache.org>
Date: Mon, 11 Nov 2002 23:10:43 +0100
From: Nicola Ken Barozzi <nicolaken@apache.org>
Reply-To: nicolaken@apache.org
User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.0; en-US;
 rv:1.1) Gecko/20020826
MIME-Version: 1.0
To: forrest-dev@xml.apache.org
Subject: Re: Skin rewrite: 0.2 release?
References: <20021111162633.GB13123@expresso.localdomain>
 <3DCFDA16.60704@apache.org> <20021111165023.GA20395@expresso.localdomain>
 <3DCFE07C.30601@apache.org> <20021111174309.GC20395@expresso.localdomain>
Content-Type: text/plain; charset=us-ascii; format=flowed
Content-Transfer-Encoding: 7bit


Jeff Turner wrote:
> On Mon, Nov 11, 2002 at 05:53:16PM +0100, Nicola Ken Barozzi wrote:
> ...
> 
>>>>I'm finishing just now to patch the sitemap to be able to accept sources 
>>>
>>>>from src/documentation/content directly instead of in the xdocs dir.
>>>
>>>
>>>Do you mean, allow XML directly in the content/ directory?  Is that a
>>>good idea? :) It's going to screw up validation..
>>
>>Ok, then I just did it :-(
>>Will fix later, I have to run now.
>>
>>
>>>Users can always set project.xdocs-dir=${project.content-dir} to have
>>>that..
>>>
>>>What's the use-case that isn't met currently?  
>>
>>Ahem... so that we will be ready when we won't copy the sources
>>anymore?  I'd like to see all the dir info in the sitemap, movung
>>things around during the build is a hack IMHO.
> 
> 
> Yes, but adding sitemap rules to load XML from anywhere doesn't get us
> closer to solving that problem.
> 
> Currently, we have a convention that content/xdocs contains XML docs.
> That convention holds regardless of whether 'content/xdocs' was copied or
> not.  The sitemap doesn't care: it just wants 'content/xdocs' to contain
> XML.  Breaking the convention achieves nothing.

Actually it's having that *configurable* that makes it more difficult; 
you are implying here that it's fixed, but in fact you also said in the 
previous mail it's configurable <dizzy/>

Anyway, I understand what you mean.

> Put another way: imagine we don't need to copy, and our sitemap is
> 'rooted' in src/documentation.  

Ok.

> What default sitemap rules should we
> provide?
> 
> a) The sitemap tries to be as general as possible:
> 
> content/**/*.xml -> **/*.html
> content/**/*.xml -> **/*.pdf
> content/**/*.png -> **/*.png
> content/**/*.gif -> **/*.gif
> ...
> 
> b) The sitemap only contains rules for the pre-established directories:
> 
> content/xdocs/**/*.xml  -> *.html
> content/xdocs/**/*.xml  -> *.pdf
> content/images/*.png -> *.png
> content/images/*.gif -> *.gif
> ...
> 
> 
> I think that b) is better, because separating 'kinds of content' is good
> practice, and we shouldn't be encouraging a free-for-all.

I go for a).

Who made the nested content/xdocs and resources/images dirs?

Me <chuckles/>

Who took the heat from users for it not being nice?

Again, also me ;-)

Users what something easy and comprehensible, and intuitive... see below

> Also, b) can easily be made to emulate a), because we can parametrise
> what we regard as "the xdocs directory". Eg we'd have a file describing
> the content layout:
> 
> <forrest-layout>
>   <xdocs dir="src/xdocs"/>
>   <skins dir="src/skins"/>
>   ...
> </forrest-layout>
> 
> and then the sitemap would use an input module (XMLModule) to read this:
> 
> {content:xdocs-dir}/**/*.xml  -> *.html
> 
> Then if the user wanted to, they could abadon the xdocs/ convention and
> map {content:xdocs-dir} to ${content:content-dir}.

Can be done, but it's wrong... again see below...

>>What do others think? Probably I'm just getting old and my brain fried...
>>
>>
>>>>It also searches in the legacy xdocs dir for compatibility.
>>>>
>>>>I want this to go in our first "unofficial" release, so we don't make 
>>>>users change doc source locations later on.
>>>
>>>Currently, everything is located through a fine-grained set of project.*
>>>properties.  It is easy to make things coarser-grained.
>>
>>I wanna zap them and make all the content in a single dir, as I thought 
>>we had decided on.
>>
>>Single dir space -> single URI space
> 
> 
> It already is.  Everything in content/ can currently be accessed from the
> sitemap.  The choice is, what default rules to we want to provide to map
> that content to public URIs.  We can try to be as general as possible in
> the mapping, or we can stick to some conventions, while allowing the
> possibility of breaking those conventions.  I'd prefer the latter..

This discussion is like the ones we already had about CAP (content aware 
pipelines) and file extensions.

To summarize, what is common practice in Cocoon, like matching file 
types by URIs is *wrong*.
File types will change over time, while sites should be more stable.
For example, if I put the license in

   http://mysite/license

The browser can get an html file, a gif file, whatever, but the URL 
stays the same. Or it camn be an image sometimes, and later an html file.

URIs are about describing what the content is about, not *how* it's 
presented.

So users should be able to put files *everywhere* in the URI space, and 
Cocoon should be able to understand *how* to serve stuff basing on other 
rules, not on matching like this, which is a hack.

Matches are to see *what* to serve, not *how*.

Now this replies to the need of putting images in an */images/** subdir.
Of course you can say that users can put images in */images/** but the 
URL will be without the preceding "*/images/**" .
But this creates confusion on the users that see the image under images 
and link it without that name in the path... at Avalon Peter and Stephen 
both were confused on some of these, so I suppose that most developers 
would... think about non technical people!

So basically what you propose is IMHO FS (flexibility syndrome).

What we had basically already agreed on is to keep three rules, applied 
in order

1) if the file is there as-is it is served
2) if not it is generated froma source in the main content dir
3) if not it's searched in the separated dir, that we decide up front.

As for number3, it was proposed that we put them in a separate 
directory, to not confuse URI spaces, like the images in the 
resources/images dir. In this way these files are seen as "global" 
resources, but of course it's just a way of seeing them.

Please, read back posts on CAPs and such, many words have already been 
said, and I think that the above considerations are sensible.

What do others think?

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