Bob Harner wrote:
> On 1/2/06, Joern Nettingsmeier <[EMAIL PROTECTED]> wrote:
>> <mini-rant obnoxiousness="medium">
>> we do need good documentation of the entire filesystem layout
>> under /build/lenya/ and what each directory and file does.
>> </mini-rant>
>> i'll start a wiki page for that.
>>
>
> A wiki page would be a good thing. But I think it might be better to
> have instead (or in addition), within most of the Lenya directories, a
> README.txt file that contains a brief description of the purpose of
> each directory, and a paragraph at the top of each file describing its
> purpose. As has been noted elsewhere, there are thousands of files in
> Lenya and many of them lack internal documentation.
>
> If the dev's agree with this, I will help where I can. For example,
> if Joern makes a wiki page describing each directory, then after
> others have reviewed it, I'll copy his text into a bunch of README.txt
> files and assemble them as a patch, attached to a bug in bugzilla,
> that a committer can then add to the appropriate directories.
cool!
for starters, i suggest we tackle lenya/webapps/lenya/pubs/... and then
move upward to lenya/webapps/lenya/*. personally i'm not too interested
in doing it for the src/ tree, because i just suck at java. wiki page is
coming...
in addition to README files explaining the meaning of the current
directory, i would also love to see comment headers in every file.
maybe we should try to come up with some standard categories to make
these docs easy to understand. here's a first go:
parsed during:
build | servlet start | page request handling (cached)
| page request handling (uncached)
parsed by:
(link to lenya/cocoon component or docs)
scope:
servlet-wide | per-publication (static)
| per-publication (fallback-enabled) (=inherited by pubs using this
one as a template)
overrides:
/path/to/higher/level/file
can be overriden by:
<derived_pub>/some/path/some.xml
| pubs/somepub/some/path/some.xml
manual modification by admin:
mandatory | optional
| not recommended (use GUI at someurl?someusecase)
| you are on your own | here be dragons
manual modification implies:
changes to foo.jx | changes to /path/to/bar.java
modified/generated by:
"some gui component at <pub_name>/authoring/somepage?someusecase"
| helper script /path/to/script
| some code snippet at...
| admin
| build.sh
it would be really practical if we could agree on such a list. it makes
grokking the comments a no-brainer and serves as an excellent and
concise questionnaire if the doc people are out of their depth and need
to pester the developers.
while we're at it, it would be nice to clean up some terminology. how about:
every *publication* can be used as a *template*, producing *derived
publications* or *child publications*. templating is implemented using
the *fallback* mechanism, a lenya-specific uri resolver that can be
applied to any uri reference in xml files by using "fallback://" as a
protocol specifier.
the creation of a new child publication from a template is called
*instantiation*. child publications can *inherit* features from the
template in two ways: by *copying* files from the template during
instantiation, or by *referencing* those files.
*copying* severs the link between child and template - later changes to
the template will not affect the child. *referencing* implies that all
changes to the template will immediately affect the child as well.
is this consistent with the usage among developers?
regards,
jörn
--
"Án nýrra verka, án nútimans, hættir fortíðin að vekja áhuga."
"Without new works, without the present the past will cease to be of
interest."
- Ásmundur Sveinsson (1893-1982)
--
Jörn Nettingsmeier, EDV-Administrator
Institut für Politikwissenschaft
Universität Duisburg-Essen, Standort Duisburg
Mail: [EMAIL PROTECTED], Telefon: 0203/379-2736
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
