forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Nicola Ken Barozzi <nicola...@apache.org>
Subject Re: [RT] Directory structure and configuration
Date Wed, 11 May 2005 22:30:36 GMT
Ferdinand Soethe wrote:
> 
>>forrest.properties to become forrest-properties.xml
>>-1
> 
>>forrest.properties should become forrest.xml like Nicola suggested
>>because it is the main configuration file for forrest like maven.xml for
>>maven. ;-)
> 
> I can't see this as such a good reason to do it the same.
> 
> In my view:
> 
> If more filename speak for themselves, less people need to to
> read documentation to get started and we'll have less questions to
> answer in the list.

Correct. But the point is: when do filenames speak for themselves?

My experience has showed me that a name you're accustomed to is more 
understandable than a long descriptive filename.

IOW:

  /src
  /build

is more understandable than

  /source-files
  /results-of-build-operation

...
> And sorry, 'forrest.xml' tells me nothing about the role if this file
> other than it being an xml-file. The knowledge that it is the main
> configuration file might be concluded by people who know the other
> products, but then why limit easy understanding to such a small group.
> 
> Isn't it a bit like speaking latin in church because it is the language
> spoken in all other churches ....

If a user cannot understand what forrest.xml is and edit it, he will not 
be particularly helped in having it with a different name.

To make it easier to use, much more than just naming is needed (like a 
GUI), and for developers, short and well-known names are better.

>>...and it has to go to FORREST-INF/!!!
> 
> OK, I can see why (see belowI and agree to a separate config directory now.
> So how about calling it 'configuration'.

Servlets have 'WEB-INF'. Linux has 'conf'. Speak the developer's 
language. I had your same opinion a couple of years ago, and tried it, 
but it did not work.

> Plugin would then have their named config subdir in there.
> 
>>>  CatalogManager.properties
>>>                     *why have a subdir just for one file?
> 
> 
>>Yes should go as well into the FORREST-INF/.
> 
> OK, everybody +1 on having it in the conf dir (whatever we name it)
> 
>>>                  
>>>  content/
>>>    status.xml
>>>    site.xml
>>>    tabs.xml
>>>    former content of xdocs here and in subdirs if required
>>>
> 
>>+1
> 
> this seem consensus as far as I can tell
> 
>>>  content-untranslated/
>>>    images, binaries ...
..
>>For me (like for Nicola) that are resources/ and would have to go to that dir.
..
>>>  * I'd rather not have untranslated content in the resources tree
>>>    as Nicola proposed (though I understand the logic behind it)
>>>    because it is much harder to create references to files if their
>>>    structure of  subdirs does not start from the same level as the
>>>    subdirs in content.
> 
>>I do not understand. In the end everything should get resolved by
>>cocoon:/(/) calls that means that problem would be the one of the
>>controller. The reference you are talking about could e.g. be a simple
>>site:images/xyz.png.
> 
> Let me explain from a use case where people have several content dir
> called 'project1', 'project2' ... each one of the coming with their
> own set of images each one being eventuelly replaces by project 5,6,7
> when they are outdated.
> 
> To keep management simple I'd suggest to keep the images in a sub dir
> structure equal to the docs structure to be able to easily delete a
> project _and_ all ite resources.
> 
> Now this might still work with one layer of projects, but as soon as
> you start having project1 with subproj11 and subproj12 people will
> start having problem maintaining these separate trees.
> 
> So you can avaid a lot of maintenance errors when you simply put the
> in the same directory. If not, at least keep the structure symetrical
> as non-techniscal users will have an easier time making the
> connection.

I'm not sure I fully understand. Could you please post two example trees 
for the two scenarios?

>>>    In fact from a users perspective I'd even suggest to have raw
>>>    content in the content dir for easier management, but I'm not sure
>>>    that is possible.
> 
> 
>>Hmm, then we need to discuss the placing of forrest:views into the
>>content dir or in a dir for it own and creating a shadow content
>>structure. There are some drawback to it like Ross stated the other
>>day. 
> 
> I need to re-read Ross' comments, but again in my experience
> maintenance will get harder the further the files that work together
> are placed.
> 
>>I think we should keep build/ as top-level because that is most common
>>in cocoon related projects. Everything that you now describe is part of
>>some kind of build.
> 
> I will make this point one last time and then keep quiet about it.

Why? It's progressing nicely and things are being ironed out. Please 
continue :-)

> This whole discussion was started because I wanted Forrest to become
> more transparent for new people beyond the sworn in community. And
> this goal is sometimes incompatible with making 'cocoonies' feel right
> at home.
> 
> But we/you need to make up our mind about that. And if you decide to
> stick to the technical naming we have now, we won't be able to explain
> structure to normal people (or train it) and so I'd start working on a
> gui interface that hides all this.

Hmmm... wait a sec, read on:

>>...but yeah static-output/ instead of site/, why not? ;-)
>>>  server-space/  instead of build/       * to mark it as server workspace
> 
> 
>>-1 see above
> 
> Same decision as above.
> 
> 
>>>    tmp/         instead of build/tmp/   * if this is really server
>>>                                           only otherwise move it up
>>>                                           one level
>>>    webapp/      instead of build/webapp/
>>>                                         * perhaps we can do without
>>>                                           this and move the files one
>>>                                           up?
>>>
> 
> 
>>I would rather keep webapp/ because it is closer to cocoon's webapp.
> 
> I could live with that because users have very little contact with
> this area.

Good point. We should only think about naming in the places that users 
are forced to look at, and have a GUI to handle the rest (the config).

That is:

- forrest.xml (identify the project as containing forrest content)
- source directories (I find this very important, see above my request
                       for an example)

Cool stuff, this is moving! :-)

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


Mime
View raw message