Here's a suggestion for a formal documentation structure to help Lenya users grok the directory hierarchy and the interaction of files in Lenya. Ideally, each file gets a comment header and each directory contains a README file that will list the following information for files and directories respectively:
parsed during
| indent |
|---|
build | servlet start | page request handling (cached) | page request handling (uncached) |
parsed by
| indent |
|---|
(link to lenya/cocoon component or docs) |
scope
| indent |
|---|
servlet-wide | per-publication (static) | per-publication (fallback-enabled) (=inherited by pubs using this one as a template) |
overrides
| indent |
|---|
(/path/to/higher/level/file) |
can be overriden by
| indent |
|---|
<derived_pub>/some/path/some.xml | pubs/somepub/some/path/some.xml |
manual modification
| indent |
|---|
mandatory | optional | not recommended (use GUI at someurl?someusecase) | you are on your own | here be dragons |
manual modification implies
| indent |
|---|
changes to foo.jx | changes to /path/to/bar.java |
modified/generated by
| indent |
|---|
"some gui component at <pub_name>/authoring/somepage?someusecase" | helper script /path/to/script | some code snippet at... | admin | build.sh |
If we can agree on a scheme like this, we might eventually apply it to solve the mysteries of DirectoryStructureLenya2.0-HEAD.