Configuration Documentation Updates

[Daniel Frey <da...@xmatrix.ch>]

Hi there,

Some documentation updates for the configuration chapter. The major parts
are typos. Just some mentionable changes: 

- In the configurations tutorial (tutorial/config) Stephen refers in the
last paragraph of the block.html to "the component has been overrided by the
information we supplied inside the <component> directive". But up to that
point a new user has no idea how a default configuration is set. I would
switch the order of Declaring (block.html) and Defaults (defaults.html) so
that we get Defaults -> Declaring -> Overriding. It's incorporated in the
patch. Ok, one could state that the fact of overriding is not wrong, as
there exists certainly a kind of default configuration object which is
instantiated without any explicit default-, block- or target-configuration
and may be overwritten by one of the configuration alternatives, but
switching makes the documentation more consistent.

- The first page mentions how to build and execute. Subsequent pages tell
the user to build and execute but literally just mention the execution line.
New users like me get confused with this and ask questions like: Is maven
just kind of an initialization and subsequent calls to Merlin do build the
system on their own? To avoid this misunderstanding, literally mention the
$maven step as well, or leave literal command lines away. I've added the
$maven command in the patch.

- I think in titles you have invented a new case algorithm/grammar: Emphasis
case ;-) Just everything that is important is title case, all the rest
lowercase. I would propose to either apply strictly title.
Example: "Declaring a configuration in the Component Directive" (block.xml).
Title case would be "Declaring a Configuration in the component Directive"
if component is a literal to the <component> element (later in the text it
is), "Declaring a Configuration in the Component Directive" otherwise. The
patches contain some title case changes in titles. I did not interpret the
directives as literals, so title cased them as well.

- Configuration: Something should be added telling how overriding behaves.
Is the <configuration> element replaced? If not, are child elements replaced
if identical? Are child elements united if different? May we compose
<configuration> directives like this?

- I'm not so good in English: But isn't the correct past of override
overridden (overrided does not exist in my English book)?

Cheers, 
Daniel

http://www.xmatrix.ch

Re: Configuration Documentation Updates

[Niclas Hedhman <ni...@hedhman.org>]

On Saturday 13 March 2004 20:12, Daniel Frey wrote:
> Some documentation updates for the configuration chapter. The major parts
> are typos. Just some mentionable changes:

Good to hear that you are into this...
You mention a 'patch', but I think either you forgot to attach it, or it is 
too big, so it got filtered away by the mailing list program.

Can you send it to me privately, and I will take a look and apply it.

Cheers
Niclas
-- 
+---------//-------------------+
|   http://www.bali.ac         |
|  http://niclas.hedhman.org   |
+------//----------------------+

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@avalon.apache.org
For additional commands, e-mail: dev-help@avalon.apache.org