avalon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Daniel Frey" <daniel.f...@xmatrix.ch>
Subject Documentation corrections
Date Fri, 12 Mar 2004 14:03:27 GMT
Hi there,

I start to develop a feeling for merlin and I am therefore reworking through
the tutorial and documentation. Appart from the funny typos (i.e. "famework"
instead of "framework") I have also met some really confusing paragraphs
which definitively need to be enhanced.

Example: In the tutorial/creation.html file, mcconnell writes in the
subchapters 3 and 4:

001 ==================================================
002 Creating a Type Descriptor
003 --------------------------
004 
005 In order for Merlin to recognize this class as a 
006 component, we need to generate a <classname>.xinfo 
007 file.
008 
009 The following text is an example of a component 
010 type definition. It contains the declaration of 
011 the component name and the component 
012 implementation version. It was generated 
013 automatically for us by the pre-goal included in 
014 the maven.xml file. The avalon:meta plugin looks 
015 for @avalon.component tags at class level and 
016 generates component descriptors for us 
017 automatically.
018 
019 <preGoal name="java:compile">
020   <attainGoal name="avalon:meta"/>
021 </preGoal>
022 
023 ==================================================
024 Generated Type Descriptor
025 -------------------------
026 
027 <type>
028   <info>
029     <name>hello</name>
030     <version>1.0.0</version>
031     <lifestyle>transient</lifestyle>
032   </info>
033 </type>

For a first time reader, as I was some days before, this is confusing
because:
- The first paragraph (005-007) addresses the xinfo file. The code that
follows next is the preGoal, the xinfo follows in the next subchapter.
- Line 009 refers to the following text as a component definition. As a
newbie I take this serious and I am not immediately able to recognize this a
mistake. Indeed, the code in the next subchapter is the component type
definition.

I propose to 
- add the following sentences to line 007: "However, this can be done
automatically by including a pre-goal as shown below into the maven.xml
file. The avaon:meta plugin looks for @avalon.component tags at class level
and generates component the descriptors for us."
- push the paragraph (009-017) down to the next subchapter and remove the
sentences in 012-017.

I may also correct them directly if you would like to give me commit rights
to the cvs.

Cheers, Daniel


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


Mime
View raw message