clarify Plexus Tools vs Components vs Utils vs (deprecated) IoC and c…

src/site/apt/index.apt

@@ -8,13 +8,15 @@
 
 Overview
 
-  Codehaus Plexus is a collection of components used by {{{http://maven.apache.org/} Apache Maven}}:
+  Codehaus Plexus -- or more precisely <<Codehaus Plexus Tools and Components>> now -- is a collection of tools and components used by {{{http://maven.apache.org/} Apache Maven}}:
 
-  * {{{./modello/} Modello}},
+  [[1]] <<tools>>:
 
-  * {{{./plexus-classworlds/}Plexus Classworlds}},
+    * {{{./modello/} Modello}}: tool for code generation from a simple model,
 
-  * Plexus Components:
+    * {{{./plexus-classworlds/}Plexus Classworlds}}: tool for advanced Java ClassLoader management.
+
+  [[2]] <<Plexus components>> (ie. implemented as {{{https://jcp.org/en/jsr/detail?id=330}JSR-330}} compliant components with <Plexus Container (deprecated)>/{{{https://www.eclipse.org/sisu/}Sisu}}):
 
     * {{{./plexus-archiver/}plexus-archiver}}: components to manipulate archives,
 
@@ -38,29 +40,38 @@ Overview
 
     []
 
-  * Plexus Parent POM: {{{./plexus-pom/}plexus}}
+  [[3]] <<Parent POMs>>:
 
-  * {{{./plexus-utils/} Plexus Utils}},
+    * Plexus Parent POM: {{{./plexus-pom/}plexus}},
 
-  * {{{./plexus-xml/} Plexus XML}}
+    * Plexus Compponents Parent POM: {{{./plexus-components/}plexus-components}}.
 
-  []
+  [[4]] <<utilities>>:
 
+    * {{{./plexus-utils/} Plexus Utils}},
+
+    * {{{./plexus-xml/} Plexus XML}}.
+
+  [[5]] <(deprecated) {{{./plexus-containers/}Plexus Container}} (IoC container and companion tools)>, replaced by {{{https://www.eclipse.org/sisu/}Eclipse Sisu}} and {{{https://jcp.org/en/jsr/detail?id=330}JSR-330}}
+
+  []
 
-Plexus History
 
 ============================
 
-* IMPORTANT NOTICE
+IMPORTANT NOTICE:
+Plexus Container and Companion Tools History
+
+  Plexus was initially composed of 2 parts: Plexus Container (IoC and companion tools) and Plexus Components (like Spring IoC and Spring Components).
 
-  The Plexus project was previously focused on {{{/plexus-containers/}IoC Plexus Container}}:
-  it is now replaced with {{{https://www.eclipse.org/sisu/}Eclipse Sisu}}, rewritten as an extension on Google Guice.
-  We kept whole content on IoC for reference, even if the IoC part is now obsolete.
+  The project was previously focused on {{{./plexus-containers/}Plexus Container (IoC and companion tools)}}, not so much on Plexus Components:
+  <<Plexus Container (IoC and companion tools)>> is now replaced with {{{https://www.eclipse.org/sisu/}Eclipse Sisu}}, written as a {{{https://jcp.org/en/jsr/detail?id=330}JSR-330}}-compliant extension on Google Guice.
+  We kept the whole IoC + components content in this site for IoC historical reference, even if the <{{{./plexus-containers/}IoC and companion tools}}> part is now obsolete.
 
 ============================
 
   See the {{{./ref/feature-comparison.html} Feature Comparison}} page for more information on
-  the differences between Plexus and other products.
+  the differences between Plexus and other IoC ecosystems.
 
   The Plexus project provides a number of pre-built components for common tasks and toolkits
   such as Velocity, i18n, and {{{./ref/available-components.html} many more}}.

src/site/apt/ref/feature-comparison.apt

@@ -9,15 +9,15 @@
 
  <<<The contents of this document are a work in progress>>>
 
-How does Plexus compare with Spring?
+How does Plexus compare with Spring (1, early 2000)?
+
+  * <<Plexus is simpler and much much smaller than Spring.>>
 
-* Plexus is simpler and much much smaller than Spring. 
-
   The simplest Spring Component which has configuration settings injected is 
   more complex than in an equivalent case for Plexus as Plexus does not require
   setters.
 
-* Spring attempts to be a Swiss Army knife.
+  * <<Spring attempts to be a Swiss Army knife.>>
 
   Spring tries to sell itself as a "j2ee framework" and as a Swiss Army knife -
   one framework for all possible problems. 
@@ -32,35 +32,35 @@ How does Plexus compare with Spring?
   Army knife you can use better tools:  hammer, screwdriver as you need to use 
   them without having to include them all.
 
-* Complex component life cycles are not supported in Spring.
+ * <<Complex component life cycles are not supported in Spring.>>
 
-* Spring configuration files are much longer than the one for Plexus.
+ * <<Spring configuration files are much longer than the one for Plexus.>>
 
   Specifically hierarchical configuration settings ala xstream are not
   supported by Spring.
 
-* Spring is not using IoC for all dependecies of components.
+ * <<Spring is not using IoC for all dependecies of components.>>
 
   For example Spring is promoting terrible things like logging based on commons-logging,
   which makes most of the component dependent on an ugly singleton (IoC is 
   against singletons!) and inevitably leads to incorrect class loader 
   hierarchies (commons-logging must be in root classloader of the container).
 
-* Missing notion of "Component identity"
+ * <<Missing notion of "Component identity">>
 
   Spring doesn't allow you to direct logging output from two deployed instances
   of the same component/bean to different files (unless you use AOP). This is
   due to the fact that "component identity" is not propagated or understood by
   the logging system. In Plexus such things are possible - but not yet
   implemented.
 
-* Component class loader isolation.
+ * <<Component class loader isolation.>>
 
   Spring doesn't allow you to easly deploy two distinct components which are 
   using conflicting version of "the same" jar (e.g. common-collections-2.x and
   commons-collection-3.x). for their internal stuff.
 
-* In Plexus you don't have to repeat yourself.
+ * <<In Plexus you don't have to repeat yourself.>>
 
   Component descriptors which are in jars contain the facts which are needed 
   by the container to manage components. Component personalities provide useful 

src/site/site.xml

@@ -39,6 +39,8 @@ under the License.
 
   <body>
     <links>
+      <item name="JSR-330" href="https://jcp.org/en/jsr/detail?id=330"/>
+      <item name="Eclipse Sisu" href="https://www.eclipse.org/sisu/"/>
       <item name="Plexus" href="http://codehaus-plexus.github.io/" />
     </links>