You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@forrest.apache.org by Jeff Turner <je...@apache.org> on 2002/11/12 01:06:12 UTC
Filesystem layout (Re: Skin rewrite: 0.2 release?)
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.
You're saying that, in order to keep things simple for users, we should
have a 1-1 mapping between filesystem and URI space. 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?
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.
- 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.
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.
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.
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.
--Jeff
Re: Filesystem layout (Re: Skin rewrite: 0.2 release?)
Posted by Jeff Turner <je...@apache.org>.
On Tue, Nov 12, 2002 at 11:43:04AM +0100, Steven Noels wrote:
> Jeff Turner wrote:
>
> >:) I think we need a proper Forrest roadmap, with use-cases and a
> >concrete, technical step-by-step guide, in order to prevent
> >misunderstandings like this from happening again.
>
> +1
>
> I don't know what has been happening recently, and sure lots of it is
> simply Good Stuff, but I have problems with this new eagerness to throw
> stuff over the wall into the open.
What do they say about omelettes and breaking eggs.. :) You get to be
our Voice of Sanity.
> I'm in good standing with the 'release early & often' strategy, but if
> we are claiming to be best-practices-driven, I don't see why we
> shouldn't take the time to double-check these practices.
>
> I have been one of the advocates of 'let the user decide how he will
> organize its resources' in the past, so I tend to agree with the idea
> Nicola is pushing forward.
I'm also in favour of the idea, just very against the implementation :)
The first thing I did in Forrest was to un-hardcode the required
filesystem. Admittedly, in a stupid way, rearranging the fs instead of
parametrising the sitemap, but back then I didn't know about input
modules :)
> OTOH, generalizing remarks from single individuals as 'general user
> requests' will bring us to FS sooner rather than later. So we need more
> debate ad perhaps a vote, sorry.
How about..
- If non-trivial, mention a proposed addition on forrest-dev
- If no comments, lazy consensus applies and change gets made
- Anyone feel free to -1 a dubious addition. Remember that each commit
should have a status.xml update, describing from a user's POV what the
change is.
--Jeff
> I know I'm doing the best I can to make myself immensely unpopular right
> now. But maybe I'm simply too afraid to throw shit towards the fan (and
> don't take this too literally!!)
>
> </Steven>
> --
> Steven Noels http://outerthought.org/
> Outerthought - Open Source, Java & XML Competence Support Center
> Read my weblog at http://radio.weblogs.com/0103539/
> stevenn at outerthought.org stevenn at apache.org
>
Re: Filesystem layout (Re: Skin rewrite: 0.2 release?)
Posted by Steven Noels <st...@outerthought.org>.
Nicola Ken Barozzi wrote:
> These are two aspects of project management, my proposal just aims to
> make the "internal" management more solid.
> The contract with the user is the other very important aspect, and has
> also to be taken into account.
I like the open-endedness in your reply: looks like we'll both need a
new toothbrush, then :-)
</Steven>
--
Steven Noels http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
Read my weblog at http://radio.weblogs.com/0103539/
stevenn at outerthought.org stevenn at apache.org
Re: Filesystem layout (Re: Skin rewrite: 0.2 release?)
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Steven Noels wrote:
> Nicola Ken Barozzi wrote:
>
>> Please comment on that, or I have to think you don't even want to look
>> at it.
>
>
> I love you. Is that enough? :-D
:-P
> Seriously: I think the idea of having a status.xml with decisions
> recorded in it is more appealing to me than using a Xyxrix-based tool to
> edit it.
Of course.
The file will become big, and since Forrest users will start to use it
also, I just reckoned that having a tool to aid them would make it more
appealing; but it's not the point, the point of course is the file itself.
> But I also think we should finish & make explicit our contract
> with the user, and he will not be happy if he needs to read status.xml
> for that.
+1
These are two aspects of project management, my proposal just aims to
make the "internal" management more solid.
The contract with the user is the other very important aspect, and has
also to be taken into account.
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: Filesystem layout (Re: Skin rewrite: 0.2 release?)
Posted by Steven Noels <st...@outerthought.org>.
Nicola Ken Barozzi wrote:
> Please comment on that, or I have to think you don't even want to look
> at it.
I love you. Is that enough? :-D
Seriously: I think the idea of having a status.xml with decisions
recorded in it is more appealing to me than using a Xyxrix-based tool to
edit it. But I also think we should finish & make explicit our contract
with the user, and he will not be happy if he needs to read status.xml
for that.
</Steven>
--
Steven Noels http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
Read my weblog at http://radio.weblogs.com/0103539/
stevenn at outerthought.org stevenn at apache.org
Re: Filesystem layout (Re: Skin rewrite: 0.2 release?)
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Steven Noels wrote:
> Nicola Ken Barozzi wrote:
>
>> Steven Noels wrote:
>>
>>> Please go forward with your good thinking, but materialize it in a
>>> document users can depend on - I've just committed a skeleton for you.
>>
>>
>>
>> Ok, this is wise.
>
>
> Phfewww - I was afraid we were losing each other. Good.
>
>> Actually, we (I'm the first) are in defect towards "The Apache Way" so
>> to speak, because we don't actually have a STATUS document that tracks
>> decisions.
>>
>> Your comment brings this into top priority now, and this is what I've
>> been thinking: to add an <issues> tag in status.xml, to track
>> descisions, a <wishlist> section and a release notes section.
>>
>> I volunteer to make a GUI editor for this, as I've done for the Gump
>> descriptor, as soon as we agree on it, and add stylesheets to make
>> these into separate RSS feeds and pages.
>
>
> Let's focus on the discussions and their results, and not on the tools
> we will use to record them ;-)
It's about doing it consistently and regularly.
Every Apache project should have a Status file, we don't.
Since we make tools for other projects, I took the occasion to show what
I had been thinking for some time.
Please comment on that, or I have to think you don't even want to look
at it.
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: Filesystem layout (Re: Skin rewrite: 0.2 release?)
Posted by Steven Noels <st...@outerthought.org>.
Nicola Ken Barozzi wrote:
> Steven Noels wrote:
>
>> Please go forward with your good thinking, but materialize it in a
>> document users can depend on - I've just committed a skeleton for you.
>
>
> Ok, this is wise.
Phfewww - I was afraid we were losing each other. Good.
> Actually, we (I'm the first) are in defect towards "The Apache Way" so
> to speak, because we don't actually have a STATUS document that tracks
> decisions.
>
> Your comment brings this into top priority now, and this is what I've
> been thinking: to add an <issues> tag in status.xml, to track
> descisions, a <wishlist> section and a release notes section.
>
> I volunteer to make a GUI editor for this, as I've done for the Gump
> descriptor, as soon as we agree on it, and add stylesheets to make these
> into separate RSS feeds and pages.
Let's focus on the discussions and their results, and not on the tools
we will use to record them ;-)
I prefer being a nail rather than a hammer.
</Steven>
--
Steven Noels http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
Read my weblog at http://radio.weblogs.com/0103539/
stevenn at outerthought.org stevenn at apache.org
Re: Filesystem layout (Re: Skin rewrite: 0.2 release?)
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Steven Noels wrote:
> Please go forward with your good thinking, but materialize
> it in a document users can depend on - I've just committed a skeleton
> for you.
Ok, this is wise.
Actually, we (I'm the first) are in defect towards "The Apache Way" so
to speak, because we don't actually have a STATUS document that tracks
decisions.
Your comment brings this into top priority now, and this is what I've
been thinking: to add an <issues> tag in status.xml, to track
descisions, a <wishlist> section and a release notes section.
I volunteer to make a GUI editor for this, as I've done for the Gump
descriptor, as soon as we agree on it, and add stylesheets to make these
into separate RSS feeds and pages.
<?xml version="1.0"?>
<status>
<developers>
<person name="..." email="..." id="..." />
...
</developers>
<issues>
<pending>
<issue date="...">
<ref>http://...</ref>
<ref>./src/...</ref>
<descr>...</descr>
</issue>
...
</pending>
<voting>
<issue date="...">
<votes>
<vote person-id="..." vote=""/>
...
<votes>
<ref>http://...</ref>
<ref>./src/...</ref>
<descr>...</descr>
</issue>
...
</voting>
<resolved>
<issue date="...">
<votes>
<vote person-id="..." vote=""/>
...
<votes>
<ref>http://...</ref>
<ref>./src/...</ref>
<descr>...</descr>
</issue>
...
</resolved>
</decisions>
<todo>
<actions priority="high">
<action context="..." dev="...">...</action>
...
</actions>
<actions priority="medium">
<action context="..." dev="...">...</action>
...
</actions>
<actions priority="low">
<action context="..." dev="...">...</action>
...
</actions>
</todo>
<changes>
<release version="..." date="...">
<summary>...</summary>
<notes>...</notes>
<action dev="NKB" type="update" context="utils">
Added a convert dir in the resources with stylesheets and builfile
to help convert Anakia and Maven-based sites.
</action>
</release>
</changes>
<wishlist>
<action context="..." dev="...">...</action>
</wishlist>
</status>
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: Filesystem layout (Re: Skin rewrite: 0.2 release?)
Posted by Steven Noels <st...@outerthought.org>.
Nicola Ken Barozzi wrote:
>> OTOH, generalizing remarks from single individuals as 'general user
>> requests' will bring us to FS sooner rather than later. So we need
>> more debate ad perhaps a vote, sorry.
>
>
> We already did.
> We discussed this already, ask your co-worker.
Colleague, please. And no, we don't have a common opinion since we work
for the same company.
> I'm surprised I have to go through this again.
That's because mailing lists serve bad as living memory for 'real
decisions'. Please go forward with your good thinking, but materialize
it in a document users can depend on - I've just committed a skeleton
for you.
(and don't feel mad, I made it already into one kill filter this week)
</Steven>
--
Steven Noels http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
Read my weblog at http://radio.weblogs.com/0103539/
stevenn at outerthought.org stevenn at apache.org
Re: Filesystem layout (Re: Skin rewrite: 0.2 release?)
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Steven Noels wrote:
> Jeff Turner wrote:
>
>> :) I think we need a proper Forrest roadmap, with use-cases and a
>> concrete, technical step-by-step guide, in order to prevent
>> misunderstandings like this from happening again.
>
>
> +1
>
> I don't know what has been happening recently, and sure lots of it is
> simply Good Stuff, but I have problems with this new eagerness to throw
> stuff over the wall into the open. I'm in good standing with the
> 'release early & often' strategy, but if we are claiming to be
> best-practices-driven, I don't see why we shouldn't take the time to
> double-check these practices.
>
> I have been one of the advocates of 'let the user decide how he will
> organize its resources' in the past, so I tend to agree with the idea
> Nicola is pushing forward.
>
> OTOH, generalizing remarks from single individuals as 'general user
> requests' will bring us to FS sooner rather than later. So we need more
> debate ad perhaps a vote, sorry.
We already did.
We discussed this already, ask your co-worker.
I'm surprised I have to go through this again.
> I know I'm doing the best I can to make myself immensely unpopular right
> now. But maybe I'm simply too afraid to throw shit towards the fan (and
> don't take this too literally!!)
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: Filesystem layout (Re: Skin rewrite: 0.2 release?)
Posted by Steven Noels <st...@outerthought.org>.
Jeff Turner wrote:
> :) I think we need a proper Forrest roadmap, with use-cases and a
> concrete, technical step-by-step guide, in order to prevent
> misunderstandings like this from happening again.
+1
I don't know what has been happening recently, and sure lots of it is
simply Good Stuff, but I have problems with this new eagerness to throw
stuff over the wall into the open. I'm in good standing with the
'release early & often' strategy, but if we are claiming to be
best-practices-driven, I don't see why we shouldn't take the time to
double-check these practices.
I have been one of the advocates of 'let the user decide how he will
organize its resources' in the past, so I tend to agree with the idea
Nicola is pushing forward.
OTOH, generalizing remarks from single individuals as 'general user
requests' will bring us to FS sooner rather than later. So we need more
debate ad perhaps a vote, sorry.
I know I'm doing the best I can to make myself immensely unpopular right
now. But maybe I'm simply too afraid to throw shit towards the fan (and
don't take this too literally!!)
</Steven>
--
Steven Noels http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
Read my weblog at http://radio.weblogs.com/0103539/
stevenn at outerthought.org stevenn at apache.org
Re: Filesystem layout (Re: Skin rewrite: 0.2 release?)
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Jeff Turner wrote:
> On Tue, Nov 12, 2002 at 10:10:37AM +0100, Nicola Ken Barozzi wrote:
> ...
>
>>>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
>
> good good..
>
>>>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.
>
> Then please describe why Centipede doesn't have one big src/, given that
> it's technically possible.
Because that's how users that have been polled have replied.
For exmaple, we are planning to have a single src dir and compile the
files in the packages indipendently, using the Gump descriptor dependencies.
>>Users have explicitely asked me to be able to have images where the
>>content is.
>
> "images where content is".. if you mean, move resources/images to
> content/images then I'm all for that.
<grrr>
>>Some are @ Avalon, not newbies.
>
>
> Please direct them to this list in future. Evidently they didn't know
> that this can be easily achieved with:
>
> project.images-dir=${project.content-dir}
> project.xdocs-dir=${project.content-dir}
Maybe it was before Forrest got to that point ;-)
> That's the point: the current system, while supporting a structured
> approach, _allows_ the unstructured approach if desired. The reverse is
> not true: if we go down your route of a sitemap full of
> general-as-possible rules, we can never go back. Fine-grained can
> emulate coarse-grained, coarse-grained cannot emulate fine-grained.
Again, I want *both* rules to apply in the same time.
That is I can put images in both places and have them delivered.
>>>- 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.
>
>
> Just like Centipede could identify JUnit test cases with:
>
> <fileset dir="src/" includes="**/*.java">
> <contains text="extends TestCase"/>
> </fileset>
In fact it can and it probably will.
> So again, given the technical feasibility, why doesn't Centipede merge
> src/testcases and src/java? Perhaps because.. it's a really dumb idea
> that users won't buy? :) If users won't buy it in Centipede, why would
> Forrest users buy it here?
Every web server does it, don't you know? :-PPP
>>>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?
>
> For the same reasons an Ant script is made simpler by partitioning src/.
> Everything is made simpler. To start with, validation, which is the tip
> of the iceberg of things broken in forrest.build.xml if we keep your
> patch. We might as well throw away forrest.build.xml and start again,
> because right at the core is the assumption that content is separated by
> type, and named with ${project.*-dir} properties.
This is just a technical thing that can be overcome.
I'm not going to make design decisions just because it's easier.
>>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?
>
> Because Javadoc cannot assume otherwise. But note that javadoc also
> suggests that large quantities of docs be stored in doc-file/ subdirs.
I know, and in fact I never said I want to *prohibit* that kind of
behaviour.
>>Why do we put properties there?
>
> Laziness. Personally I store non-Java files (manifests, properties,
> resourcebundles) in a src/res (resources) tree. For large projects it
> really is much better.
Don't assume that your way of doing it is necessarily "The Right Way".
>>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.
>
> Agreed.
>
>>We still have a resources dir, and *there* I would like to see what you
>>propose.
>
> Ahem.. I am defending the status quo here, which you just broke ;P
Ahem...
>>So users can decide to put images in the content, or treat them as
>>global "resources".
>>
>>It has been asked many times,
>
> never on list...
Are you sure? What about Ken (IIUC) that wants to be able to have
Forrest serve any file that's in the directory?
Probably I just also misunderstood Ken, Peter, Stephen, Cristina here at
my workplace, etc...
>>I don't see technical difficulties,
>
> perhaps you haven't examined forrest.build.xml recently?
I have, but not with this in mind.
I will soon.
>>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.
>
>
> +1. Mine does, yours doesn't :) Here's how the current system can
> emulate yours:
>
> project.content-dir=src/documentation/content
> project.xdocs-dir=${project.content-dir}
> project.images-dir=${project.content-dir}
>
> That _works_ right now.
No, it doesn't. It doesn't cater for a mixed scenario and needs work to
make it copy-less.
But validation is more important ATM, so I've reverted my commit.
> Any users who prefer a single content dir can do
> just that. Sure, they'll get 3 copies of the content/ directory in
> build/tmp/, but it will work, and as soon as we eliminate the copy step
> (by parametrising the sitemap) that problem will go away.
>
>
>>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.
>
> Can do that too.
>
>>I like it.
>
>
> :) I think we need a proper Forrest roadmap, with use-cases and a
> concrete, technical step-by-step guide, in order to prevent
> misunderstandings like this from happening again.
This was decided IIRC in previous discussions, and I'm sorry nobody else
jumps in this discussion to state opinions or memories.
Anyway, you have the ball now.
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: Filesystem layout (Re: Skin rewrite: 0.2 release?)
Posted by Jeff Turner <je...@apache.org>.
On Tue, Nov 12, 2002 at 10:10:37AM +0100, Nicola Ken Barozzi wrote:
...
> >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
good good..
> >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.
Then please describe why Centipede doesn't have one big src/, given that
it's technically possible.
> Users have explicitely asked me to be able to have images where the
> content is.
"images where content is".. if you mean, move resources/images to
content/images then I'm all for that.
> Some are @ Avalon, not newbies.
Please direct them to this list in future. Evidently they didn't know
that this can be easily achieved with:
project.images-dir=${project.content-dir}
project.xdocs-dir=${project.content-dir}
That's the point: the current system, while supporting a structured
approach, _allows_ the unstructured approach if desired. The reverse is
not true: if we go down your route of a sitemap full of
general-as-possible rules, we can never go back. Fine-grained can
emulate coarse-grained, coarse-grained cannot emulate fine-grained.
> > - 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.
Just like Centipede could identify JUnit test cases with:
<fileset dir="src/" includes="**/*.java">
<contains text="extends TestCase"/>
</fileset>
So again, given the technical feasibility, why doesn't Centipede merge
src/testcases and src/java? Perhaps because.. it's a really dumb idea
that users won't buy? :) If users won't buy it in Centipede, why would
Forrest users buy it here?
> >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?
For the same reasons an Ant script is made simpler by partitioning src/.
Everything is made simpler. To start with, validation, which is the tip
of the iceberg of things broken in forrest.build.xml if we keep your
patch. We might as well throw away forrest.build.xml and start again,
because right at the core is the assumption that content is separated by
type, and named with ${project.*-dir} properties.
> 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?
Because Javadoc cannot assume otherwise. But note that javadoc also
suggests that large quantities of docs be stored in doc-file/ subdirs.
> Why do we put properties there?
Laziness. Personally I store non-Java files (manifests, properties,
resourcebundles) in a src/res (resources) tree. For large projects it
really is much better.
> 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.
Agreed.
> We still have a resources dir, and *there* I would like to see what you
> propose.
Ahem.. I am defending the status quo here, which you just broke ;P
> So users can decide to put images in the content, or treat them as
> global "resources".
>
> It has been asked many times,
never on list...
> I don't see technical difficulties,
perhaps you haven't examined forrest.build.xml recently?
> 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.
+1. Mine does, yours doesn't :) Here's how the current system can
emulate yours:
project.content-dir=src/documentation/content
project.xdocs-dir=${project.content-dir}
project.images-dir=${project.content-dir}
That _works_ right now. Any users who prefer a single content dir can do
just that. Sure, they'll get 3 copies of the content/ directory in
build/tmp/, but it will work, and as soon as we eliminate the copy step
(by parametrising the sitemap) that problem will go away.
> 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.
Can do that too.
> I like it.
:) I think we need a proper Forrest roadmap, with use-cases and a
concrete, technical step-by-step guide, in order to prevent
misunderstandings like this from happening again.
--Jeff
Re: Filesystem layout (Re: Skin rewrite: 0.2 release?)
Posted by Nicola Ken Barozzi <ni...@apache.org>.
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)
---------------------------------------------------------------------