Index: cocoon.xconf
===================================================================
RCS file: /home/cvspublic/xml-cocoon2/webapp/cocoon.xconf,v
retrieving revision 1.23
diff -u -r1.23 cocoon.xconf
--- cocoon.xconf	2001/07/19 17:27:52	1.23
+++ cocoon.xconf	2001/07/23 16:54:46
@@ -56,12 +56,24 @@
   <source-handler>
   </source-handler>
 
+  <!-- The ProgamGenerator builts programs from a XML document written in 
+       a MarkupLanguage.
+       auto-reload: 
+       root-package: persistent code repository.
+       preload:  -->
   <program-generator>
     <parameter name="auto-reload" value="true"/>
     <parameter name="root-package" value="org.apache.cocoon.www"/>
     <parameter name="preload" value="true"/>
   </program-generator>
 
+  <!-- The JspGenerator selects a JSPEngine component. The JSPEngine component launches 
+       a JSP servlet engine of your servlet container, feeds the HttpRequest into the JSP 
+       servlet engine, and pipes the jsp response as SAX events into Cocoon2. The JSP page 
+       is specified by the HttpRequest. This way you can continue to use your JSP pages. 
+       Your migration from JSP to XSP may be done step by step. You may specify your JSP 
+       pages either as JSP scriptlets or as JSP-XML. But keep in mind that your JSP output 
+       should be valid XML. -->
   <jsp-engine>
     <parameter name="servlet-class" value="org.apache.jasper.servlet.JspServlet"/>
     <parameter name="servlet-name" value="*.jsp"/>
@@ -78,32 +90,46 @@
       <!-- Specifies which formatter to use to format source code.
            This parameter is optional. -->
       <parameter name="code-formatter" value="org.apache.cocoon.components.language.programming.java.JstyleFormatter"/>
+      <!-- A singleton-like implementation of a ClassLoader -->
       <parameter name="class-loader" value="org.apache.cocoon.components.classloader.ClassLoaderManagerImpl"/>
     </java-language>
   </programming-languages>
 
+  <!-- A singleton-like implementation of a ClassLoader -->
   <classloader class="org.apache.cocoon.components.classloader.ClassLoaderManagerImpl"/>
-
+  
+  <!-- This section defines several builtin logicsheets. A logicsheet is an XML filter used 
+       to translate user-defined, dynamic markup into equivalent code embedding directives 
+       for a given markup language. -->
   <markup-languages>
     <xsp-language name="xsp">
       <parameter name="prefix" value="xsp"/>
       <parameter name="uri" value="http://apache.org/xsp"/>
 
+      <!-- Defines the XSP Core logicsheet for the Java language -->
       <target-language name="java">
         <parameter name="core-logicsheet" value="resource://org/apache/cocoon/components/language/markup/xsp/java/xsp.xsl"/>
-
+        
+        <!-- The Request logicsheet (taglib) is an XSP logicsheet that wraps XML tags 
+             around standard request operations -->
         <builtin-logicsheet>
           <parameter name="prefix" value="xsp-request"/>
           <parameter name="uri" value="http://apache.org/xsp/request/2.0"/>
           <parameter name="href" value="resource://org/apache/cocoon/components/language/markup/xsp/java/request.xsl"/>
         </builtin-logicsheet>
-
+       
+        <!-- The Response logicsheet (taglib) is an XSP logicsheet that wraps XML tags 
+             around standard response operations -->
         <builtin-logicsheet>
           <parameter name="prefix" value="xsp-response"/>
           <parameter name="uri" value="http://apache.org/xsp/response/2.0"/>
           <parameter name="href" value="resource://org/apache/cocoon/components/language/markup/xsp/java/response.xsl"/>
         </builtin-logicsheet>
 
+        <!-- The Session logicsheet (taglib) is an XSP logicsheet that wraps XML tags around 
+             standard session operations. Specifically, the Session logicsheet provides an 
+             XML interface to most methods of the HttpSession object (see the Java Servlet API 
+             Specification, version 2.2 ) for more information. -->
         <builtin-logicsheet>
           <parameter name="prefix" value="session"/>
           <parameter name="uri" value="http://apache.org/xsp/session/2.0"/>
@@ -116,6 +142,9 @@
           <parameter name="href" value="resource://org/apache/cocoon/components/language/markup/xsp/java/cookie.xsl"/>
         </builtin-logicsheet>
 
+        <!-- The ESQL logicsheet is an XSP logicsheet that performs sql queries and 
+             serializes their results as XML. This allows you to work with data from a 
+             wide variety of different sources when using Apache Cocoon. -->
         <builtin-logicsheet>
           <parameter name="prefix" value="esql"/>
           <parameter name="uri" value="http://apache.org/cocoon/SQL/v2"/>
@@ -133,7 +162,9 @@
           <parameter name="uri" value="http://apache.org/xsp/util/2.0"/>
           <parameter name="href" value="resource://org/apache/cocoon/components/language/markup/xsp/java/util.xsl"/>
         </builtin-logicsheet>
-
+        
+        <!-- The xsp-formval taglib serves as interface to retrieve validation results 
+             from a request attribute -->
         <builtin-logicsheet>
           <parameter name="prefix" value="xsp-formval"/>
           <parameter name="uri" value="http://apache.org/xsp/form-validator/2.0"/>
@@ -149,6 +180,7 @@
       </target-language>
     </xsp-language>
 
+    <!-- Defines Sitemap Core logicsheet for the Java language -->
     <sitemap-language name="sitemap">
       <parameter name="prefix" value="map"/>
       <parameter name="uri" value="http://apache.org/cocoon/sitemap/1.0"/>
@@ -250,7 +282,6 @@
      <parameter name="threadpriority" value="5"/>
      <parameter name="filesystem" value="true"/>
   </event-cache>
-
 
   <!-- The SAXConnector connects the various pipeline components.
        LoggingSAXConnector logs SAX events between pipeline components