Mailing-List: contact forrest-dev-help@xml.apache.org; run by ezmlm
Precedence: bulk
Reply-To: forrest-dev@xml.apache.org
Message-ID: <3DD0C58D.3080304@apache.org>
Date: Tue, 12 Nov 2002 10:10:37 +0100
From: Nicola Ken Barozzi <nicolaken@apache.org>
Reply-To: nicolaken@apache.org
Organization: Apache Software Foundation
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: Filesystem layout (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>
 <3DD02AE3.3000904@apache.org> <20021112000612.GA2565@expresso.localdomain>
Content-Type: text/plain; charset=us-ascii; format=flowed
Content-Transfer-Encoding: 7bit


Jeff Turner wrote:
> On Mon, Nov 11, 2002 at 11:10:43PM +0100, Nicola Ken Barozzi wrote:
> ... 
> 
>>>>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.
> 
> Yes. URI space should be semantically rich and independent of filesystem
> layout.  The sitemap translates from filesystem to URI space.
> 
>>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!
> 
> 
> Okay.. let me see if I understand.
> 
> A few paragraphs ago, you were extolling the virtues of a semantic URI
> space, where a URI does not imply the content type.  We all agree this is
> a Good Thing.  The question here is how to order the filesystem.

Hmmm, not really, because I also tout 1-1 mapping between URI space and 
filesystem space is easier for users.

> You're saying that, in order to keep things simple for users, we should
> have a 1-1 mapping between filesystem and URI space.

Ah, ok ;-)

> Implication: you
> want a semantic filesystem layout, as well as a semantic URI space.
> Files are arranged according to what the _mean_, not what the _are_.
> 
> Example: if we wanted:
> 
> http://mysite/license
> 
> then it's contents should be obtained from content/license.*, where the
> extension (if present) is purely a hint to the sitemap as to which
> pipeline to use.
> 
> Is that what you're getting at?

+1

> My take on this is that the filesystem should be organized FIRST on
> content type, THEN on semantics.  A direct analogy:
> 
> FIRST we order projects by file type:
> 
> src/java
> src/test
> src/scripts
> src/etc
> ...
> 
> THEN, inside each directory, we order by meaning:
> 
> src/java/..../myproject/parsing/*.java
> src/java/..../myproject/servlet/*.java
> src/java/..../myproject/util/*.java
> 
> 
> Likewise, in Forrest we should order first by type:
> 
> content/xdocs
> content/images
> content/html
> 
> then by meaning:
> 
> content/xdocs/*.xml
> content/xdocs/drafts/*.xml
> content/xdocs/manual/*.xml
> content/images/*.png
> content/images/drafts/*.png
> content/images/manual/*.png
> content/html/sitemockups/*.html
> 
> 
> Why do the initial split by content type?  Two reasons:
> 
>  - Users prefer it.  It provides a way of ordering one's project.  Users
>    don't _want_ images and xdocs all jumbled together.

I disagree.
Users have explicitely asked me to be able to have images where the 
content is. Some are @ Avalon, not newbies.

>  - Simple pragmatism.  In projects, Ant needs to apply operations to
>    _types_ of files, regardless of meaning.  In Forrest, exactly the same
>    thing: we need to apply transformations based on _types_ of files,
>    regardless of semantics.

DTD states the type. It's in the file.

> As for the second reason: yes we could 'infer' the content type by
> looking at the extension, just like we could compile *.java wherever it
> occurs under src/.  I just think it's cleaner to match on directory
> rather than extension.

Why?
A gif file is a gif file whether I put it in a certain dir.
If I *have* to do it it's because something is not clever enough to 
understand it for me.

> Here's a question: why does Centipede separate src/java from
> src/documentation, when technically Ant could easily deal with everything
> in a single src/ directory?  Why not, as you suggest for Forrest, order
> by semantics, not type:
> 
> src/util/*.java 
> src/util/*.xml      # xdocs for 'util' code
> src/servlet/*.java  # servlet interface
> src/servlet/*.xml      # xdocs for servlet interface
> 
> In fact, why not throw src/testcases/ in there too; we could always use
> Ant selectors to distinguish JUnit source from normal source, just like
> CAPs distinguish types of XML.

Why does Java ask us to put html descriptions of the packages *in* the 
class dirs?
Why do we put properties there?

Because they are strictly related.

Now, I'm not saying that we stuff *all* in the content dir, just *content*.
I think that gifs, html, xml, etc are all content, and all are the same.

We still have a resources dir, and *there* I would like to see what you 
propose.

So users can decide to put images in the content, or treat them as 
global "resources".

It has been asked many times, I don't see technical difficulties, I like 
it myself.

What do others think?
What do *users* really think?

> Conclusion: history and experience show that ordering by type, and then
> by meaning, provides something that a) users like, b) is technically
> simple and unambiguous to deal with.

My experience is different, that it's not always the case.
We must cater for both behaviours, and also mixed ones.

On a list it has been written that some would commit images in the 
content and move them to resources if used by more pages, giving a 
simple migration path.

I like it.

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