cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From stef...@locus.apache.org
Subject cvs commit: xml-cocoon/xdocs/images/orig powered by cocoon.psd pyramid model of contracts.ai
Date Thu, 27 Jan 2000 03:46:06 GMT
stefano     00/01/26 19:46:06

  Added:       xdocs    WD-xsp.xml cocoon2.xml dcpprocessor.xml
                        docs-book.xml dynamic.xml faq.xml guide.xml
                        index.xml installing.xml javadoc.xml
                        ldapprocessor.xml license.xml site-book.xml
                        sqlprocessor.xml technologies.xml xspprocessor.xml
               xdocs/dtd changes-v10.dtd characters.ent document-v10.dtd
                        faq-v10.dtd javadoc-v04draft.dtd
                        specification-v10.dtd todo-v10.dtd
               xdocs/images add.jpg cocoon-small.jpg cocoon.jpg
                        dcp-fig-1.gif dcp-fig-2.gif fix.jpg
                        pyramid-model.gif remove.jpg schema.jpg update.jpg
               xdocs/images/orig powered by cocoon.psd pyramid model of
                        contracts.ai
  Log:
  the new docs
  
  Revision  Changes    Path
  1.1                  xml-cocoon/xdocs/WD-xsp.xml
  
  Index: WD-xsp.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <!DOCTYPE specification SYSTEM "./dtd/specification-v10.dtd">
  
  <specification>
   <header>
    <title>eXtensible Server Pages</title>
    <version>2000-01-09</version>
    <type>Working Draft</type>
    <authors>
     <person name="Stefano Mazzocchi" email="stefano@apache.org"/>
     <person name="Ricardo Rocha" email="ricardo@apache.org"/>
    </authors>
    <notice>
      This is an Apache Working Draft for review by all interested
      parties. It is a draft document and may be updated, replaced, or obsoleted by other
      documents at any time. It is inappropriate to use Working Drafts as reference material or
      to cite them as other than &quot;work in progress&quot;. This work is part of the <link
      href="http://xml.apache.org/cocoon/">Apache Cocoon Project</link>
    </notice>
    <abstract>
      This document specifies an XML namespace that addresses a complete
      region of web publishing, that of logic-based, dynamic content generation. This language
      is introduced to fill an existing gap between the W3C specifications and working draft and
      the increasing demand for a flexible server side approach based on the new XML paradigm.
    </abstract>
   </header>
   
   <body>
    <s1 title="Introduction">
     <p>This document specifies both an XML document type definition and a development
     methodology to generate dynamic XML by server side processing of client's requests. Such a
     specification is useful to define an open and standard way to develop and maintain dynamic
     XML server pages. The technology described in this document was designed to complete the
     XML-based publishing framework defined by the Cocoon Project and it's mainly targeted
     on this project, even if the final goal of this effort is to submit a request to a standard
     body (such as W3C) for final recommendation.</p>
     
     <s2 title="Origins">
     <p>The need for an open language to standardizing server side programmatic XML generation
    was observed when XML-based web publishing frameworks emerged and no available technology
    was detailed, stable, useful and open enough to be used. XSP, by mixing Turing-complete
    programming logic with page content, provide a flexible yet fully portable and extensible
    way to develop dynamic XML content. Moreover, being completely XML-based, XSP are fully
    integrated with XML-based web architectures that allow XSL-transformation to obtain the
    context separation that is needed for complex sites to increase their management
    parallelism.</p>
    
    <p>Being based on an XML paradigm from the beginning, XSP don't suffer limitations other
    server pages technologies do: the ability to XSL-transform XSP directly and recursively
    allows a more compact and precise DTD to be designed since content/logic/style separation
    is performed by the architecture and not by the language itself. For this reason, XSP are
    completely transparent to the namespaces/document-types used.</p>
     </s2>
   
  <s2 title="Layer Separation">
    <p>Being a rather complex technology, the XSP specification will be separated into layers.
    These layers will have different goals and restrictions and will allow faster development
    cycles and a better defined development model. Every layer will define its own document
    type definition which may extend the one of the previous layer or completely change it,
    depending on layer goals. Layers should be seen as levels of abstraction, much like
    programming languages range from higher-levels to lower-levels.</p>
  </s2>
  
  <s2 title="General Goals">
    <p>Following is a summary of the design principles governing the general XSP specification:</p>
    <ol>
     <li>should integrate completely with existing W3C recommendations and working drafts</li>
     <li>should be programming language independent</li>
     <li>should be aimed to programmers but should be relatively easy to understand</li>
     <li>should allow pages to be compiled (into Java servlets or other equivalent technology)</li>
     <li>should not aim to replace existing technologies</li>
     <li>should be document oriented</li>
     <li>should allow easy reusability of page code</li>
     <li>should allow complete separation of knowledge contexts (content, logic and style)</li>
     <li>should be transparent to all but page programmers</li>
     <li>specification should be open to all but controlled directly by the Cocoon Project</li>
    </ol>
  </s2>
  
  <s2 title="Layer 1 Goals">
    <p>Following is a summary of the design principles governing the Layer 1 of the XSP
    specification:</p>
    <ol>
      <li>should define the complete element set</li>
      <li>should be aimed to machine generations so:
       <sl>
        <li>reducing the number of elements to a minimum is of maximal importance</li>
        <li>verbosity of the generated documents is of minimal importance</li>
       </sl>
      </li>
      <li>should be human readable/editable so:
       <sl>
        <li>terseness and readability are of maximal importance</li>
        <li>indenting and formattation are of maximal importance</li>
       </sl>
      </li>
      <li>should be possibly XSLT transformed directly into programming language source code</li>
      <li>should define the relations to the programming languages (object models, variable scopes)</li>
    </ol>
  </s2>
  
  <s2 title="Layer 2 Goals">
    <p>Following is a summary of the design principles governing the Layer 2 of the XSP
    specification:</p>
    
    <ol>
     <li>should define a human oriented element set</li>
     <li>should be aimed to human generations so:
      <sl>
       <li>reducing the number of elements to a minimum is of minimal importance</li>
       <li>reducing verbosity of the documents is of maximal importance</li>
      </sl>
     </li>
     <li>should be aimed to medium-low knowledged programmers:
      <sl>
       <li>automatization of complex operations is of maximal importance</li>
       <li>tendency to hide page logic is of maximal importance</li>
      </sl>
     </li>
     <li>should be possibly XSLT transformed into XSP Layer 1 documents</li>
    </ol>
  </s2>
  
  <s2 title="Final Goals">
    <p>The XSP specification would eventually evolve into a single specification with a single
    document type definition. This will happen when the working draft phase will be terminated
    and all involved parties will agree on the specification stability. The Layer 1 will be
    the first to be developed and tested in a working implementation. Subsequent layers will
    probably need several evolution stages to reach their final shape.</p>
  </s2>
  
  <s2 title="Relationship to Existing Standards">
    <p>Three standards have been especially influential:</p>
    <dl>
      <dt>JSP</dt>
      <dd>defines a way to embed programmatic logic into web documents.</dd>
      <dt>XSLT</dt>
      <dd>defines a way to transform XML documents.</dd>
      <dt>XML</dt>
      <dd>defines a flexible still highly structured paradigm for web
        content generation and distribution.</dd>
    </dl>
    <p>Many server side dynamic web content generators have been evaluated and confronted,
    especially WebMacro and GSP.</p>
  </s2>
  
  <s2 title="Terminology">
    <p>The following basic terms apply in this document:</p>
    <dl>
      <dt>document</dt>
      <dd>
        a document is the final result of the client request phase and they can be obtain from a
        single file that is read from disk/cache or by processing several ones. Documents are said
        <em>static</em> if their content doesn't change with user request parameters nor time.
        Documents are said <em>dynamic</em> if they do.
      </dd>
      <dt>page</dt>
      <dd>
        a page is the entity that is requested by the client and drives the document creation
        process. In the simplest case, a document is created reading the page and sending it
        directly without further processing. In case of compiled pages, a binary object is
        executed and it's content is used as page content. Pages are said <em>compiled</em> if
        they are translated into binary code. Note that compiled pages may be created from normal
        pages the first time the page is requested and executed as binary code in further requests
        for performance reasons.
      </dd>
      <dt>sheet</dt>
      <dd>
        a sheet is the processing unit of the document creation chain. Each sheet is a file and
        they contain the instructions to transform the requested page into the document sent to
        the requesting client. Sheets are said <em>style sheets</em> if they are the last of the
        chain and no further processing in performed, <em>logic sheets</em> if they contain XSP
        elements. Both types are said <em>transformation sheets</em> since they contain XSLT
        elements.
      </dd>
      <dt>document type</dt>
      <dd>
        a document type is a unique name that identifies the type of the document being
        generated. This term has the same meaning as in the XML specification. Note how a document
        has only one document type but this could change during processing since transformation
        sheets allow the transformation from one document type into another.
      </dd>
    </dl>
  </s2>
  </s1>
  
  <s1 title="XSP Syntax and DTD">
  
  <s2 title="Defined External Entities">
  
    <p>The XSP specification defines some external entities that may be used to reduce the
    verbosity of XSP document, allowing the inclusion the default DTD via entity mapping. The
    standard way to include the XSP DTD into XSP documents is:</p>
  
  <source><![CDATA[
  <!DOCTYPE page PUBLIC 
     "-//Apache//DTD XSP//EN" 
     "http://www.apache.org/1999/XSP/Core"
  >
  ]]></source>
  
  </s2>
  
  <s2 title="The XSP Layer 1 Document Type Definition">
    <p>The XSP DTD was designed with simplicity in mind. The number of elements and attributes
    was reduced to a minimum to allow a fast and easy learning process. On the other hand, no
    special helper elements were defined in Layer 1 to reduce the spec development time and to
    favor early feedback from both implementers and users.</p>
    
    <p>The following is the complete DTD. It must be noted that this DTD can hardly be used
    (alone) to validate any XSP due to the fact that XSP are namespace orthogonal and are
    designed to include as content mark-up elements that belong to other namespaces.
    The XSchema effort will allow multi-namespace validation.</p>
  
  <source><![CDATA[
  
  <!ENTITY % elements "xsp:expr | 
                       xsp:element | 
                       xsp:pi | 
                       xsp:comment">
  
  <!ELEMENT xsp:page (xsp:structure?, xsp:logic?, xsp:content)>
  <!ATTLIST xsp:page
    language CDATA #REQUIRED
    indent-result (yes|no) "no"
    xmlns:xsp CDATA #FIXED "http://www.apache.org/1999/XSP/Core"
    xml:space (default|preserve) "preserve"
  >
  
  <!ELEMENT xsp:structure (xsp:dtd?, xsp:include*)>
  
  <!ELEMENT xsp:dtd (#PCDATA)>
  <!ELEMENT xsp:include (#PCDATA)>
  
  <!ELEMENT xsp:content (#PCDATA | xsp:logic | %elements;)*>
  
  <!ELEMENT xsp:logic (#PCDATA | xsp:content | %element;)*>
  <!ATTLIST xsp:logic xml:space (default|preserve) "preserve">
  
  <!ELEMENT xsp:element
            (#PCDATA | 
            xsp:attribute | 
            xsp:element | 
            xsp:logic)*>
  <!ATTLIST xsp:element
            name CDATA #REQUIRED>
  
  <!ELEMENT xsp:attribute (#PCDATA)>
  <!ATTLIST xsp:attribute 
            name CDATA #REQUIRED
            xml:space (default|preserve) "preserve">
  
  <!ELEMENT xsp:pi (#PCDATA | xsp:expr>
  <!ELEMENT xsp:comment (#PCDATA | xsp:expr)>
  <!ELEMENT xsp:expr (#PCDATA)>  
  
  ]]></source>
    
  </s2>
  </s1>
  
  <s1 title="Example of Usage">
    <p>Consider the following XML source document:</p>
  
    <source><![CDATA[
      <?xml version="1.0"?>
  
      <page>
        <title>A Simple XSP Page</title>
        <p>Hi, I've been hit <counter/> times.</p>
      </page>  
    ]]></source>
  
    <p>This simple example shows the power of content/logic/style separation. While the <code>&lt;title&gt;</code>
    tag has a very special meaning in the <em>page</em> document type, indicating the page
    title, the <code>&lt;counter&gt;</code> element is needs to be dynamically substituted by
    the number of times the document has been requested. The logic that performs such behavior
    is included in tag itself, but unlike other existing server side technologies, the
    behavior is not defined in the page itself, but on the logic sheet that is applied to
    evaluate this behavior. In fact, the same page may have a totally different behavior
    depending on the logicsheet that is applied to the page. Note that it's beyond the scope
    of this specification to define a way to associate transformation sheets to pages. The
    associated logicsheet that uses the Java language as logic definition may look like:</p>
    
  <source><![CDATA[
  <?xml version="1.0"?>
  <xsl:transform
   xmlns:xsl="http://www.w3.org/1999/XSL/Tranform" 
   xmlns:xsp="http://www.apache.org/1999/XSP/Core"
  >
     
   <xsl:template match="page">
    <xsp:page language="java">
  
     <xsp:structure>
      <xsp:include>java.lang.*</xsp:include>
     </xsp:structure>
       
     <xsp:logic>
      private static int counter = 0;
           
      private synchronized int currentCount() {
        return ++counter;
      }
     </xsp:logic>
        
     <xsp:content>
      <page>
       <xsl:apply-templates/>
      </page>
     </xsp:content>
    </xsp:page>
   </xsl:template>
      
   <xsl:template match="counter">    
    <xsp:expr>currentCount()</xsp:expr>
   </xsl:template>
  
   <!-- Transcribe everything else verbatim -->
   <xsl:template match="*|@*|comment()|pi()|text()">
    <xsl:copy>
     <xsl:apply-templates/>
    </xsl:copy>
   </xsl:template>
  </xsl:transform>
  ]]></source>
      
    <p>After applying the above logic sheet, the resulting document would be equivalent to the
    following:</p>
    
  <source><![CDATA[
  <xsp:page 
   result-ns="http://www.dummy.org/SimpleHomepageDTD"
   language="java">
  
   <xsp:structure>
    <xsp:include>java.lang.*</xsp:include>
   </xsp:structure>
  
   <xsp:logic>
    private static int counter = 0;
          
    private synchronized int currentCount() {
      return ++counter;
    }
   </xsp:logic>
  
   <xsp:content>
    <page>
     <title>A Sample XSP Page</title>
     <p>
      Hi, I've been hit 
       <xsp:expr>currentCount()</xsp:expr>
      times.
     </p>
    </page>
   </xsp:content>
  </xsp:page>     
  ]]></source>
    
    <p>At this point it's worth to note that from an XSP point of view, there is 
       no difference in how the XSP page was created, either directly written or 
       created with n levels of transformation. So, independently of whether an 
       XSL stylesheet or a special algorithm was used to generate the final 
       source code, it may look like this [<em>Note</em>: many key issues regarding 
       servlets were omitted for simplicity and this example must not be 
       considered mandating as a way to format XSP into servlet source code]</p>
    
  <source><![CDATA[
  // package automatically created from the full request URL...
  package org.apache.cocoon.xsp.example;
  
  // packages imported automatically by source code generator
  import java.io.*;
  import java.util.*;
  import javax.servlet.*;
  import javax.servlet.http.*;
  import org.w3c.dom.*;
    
  // packages imported due to XSP structure
  import java.lang.*;
  
  // class name automatically created from the 
  // request URI file name...
  public class Counter extends HttpServlet {
  
    public void init(ServletConfig config) 
      throws ServletException
    {
      super.init(config);
    }
  
    private static int counter = 0;
              
    private synchronized int currentCount() {
      return ++counter;
    }
   
    public void service(HttpServletRequest request, 
         HttpServletResponse response) throws IOException 
    {
      Document document = parser.createEmptyDocument();
      Element root = document.createElement("page");
      document.appendChild(root);
    
      Element element_1 = document.createElement("title");
      root.appendChild(element_1);
      Text textNode_1 = document.createTextNode("A Sample XSP Page");
      element_1.appendChild(textNode_1);
  
      Element element_2 = document.createElement("p");
      root.appendChild(element_2);
      Text textNode_2 = document.createTextNode("Hi, I've been hit ");
      element_2.appendChild(textNode_2);
      StringBuffer buffer_1 = new StringBuffer.append(currentCount());
      Text textNode_3 = document.createTextNode(string_1.toString());
      element_2.appendChild(textNode_3);
      Text textNode_4 = document.createTextNode("times.");
      element_2.appendChild(textNode_4);
    
      // Produce generated DOM tree on output as an XML stream
      ((Child) document).toXMLString(response.getWriter());
    }
  }  
  ]]></source>  
   
    <p>Note that in this example the XML document is being generated as a <em>stream</em>
    but a DOM tree is used to create it. The DOM tree can't be passed directly to
    the servlet engine for further processing because the current servlet specification
    (2.2) does not allow for content generation in a format other than a stream. A rather undesirable consequence
    of this is that the resulting XML document would need to be re-parsed in case a final XSL
    stylesheet or other post-transformation must be applied.</p>
    
    <p>To solve this problem and speed up the execution on server side XML
    processing, the XSP can be compiled into something like this:</p>
  
  <source><![CDATA[
  // package automatically created from the full request URL...
  package org.apache.cocoon.xsp.example;
  
  // packages imported automatically by source code generator
  import java.io.*;
  import java.util.*;
  import org.xml.sax.*;
  import org.apache.cocoon.*;
    
  // packages imported due to XSP structure
  import java.lang.*;
  
  // class name automatically created from the 
  // request URI file name...
  public class Counter extends AbstractProducer {
  
    private static final char[] chars_0 = 
     {'A',' ','S','i','m','p','l','e',' ','X','S','P',' ','P','a','g','e'};
    private static final char[] chars_1 = 
     {'H','i',' ','I','\'','v','e',' ','b','e','e','n',' ','h','i','t',' '};
    private static final char[] chars_3 = 
     {' ','t','i','m','e','s'};
  
    private static int counter = 0;
              
    private synchronized int currentCount() {
      return ++counter;
    }
   
    public void toSAX(Request request, DocumentHandler handler) 
      throws SAXException 
    {
      handler.startDocument();
        handler.startElement("page", null);
          handler.startElement("title", null);
            handler.characters(chars_0, 0, 17);
          handler.endElement("title");
          handler.startElement("p", null);
            handler.characters(chars_1, 0, 17);
            String string_0 = (new StringBuffer.append(
              currentCount()
            )).toString();
            int string_0_length = string_0.length();
            char[] chars_2 = char[string_0_length];
            string_0.getChars(0, string_0_length, chars_2, 0);
            handler.characters(chars_3, 0, 6);
          handler.endElement("p");
        handler.endElement("page");
      handler.endDocument();
    }
  }  
  ]]></source>
  
    <p>The above shows one of the best features of XSP: output independence.
    Since the output objects are not accessible directly from the internal page
    logic (unlike other similar technologies, such as JSP), the page compiler can
    choose between a great variety of possible ways to generate and forward the
    page content. In fact, while the first example uses DOM as a construction set
    and a stream as output method, the exact same page is compiled in the second
    example to use a SAX event-based model and a document handler as output.</p>
    
    <p>Finally, It is beyond the scope of this specification to define how XSP are translated
    into binary code and how these interact with the publishing frameworks that handle
    them, but it is mandated that this should be completely transparent to the
    page programmer and an XSP page should behave exactly the same (modulo
    performance) in every XSP engine.</p>
  </s1>
  
  <s1 title="XSP and JSP">
    <p>XSP and JSP might appear as overlapping at a first glance since they both:</p>
    
    <ul>
      <li>follow the <em>compiled server pages</em> model, allowing server pages to
        be compiled into binary code for faster execution.</li>
      <li>can be parsed and validated by regular XML parsers</li>
      <li>can be transformed by XSLT processors</li>
      <li>aim to programming language abstraction</li>
    </ul>
    
    <p>While these are very important points were the two specifications <em>do</em>
    overlap, there are significant differences described hereafter.</p>
  
  <s2 title="Output Exposure">
    <p>In all different server pages technologies, some data regarding the status
    of the resource are available to page logic. Since JSP follow the Servlet API
    model, expecting JSP pages to be compiled into servlets, the same data
    available to servlet is available to page logic. This allows the page logic to
    obtain access to the output channel (being either an OutputStream or a Writer
    for servlets).</p>
    
    <p>While this is not a problem for normal web operation when no further server
    side processing is performed, for XML generation (where further server side
    processing may be needed, depending on client capabilities) the Servlet/JSP
    limitations impose on the server pages engine a parsing stage that is
    completely avoided in XSP.</p>
    
    <p>In fact, in XSP, page logic has <em>not</em> direct access to the output
    channel and it's the page compiler responsibility to choose the preferred
    method to compile the page, depending on processing needs and server
    requirements.</p>
    <p>It should be noted how XSP spec provides three different contexts: <code>content</code>,
    <code>logic</code> and <code>eval</code>. These three contexts never overlap
    since <code>content</code> is used to create static markup content, <code>logic</code>
    to indicate programming logic and <code>eval</code> to bridge the two domains,
    allowing a logic component to be evaluated without exposing the output channel
    to the logic context.</p>
    <p>This is a very significant difference since it allows XSP page compiler to <em>hardcode</em>
    pre-parsed XML content thus removing the request time parsing overhead that
    JSP always require.</p>
  </s2>
  
  <s2 title="Page Readability">
    <p>For these reasons, XSP, unlike JSP, uses the XML feature of <em>syntax
    orthogonalily</em> that allows almost any programming language code to be
    easily distinguishable between markup elements, while JSP needs to enclose
    programming code by <code>scriptlet</code> tags. The following is an example to show
    the different results based on the same logic and code.</p>
    
  <source><![CDATA[
  <xsp:logic>
   e = request.getParameterNames(); 
   if ((e != null) &amp;&amp; (e.hasMoreElements())) {
    <xsl:content>
     <list>
      <title>Servlet Parameters</title>
      <xsp:logic>
       while (e.hasMoreElements()) { 
        String k = (String) e.nextElement();
        String val = request.getParameter(k); 
        String vals[] = request.getParameterValues(k);
        <xsp:element name="element">
         <xsp:attribute name="name">
          <xsp:expr>k</xsp:expr>
         </xsp:attribute>
         <xsp:logic>
          for(int i = 0; i &lt; vals.length; i++) {
           <item>
            <xsp:expr>vals[i]</xsp:expr>
           </item>
          }
         </xsp:logic>
        </xsp:element>
       }
      </xsp:logic>
     </list>
    </xsl:content>
   } 
  </xsp:logic>  
  ]]></source>
  
    <p>This is the JSP equivalent:</p>
    
  <source><![CDATA[
  <jsp:scriplet>
   e = request.getParameterNames(); 
   if ((e != null) &amp;&amp; (e.hasMoreElements())) {
  </jsp:scriplet>
    <list>
     <title>Servlet Parameters</title>
     <jsp:scriplet>
       while (e.hasMoreElements()) { 
        String k = (String) e.nextElement();
        String val = request.getParameter(k); 
        String vals[] = request.getParameterValues(k);
        out.println("&lt;element name=\"name\"&gt;");
     </jsp:scriplet>
        <jsp:expression>k</jsp:expression>
        <jsp:scriplet>
         out.println("&lt;/element&gt;");
         for(int i = 0; i &lt; vals.length; i++) {
        </jsp:scriplet>
          <item>
           <jsp:expression>vals[i]</jsp:expression>
          </item>
        <jsp:scriplet>}</jsp:scriplet>
      <jsp:scriplet>}</jsp:scriplet>
    </list>
  <jsp:scriplet>}</jsp:scriplet>  
  ]]></source>
  
    <p>It must be noted the use of the <code>out</code> object in the JSP example while
    XSP provide specific tags to avoid that.</p>
  </s2>
  </s1>
  </body>
  
  <appendices>
  
  <s1 title="Normative References">
  <bl>
    <bi name="DOM" 
        href="http://www.w3.org/TR/REC-DOM-Level-1" 
        title="Document Object Model (DOM) Level 1 Specification"
        authors="Lauren Wood et al."
        date="1 October 1998"/>
        
    <bi name="RFC2119" 
        href="http://www.ietf.org/rfc/rfc2119.txt"
        title="Key words for use in RFCs to Indicate Requirement Levels"
        authors="S. Bradner"
        date="March 1997"/>
        
    <bi name="RFC2376" 
        href="http://www.ietf.org/rfc/rfc2376.txt"
        title="XML Media Types"
        authors="E. Whitehead, M. Murata"
        date="July 1998"/>
        
    <bi name="RFC2396"
        href="http://www.ietf.org/rfc/rfc2396.txt"
        title="Uniform Resource Identifiers (URI): Generic Syntax"
        authors="T. Berners-Lee, R. Fielding, L. Masinter"
        date="August 1998"/>
        
    <bi name="XML" 
        href="http://www.w3.org/TR/REC-xml"
        title="Extensible Markup Language (XML) 1.0 Specification"
        authors="T. Bray, J. Paoli, C. M. Sperberg-McQueen"
        date="10 February 1998"/>
        
    <bi name="XMLNAMES"
        href="http://www.w3.org/TR/REC-xml-names"
        title="Namespaces in XML"
        authors="T. Bray, D. Hollander, A. Layman"
        date="14 January 1999"/>
        
    <bi name="XSLT"
        href="http://www.w3.org/TR/xslt"
        title="XSL Transformations (XSLT) Specification Version 1.0"
        authors="J. Clark"
        date="16 November 1999"/>
        
    <bi name="SAX"
        href="http://www.megginson.com/SAX/"
        title="The Simple API for XML (Java implementation) version 1.0"
        authors="D.Megginson"/>
  </bl>
  </s1>
  </appendices>
  </specification>
  
  
  
  
  1.1                  xml-cocoon/xdocs/cocoon2.xml
  
  Index: cocoon2.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <!DOCTYPE document SYSTEM "./dtd/document-v10.dtd">
  
  <document>
   <header>
    <title>Cocoon 2</title>
    <authors>
     <person name="Stefano Mazzocchi" email="stefano@apache.org"/>
    </authors>
   </header>
  
   <body>
   <s1 title="Introduction">
    <p>The Cocoon Project has gone a long way since it's creation on
    January 1999. It started as a simple servlet for static XSL styling and became
    more and more powerful as new features were added. Unfortunately, design
    decisions made early in the project influenced its evolution. Today, some of
    those constraints that shaped the project were modified as XML standards have evolved and
    solidified. For this reason, those design decisions need to be reconsidered
    under this new light.</p>
  
    <p>While Cocoon started as a small step in the direction of a new
    web publishing idea based on better design patterns and reviewed estimations
    of management issues, the technology used was not mature enough for tools to
    emerge. Today, most web engineers consider XML as the key for an improved web
    model and web site managers see XML as a way to reduce costs and ease
    production.</p>
    
    <p>In an era where services rather than software will be key for
    economical success, a better and less expensive model for web publishing will
    be a winner, especially if based on open standards.</p>
   </s1>
  
   <s1 title="Passive APIs vs. Active APIs">
    <p>Web serving environments must be fast and scalable to be
    useful. Cocoon1 was born as a &quot;proof of concept&quot; rather than a
    production software and had significant design restrictions based mainly on
    the availability of freely redistributable tools. Other issues were lack of
    detailed knowledge on the APIs available as well as underestimation of the
    project success, being created as a way to learn XSL rather than a full
    publishing system capable of taking care of all XML web publishing needs.</p>
    
    <p>For the above reasons, Cocoon1 was based on the DOM level 1
    API which is a <em>passive</em> API and was intended mainly for client side
    operation. This is mainly due to the fact that most (if not all!) DOM
    implementations require the document to reside in memory. While this is
    practical for small documents and thus good for the &quot;proof of
    concept&quot; stage, it is now considered a main design constraint for Cocoon
    scalability.</p>
    
    <p>Since the goal of Cocoon2 is the ability to process
    simultaneously multiple 100Mb documents in JVM with a few Mbs of heap size,
    careful memory use and tuning of internal components is a key issue. To reach
    this goal, an improved API model was needed. This is now identified in the SAX
    API which is, unlike DOM, event based (so <em>active</em>, in the sense that its
    design is based the <em>inversion of control</em> principle).</p>
    
    <p>The event model allows document producers to trigger producing
    events that get handled in the various processing stages and get finally
    formatted in the response stream. This has significant impacts on performance
    and memory needs:</p>
    
    <dl>
      <dt>incremental operation</dt>
      <dd>
        the response is created
        during document production. Client's perceived performance is dramatically
        improved since clients can start receiving data as soon as it is created,
        not after all processing stages have been performed. In those cases where
        incremental operation is not possible (for example, element sorting),
        internal buffers store the events until the operation can be performed.
        However, even in these cases performance can be increased with the use of
        tuned memory structures.
      </dd>
      <dt>lowered memory consumption</dt>
      <dd>
        since most of the
        server processing required in Cocoon is incremental, an incremental model
        allows XML production events to be transformed directly into output events
        and character written on streams, thus avoiding the need to store them in
        memory.
      </dd>
      <dt>easier scalability</dt>
      <dd>
        reduce memory needs allow more
        concurrent operation to be possible, thus allowing the publishing system
        to scale as the load increases.
      </dd>
      <dt>more optimizable code model</dt>
      <dd>
        modern virtual
        machines are based on the idea of <em>hot spots</em>, code fragments that
        are used often and, if optimized, increase the process execution by far.
        This new event model allows easier detection of hot spots since it's a
        method driven operation, rather than a memory driven one. Hot methods can
        be identified earlier and their optimization performed better.
      </dd>
      <dt>reduced garbage collection</dt>
      <dd> 
        even the most advanced
        and lightweight DOM implementation require at least three to five times
        (and sometimes much more than this) more memory than original document
        size. This does not only reduce the scalability of the operation, but also
        impact overall performance by increasing the number of memory garbage that
        must be collected after the response in sent to the client. Even if modern
        virtual machines reduced the overhead of garbage collection, less garbage
        will always have performance and scalability impacts.
      </dd>
    </dl>
    
    <p>The above points, alone, would be enough for the Cocoon2
    paradigm shift, even if this event based model impacts not only the general
    architecture of the publishing system but also its internal processing
    components such as XSLT processing and PDF formatting. These components will
    require substantial work and maybe design reconsideration to be able to follow
    a pure event-based model. The Cocoon Project will work closely with the other
    component projects to be able to influence their operation in this direction.</p>
  </s1>
  
  <s1 title="Reactors Reconsidered">
    <p>Another design choice that should be revised is the reactor
    pattern that was introduced to allow components to be connected in more
    flexible way. In fact, opposed to the fixed pipe model used up to Cocoon
    1.3.1, the reactor approach allows components to be dynamically connected,
    depending on reaction instructions introduced inside the documents.</p>
    
    <p>While this at first seemed a very advanced and highly
    appealing model, it turned out to be a very dangerous approach. The first
    concern is mainly technical: porting the reactor pattern under an event-based
    model requires limitations and tradeoffs since the generated events must be
    cached until a reaction instruction is encountered.</p>
    
    <p>But even if the technical difficulties are solved, a key limitation
    remains: there is no single point of management.</p>
  </s1>
  
  <s1 title="Management Considerations">
    <p>The web was created to reduce information management costs by
    distributing them back on information owners. While this model is great for
    user communities (scientists, students, employees, or people in general) each
    of them managing small amount of personal information, it becomes impractical
    for highly centralized information systems where distributed management is
    simply not practical.</p>
    
    <p>While in the HTML web model the page format and URL names
    where the only necessary contracts between individuals to create a world wide
    web, in more structured information systems the number of contracts increases
    by a significant factor due to the need of increased coherence between the
    hosted information: common style, common design issues, common languages,
    server side logic integration, data validation, etc...</p>
    
    <p>It is only under this light that XML and its web model reveal
    their power: the HTML web model had too little contracts to be able to develop
    a structured and more coherent distributed information system, reason that is
    mainly imposed by the lack of good and algorithmically certain information
    indexing and knowledge seeking. Lacks that tend to degrade the quality of the
    truly distributed web in favor of more structured web sites (that based their
    improved site structure on internal contracts).</p>
    
    <p>The simplification and engineering of web site management is
    considered one of the most important Cocoon2 goals. This is done mainly by
    technologically imposing a reduced number of contracts and place them in a hierarchical
    shape suitable to replace current high-structure web site management
    models.</p>
    
    <p>The model that Cocoon2 adopts is the &quot;pyramid model of
    web contracts&quot; which is outlined in the picture below</p>
    
    <figure src="images/pyramid-model.gif" alt="The Cocoon2 Pyramid Model of Contracts"/>
    
    <p>and is composed by four different working contexts (the rectangles)</p>
    
    <dl>
      <dt>Management</dt>
      <dd>
        the people that decide what the site should
        contain, how it should behave and how it should appear
      </dd>
      <dt>Content</dt>
      <dd>
        the people responsible to write, own and manage
        the site content. This context may contain several sub-contexts one
        for each language used to express page content.
      </dd>
      <dt>Logic</dt>
      <dd>
        the people responsible for integration with dynamic
        content generation technologies and database systems.
      </dd>
      <dt>Style</dt>
      <dd>
        the people responsible for information
        presentation, look &amp; feel, site graphics and its maintenance.
      </dd>
    </dl>
    
    <p>and five contracts contexts (the lines)</p>
    
    <ul>
      <li>management - content</li>
      <li>management - logic</li>
      <li>management - style</li>
      <li>content - logic</li>
      <li>content - style</li>
    </ul>
  </s1>
  
  <s1 title="Overlapping contexts and Chain Mapping">
    <p>The above model can be applied only if the different contexts
    never overlap, otherwise there is no chance of having a single management
    point. For example, if the W3C-recommended method to link stylesheets to XML
    documents is used, the content and style contexts overlap and it's impossible
    to change the styling behavior of the document without changing it. The same
    is true for the processing instructions used by the Cocoon1 reactor to drive
    the page processing: each stage concur to determine the result thus increasing
    management and debug complexity. Another overlapping in context contracts is
    the need for URL-encoded parameters to drive the page output. These overlaps
    break the pyramid model and increase the management costs.</p>
    
    <p>In Cocoon2, the reactor pattern will be abandoned in favor of
    a chain mapping technique. This is based on the fact that the number of
    different contracts is limited even for big sites (for example, even if the
    pages are millions, they probably all share no more than a few different DTDs
    and each DTD has no more than a couple of stylesheets).</p>
    
    <p>Also, for performance reasons, Cocoon2 will try to compile
    everything that is possibly compilable (pages/XSP into producers, stylesheets
    into processors, etc...) so, in this new model, the <em>processing chain</em>
    that generates the page contains (in a direct executable form) all the
    information/logic that handles the requested resource to generate its
    response.</p>
    
    <p>This means that instead of using even-driven request-time DTD
    interpretation (done in all Cocoon1 processors), these will be either compiled
    into processors directly (XSLT stylesheet compilation) or compiled into
    producers using logicsheets and XSP which will remove totally the need for
    request-time interpretation solutions like DCP that will be removed.</p>
  </s1>
  
  <s1 title="Pre-compilation, Pre-generation and Caching">
    <p>The cache system in Cocoon1 will be ported with no important
    design changes since it's very flexible and was not polluted by early design
    constraints since it appeared in later versions. The issue regards static file
    caching that, no matter what, will always be slower than direct web server
    caching.</p>
    
    <p>To be able to put most of the static part job back on the web
    server (where it belongs), Cocoon2 will greatly improve it's command line
    operation, allowing the creation of <em>site makefiles</em> that will
    automatically scan the web site and the source documents and will provide a
    way to <em>regenerate</em> the static part of a web site (images and tables
    included!) based on the same XML model used in the dynamic operation version.</p>
    
    <p>It will be up to the web server administrator to use static
    regeneration capabilities on a time basis, manually or triggered by some
    particular event (database update signal) since Cocoon2 will only provide
    servlet and command line capabilities. The nice integration is based on the
    fact that there will be no behavioral difference if the files are dynamically
    generated in Cocoon2 via the servlet operation and cached internally or
    pre-generated and served directly by the web server, as long as URI contracts
    are kept the same by the system administrator (via URL-rewriting or aliasing)</p>
    
    <p>Also, it will be possible to avoid on-fly page and stylesheet
    compilation (which make debugging harder) with command line pre-compilation
    hooks that will work like normal compilers from a developer's point of view.</p>
  </s1>
  
  <s1 title="Conclusions">
    <p>Cocoon2 is a big and very ambitious project, not only for the
    technological issues involved (which will require strong integration with XML
    components) but also for the significant paradigm shifts imposed by the new
    technologies. On the other hand, we strongly believe this to be the winner
    model for future web engineering and if you believe in this yourself, we
    invite you to join us or help us in any way you can provide.</p>
  </s1>
  </body>
  </document>
  
  
  
  1.1                  xml-cocoon/xdocs/dcpprocessor.xml
  
  Index: dcpprocessor.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <!DOCTYPE document SYSTEM "./dtd/document-v10.dtd">
  
  <document>
   <header>
   <title>DCP Processor</title>
   <version>12141999</version>
   <authors>
    <person name="Ricardo Rocha" email="ricardo@apache.org"/>
   </authors>
   </header>
   
   <body>
   <s1 title="Introduction">
    <p>
     In addition to static content (that is, hand-written documents produced
     by web authors), web publishing also requires <em>dynamic content
     generation</em>.  In dynamic content generation, XML documents or
     fragments are programmatically produced at request time.
    </p>
  
    <p>
     In this context, content is the result of a computation based on request
     parameters and, frequently, on access to external data sources such as
     databases or remote server processes. This distinction in content origin
     justifies the extension of the &quot;traditional&quot; regions of web
     publishing (content and presentation) to also encompass that of
     <em>logic</em>.
    </p>
   </s1>
    
    <s1 title="Origins">
     <p>
      The Cocoon community has long recognized the need for dynamic content
      generation capabilities. In response to this requirement, the Cocoon
      project has proposed
      <link href="http://xml.apache.org/cocoon/xsp.html">XSP</link>
      (<em>eXtensible Server Pages</em>). XSP defines a new XML DTD and
      namespace that addresses a complete region of web publishing, that of
      logic-based, dynamic content generation. XSP is a key component of future
      Cocoon versions and currently in development.
     </p>
  
     <p>
      DCP (<em>Dynamic Content Processor</em>), on the other hand, aims at
      providing easy-to-use dynamic content generation capabilities in the
      context of the current version of Cocoon. DCP is also a testbed for
      implementation-related issues in the upcoming development of XSP.
      These issues include aspects such as multiple language support,
      automatic code reloading and code reuse.
     </p>
    </s1>
   
    <s1 title="Goals">
     <p>
      DCP has been designed to provide dynamic content generation capabilities
      to Cocoon with the following goals in mind:
     </p>
   
     <ul> 
      <li>
       Minimal changes to the current architecture.
      </li>
      <li>
       Maximal ease of use for authors and developers.
      </li>
      <li>
       Avoiding XSP implementation complexities while still providing a useful
       facility for dynamic content generation.
      </li>
     </ul> 
   
     <p>
      In order to maximize ease of use, the following early decisions were made
      for DCP:
     </p>
   
     <ul> 
      <li>
       Other than the source XML document itself, no external documents should
       be required to map inline dynamic content generation directives to
       external programs.
      </li>
      <li>
       External programs should be as easy to write as possible. In addition to
       Java, it should be possible to also write external programs in
       easy-to-use scripting languages.
      </li>
     </ul> 
   
     <p>
      By restricting the use of external documents (such as XSP libraries)
      to specify how to map content generation directives to external programs,
      the obvious choice was the use of processing instructions (e.g.
      <em>&lt;?dcp-object?&gt;</em>, <em>&lt;?dcp-content?&gt;</em>).
     </p>
   
     <p>
      This decision results in a number of limitations when compared to the more
      general mechanism of transforming DOM <em>elements</em> (as opposed to
      processing instructions).
     </p>
   
     <p>
      One such limitation is that passing [static] parameters to external
      programs is limited to the single-valued pseudo-attributes used in
      processing instructions.  Closer inspection reveals, however, that
      this mechanism is appropriate for a large number of dynamic content
      generation requirements.
     </p>
   
     <p>
      Keeping external program writing simple means not requiring programmers
      to learn a new API or to follow restrictive coding conventions. The
      ability to write programs in easy-to-use scripting languages also
      contributes to simplifying development. This is particularly appealing,
      for instance, to web authors already familiar with Javascript, which
      is currently supported.
     </p>
   
     <p>
      Jean-Marc Lugrin's
      (<link href="http://home.worldcom.ch/jmlugrin/fesi/index.html">Fesi</link>)
      (<em>Free EcmaScript Interpreter</em>) is used to provide support for
      Javascript.
     </p>
    </s1>
  
    <s1 title="Relationship with Existing Technologies">
     <p>
      DCP (and XSP, for that matter) differs from existing dynamic web content
      generation technologies in that it deals with DOM trees rather than with
      the textual representation of HTML documents.
     </p>
   
     <p>
      Such technologies, however, have had a strong influence in DCP's design
      both because they pioneered programmatic web content generation and
      because DCP (and, again, XSP) aims at overcoming their limitations in
      the realm of XML-based document processing.
     </p>
   
     <p>
      <link href="http://www.javasoft.com/products/jsp/index.html">JSP</link>,
      in particular, is a widely used standard in the Java environment. Other
      comparable technologies are Microsoft's
      <link href="http://www.microsoft.com/ntserver/web/deployment/planguide/WebAppDev.asp">
       ASP
      </link>,
      <link href="http://www.coldfusion.com/">
       Cold Fusion
      </link>,
      Sun's [deprecated]
      <link href="http://www.sun.com/software/jwebserver/features/index.html#dsp">
       Page Compilation
      </link>,
      <link href="http://www.webmacro.org/">
       Webmacro
      </link>
      and
      <link href="http://www.bitmechanic.com/projects/gsp">
       GSP
      </link>.
     </p>
   
     <p>
      These technologies share three common characteristics:
     </p>
   
     <ul> 
      <li>
       <strong>Text-based</strong>.
       Not being XML-aware, these technologies deal with textual streams,
       rather than with DOM trees or SAX events.
      </li>
      <li>
       <strong>Html-oriented</strong>.
       Generation capabilities have been designed with HTML in mind and
       do not lend themselves easily to produce XML.
      </li>
      <li>
       <strong>No separation of logic and content</strong>.
       Probably their most problematic area; these technologies mix content and
       program logic in the same document. This impairs labor division in web
       publishing.
      </li>
     </ul> 
   
     <p>
      DCP and XSP, on the other hand, aim at a complete separation of logic
      and content.
     </p>
   
     <p>
      In DCP, web authors specify dynamic content insertion using a simple,
      standard XML syntax while programmers concentrate on content generation
      without being concerned by context or presentation issues.
     </p>
   
     <p>
      Finally, the difference between DCP and XSP is that while DCP is
      interpreted and executed at runtime, XSP page are compiled and executed
      directly as document producers. This allows better separation of content
      and logic (since the XSP pages can be processed like regular document at
      first) and increased performance (since no interpretation is required and
      compiled pages are cached).
     </p>
    </s1>
   
    <s1 title="A Simple Javascript Example">
     <p>
        Consider the following dynamic Cocoon XML document
        (<link href="http://www.plenix.com/dcp/ecmascript/sample-page.xml?country=Canada&amp;language=English&amp;language=French">sample.xml</link>):
     </p>
  
     <figure src="images/dcp-fig-1.gif" alt="Ecmascript Example" height="303" width="526"/>
  
     <p>
       In this example, portions shown in red are to be dynamically generated
       every time the document is requested.
     </p>
  
     <p>
       For this to be achieved, three separate components must be written:
     </p>
  
     <ul> 
      <li>
        A <em>source XML file</em> containing the static portions of the document
        and some dynamic content insertion directives.
      </li>
      <li>
        A <em>DCP script</em> containing DOM node-generation functions. This
        script can be used by many different XML documents.
      </li>
      <li>
        An <em>XSL stylesheet</em> containing transformation rules to generate
        HTML from the (expanded) XML document. Again, this stylesheet can be
        used by many different XML documents.
      </li>
    </ul> 
  
    <p>
      The following processing instructions are recognized:
    </p>
  
    <ul> 
     <li>
      <code>
        &lt;?dcp-object name="objectName" [language="languageName"] code="codeLocation"?&gt;
      </code>
      <br/><br/>
  
       This instruction declares an external program (or DCP script) that
       contains node-generation methods. These methods will be invoked during
       document processing as dictated by the appearance of subsequent
       <code>&lt;?dcp-content?&gt;</code> directives (explained below). 
      <br/><br/>
      
       <ul>
        <li>
         Attribute <em>name</em> specifies an author-defined objectName that will
         be used to qualify method names in the DCP script. This name must be
         unique within the document. 
        </li>
      
        <li>
         Attribute <em>language</em> specifies the programming language in which
         the DCP script is written. Currently supported values for this attribute
         are <em>java</em> and <em>javascript</em> (also referred to as
         <em>ecmascript</em>). This attribute is optional; its default value
         is <em>java</em>. Other languages may be added in the future.
         It is valid for the same XML document to use multiple DCP scripts
         written in different languages. 
        </li>
      
        <li>
         Attribute <em>code</em> specifies the actual DCP script location.
         Interpretation of this mandatory attribute is language-dependent.
         For Java, it is a fully qualified class name. For Javascript, it is
         a script filename relative to the path of the invoking XML document.
         The same code can be specified multiple times in a given document,
         provided a different <em>objectName</em> is used in each case. 
        </li>
       </ul>
     </li>
  
     <li>
       <code>
         &lt;?dcp-content method="object.method" [param1="value" param2="value" ...] ?&gt;
       </code>
      <br/><br/>
  
       This instruction requests the substitution of its corresponding node by
       the return value of a named method defined in a DCP script. 
      <br/><br/>
      
       Single-valued, named parameters can be passed to node-generation methods
       by specifying additional attributes in the
       <code>&lt;?dcp-content?&gt;</code>
       processing instruction. These attributes are made available to the
       method through a <code>Dictionary</code> argument. 
      <br/><br/>
      
       Attribute <em>method</em> defines what method to invoke on a given
       object. The object <em>name</em> must have been associated with a DCP
       script by means of a previous <code>&lt;?dcp-object?&gt;</code>
       processing instruction.  Node-generation methods must be
       <code>public</code> and conform to the following signature: 
      <br/><br/>
  
      <code>
       methodName(
            [java.util.Dictionary parameters],
            [org.w3c.Node source]
        )
      </code>
      <br/><br/>
  
       where the [optional] function arguments are: 
      <br/><br/>
      
      <ul> 
       <li>
        <code>parameters</code>.
        A dictionary containing any optional named parameters specified as
        additional attributes to the <code>&lt;?dcp-content?&gt;</code>
        processing instruction. 
       </li>
       <li>
        <code>source</code>.
        The processing instruction node corresponding to the
        <code>&lt;?dcp-content?&gt;</code> directive itself. This is useful
        for methods that need access to siblings or ancestors in the DOM tree. 
       </li>
      </ul> 
      <br/><br/>
  
       Methods can return any type of value, including primitive types,
       <code>void</code> and <code>null</code>. <code>Void</code> and
       <code>null</code> are understood as a request to remove the
       corresponding node. Returned values that are instances of
       <code>org.w3c.Node</code> are simply inserted into the corresponding
       DOM tree position. Primitive types and regular objects are wrapped
       as strings in <code>org.w3c.Text</code> nodes. Arrays are wrapped
       as <code>org.w3c.DocumentFragment</code>'s containing as many children
       as elements in the array; each element is recursively wrapped according
       to the above rules. 
     </li>
  
     <li>
      <code>
       &lt;?dcp-var name1="value1" [name2="value2" ...]?&gt;
      </code>
      <br/><br/>
  
       This instruction declares one or more global variables that will be
       passed in each subsequent method invocation as if explicitly specified
       as parameters. 
      <br/><br/>
        
       This mechanism is basically a convenience shorthand to avoid cluttering
       <code>&lt;?dcp-content?&gt;</code> instructions with too long parameter
       lists. 
      <br/><br/>
        
       Declared variables are global to all subsequent method invocations.
       For a method to use a given global variable as a parameter, it must
       have been previously declared in the same document. 
      <br/><br/>
     </li>
    </ul> 
  
    <p>
     That said, the source XML document for the above example would be: 
    </p>
  
    <figure src="images/dcp-fig-2.gif" alt="Ecmascript Example Source" height="416" width="573"/>
  
     <p>
      In this document: 
     </p>
  
     <ul> 
      <li>
         The processing instruction:
         <br/><br/>
         <code>
          &lt;?dcp-object name="util" language="javascript" code="test.es"?&gt;
         </code>
         <br/><br/>
         declares the existence of an external Javascript program contained in
         a file called <em>test.es</em>.
         <br/><br/>
  
         Subsequent references to file <em>test.es</em> will use the alias
         <em>util</em>.
      </li>
  
      <li>
        The processing instruction:
        <br/><br/>
        <code>
         &lt;?dcp-content method="util.getSystemDate" format="MM/dd/yyyy"?&gt;
        </code>
        <br/><br/>
        specifies that function <em>getSystemDate</em> (contained in file
        <em>test.es</em>) must be called and its return value substituted in
        the document position where the <code>&lt;?dcp-content?&gt;</code>
        directive originally appeared. 
        <br/><br/>
  
        Furthermore, when this function is called, it is passed a parameter
        of name <em>format</em> and value <em>MM/dd/yyyy</em>.
      </li>
     </ul> 
  
     <p>
      The initial portion of the script file <em>test.es</em> contains: 
     </p>
  
     <source>
      var count = 0;
    
      /* Node Generation Functions */
      function getCount() {
        /* To reference variables as static, prepend "global." */
        return formatCount(++global.count);
      }
  
      function getSystemDate(parameters) {
       var now = new Date();
       var format = parameters.get("format");
    
       if (format != null) {
        return formatDate(now, format);
       }
    
       return now;
      }
     </source>
  
     <p>
      DCP automatically reloads Javascript script files whenever they change on
      disk. 
     </p>
  
     <p>
      When a global variable must be treated as static, references to it must be
      qualified by the <em>global</em> modifier. This is convenient when the
      programmer wants the variable to retain its value across requests. 
     </p>
  
     <p>
      For functions returning simple object values, DCP takes care of wrapping
      the returned value as an <code>org.w3c.dom.Text</code> node containing
      the <code>toString()</code> form of the object. When a function returns
      <code>null</code>, the corresponding node is removed from the DOM tree. 
     </p>
  
     <p>
      Of course, returned values can be instances of a DOM <code>Node</code>
      type. This is illustrated by the function <code>getParameters</code>
      below: 
     </p>
  
     <source>
      function getParameters() {
       var parameterNames = request.getParameterNames();
    
       if (!parameterNames.hasMoreElements()) {
        return null;
       }
    
       var parameterList = createElement("parameters");
    
       while (parameterNames.hasMoreElements()) {
        var parameterName = parameterNames.nextElement();
    
        var parameterElement = createElement("parameter");
        parameterElement.setAttribute("name", parameterName);
    
        var parameterValues = request.getParameterValues(parameterName);
    
        for (var i = 0; i &lt; parameterValues.length; i++) {
         var valueElement = createElement("parameter-value");
         valueElement.appendChild(createTextNode(parameterValues[i]));
         parameterElement.appendChild(valueElement);
        }
    
        parameterList.appendChild(parameterElement);
       }
    
       return parameterList;
      }
     </source>
  
     <p>
      Thus, if our example processes the request: 
     </p>
  
     <source>
      sample.xml?me=Tarzan&amp;you=Jane&amp;you=Cheetah 
     </source>
  
     <p>
      the above function would generate a DOM subtree equivalent to the
      following XML fragment: 
     </p>
  
     <source>
      &lt;parameters&gt;
    
        &lt;parameter name="me"&gt;
          &lt;parameter-value&gt;Tarzan&lt;/parameter-value&gt;
        &lt;/parameter&gt;
    
        &lt;parameter name="you"&gt;
          &lt;parameter-value&gt;Jane&lt;/parameter-value&gt;
          &lt;parameter-value&gt;Cheetah&lt;/parameter-value&gt;
        &lt;/parameter&gt;
    
      &lt;/parameters&gt;  
     </source>
  
     <p>
      The general signature for a dynamic content generation Javascript function
      is: 
     </p>
  
     <source>
      function functionName(parameters, source) 
     </source>
  
     <p>
      where: 
     </p>
  
     <ul> 
      <li>
       <code>parameters</code> is an instance of
       <code>java.util.Dictionary</code> containing user-supplied parameters
       specified as <code>&lt;?dcp-content?&gt;</code> pseudo-attributes.
       Example: parameter <code>format</code> in function
       <code>getSystemDate</code>.
      </li>
      <li>
       <code>source</code> is an instance of
       <code>org.w3c.dom.ProcessingInstruction</code>
       corresponding to the actual <code>&lt;?dcp-content?&gt;</code>
       processing instruction.  This node is useful for performing
       context-dependent processing such as examining sibling or parent
       DOM nodes. 
      </li>
     </ul> 
  
     <p>
      Note: Programmers may omit any or all of these arguments if they are
      not actually needed by the task at hand. 
     </p>
  
     <p>
      The following objects are always made available to external Javascript
      programs as global variables: 
     </p>
  
     <ul> 
      <li>
       <code>javax.servlet.http.HttpServletRequest request</code>
      </li>
      <li>
       <code>org.w3c.dom.Document document</code>
      </li>
     </ul> 
  
     <p>
      The following convenience functions are made accessible by DCP to external
      Javascript programs: 
     </p>
  
     <ul> 
      <li>
        DOM factory functions are provided by DCP for easy construction of DOM
        nodes: <code>createTextNode(data)</code>,
        <code>createElement(tagName)</code>, etc. 
  
         In general, all DOM factory methods defined for interface
         <code>org.w3c.dom.Document</code> are available as global
         Javascript functions. 
      </li>
  
      <li>
        Formatting functions for numbers and dates: 
        <ul> 
         <li>
          <code>function formatCount(number)</code>,
         </li>
         <li>
          <code>function formatCurrency(number)</code>,
         </li>
         <li>
          <code>function formatPercentage(number)</code> and 
         </li>
         <li>
          <code>function formatDate(date, format)</code>. Date format
          strings conform to the syntax defined by class
          <code>java.text.DateFormat</code>.
         </li>
        </ul> 
      </li>
  
      <li>
       A JDBC access function function
  
        <code>sqlRowSet(connectionName, selectStatement)</code>,
  
         that returns an array of Javascript objects whose member names are
         given by the lowercase form of each <em>SELECT</em> column label.
         The array contains as many elements as rows are returned by the
         <em>SELECT</em> statement. 
  
        Parameters to this function are: 
  
       <ul> 
        <li>
         <code>connectionName</code>.
         A connection pool name as specified by Gefion Software's
         <link href="http://www.webdevelopersjournal.com/columns/connection_pool.html">
          <code>DBConnectionManager</code>
         </link>
         in the resource file
         <code>db.properties</code> (see below).
        </li>
  
        <li>
         <code>selectStatement</code>.
         A SQL <em>SELECT</em> statement for the database manager in use. 
        </li>
       </ul> 
      </li>
     </ul>
  
     <p>
      Using the Oracle demo connection in file <em>db.properties</em>
     </p>
     
     <source>
    logfile=/tmp/dbcm.log
    drivers=postgresql.Driver oracle.jdbc.driver.OracleDriver
  
    dictionary.url= jdbc:postgresql:translator
    dictionary.maxconn=8
    dictionary.user=clark
    dictionary.password=kent
  
    demo.url=jdbc:oracle:thin:@localhost:1521:orcl
    demo.maxconn=4
    demo.user=scott
    demo.password=tiger
    </source>
     
     <p>
      a sample Javascript user function would look like: 
     </p>
  
     <source>
      var selectStatement =
       "SELECT   EMPNO, " +
       "         ENAME, " +
       "         SAL + NVL(COMM, 0) AS INCOME " +
       "FROM     EMP " +
       "ORDER BY EMPNO";
  
      var emps = sqlRowSet("demo", selectStatement);
  
      for (var i = 0; i &lt; emps.length; i++) {
       addEmp(emps[i].empno, emps[i].ename, emps[i].income)
      }
     </source>
  
     <p>
      Finally, it is possible, in general, to: 
     </p>
  
     <ul> 
      <li>
       Declare multiple external programs in the same XML document. 
       <br/><br/>
  
       <code>
         &lt;?dcp-object name="emp" language="javascript" code="emp.es"?&gt;
       </code>
       <br/>
       <code>
         &lt;?dcp-object name="dept" language="javascript" code="dept.es"?&gt;
       </code>
       <br/>
      </li>
      <li>
       Declare the same external program multiple times in the same XML
       document, provided different names are used for each declaration. 
       <br/><br/>
  
       <code>
        &lt;?dcp-object name="emp" language="ecmascript" code="emp.es"?&gt;
       </code>
       <br/>
       <code>
        &lt;?dcp-object name="boss" language="ecmascript" code="emp.es"?&gt;
       </code>
       <br/>
      </li>
      <li>
       Mix external programs written in different languages in the same XML
       document. 
       <br/><br/>
  
       <code>
        &lt;?dcp-object name="emp" language="ecmascript" code="emp.es"?&gt;
       </code>
       <br/>
       <code>
        &lt;?dcp-object name="dept" language="java" code="payroll.Department"?&gt;
       </code>
       <br/>
      </li>
     </ul> 
    </s1>
  
  
    <s1 title="Java DCP Programming">
     <p>
      For the Java language, the attribute <code>code</code> in the declaration 
     </p>
  
     <source>
      &lt;?dcp-object name="util" language="java" code="payroll.Employee"?&gt;
     </source>
  
     <p>
      is interpreted as a class name. Such class must be accessible through
      the servlet engine's classpath setting. 
     </p>
  
     <p>
      Node-generation methods in Java conform to the following signature: 
     </p>
  
     <source>
      public methodName(
       [java.util.Dictionary parameters],
       [org.w3c.dom.Node source]
      )
     </source>
  
     <p>
      Like in Javascript, these arguments are optional. The return type can be
      of any Java type including <code>void</code>.
     </p>
  
     <p>
       Java classes used as DCP objects need not implement/extend any particular
       interface or class. In the Cocoon environment, however, it is strongly
       recommended to extend class: 
     </p>
  
     <source>
      org.apache.cocoon.processor.dcp.java.ServletDCPProcessor. 
     </source>
  
     <p>
       This class provides the following convenience services: 
     </p>
  
     <ul>
      <li>
       Direct access to the servlet <em>request</em> object 
      </li>
      <li>
       Direct access to the document being processed 
      </li>
      <li>
        Factory methods to create all types of DOM nodes (elements, text nodes,
        document fragments, processing instructions, etc) 
      </li>
     </ul>
  
     <p>
      If developers choose not to extend this convenience class, the following
      requeriments must be honored: 
     </p>
  
     <ul>
      <li>
       The class must have an empty constructor 
      </li>
      <li>
       The class must have at least one method that conforms to the above
       signature. 
      </li>
     </ul>
  
     <p>
      In absence of a non-empty constructor, if the class does require
      initialization it can implement: 
     </p>
  
     <source>
      org.cocoon.framework.Configurable. 
     </source>
  
     <p>
      In this case, the DCP processor will invoke the class' init method
      immediately after instantiation. The configuration values passed in
      this case are: 
     </p>
  
     <ul>
      <li>
       The document being processed 
      </li>
      <li>
       The parameters passed to the processor by the invoking environment 
      </li>
     </ul>
  
     <p>
      For the Cocoon environment, parameters contain: 
     </p>
  
     <ul>
      <li>
       The <code>javax.servlet.http.HttpServletRequest request</code> object
       corresponding to the current web server's request. 
      </li>
      <li>
       The <code>java.lang.String path</code> associated with the current source
       XML document. 
      </li>
      <li>
       The <code>java.lang.String browser</code> associated with the current
       request's <em>User-Agent</em> HTTP header. 
      </li>
     </ul>
  
     <p>
      Based on the above, for our tutorial example, the corresponding Java
      class would be: 
     </p>
  
     <source>
      import java.util.*;
      import java.text.*;
      import org.w3c.dom.*;
      import javax.servlet.http.*;
      import org.apache.cocoon.processor.dcp.java.ServletDCPProcessor;
      
      public class Util extends ServletDCPProcessor {
        private static int count = 0;
      
        public synchronized int getCount() {
          return ++count;
        } 
      
        public String getSystemDate(Dictionary parameters) {
          Date now = new Date();
          String formattedDate = now.toString();
          String format = (String) parameters.get("format");
      
          if (format != null) {
            try {
              SimpleDateFormat dateFormat = new SimpleDateFormat(format);
              formattedDate = dateFormat.format(now);
            } catch (Exception e) { } // Bad format, ignore and return default
          }
      
          return formattedDate;
        }
      
        public Element getRequestParameters() {
          Enumeration e = this.request.getParameterNames();
      
          if (!e.hasMoreElements()) { // No parameters given, remove node from document 
            return null;
          }
      
          Element parameterList = createElement("parameters");
      
          int count;
          Element parameterValue;
          Element parameterElement;
          for (count = 0; e.hasMoreElements(); count++) {
            String name = (String) e.nextElement();
            String[] values = this.request.getParameterValues(name);
      
            parameterElement = createElement("parameter");
            parameterElement.setAttribute("name", name);
      
            for (int i = 0; i &lt; values.length; i++) {
              parameterValue = createElement("parameter-value");
              parameterValue.appendChild(createTextNode(values[i]));
      
              parameterElement.appendChild(parameterValue);
            }
      
            parameterList.appendChild(parameterElement);
          }
      
          return parameterList;
        }
      }
     </source>
    </s1>
  
    <s1 title="Known Problems">
     <ul>
      <li>
       <strong>Restricted Static Parameter Passing</strong>.
       Due to the use of processing instructions as a means of inserting
       dynamic content in XML documents (as opposed to DOM elements),
       structured parameter passing can become too complex. 
       <br/><br/>
  
       Consider the case when an employee list must be dynamically generated.
       Using elements to pass parameters to node-generation methods would allow
       for complex forms.
       <br/><br/>
  
       <!--
       <source>
        &lt;employee-listing&gt;
          &lt;database-connection&gt;
            &lt;jdbc-driver&gt;oracle.jdbc.driver.OracleDriver&lt;/jdbc-driver&gt;
            &lt;connect-url&gt;jdbc:oracle:thin:@localhost:1521:orcl&lt;/connect-url&gt;
            &lt;user-name&gt; &lt;request-parameter name="user"/&gt; &lt;/user-name&gt;
            &lt;password&gt; &lt;request-parameter name="password"/&gt; &lt;/password&gt;
          &lt;/database-connection&gt;
          &lt;selection-criteria&gt;
            &lt;department-list&gt;
              &lt;deptno&gt;10&lt;/deptno&gt;
              &lt;deptno&gt;30&lt;/deptno&gt;
            &lt;/department-list&gt;
          &lt;/selection-criteria&gt;
        &lt;/employee-listing&gt;
       </source>
           
       An equivalent &lt;?dcp-content?&gt; parameter list, while possible, would
       be too long and, certainly, hard to read. 
       -->
  
       Other nested, multivalued parameter forms simply cannot be expressed by
       means of single-valued processing instruction pseudo-attributes. 
       <br/><br/>
  
       A workaround for this is the traditional HTML idiom of using hidden
       fields in HTTP forms to pass static parameters. 
       <br/><br/>
  
       Important to note, XSP uses elements (instead of processing instructions)
       to specify dynamic content substitution. 
      </li>
  
      <li>
       <strong>Javascript Performance</strong>.
       While the current Javascript DCP performance is acceptable for small
       and medium-sized applications with light traffic, its response time is
       perceivably slower than that of Java. 
       <br/><br/>
  
       This is a natural consequence of Javascript being interpreted by Java
       (itself interpreted by the underlying VM). As such, this restriction
       may also apply to other scripting languages such as WebL. 
       <br/><br/>
  
       An alternative would be the use of Netscape's
       <link href="http://www.mozilla.org/rhino/">Rhino</link>
       (which supports compilation to class files),
       but this may create incompatibilities with existing programs
       that depend on FESI features.
       <br/><br/>
  
       In the meantime, some Fesi-based workarounds are in place, most
       notably evaluator pooling, a technique based on dynamically cloning
       script evaluators when multiple, concurrent requests use the same
       Javascript external program. 
      </li>
  
      <li>
       <strong>No Java Class Reloading</strong>.
       While Javascript files are automatically reloaded when they change on
       disk, currently there is no provision for automatic Java class reloading.
       <br/><br/>
  
       Implementing this feature requires a specialized class loader. Note that
       servlet engine-provided class reloading does not apply to DCP because
       external Java programs are not servlets but, rather, regular classes
       dynamically instantiated by the DCP driver instead of by the underlying
       servlet engine. 
       <br/><br/>
  
       The latter is also true if the user-supplied class extends DCP's
       convenience class
       <code>org.apache.cocoon.processor.dcp.java.ServletDCPProcessor</code>.
      </li>
     </ul>
    </s1>
  
    <s1 title="Additional Examples">
     <p>
      In addition to the examples presented in this document, there is a more
      complex application written entirely in Cocoon using Java DCP: the
      <link href="http://www.plenix.com/translator/">
        Cocoon Multilingual Dictionary
      </link>.
     </p>
  
     <p>
      This application lets users lookup terms and their translations in a
      number of European languages using Esperanto as the intermediate language.
      The entire example (source code and data, ~750K) can be downloaded from
      the above location. 
     </p>
    </s1>
  
    <s1 title="Future Directions">
      <p>
        DCP will be deprecated in favor of
        <link href="http://xml.apache.org/cocoon/xsp.html">XSP</link>.
        Therefore, development is currently limited to bug fixes.
      </p>
    </s1>
  
    <s1 title="Acknowledgments">
     <p>
      The following people have contributed to the definition of DCP:
     </p>
  
     <ul>
      <li>
       Assaf Arkin, &lt;arkin@trendline.co.il&gt; 
      </li>
      <li>
       Brett Knights, &lt;bknights@uniserve.com&gt; 
      </li>
      <li>
       Donald Ball, &lt;balld@apache.org&gt; 
      </li>
      <li>
       Keith Visco, &lt;kvisco@ziplink.net&gt; 
      </li>
      <li>
       Stefano Mazzocchi, &lt;stefano@apache.org&gt; 
      </li>
     </ul>
    </s1>
  
  </body>
  </document>
  
  
  
  1.1                  xml-cocoon/xdocs/docs-book.xml
  
  Index: docs-book.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <book software="Cocoon" title="Cocoon documentation" copyright="@@year@@ The Apache Software Foundation">
  
    <page id="index" label="Index" source="index.xml"/>
    <page id="license" label="License" source="license.xml"/>
    <page id="install" label="Install" source="installing.xml"/>
  <separator/>
    <page id="technologies" label="Technologies" source="technologies.xml"/>
    <page id="guide" label="User Guide" source="guide.xml"/>
    <page id="dynamic" label="Dynamic Content" source="dynamic.xml"/>
  <separator/>
    <page id="xsp" label="XSP Processor" source="xspprocessor.xml"/>
    <page id="dcp" label="DCP Processor" source="dcpprocessor.xml"/>
    <page id="sql" label="SQL Processor" source="sqlprocessor.xml"/>
    <page id="ldap" label="LDAP Processor" source="ldapprocessor.xml"/>
  <separator/>
    <spec id="wd-xsp" label="XSP WD" source="WD-xsp.xml"/>
  <separator/>
    <external href="./api/index.html"  label="Javadocs"/>
  <separator/>
    <page id="cocoon2" label="Cocoon 2" source="cocoon2.xml"/>
    <page id="javadoc" label="Javadoc XML" source="javadoc.xml"/>
  <separator/>
    <faqs id="faqs" label="FAQ" source="faq.xml"/>
    <changes id="changes" label="Changes" source="changes.xml"/>
    <todo id="todo" label="Todo" source="todo.xml"/>
   
  </book>
  
  
  
  1.1                  xml-cocoon/xdocs/dynamic.xml
  
  Index: dynamic.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <!DOCTYPE document SYSTEM "./dtd/document-v10.dtd">
  
  <document>
   <header>
    <title>Dynamic XML in Cocoon</title>
    <authors>
     <person name="Stefano Mazzocchi" email="stefano@apache.org"/>
    </authors>
   </header>
   <body>
   
  <s1 title="Introduction">
    <p>Web publishing is very limited without the ability to create
    dynamic content. For dynamic XML we refer to the content that is created as a
    function of request parameters or state of the requested resource. For this
    reason, a lot of work and design has been put into Cocoon to allow dynamic XML
    content to be generated.</p>
  </s1>
  
  <s1 title="The Servlet/JSP model">
    <p>People are used to write small Java programs to create their
    dynamic web content. Servlets, and Java in general, are very powerful, easy to
    write and fast to debug, but they impose (like any other pure-logic solution)
    a significant management cost. This is due to the fact that programmable
    components like servlets must include both the logic to generate the dynamic
    code as well as all static elements (such as static content and style).The
    need for a more useful solution soon appeared.</p>
    
    <p>To fill the gap between Java programmers and web engineers (groups
    that rarely overlap), Sun proposed the Java Server Pages (JSP) specification,
    a markup language (today with both SGML and XML syntax) that allows web
    engineers to include code in their pages, rather than include pages in their
    code. The impact of this strategy was significant: servlets were written
    directly in Java code if very little static content was to be used, otherwise
    JSP or other compiled server pages technologies were used.</p>
    
    <p>This said, it would seem that using servlets/JPS to create
    dynamic XML content would be the perfect choice, unfortunately design issues
    impose that we take a second look to the technology and understand why this
    isn't so.</p>
  </s1>
  
  <s1 title="Servlet Chaining Vs. Servlet Nesting">
    <p>Java Servlets were introduced by the Java Web Server team as a
    way to allow users to create their own <em>web plug-ins</em>. They were designed
    to handle the HTTP protocol and all possible dynamic web content (including
    HTML, XML, images, etc. both text and binary streams). Unfortunately, the need
    for a componentized request handler was not taken into serious consideration
    in the design phase but only later, when at an implementation phase.</p>
    
    <p>In fact, the Java Web Server provided the ability to <em>chain</em>
    multiple servlets, one becoming the filter of the other. Unfortunately, since
    the API don't include such possibility in their design, such servlet chain is
    very limited in its behavior and poses significant restriction on the API use.
    Something that forced the Servlet API architects to come up with better
    solutions.</p>
    
    <p>The solution was <em>servlet nesting</em>: the ability to
    include a servlet output inside its own transparently. This allowed
    programmers to separate different logic on different servlets, thus removing
    the need for servlet chaining</p>
  </s1>
  
  <s1 title="The limitations of Servlet Nesting">
    <p>While servlet nesting was a major advantage over servlet
    chaining because it allowed servlets to be somewhat modular without loosing
    the full API power, a common design pattern applies to the Servlet model in
    general: no servlet is allowed to modify the output of another servlet. This
    holds true for all servlet API versions up to today (version 2.2).</p>
    
    <p>This limitation is the key: if no further XML processing is
    needed on the server side, using servlets/JSP for creating XML is a perfect
    choice, but if this output requires some server side processing (for example
    XSLT transformations), the Servlet API does not allow another servlet to post
    process it's output. This other servlet is, in our case, Cocoon.</p>
    
    <p>In a few words, the Servlet API doesn't support <em>Servlet
    Piping</em>.</p>
  </s1>
  
  <s1 title="The Cocoon model">
    <p>Rather than turning Cocoon into a servlet engine, thus
    limiting its portability, this documents outlines some solutions that allow
    Cocoon users to get the servlet-equivalent functionality with internal Cocoon
    design ideas.</p>
    
    <p>The Cocoon processing model is based on the separation of</p>
    
    <dl>
      <dt>Production</dt>
      <dd>where XML content is generated based on Request parameters (servlet equivalent)</dd>
      <dt>Processing</dt>
      <dd>where the produced XML content is transformed/evaluated</dd>
      <dt>Formatting</dt>
      <dd>where the XML content is finally formatted into the wanted output format for client use.</dd>
    </dl>
    
    <p>This separation of working contexts allows Cocoon users to
    implement their own internal modules to add the functionality they require to
    the whole publishing system. In fact, while a few of these components are
    already shipped with Cocoon, the highly modular structure allows you to build
    your own to fit your particular needs.</p>
  </s1>
  
  <s1 title="Writing Producers">
    <p>Producers initiate the request handling phase. They are
    responsible to evaluate the HttpServletRequest parameters provided and create
    XML content that is fed into the processing reactor. A servlet logic should be
    translated into a producer if the request parameters can be used directly to
    generate the XML content (for example the FileProducer which loads the
    requested file from disk).</p>
    
    <p>Here follows the code for an example producer distributed with
    Cocoon:</p>
    
  <source><![CDATA[
  public class DummyProducer 
    extends AbstractProducer 
    implements Status 
  {
            
    String dummy = "<?xml version=\"1.0\"?>" 
        + "<?cocoon:format type=\"text/html\"?>"
        + "<html><body>"
        + "<h1 align=\"center\">"
            + "Hello from a dummy page"
        + "</h1>"
        + "</body></html>";
        
    public Reader getStream(HttpServletRequest request) 
      throws IOException 
    {
      return new StringReader(dummy);
    }
  
    public String getPath(HttpServletRequest request) {
      return "";
    }
    
    public String getStatus() {
      return "Dummy Producer";
    }
  }
  ]]></source>
  
    <p>The key method is <code>getStream()</code> which is responsible to create
    process the given servlet request and provide an output stream for reading the
    generated XML document.</p>
    
    <p>Note that Produce has also another method, <code>getDocument(request)</code>,
    which is responsible to return directly a DOM tree. In case you need to render
    you servlet code Cocoon-aware, the above example should tell you what to do.</p>
    
    <p>Please, look at the shipped producers source code for example
    code and look at the <connect href="guide.xml">user guide</connect> on how to install and
    use your own producers.</p>
  </s1>
  
  <s1 title="Writing Processors">
    <p>If your servlet needs many parameters to work, it is more
    reasonable that you write a Processor instead. A Processor transforms a given
    XML document (which, in this case should contain the needed static parameters)
    into something else, driven both by the input document and by the request
    object which is also available.</p>
    
    <p>Here is a simple processor example that should show you what
    the above means. Suppose you have the following document as input (note that
    it may have been produced from a file, from other sources or dynamically, see
    the above paragraph):</p>
    
  <source><![CDATA[
  <?xml version="1.0"?>
  <page>
   <p>Current time is <time/></p>
  </page>
  ]]></source>
    
    <p>Our simple example processor will look for the %lg;time/%gt; tags and will 
    expand them to the current local time, creating this result document:</p>
    
  <source><![CDATA[
  <?xml version="1.0"?>
  <page>
   <p>Current time is 6:48PM</p>
  </page>
  ]]></source>
              
    <p>Please, look at the shipped processors source code for example
    code and look at the <connect href="guide.xml">user guide</connect> on how to install and
    use your own processors.</p>
  </s1>
  
  <s1 title="Using Cocoon processors">
    <p>The above example shows a very simple situation but needs
    non-trivial code to implement it. For this reason, the Cocoon distribution
    includes a number of processors that implement common needs and situations.
    These are:</p>
    
    <dl>
      <dt>The XSLT processor</dt>
      <dd>
        the <em>XSLT</em> processor that applies XSLT
        transformations to the input document. XSLT allows you to solve your
        transformation needs as well as simple tag evaluation/processing due to
        its extensible and programmable nature.
      </dd>
      <dt>The XSP processor</dt>
      <dd>
        the <em>XSP</em> processor that evaluates XSP pages and compiles them into
        producers. This processor allows you include programmatic logic into 
        your pages as well as to separate the logic from the content. See the
        <connect href="xsp-primer.xml">XSP user guide</connect> for more information.
      </dd>
      <dt>The DCP processor</dt>
      <dd>
        the <em>DCP</em> processor that evaluates XML processing
        instructions with multi-language (Java and EcmaScript) logic. This
        processor allows you to do programmatic substitution and inclusion
        eliminating the need for complex processing logic. See the <connect href="dcpprocessor.xml">DCP
        user guide</connect> for more information.
      </dd>
      <dt>The SQL processor</dt>
      <dd>
        the <em>SQL</em> processor that evaluates simple tags
        describing SQL queries to JDBC drivers and formats their result-set in XML
        depending on given parameters. See the <connect href="sqlprocessor.xml">SQL
        processor user guide</connect> for more information.
      </dd>
      <dt>The LDAP processor</dt>
      <dd>
        the <em>LDAP</em> processor that evaluates simple tags
        describing LDAP queries to directory services and formats their result-set in XML
        depending on given parameters. See the <connect href="ldapprocessor.xml">LDAP
        processor user guide</connect> for more information.
      </dd>
    </dl>
  </s1>
  </body></document>
  
  
  1.1                  xml-cocoon/xdocs/faq.xml
  
  Index: faq.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <!DOCTYPE faqs SYSTEM "./dtd/faq-v10.dtd">
  
  <faqs title="Frequently Asked Questions">
  
  <faq>
   <question>Previous Cocoon releases said that this product was to consider a 
   proof of concept rather than a working solution. I can't find that sentence
   anymore. What happened?</question>
   <answer>
    <p>We believe that Cocoon has entered the final stage of its evolution but
    as it stands today, it is ready to be used for a production environment.</p>
    <p>Careful, we don't say it's perfect or bug-free, this is impossible to say,
    but at least, we think this technology is good enough for you to try it out
    against other solutions for web publishing.</p>
    <p>Warning: this doesn't mean that Cocoon evolution came to an end, not at all,
    but that we believe it's mature enough to be deployed in a working environment
    with no particular problems.</p>
    <p>Note, however, that this software comes "as is" so you should always be
    aware of the risks as for any other open source software, but I think that
    if you read this, you already know what we mean :)</p>
   </answer>
  </faq>
  
  <faq>
   <question>How come Apache is not redirecting requests to Cocoon?</question>
   <answer>
   <p>There is a bug in mod_jserv that makes it dependent on its configuration
   position. If you use <em>ApJServHandler</em> you should change this to more
   standard <em>Action and AddHandler</em>. If you installed an old version
   of Cocoon, read again the installation instructions to find a solutions for
   this problem. (thanks to Dan Egnor for finding and solving the problem).</p>
   </answer>
  </faq>
  
  <faq>
   <question>How do I pipe my servlet output into Cocoon?</question>
   <answer>
    <p>Simple answer: <em>you don't!!!</em> read <connect href="dynamic.xml">the page
    about dynamic content</connect> to find out equivalent ways to do what you need.</p>
    <p>Complex answer: the Servlet API <em>was not</em> designed with servlet
    chaining capabilities in mind. Servlet chaining was a night hack of the
    original Java web server authors that allowed to pipe one servlet output
    into the request of another. Currently (version 2.2) the Servlet API spec
    doesn't allow a servlet to post-process the output of another servlet, so,
    since Cocoon is a servlet, there is no portable way for it to call
    your servlet and to process its output.</p>
    <p>The Cocoon Project is in close contact with the Servlet API Expert Group at
    Sun (being Stefano Mazzocchi a member of that board) and will propose 
    post-processing hooks for inclusion in the next Servlet API specifications. 
    Since this is work in progress, please, don't fill up the mail list with 
    questions about this: Cocoon will reflect the API changes as soon as they 
    are publicly available.</p>
   </answer>
  </faq>
  
  <faq>
   <question>Where do I get more information on XSL and XML?</question>
   <answer>
    <p>
      The web community is very exited about XML and XSL and many sources of
      information are coming up even if these languages are fairly new. Here is a list of
      locations you might be interested in to continue to gather resources on this
      state-of-the-art technology</p>
    <ul>
      <li><link href="http://www.xml.org">http://www.xml.org</link> - A very nice site for XML
        information.</li>
      <li><link href="http://www.w3.org/xml/">http://www.w3.org/xml/</link> - The XML
        official home page at W3C</li>
      <li><link href="http://www.w3.org/style/xsl">http://www.w3.org/style/xsl</link> - The XSL official
        home page W3C</li>
      <li><link href="http://www.software.ibm.com/xml/education/tutorial-prog/abstract.html">http://www.software.ibm.com/xml/education/tutorial-prog/abstract.html</link>
        - XML Tutorial from IBM</li>
      <li><link href="http://www.webtechniques.com/features/1999/01/walsh/walsh.shtml">http://www.webtechniques.com/features/1999/01/walsh/walsh.shtml</link>
        - XSL Tutorial</li>
      <li><link href="http://www.oasis-open.org/cover/xml.html">http://www.oasis-open.org/cover/xml.html</link>
        - XML Resource Listing</li>
      <li><link href="http://www.oasis-open.org/cover/xsl.html">http://www.oasis-open.org/cover/xsl.html</link>
        - XSL Resource Listing</li>
      <li><link href="http://www.xmlsoftware.com">http://www.xmlsoftware.com</link> -
        XML software listing</li>
      <li><link href="http://www.xmlinfo.com">http://www.xmlinfo.com</link> - XML
        information updates on W3C status and others</li>
      <li><link href="http://www.xslinfo.com">http://www.xslinfo.com</link> - XSL
        information, updates, example stylesheets</li>
      <li><link href="http://www.schema.net">http://www.schema.net</link> - Repository
        of standard DTDs</li>
    </ul>
  </answer>
  </faq>
  
  <faq>
   <question>Are there document translations to other languages?</question>
   <answer>
    <p>Given the problems we already have with documentation (which is never big and good enough), 
    the Cocoon Project uses English as its standard and only documentation language. This is also
    the only language used in the mail lists. Also, the Cocoon distribution will contain
    English documentation only to reduce updating problems.</p>
    <p>On the other hand, we welcome any effort that provides document translations and
    we will keep here links to those translated documents.</p>
    <ul>
     <li><link href="http://www.epita.net">French Translation</link></li>
    </ul>
    <note>The Cocoon Project is not directly involved in these translating efforts
    and we are not resposible for any lack of synch between the official Cocoon
    documentation and the translated version. For this reason, do not contact
    the Cocoon Project but directly the people that provide the translation. Thank you.</note>
   </answer>
  </faq>
  
  <faq>
   <question>Why do I keep getting FileNotFoundException under Tomcat 3.0?</question>
   <answer><p>See question below</p></answer>
  </faq>
  
  <faq>
   <question>How come Cocoon doesn't work on Tomcat 3.0?</question>
   <answer>
    <p>You must apply this patch to Tomcat 3.0 and recompile it or it won't work.
    This patch is already present in latest CVS code but in case you don't want
    to download the latest code you can apply this:</p>
    
    <source><![CDATA[ Index: RequestMapper.java
     ===================================================================
     RCS file: /home/cvs/jakarta-tomcat/src/share/org/apache/tomcat/core/RequestMapper.java,v
   
     retrieving revision 1.5
     retrieving revision 1.6
     diff -u -r1.5 -r1.6
     --- RequestMapper.java 1999/11/05 18:36:33  1.5
     +++ RequestMapper.java 1999/12/17 18:59:14  1.6
     @@ -285,13 +285,7 @@
                  mapPath = "/" + s;
              } else if (mapPath == null &&
                  this.resourceName != null) {
     -            // XXX
     -            // hack to differentiate amongst a mapped servlet and a jsp
     -      if (! wrapper.getServletClass().equals(Constants.JSP.CLASSNAME)) {
     -                mapPath = "/" + wrapper.getServletClass();
     -            } else {
     -                mapPath = this.resourceName;
     -            }
     +            mapPath = this.resourceName;
              }
   
              return mapPath;]]></source>
   </answer>
  </faq>
  
  <faq>
   <question>Are external entities still broken?</question>
   <answer>
    <p>No, external entity support has been fixed for both absolute and relative
    URIs. Note that ProjectX and Xerces behave differently on these but this
    is not something we are in control of.</p>
   </answer>
  </faq>
  
  <faq>
   <question>I see that Cocon 1.x has starting to incorporate features planned for 
   Cocoon 2.x, why?</question>
   <answer>
    <p>We believe that smooth project evolution is much better than step-wise
    revolutionary paths. For this reason, we'll try hard to incorporate all the
    Cocoon2 features in the main project thus limiting the porting effort for you
    over time.</p>
    <p>Note that this doesn't mean that Cocoon won't change in the future and we
    state clearly that we do care about back compatibility but only when this is
    not limiting the evolution of he platform too much.</p>
    <p>For this reason, while the DOM->SAX evolution might be totally painless, the
    sitemap proposal will completely change the Cocoon configurations. Anyway, Cocoon
    has a long way to go and if it changes during its evolution to a final state,
    don't complain: you have been warned.</p>
    <p>However, we DO consider and value the time you invested in Cocoon so we'll
    do our best to make sure that unneeded back incompatibilities don't get included.</p>
   </answer>
  </faq>
  
  <faq>
   <question>The XSL book I read says the correct way of indicating the XSL stylesheet is by
      using the XML processing instruction <code>&lt;?xml:stylesheet?&gt;</code> while Cocoon is
      using <code>&lt;?xml-stylesheet?&gt;</code>. Who is right?
   </question>
   <answer>
    <p>The PI <code>&lt;?xml:stylesheet type=&quot;text/xsl&quot; href=&quot;&quot;?&gt;</code>
    is the old method of associating a stylesheet with an XML document. Unfortunately, this
    technology is rapidly changing and your books should warn you that the topic they are
    discussing is not even in W3C Recommendation state. Which means that more changes are on
    their way.</p>
    <p>The current and proper way to associate a stylesheet with an XML document can be found at 
    <link href="http://www.w3.org/TR/xml-stylesheet">http://www.w3.org/TR/xml-stylesheet</link> and
    clearly indicates that <code>&lt;?xml-stylesheet ...?&gt;</code> is the proper way.</p>
   </answer>
  </faq>
  
  <faq>
   <question>
      I think that using Processing Instructions to &quot;chain&quot;
      document layers somehow violates the context separation since I would like
      to be able to place style sensible information in sessions or request
      parameters. What do you think about this?
   </question>
   <answer>
    <p>You are right, PI reaction breaks the context separation and it's, at the
      very end, the wrong approach. To follow a complete &quot;model, view,
      controller&quot; design pattern, one should be able to associate a different
      processing chain for each requested URI and for every possible request state
      (with request parameters, session parameters and environment parameters).</p>
    <p>The proposed solution (as you read in the <connect href="cocoon2.xml">Cocoon2
      outline</connect>) is to have a site map where site
      managers decide what processing chain to apply to each possible request.
      This somehow follows the mod_rewrite model in the Apache Web Server, but
      rather than URL rewriting, the site map allows site designers to control the
      behavior of their documents in one place without having to modify every
      single reactive PI in each source file.</p>
    <p>So, you've been warned: the PIs will go away, current functionality will
      remain but the processing management will be abstracted one layer up.</p>
  </answer>
  </faq>
  
  <faq>
  <question>What is WAP and how do I browse WML?</question>
  <answer>
    <p>WAP stands for Wireless Application Protocol and WML stands for Wireless
      Markup Language. For more information about these two, please refer to the 
      <link href="http://www.wapforum.org">WAP Forum</link>. For a client able 
      to browse WML 1.1, Cocoon has been tested with the 
      <link href="http://www.nokia.com">Nokia WAP Toolkit</link> which
      emulates a Nokia WAP cell phone on your desktop.</p>
  </answer>
  </faq>
  
  <faq>
  <question>What is VoxML and how do I browse VML?</question>
  <answer>
    <p>VoxML is a voice markup language, designed to allow direct integration 
      between voice recognition/synthesis software and web technologies. 
      The Cocoon VML samples have been tested with the 
      <link href="http://www.voxml.org">Motorola VoxML SDK 1.1</link>(for windows)
      which is freely available.</p>
  </answer>
  </faq>
  
  <faq>
  <question>Why is my Internet Explorer not showing PDF or VRML samples?</question>
  <answer>
    <p>This is a long-time problem with internet explorer which, illegally, 
    reacts on URI extention rathen than returned MIME type. The only think you can
    do for now is to map .pdf or .wrl to Cocoon for handling, but we know that
    sucks. Don't worry, in the future, the sitemap proposal will allow you
    to work around this magically. For now, just don't use IE :)</p>
  </answer>
  </faq>
  
  <faq>
  <question>When I compile Cocoon on my system, I get all a bunch of errors. What's wrong?</question>
  <answer>
    <p>You probably didn't add all the needed packages to your compiler's classpath.
      Note that Cocoon supports much more packages than you normally use and you should have
      them all to compile the full source code (this is why the cocoon.jar is distributed). To
      avoid this, simply remove (or rename) the classes that wrap around the packages you don't
      use.</p>
    <p>Note that if you tried to compile Cocoon.java alone, many classes are not compiled
    because there is no hardcoded reference to them. Cocoon uses dynamic loading based on its
    property file to get the modules it needs when started. For this reason, the compiler is
    not able to tell which class will be use and its dependency checks are never complete. The
    only way to compile it is to manually indicate all the files to compile or to use the
    makefiles after removing the unwanted wrapper classes for the packages you don't have or
    you don't want.</p>
    <p>Note that Cocoon is built using Ant: please, refer to the build.xml file
    for more information on how to set up your system to compile Cocoon</p>
  </answer>
  </faq>
  
  <faq>
   <question>Why the name &quot;Cocoon&quot;?</question>
   <answer>
    <p> (Cocoon's creator Stefano Mazzocchi answers): It's a pretty stupid reason and a funny
    story: I spent my 1998 Xmas vacation with my girlfriend up on the Alps at her cottage. One
    night I couldn't sleep, I went to watch some TV and finishing reading the XSL
    documentation I brought with me. Being a science fiction <em>afficionado</em>, I found out
    that Ron Howard's movie <em>Cocoon</em> was on and I started watching it. The idea of the XSL
    rendering servlet stoke me like the alien &quot;cocoons&quot; in the pool stroke those old men in the
    movie and, while watching, I started paper-coding it right away. After a while the movie
    was over and the publishing framework designed. The name &quot;Cocoon&quot; seemed right
    for the thing, meaning to be a way to bring new life to old ideas as well as to create <em>cocoons</em>
    for such new ideas to become beautiful butterflies. :-)</p>
  </answer>
  </faq>
  
  </faqs>
  
  
  1.1                  xml-cocoon/xdocs/guide.xml
  
  Index: guide.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <!DOCTYPE document SYSTEM "./dtd/document-v10.dtd">
  
  <document>
   <header>
    <title>User Guide</title>
    <authors>
     <person name="Stefano Mazzocchi" email="stefano@apache.org"/>
    </authors>
   </header>
  
   <body>
  
  <s1 title="Introduction">
    <p>This document assumes the knowledge of the W3C recommendation
    or working drafts used in Cocoon (mainly <link href="http://www.w3.org/TR/REC-xml">XML</link>,
    <link href="http://www.w3.org/TR/WD-xsl">XSL</link> in both its <link href="http://www.w3.org/TR/WD-xslt">transformation</link>
    and <link href="http://www.w3.org/TR/WD-xsl">formatting</link> capabilities). This
    document is not intended to be an XML or XSL tutorial but just shows how these
    technologies may be used inside the Cocoon framework to create web content.</p>
  </s1>
  
  <s1 title="General overview">
    <p>Cocoon is a publishing system that allows you to separate web development in three different
    layers: content, style and logic.</p>
    
    <p>Cocoon does not aim to simplify the creation of web content: in fact, it is harder to
    create XML/XSL content than it is to use HTML from the beginning. So, if you
    are happy with the web technology you are using today, don't waste your time
    and stick with what you already have. Otherwise, if your troubles are site
    management, if your graphic people is always in the way, if you HTML authors
    always mess up your page logic, if your managers see no results in hiring new
    people to work on the site, go on and make your life easier.</p>
    
    <p>This comment posted on the Cocoon mail list shows you what we mean:</p>
    
  <source>
  I've got a site up and running that uses Cocoon. 
  It rocks, the management loves me (they now treat 
  me like I walk on water), and a couple of summer 
  interns that I had helping me on the project are 
  suddenly getting massively head-hunted by companies 
  like AT&amp;T now that they can put XML and XSL on 
  their resumes.  In a word: Cocoon simply rocks!
  </source>
  </s1>
  
  <s1 title="Hello World">
    <p>Every good user guide starts with an <code>Hello World</code> example and since we hope to
    write good documentation (even if its hard like hell!), we start from there
    too. Here is a well-formed XML file that uses a custom and simple DTD</p>
    
  <source><![CDATA[
  <?xml version="1.0"?>
  <page>
   <title>Hello World!</title>
   <content>
    <paragraph>This is my first Cocoon page!</paragraph>
   </content>
  </page>
  ]]></source>
    
    <p>Even if this page mimics HTML (in a sense, HTML was born as a simple DTD
    for homepages), it is helpful to note that there is no style information
    and all the styling and graphic part is missing. Where do I put the title? How
    do I format the paragraph? How do I separated the content from the other
    elements? All these questions do not have answers because in this context they
    don't need one: this file should be created and maintained by people that
    don't need to be aware of how this content if further processed to become a
    served web document.</p>
    
    <p>On the other hand, we need to indicate how the presentation questions will
    be answered. To do this, we must indicate a <em>stylesheet</em> that is able to
    indicate how to interpret the elements found in this document. Thus, we
    follow a <link href="http://www.w3.org/TR/WD-xml-stylesheet">W3C recommendation</link>
    and add the XML processing instruction to map a stylesheet to a document:</p>
    
    <source>&lt;xml-stylesheet href"hello.xsl" type="text/xsl"&gt;</source>
    
    <p>Now that our content layer is done, we need to create a stylesheet to
    convert it to a format readable by our web clients. Since most available web
    clients use HTML as their <em>lingua franca</em>, we'll write a stylesheet to
    convert our XML in HTML (More precisely, we convert to XHTML which is the XML
    form of HTML, but we don't need to be that precise at this point).</p>
    
    <p>Every valid stylesheet must start with the root element <em>stylesheet</em>
    and define its own namespace accordingly to the W3C directions. So the
    skeleton of your stylesheet is:</p>
    
  <source><![CDATA[
  <?xml version="1.0"?>
  <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  </xsl:stylesheet>
  ]]></source>
  
    <p>Once the skeleton is done, you must include your <code>template</code> elements,
    which are the basic unit of operation for the XSLT language. Each template is
    matched against the occurrence of some elements in the original document and
    the element is replaced with the children elements, if they belong to other
    namespaces, or, if they belong to the XSLT namespace, they are further
    processed in a recursive way.</p>
    
    <p>Let's make an example: in our <code>HelloWorld.xml</code> document <code>page</code> is the
    root element. This must be transformed in all those tags that identify a good
    HTML page. Your template becomes:</p>
    
  <source><![CDATA[
  <xsl:template match="page">
   <html>
    <head>
     <title><xsl:value-of select="title"/></title>
    </head>
    <body bgcolor="#ffffff">
     <xsl:apply-templates/>
    </body>
   </html>
  </xsl:template>
  ]]></source>
               
    <p>were some elements belong to the standard namespace (which we associate to
    HTML) and some others to the <em>xsl:</em> namespace. Here we find two of those
    XSLT elements: <code>value-of</code> and <code>apply-templates</code>. While 
    the first <em>searches</em> the <code>page</code> element direct children for the 
    <code>title</code> element and
    replace itself with the content of the retrieved element, the second indicates
    to the processor that should continue the processing of the other templates
    described in the stylesheets from that point.</p>
    
    <p>Other possible templates are:</p>
    
  <source><![CDATA[
  <xsl:template match="title">
   <h1 align="center">
    <xsl:apply-templates/>
   </h1>
  </xsl:template>
  
  <xsl:template match="paragraph">
   <p align="center">
    <i><xsl:apply-templates/></i>
   </p>
  </xsl:template> 
  ]]></source> 
  
    <p>After the XSLT processing, the original document is transformed to</p>
  
  <source><![CDATA[
  <html>
   <head>
    <title>Hello</title>
   </head>
   <body bgcolor="#ffffff">
    <h1 align="center">Hello</h1>
    <p align="center">
     <i>This is my first Cocoon page!</i>
    </p>
   </body>
  </html>
  ]]></source>
  
  </s1>
  
  <s1 title="Browser Dependent Styling">
    <p>When a document is processed by an XSLT processor, its output is exactly the same for every browser that requested
    the page. Sometimes it's very helpful to be able to discriminate the client
    capabilities and transform content layer into different views/formats. This is
    extremely useful when we want to serve content do very different types of
    clients (fat clients like desktop workstations and thin clients like wireless
    PDAs) but we want to use the same informative source and create the smallest
    possible impact on the site management costs.</p>
    
    <p> Cocoon is able to discriminate between browsers, allowing the different stylesheets to
    be applied. This is done by indicating in the stylesheet linking PI the <em>media</em>
    type, for example, continuing with the HelloWorld.xml document, these PIs</p>
    
  <source><![CDATA[
  <?xml version="1.0"?>
  <?xml-stylesheet href="hello.xsl" type="text/xsl"?>
  <?xml-stylesheet href="hello-text.xsl" type="text/xsl" media="lynx"?>
  
  ...
  
  ]]></source>
  
    <p>would tell Cocoon to apply the <code>hello.text.xsl</code> stylesheet if the Lynx browser
    is requesting the page. This powerful feature allows you to design your content
    independently and to choose its presentation depending on the capabilities of the browser
    agent.</p>
  
    <p>The media type of each browser is evaluated by Cocoon at request time,
    based on their <code>User-Agent</code> http header information.
    Cocoon is preconfigured to handle these browsers:</p>
    
    <dl>
      <dt>explorer</dt>
      <dd>
        any Microsoft Internet Explorer, searches for <em>MSIE</em> (before
        searching for Mozilla, since they include it too)
      </dd>
      <dt>opera</dt>
      <dd>
        the Opera browser (before searching for Mozilla, since
        they include it too)
      </dd>
      <dt>lynx</dt>
      <dd>the text-only Lynx browser</dd>
      <dt>java</dt>
      <dd>any Java code using standard URL classes</dd>
      <dt>wap</dt>
      <dd>the Nokia WAP Toolkit browser</dd>
      <dt>netscape</dt>
      <dd>any Netscape Navigator, searches for <em>Mozilla</em></dd>
    </dl>
    
    <p>but you can add your own by personalizing the <code>cocoon.properties</code> file
    modify the <code>browser</code> properties. For example</p>
    
  <source>
  browser.0=explorer=MSIE
  browser.1=opera=Opera
  browser.2=lynx=Lynx
  browser.3=java=Java
  browser.4=wap=Nokia-WAP-Toolkit
  browser.5=netscape=Mozilla
  </source>
      
    <p>indicates that Cocoon should look for the token <em>MSIE</em> inside the
    User-Agent HTTP request header first, then <em>Opera</em>
    and so on, until <em>Mozilla</em>. If you want to recognize different generations of the same browser you should
    do find the specific string you should look for and indicate the order of searching since
    more browsers may contain the same string.</p>
  </s1>
  
   <s1 title="Cocoon Internals">
    <p>The Cocoon publishing system has an engine based on the <em>reactor</em> design
    pattern which is described in the picture below:</p>
    
    <figure alt="Cocoon Schema" src="images/schema.jpg"/>
    
    <p>Let's describe the components that appear on the schema:</p>
    
    <dl>
     <dt>Request</dt>
     <dd>
       wraps around the client's request and
       contains all the information needed by the processing engine. The request
       must indicate what client generated the request, what URI is being
       requested and what producer should handle the request.
     </dd>
     <dt>Producer</dt>
     <dd>
       handles the requested URI and produces an
       XML document. Since producers are pluggable, they work like subservlets
       for this framework, allowing users to define and implement their own
       producers. A producer is responsible of creating the XML document which is
       fed into the processing reactor. It's up to the producer implementation to
       define the function that produces the document from the request object.
     </dd>
     <dt>Reactor</dt>
     <dd>
       is responsible of evaluating what
       processor should work on the document by reacting on XML processing
       instructions. The reactor pattern is different from a processing pipeline
       since it allows the processing path to the dynamically configurable and it
       increases performance since only those required processors are called to
       handle the document. The reactor is also responsible to forward the
       document to the appropriate formatter.
     </dd>
     <dt>Formatter</dt>
     <dd>
       transforms the memory representation of
       the XML document into a stream that may be interpreted by the requesting
       client. Depending on other processing instructions, the document leaves
       the reactor and gets formatted for its consumer. The output MIME type of
       the generated document depends on the formatter implementation.
     </dd>
     <dt>Response</dt>
     <dd>
       encapsulates the formatted document along
       with its properties (such as length, MIME type, etc..)
     </dd>
     <dt>Loader</dt>
     <dd>
       is responsible of loading the formatted
       document when this is executable code. This part is used for compiled
       server pages where the separation of content and logic is merged and
       compiled into a Producer. When the formatter output is executable code, it
       is not sent back to the client directly, but it gets loaded and executed
       as a document producer. This guarantees both performance improvement
       (since the producer are cached) as well as easier producer development,
       following the common compiled server pages model.
     </dd>
    </dl>
   </s1>
    
  <s1 title="Cocoon Processing Instructions">
    <p>The Cocoon reactor uses XML processing instructions to forward the document
    to the right processor or formatter. These processing instructions are:</p>
    
  <source>
  &lt;?cocoon-process type="xxx"?&gt; for processing
  
        and
  
  &lt;?cocoon-format type="yyy"?&gt; for formatting
  </source>
  
    <p>These PIs are used to indicate the processing and formatting path that the
    document should follow to be served. In the example above, we didn't use them
    and Cocoon wouldn't know (rather than by the presence of the XSL PIs) that the
    document should be processed by the XSLT processor. To do this, the HelloWorld.xml
    document should be modified like this:</p>
    
  <source><![CDATA[
  <?xml version="1.0"?>
  <?cocoon-process type="xslt"?>
  <?xml-stylesheet href="hello.xsl" type="text/xsl"?>
  <page>
   <title>Hello World!</title>
   <content>
    <paragraph>This is my first Cocoon page!</paragraph>
   </content>
  </page>
  ]]></source>  
    
    <p>The other processing instruction is used to indicate what formatter should
    be used to transform the document tree into a suitable form for the requesting
    client. For example, in the document below that uses the XSL formatting object
    DTD, the Cocoon PI indicates that this document should be formatted using the
    formatter associated to the <code>text/xslfo</code> document type.</p>
  
  <source><![CDATA[
  <?xml version="1.0"?>
  <?cocoon-format type="text/xslfo"?>
  
  <fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">
   <fo:layout-master-set>
    <fo:simple-page-master 
        page-master-name="one" 
        margin-left="100pt"
        margin-right="100pt">
     <fo:region-body margin-top="50pt" 
         margin-bottom="50pt"/>
    </fo:simple-page-master>
   </fo:layout-master-set>
   
   <fo:page-sequence>
    <fo:sequence-specification>
     <fo:sequence-specifier-repeating 
         page-master-first="one" 
         page-master-repeating="one"/>
    </fo:sequence-specification>
    
    <fo:flow font-size="14pt" line-height="14pt">
     <fo:block>Welcome to Cocoon</fo:block>  
    </fo:flow>  
   </fo:page-sequence> 
  </fo:root>
  ]]></source>  
  
  </s1>
  
  <s1 title="Cocoon Cache System">
    <p>In a complex server environment like Cocoon, performance and
    memory usage are critical issues. Moreover, the processing requirement for
    both XML parsing, XSLT transformations, document processing and formatting are
    too heavy even for the lightest serving environment based on the fastest
    virtual machine. For this reason, a special cache system was designed underneath the Cocoon
    engine and its able to cache both static and dynamically created pages.</p>
    
    <p>Its operation is simple but rather powerful:</p>
    
    <sl>
     <li>when the request comes, the cache is searched.</li>
     <sl>
      <li>if the request is found;</li>
      <sl>
       <li>its <em>changeable</em> points are evaluated</li>
       <li>if all changeable points are unchanged</li>
       <sl>
        <li>the page is served directly from the cache</li>
       </sl>
       <li>if a single point has changed and requires reprocessing</li>
       <sl>
        <li>the page is invalidated and continues as if it wasn't found</li>
       </sl>
      </sl>
      <li>if the request is not found:</li>
      <sl>
       <li>the page is normally processed</li>
       <li>it's sent to the client</li>
       <li>it's stored into the cache</li>
      </sl>
     </sl>
    </sl>
    
    <p>This special cache system is required since the page is
    processed with the help of many components which, independently, may change
    over time. For example, a stylesheet or a file template may be updated on
    disk. Every processing logic that may change its behavior over time it's
    considered <em>changeable</em> and checked at request time for change.</p>
    
    <p>Each changeable point is queried at request time and it's up
    to the implementation to provide a fast method to check if the stored page is
    still valid. This allows even dynamically generated pages (for example,
    an XML template page created by querying a database) to be cached and,
    assuming that request frequency is higher than the resource changes, it
    greatly reduces the total server load.</p>
    
    <p>Moreover, the cache system is based on a persistent object
    storage system which is able to save stored objects in a persistent state that
    outlives the JVM execution. This is mainly used for pages that are very
    expensive to generate and last very long without changes, such as compiled
    server pages.</p>
    
    <p>The store system is responsible of handling the cached pages
    as well as the pre-parsed XML documents. This is mostly used by XSLT
    processors which store their stylesheets in a pre-parsed form to speed up
    execution in those cases where the original file has changed, but the
    stylesheet has not (which is a rather frequent case).</p>
  </s1>
  </body>
  </document>
  
  
  1.1                  xml-cocoon/xdocs/index.xml
  
  Index: index.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <!DOCTYPE document SYSTEM "./dtd/document-v10.dtd">
  
  <document>
   <header>
    <title>Cocoon</title>
    <subtitle>XML Publishing Framework</subtitle>
    <authors>
     <person name="Stefano Mazzocchi" email="stefano@apache.org"/>
    </authors>
   </header>
  
   <body>
   <s1 title="What is it?">
    
    <p>
     <img src="images/cocoon.jpg" alt="Cocoon"/> Cocoon is a 100% pure 
     Java publishing framework that relies on new W3C
     technologies (such as DOM, XML, and XSL) to provide web content.
    </p>
   
    <p>
     The Cocoon project aims to change the way web information is created,
     rendered and served. This new paradigm is based on fact that document content, style and
     logic are often created by different individuals or working groups. Cocoon aims to a
     complete separation of the three layers, allowing the three layers to be independently
     designed, created and managed, reducing management overhead, increasing work reuse and
     reducing time to market.
    </p>
    
    <p>
     Read the <connect href="technologies.xml">Introduction on Cocoon
     technologies</connect> white paper to find out more on the subject.
    </p>
   </s1>
   
   <s1 title="What does it do?">
    <p>
     Web content generation is mostly based on HTML, but HTML doesn't separate
     the information from its presentation, mixing formatting tags, descriptive tags and
     programmable logic (both on server side and client side). Cocoon changes this view
     allowing content, logic and style on different XML files and uses XSL transformation
     capabilities to merge them.
    </p>
   </s1>
   
   <s1 title="What does it change for me?">
    <p>
     Even if the most common use of Cocoon is the automatic creation of HTML
     through the processing of statically or dynamically generated XML files, Cocoon is also
     able to perform more sophisticated formatting, such as XSL:FO rendering on PDF,
     client-depending transformations such as WML formatting for WAP-enabled
     devices or direct XML serving to XML and XSL aware clients.
    </p>
   
    <p>
     The Cocoon model allows web sites to be highly structured and
     well designed, reducing duplication efforts and site management costs by
     allowing different presentations of the same data depending on the requesting
     client (HTML clients, PDF clients, WML clients) and separating on different <em>contexts</em>
     different requirements, skills and capacities. Cocoon allows a better human
     resource management by giving to each individual its job and reducing to a
     minimum the cross-talks between different working contexts.
    </p>
      
    <p>
     To do this, the Cocoon model divides the development of web content in three
     separate levels:
    </p>
    
    <dl>
      <dt>XML creation</dt>
      <dd>the XML file is created by the <em>content owners</em>. They do not
       require specific knowledge on how the XML content is further processed rather than the
       particular chosen DTD/namespace. This layer is always performed by humans directly
       through normal text editors or XML-aware tools/editors.</dd>
      <dt>XML processing</dt>
      <dd>the requested XML file is processed and the logic contained in its 
       logicsheet is applied. Unlike other dynamic content generators, the logic
       is separated from the content file.</dd>
      <dt>XSL rendering</dt>
      <dd>the created document is then rendered by applying an XSL
       stylesheet to it and formatting it to the specified resource type 
       (HTML, PDF, XML, WML, XHTML)</dd>
    </dl>
   </s1>
  
   <s1 title="Are there any known problems?">
    <p>
     The biggest known problem in this framework is the lack of XML/XSL
     knowledge, being relatively new formats. We do believe, though, that this publishing
     framework will be a winner in web sites of medium to high complexity and will lead the
     transition from an HTML-oriented to a XML-oriented web publishing model, still allowing the
     use of existing client technologies as well as supporting new types of clients
     (such as WAP-aware ultra thin clients like cell phones or PDAs).
    </p>
    <p>
     Even if considered heavy and hype overloaded, the XML/XSL pair will do
     magic once its public knowledge receives the spread it deserves. This project wants to be
     a small step in this direction, helping people to learn this technology and to focus on
     what they need with examples, tutorial and source code and a real-life system
     carefully designed with portability, modularity and real-life usage in
     mind.
    </p>
    <p>
     The main concern remains processing complexity: the kind of operations required
     to process the document layers are complex and not designed for real-time
     operation on the server side. For this reason, Cocoon is designed to be a page compiler for dynamic pages,
     trying to hardcode, whenever possible, those layers in precompiled binary
     code coupled with an adaptive and memory-wise cache system for both static and
     dynamic pages. Most of the development effort is focused on performance
     improvement of both processing subsystems as well as the creation and testing
     of special cache systems.
    </p>
    <p>
     Another problem is the intrinsic impossibility of page-compiling all the three
     processing layers, due to the post-processing requirements of XSL styling. This 
     problem will be solved (hopefully!) with the availability of XSL-enabled
     web browsers since the XSL rendering would be then
     performed on client side reducing the server work.
    </p>
   </s1>
  
   <s1 title="Where do I get it?">
    <p>
     Here is the <link href="http://xml.apache.org/dist/">download area</link>.
    </p>
   </s1>
   
   <s1 title="How do I Contribute?">
    <p>
     The Cocoon Project is an open volunteer project based on the spirit of the 
     <link href="http://www.apache.org">Apache Software Foundation</link> (ASF). 
     This means that there are lots of ways to contribute to the project, either 
     with direct participation (coding, documenting, answering questions, 
     proposing ideas, reporting bugs, suggesting bug-fixes, etc..) or by resource 
     donation (money, time, publicity, hardware, software, conference 
     presentations, speeches, etc...).
    </p>
    <p>
     For direct participation, we suggest you to subscribe to the 
     <link href="http://xml.apache.org/mail.html">Cocoon mail lists</link> 
     (follow the link for information on how to subscribe and to access the mail 
     list archives), to checkout the <link href="http://xml.apache.org/websrc/cvsweb.cgi/xml-cocoon/">
     latest and greatest code</link> (which you found in the xml-cocoon module in 
     the xml.apache.org CVS code repository, or from the 
     <link href="http://xml.apache.org/from-cvs/xml-cocoon/">CVS snapshots</link>), 
     control the <connect href="../todo.xml">todo</connect>
     list and jump in. Document writers are usually the most wanted people so if
     you like to help but you're not familiar with technical details, don't worry:
     we have work for you.
    </p>
    <p>
     For money funding in particular, the Cocoon Project and the ASF in general 
     is closely collaborating with the <link href="http://www.sourcexchange.com">Collab.net
     SourceXchange</link> program that will provide a legal, solid and well
     established resource for money collecting to fund direct software production
     under the open source flag. Please, feel free to contact directly Cocoon's
     main architect and project creator <link href="mailto:stefano@apache.org">Stefano
     Mazzocchi</link> or the ASF President and Collab.net co-founder <link href="mailto:brian@collab.net">Brian
     Behlendorf</link> for more information on how to contribute directly to the
     advancement of this project.
    </p>
    <p>
     Anyway, a great way of contributing back to the project is to
     allow others to know about it so that the word spreads and others may wish to
     contribute, so, please, help us by placing the cocoon logo somewhere in your
     site to indicate that you are using and supporting the Cocoon Project.
    </p>
    
    <p>
     Thank you very much. <img src="images/cocoon-small.jpg" alt="Powered by Cocoon"/>
    </p>
   </s1>
   </body>
  </document>
  
  
  
  1.1                  xml-cocoon/xdocs/installing.xml
  
  Index: installing.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <!DOCTYPE document SYSTEM "./dtd/document-v10.dtd">
  
  <document>
   <header>
    <title>Installing Cocoon</title>
    <authors>
     <person name="Stefano Mazzocchi" email="stefano@apache.org"/>
     <person name="Brett McLaughlin" email="bmclaugh@algx.net"/>
     <person name="Russell Castagnaro" email="russell@synctank.com"/>
    </authors>
   </header>
   
   <body>
   
   <s1 title="System Requirements">
    <p>
     Cocoon requires the following systems to be already installed in your
     system:
    </p>
    
    <ul>
     <li><strong>Java Virtual Machine</strong>
      A Java 1.1 or greater compatible virtual machine must be present for both
      command line and servlet type usage of Cocoon. Note that all servlet engines
      require a JVM to run so if you are already using servlets you already have
      one installed.
     </li>
     <li><strong>Servlet Engine</strong>
      A Servlet 2.x compliant servlet engine  must be present in order to support 
      servlet operation and dynamic request handling. Note that this requirement
      is optional for command line operation.
     </li>
    </ul>
   </s1>
   
   <s1 title="Required Components">
    <p>
     Cocoon is a publishing framework and was designed to be highly modular to
     allow users to choose their preferred implementation for the required
     component and to allow better and faster parallel development.
    </p>
    
    <p>
     Here is a list of supported components with their minimum version required
     to operate with this version of Cocoon:
    </p>
    
    <table>
     <caption>XML Parsers</caption>
      <tr>
       <th>Name</th>
       <th>Version</th>
       <th>Location</th>
      </tr>
      <tr>
       <td>Apache Xerces</td>
       <td>1.0.1 (java edition)</td>
       <td><link href="http://xml.apache.org/dist/">xml.apache.org</link></td>
      </tr>
      <tr>
       <td>Sun ProjectX</td>
       <td>TR2</td>
       <td><link href="http://developer.java.sun.com/developer/products/xml/">java.sun.com</link></td>
      </tr>
      <tr>
       <td colspan="3">Cocoon comes preconfigured for Xerces</td>
      </tr>
    </table>
     
    <table>
     <caption>XSLT Processor</caption>
      <tr>
       <th>Name</th>
       <th>Minimum Version</th>
       <th>Location</th>
      </tr>
      <tr>
       <td>Apache Xalan</td>
       <td>0.19.0</td>
       <td><link href="http://xml.apache.org/dist/">xml.apache.org</link></td>
      </tr>
      <tr>
       <td>James Clark's XT</td>
       <td>19991102</td>
       <td><link href="http://www.jclark.com/">www.jclark.com</link></td>
      </tr>
      <tr>
       <td colspan="3">Cocoon comes preconfigured for Xalan</td>
      </tr>
    </table>   
     
    <table>
     <caption>Other Packages</caption>
      <tr>
       <th>Name</th>
       <th>Minimum Version</th>
       <th>Location</th>
      </tr>
      <tr>
       <td>Apache FOP</td>
       <td>0.12.0</td>
       <td><link href="http://xml.apache.org/dist/">xml.apache.org</link></td>
      </tr>
      <tr>
       <td>FESI EcmaScript Engine</td>
       <td>1.2.1</td>
       <td><link href="http://home.worldcom.ch/jmlugrin/fesi/download.html">home.worldcom.ch/jmlugrin/fesi</link></td>
      </tr>
      <tr>
       <td>GNU Regexp</td>
       <td>1.0.8</td>
       <td><link href="http://www.cacas.org/java/gnu/regexp/">www.cacas.org/java/gnu/regexp</link></td>
      </tr>
      <tr>
       <td>JNDI API</td>
       <td>1.2.1</td>
       <td><link href="http://java.sun.com/products/jndi/index.html">java.sun.com</link></td>
      </tr>
    </table>   
    
    <note>
     Cocoon is strictly dependent on some printing classes contained into Xerces
     so, even if you use another parser, you should still keep Xerces visible
     to Cocoon.
    </note>
    
    <p>
     Being an Apache project, Cocoon focuses on Apache technologies but we are
     dedicated to support all compatible XML/XSL technologies and will welcome
     contributions to add support for other components not currently supported.
    </p>
    
    <p>
     So this is your shopping list for components for complete operation:
    </p>
     
     <ul>
      <li>Apache Xerces (required for the formatting classes <em>org.apache.xml.serialize</em>)</li>
      <li>Your favorite XML parser</li>
      <li>Your favorite XSLT processor</li>
      <li>Apache FOP (optional, unless you want PDF rendering)</li>
      <li>GNU Regexp (optional, unless you use <em>ProducerFromMap</em>)</li>
      <li>FESI (optional, unless you use <em>DCP</em>)</li>
      <li>JNDI (optional, unless you use the <em>LDAP processor</em>)</li>
     </ul>
     
    <p>
     All right. Now that you have downloaded all the components you need, go on
     and jump to the installation instructions for your servlet engine.
    </p>
   </s1>
   
   <s1 title="Installing Cocoon">
    <p>
     Being Cocoon a servlet, you should be able to install it on every compliant
     servlet engine by associating the "org.apache.cocoon.Cocoon" servlet
     with the requests you want it to handle. In order to do this, there is no
     standard way, so we try to provide detailed information for the most used
     servlet systems.
    </p>
    
    <s2 title="General considerations">
     <p>
      There are some general considerations that apply to all systems.
     </p>
     
     <p>
      Since there is no portable way, in a Java platform, to tell how much memory an object
      is using, the memory cache works in a rather cumbersome manner:  you set up
      a lower limit that the cache must always leave free for the JVM operation. 
      This means, that if the memory limit is 200Kb, Cocoon uses all your JVM
      heap size to store pages in memory and makes sure that 200Kb are available
      for other operations.
     </p>
     
     <p>
      This does not impact the JVM operation, if enough memory is left for the
      normal operation. You must be aware of the fact that leaving Cocoon with
      too little memory for operation does impact peformance since the JVM
      garbage collector has to do more work to keep up with execution and 
      memory cleanup. Sometimes, you may even end up having OutOfMemoryExceptions
      if your limit is lower than the memory required for the operation.
     </p>
     
     <p>
      A good way to control your memory is to setup your JVM with a fixed
      heap limit and to give it enough memory to start. This is done by using
      command line parameters for your java interpreter such as:
     </p>
     
     <ul>
      <li>Startup heap size:
       <sl>
        <li>java 1.1 - <code>-ms[size]</code></li>
        <li>java 1.2 - <code>-Xms[size]</code></li>
       </sl>
      </li>
      <li>Maximum heap size:
       <sl>
        <li>java 1.1 - <code>-mx[size]</code></li>
        <li>java 1.2 - <code>-Xmx[size]</code></li>
       </sl>
      </li>
     </ul>
       
     <p>
      A well balanced system should have something like 8Mb start heap, 2Mb
      Cocoon memory limit and 64Mb or greater max heap, but these depend heavily
      on your system load/configuration to be generally meaningful.
     </p>
     
     <p>
      To change the cocoon object store memory limit open you should change the
      following property in the <code>cocoon.properties</code> file.
     </p>
     
  <source>store.memory = 200000</source>   
      
     <p>
      Another important part of Cocoon is the page compiler used inside the
      XSP processor which store the generated/compiled pages on file system. 
      The default directory is <code>./repository</code> which is usually relative
      to the web server or servlet engine working directory.
     </p>
     
     <p>
      If you experience
      troubles (such as not having reading/writing permissions) or you want to 
      locate this directory somewhere else, you have to change the
     </p>
     
  <source>processor.xsp.repository = ./repository</source>
  
     <p>
      property in the cocoon configuration file.
     </p>
     
     <p><strong>Warning:</strong>
      Since this directory may contain security sensible information, make sure 
      you deny access (even read-only) to untrusted users.
     </p>
    </s2>
    
    <s2 title="Installing Cocoon on Apache JServ">
     <p>
      Apache JServ has one configuration file for the whole engine (normally called
      <code>jserv.properties</code>) and one for each servlet zone. Please, refer
      to the Apache JServ documentation for more information on this.
     </p>
     
     <p>
      First thing to do is to make sure that Cocoon and all the needed components
      (as explained in the previous section) are visible. This implies adding 
      this to the servlet engine classpath by adding a line like this in your 
      <code>jserv.properties</code> file for each jar package you have to install
      (after substituting <em>[path-to-jar]</em> with the path to the jar file and
      <em>[jar-name]</em> with the package file name).
     </p>
      
  <source>wrapper.classpath=[path-to-jar]/[jar-name].jar</source>
     
     <p>
      Here is an example:
     </p>
     
  <source>
  wrapper.classpath=/usr/local/java/lib/cocoon.jar
  wrapper.classpath=/usr/local/java/lib/xerces.jar
  wrapper.classpath=/usr/local/java/lib/xalan.jar
  wrapper.classpath=/usr/local/java/lib/fop.jar
  wrapper.classpath=/usr/local/java/lib/regexp.jar
  wrapper.classpath=/usr/local/java/lib/jndi.jar
  </source>
     
     <note>
      from this version of Cocoon the <code>Cocoon.jar</code> 
      package should be added to the servlet engine classpath as any other
      required package (as shown above).
     </note>
     
     <p>
      At this point, you must set the Cocoon configurations. To do this, you 
      must choose the servlet zone(s) where you want Cocoon to reside (Note that
      Cocoon can safely reside on different servlet zones with different
      configuration files). If you don't know what a servlet zone is, you 
      probably want to open the <code>zone.properties</code> file that represents 
      the default servlet zone.
     </p>
     
     <p>
      To configure Cocoon, you must pass the <code>cocoon.properties</code>
      file location to the servlet by adding the following to the 
      <code>zone.properties</code> file (or each servlet zone file you want
      Cocoon to reside):
     </p>
     
  <source>servlet.org.apache.cocoon.Cocoon.initArgs=properties=[path-to-cocoon]/bin/cocoon.properties</source>
    
     <p>
      Note that you should not need to change anything from the template
      properties file found in the distribution (under <code>/conf/</code>), 
      but you must edit it for more complex operation. Please refer directly to 
      the file that contains breaf indications and comments on the different 
      configurations, but you don't need to care about that at this point.
     </p>
     
     <p>
      Now your cocoon servlet is properly configured, but you should tell Apache
      to direct any call to an XML file (or any other file you want Cocoon to
      process) to the Cocoon servlet. To do this, you should add the following line
      to your <code>mod_jserv.conf</code> or <code>jserv.conf</code> file:
     </p>
      
  <source>Action cocoon /servlet/org.apache.cocoon.Cocoon
  AddHandler cocoon xml</source>
    
     <p>
      where <em>xml</em> is the file extention you want to map to the servlet
      and <em>/servlet/</em> is the mount point of your servlet zone (and the
      above is the standard name for servlet mapping for Apache JServ).
     </p>
  
     <p>
      At this point, you should check if your system matches the global 
      considerations about Cocoon properties. Usually, you might want to give
      the installation a try as it is and then read again that section if
      something goes wrong. Most installations don't need any changes to
      be operational.
     </p>
         
     <p>
      Everything should be configured fine. Restart both Apache and Apache JServ
      and try accessing the samples contained in the distribution to see
      Cocoon in action or the <code>/Cocoon.xml</code> page for Cocoon internal
      status.
     </p>
     
     <p>
      <strong>Note</strong>: you may want Cocoon to handle two different 
      extentions with different configurations. To do this, you must set the two 
      different configurations in two different servlet zones, then associate the 
      extentions like this:
     </p>
     
  <source>Action cocoon1 /zone1/org.apache.cocoon.Cocoon
  Action cocoon1 /zone2/org.apache.cocoon.Cocoon
  AddHandler cocoon1 xml1
  AddHandler cocoon2 xml2</source>
  
     <p>
      where <em>xml1</em> is handled by the Cocoon residing on <em>zone1</em>
      and <em>xml2</em> is handled by the Cocoon residing on <em>zone2</em>
      which have different configurations and thus different behavior.
     </p>
    </s2>
    
    <s2 title="Installing Cocoon on Apache Tomcat">
      <p>
       Tomcat has two basic methods of locating Java classes for the runtime environment.
       The first is the overall classpath that Tomcat uses to run, and this is the
       classpath provided to Java classes that use constructs such as
       <code>Class.forName().newInstance()</code>.  The second classpath is
       associated with a specific context, and is somewhat analagous to the
       servlet zones used in Apache JServ (see section above).
      </p>
  
      <p>
       Because the Cocoon framework utilizes <code>Class.forName()</code> and other
       dynamic instance handling techniques, the Cocoon classes need to have its
       classpath aware of the component classes used within the framework.  To do 
       this, take all the required components (see above) and put them in your 
       <em>&lt;Tomcat-Root&gt;/lib</em> directory.  This is the standard location 
       for Tomcat core libraries. To ensure that Tomcat will use these, you need 
       to edit the Tomcat startup file.
      </p>
      
      <p>
       On Windows, this is <em>&lt;Tomcat-Root&gt;/tomcat.bat</em> and on
       Unix, this is <em>&lt;Tomcat-Root&gt;/tomcat.sh</em>.  In this 
       file you must add all the component jar files to Tomcat's classpath.
      </p>
  
      <note>
       from this version of Cocoon the <code>Cocoon.jar</code> 
       package should be added to the servlet engine classpath as any other
       required package (as shown above).
      </note>
     
      <p>
       Next you need to tell your context where Cocoon can find it's properties 
       file, as well as to map Cocoon to XML document requests.
       Make sure you have a <em>web.xml</em> file in your context's
       <em>WEB-INF</em> directory (look in <code>src/WEB-INF/</code> to find a
       template <em>web.xml</em>).  This file specifies servlet mappings
       and initial arguments to servlets and looks like this:
      </p>
  
  <source><![CDATA[
  <servlet>
   <servlet-name>org.apache.cocoon.Cocoon</servlet-name>
   <servlet-class>org.apache.cocoon.Cocoon</servlet-class>
   <init-param>
    <param-name>properties</param-name>
    <param-value>
      [path-to-cocoon.properties]/cocoon.properties
    </param-value>
   </init-param>
  </servlet>
  
  <servlet-mapping>
   <servlet-name>org.apache.cocoon.Cocoon</servlet-name>
   <url-pattern>*.xml</url-pattern>
  </servlet-mapping>
  ]]></source>
  
      <p>
       Make sure you replaced the path to the Cocoon.properties file with the 
       actual location of that file on your system.
       Note that you should not need to change anything from the template
       properties file found in the distribution, but you must edit it for
       more complex operation. Please refer directly to the file that contains
       brief indications and comments on the different configurations, but you
       don't need to care about that at this point.
      </p>
  
     <p>
      At this point, you should check if your system matches the global 
      considerations about Cocoon properties. Usually, you might want to give
      the installation a try as it is and then read again that section if
      something goes wrong. Most installations don't need any changes to
      be operational.
     </p>
  
     <p>
      Everything should be configured fine. Restart both Apache and Tomcat
      and try accessing the samples contained in the distribution to see
      Cocoon in action or the <code>/Cocoon.xml</code> page for Cocoon internal
      status.
     </p>
         
      <note>
       Tomcat 3.0 has a bug that prevents Cocoon operation. In order to make
       Cocoon work under Tomcat you need to download a newer version or, if 
       none is yet avaiable, build it from the latest source code found in the
       <code>jakarta-tomcat</code> CVS module under <em>jakarta.apache.org</em>.
       We apologize for this, but it's not something we can control or work
       around.
      </note>
    </s2>
  
    <s2 title="Installing Cocoon on BEA WebLogic">
     <p>
      After you have obtained all the jar packages you need (see the above
      section), you should add all of them (included the <code>cocoon.jar</code>
      package to your <code>weblogic.class.path</code> variable either
      using the <em>t3config</em> utility or use the <code>-Dweblogic.class.path</code>
      argument with the java runtime that invokes the system.
     </p>
     <p>
      Once you've done that, you should register Cocoon by adding these lines
      to your configuration files:
     </p>
  <source>weblogic.httpd.register.*.xml=\org.apache.cocoon.Cocoon
  weblogic.httpd.initArgs.*.xml=\properties=[path-to-cocoon]/bin/cocoon.properties</source>
     <p>
      making sure that you replaced <em>[path-to-cocoon]</em> with the actual
      path in your system.
     </p>
  
     <p>
      At this point, you should check if your system matches the global 
      considerations about Cocoon properties. Usually, you might want to give
      the installation a try as it is and then read again that section if
      something goes wrong. Most installations don't need any changes to
      be operational.
     </p>
     
     <p>
      Everything should be configured fine. Restart Weblogic
      and try accessing the samples contained in the distribution to see
      Cocoon in action or the <code>/Cocoon.xml</code> page for Cocoon internal
      status.
     </p>
        
    </s2>
    
    <s2 title="Installing Cocoon on other platforms">
     <p>Yet to be written! <em>Volunteers welcome!</em></p>
    </s2>
    
   </s1>
   
   <s1 title="Working Systems">
    <p>
     Cocoon has been reported to be working on these systems:
    </p>
    
    <table>
    <tr>
     <th>Operating System</th>
     <th>Web Server</th>
     <th>Servlet Engine</th>
     <th>JVM</th>
    </tr>
    <tr>
     <td>RedHat Linux 6.0</td>
     <td>Apache 1.3.9</td>
     <td>Apache JServ 1.0</td>
     <td>IBM JDK 1.1.8</td>
    </tr>
    <tr>
     <td>RedHat Linux 6.0</td>
     <td>Apache 1.3.9</td>
     <td>Apache JServ 1.1b3</td>
     <td>IBM JDK 1.1.8</td>
    </tr>
    <tr>
     <td>RedHat Linux 6.0</td>
     <td>Apache 1.3.9</td>
     <td>Apache JServ 1.0</td>
     <td>Blackdown JDK 1.2pre2</td>
    </tr>
    <tr>
     <td>RedHat Linux 6.1</td>
     <td>Apache 1.3.9</td>
     <td>JRun 2.3.3</td>
     <td>IBM JRE 1.1.8</td>
    </tr>
    <tr>
     <td>Windows 98</td>
     <td>Apache 1.3.9</td>
     <td>Apache JServ 1.0</td>
     <td>Sun JDK 1.2.2</td>
    </tr>
    <tr>
     <td>Windows 98</td>
     <td>Apache 1.3.9</td>
     <td>Apache JServ 1.0</td>
     <td>IBM JDK 1.1.7</td>
    </tr>
    <tr>
     <td>Windows 98</td>
     <td>Apache 1.3.9</td>
     <td>Apache JServ 1.1b3</td>
     <td>Sun JDK 1.2.2</td>
    </tr>
    <tr>
     <td>Windows 98</td>
     <td>Apache 1.3.9</td>
     <td>Apache JServ 1.1b3</td>
     <td>IBM JDK 1.1.7</td>
    </tr>
    <tr>
     <td>Windows 98</td>
     <td>MS Personal Web Server</td>
     <td>ServletExec 2.2</td>
     <td>Sun JDK 1.2.1</td>
    </tr>
    <tr>
     <td>Windows NT 4.0</td>
     <td>IIS 4.0</td>
     <td>ServletExec 2.2</td>
     <td>Sun JDK 1.2.1</td>
    </tr>
    <tr>
     <td>Windows NT 4.0</td>
     <td>IIS 4.0</td>
     <td>JRun 2.3.3</td>
     <td>Sun JDK 1.2.1</td>
    </tr>
    <tr>
     <td>Windows NT 4.0</td>
     <td>Apache 1.3.9</td>
     <td>JRun 2.3.3</td>
     <td>Sun JDK 1.2.2</td>
    </tr>
    <tr>
     <td>Windows NT 4.0</td>
     <td colspan="2">Apache Jakarta Tomcat 3.1 Milestone 1</td>
     <td>Sun JDK 1.2.2</td>
    </tr>
    <tr>
     <td>MacOS 8.6</td>
     <td>WebSTAR 4.0</td>
     <td>JRun 2.3</td>
     <td>MrJ 2.1.4</td>
    </tr>
    <tr>
     <td>MacOS 8.6</td>
     <td>WebSTAR 4.0</td>
     <td>ServletExec 2.1</td>
     <td>Mrj 2.1.4</td>
    </tr>
    <tr>
     <td>MacOS 8.6</td>
     <td>Quid Pro Quo 2.1.3</td>
     <td>ServletExec 2.2</td>
     <td>Mrj 2.1.4</td>
    </tr>
    <tr>
     <td>SunOS Netria 5.6</td>
     <td>Apache 1.3.9</td>
     <td>Apache JServ 1.1b3</td>
     <td>Sun JDK 1.1.7</td>
    </tr>
    <tr>
     <td>FreeBSD 3.4</td>
     <td>Apache 1.3.9</td>
     <td>Apache JServ 1.0</td>
     <td>Blackdown JDK 1.1.8</td>
    </tr>
    <tr>
     <td>SCO OpenServer 5</td>
     <td colspan="2">WebLogic 4.5.1</td>
     <td>SCO JDK 1.1.7A</td>
    </tr>
    </table>
    
    <note>
     Due to a bug in <link href="http://www.blackdown.org">Blackdown
     JDK 1.2pre2</link> for Linux, we suggest you to use green threads instead of the
     native ones which are much less stable, expecially highly concurrent operations
     like servlet engines and servlet execution.
    </note>
    <p>
     Please, submit your feedback if you were able to install Cocoon on a
     different combination not listed above. Thanks.
    </p>
   </s1>
  </body></document>
  
  
  1.1                  xml-cocoon/xdocs/javadoc.xml
  
  Index: javadoc.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <!DOCTYPE document SYSTEM "./dtd/document-v10.dtd">
  
  <document>
   <header>
    <title>Javadoc Documentation in XML</title>
    <authors>
     <person name="Kenneth Murphy" email="murphyk@umsystem.edu"/>
     <person name="Stefano Mazzocchi" email="stefano@apache.org"/>
    </authors>
   </header>
  
   <body>
    <s1 title="Introduction">
     <p>We are currently working on enhancing the documentation provided for the
     Cocoon XML publishing framework by converting javadoc commented source code into
     XML for use within Cocoon.</p>
    </s1>
  
    <s1 title="The plan">
     <p>In order to do this we are currently planning to implement the following
  phases:</p>
  
    <ol>
    <li>Develop a JavaDoc XML DTD that acts as a data structure representing the
      information provided by the rootDoc object of the SUN Javadoc program to a
      plugged doclet. This DTD is intended to closely mirror the look of a raw
      java source file.</li>
    <li>Develop a JavaDoc doclet (JavaDocXML) that takes the information from the
      JavaDoc rootDoc object and converts it into an XML file using the
      javadoc.dtd.</li>
    <li>Wrap the javadoc with XML doclet invocation into a cocoon producer as follows:</li>
    <ul>
     <li>reads the document from the file system</li>
     <li>spawns the javadoc tool using the javadoc XML servlet and using the
         parameters found in the "javadoc makefile"</li>
     <li>produces the XML output as a single document</li>
     <li>the Cocoon engine process it with the stylesheet indicated (from
         command line or whatever)</li>
     <li>formats it either as PDF or HTML or whatever depending on the chosen
         stylesheet. (the HTML formatter will be able to split a single
         XML document into several ones based on special page-break tags or PIs
          or using FO directly)</li>
     <li>formatter will also be able to react on the SVG namespace
         inlining vector graphics or formatted as raster graphics.</li>
    </ul>
    <li>Some final formats we could produce are:</li>
    <ul>
      <li>javadoc.dtd ---&gt; javadoc_html.dtd ---&gt; HTML (this would create a
          javadoc that looks like the current HTML javadoc standard).</li>
      <li>javadoc.dtd ---&gt; docBook.dtd (this would facilitate printed
          books based having heavy content about java API's. For example &quot;The
          JDBC API Tutorial and Reference: 2nd Edition&quot; could make heavy use
          of this.</li>
      <li>javadoc.dtd ---&gt; ebook.dtd (this would facilitate the electronic
          version of documentation)</li>
      <li>javadoc.dtd ---&gt; ??? ---&gt; pdf</li>
    </ul>
    <li>Using this method we will then enhance the existing Cocoon documentation to provide rich documentation
        using some subset of the above formats.</li>
    <li>Finally, we can incorporate XML versions of UML vector diagrams to further enhance the
        source code documentation.</li>
    </ol>
    </s1>
  
    <s1 title="Progress to date">
     <p>
        The first phase has been complete and a complete javadoc DTD was
        created. We feel confortable with the solidity of that DTD and we plan
        to move over to the actual XML doclet implementation.
     </p>
     <p>
        The problem is that the original Javadoc XML proposal author quit the
        project for lack of time, so <strong>we are currently looking for people</strong>
        to move the task forward since we are almost stuck at this point.
     </p>
    </s1>
    
    <s1 title="To do">
     <p>
        Being the first phase complete (the DTD is still in working-draft phase,
        but it's complete and usable), we need to write the doclet, but the
        task is stalled for lack of active contributors. <strong>Any help is
        always welcome</strong>.
     </p>
    </s1>
  
   </body>
  </document>
  
  
  1.1                  xml-cocoon/xdocs/ldapprocessor.xml
  
  Index: ldapprocessor.xml
  ===================================================================
  <?xml version="1.0" encoding="utf-8"?>
  
  <!DOCTYPE document SYSTEM "./dtd/document-v10.dtd">
  
  <document>
  	<header>
  		<title>LDAP Processor</title>
  		<authors>
  			<person name="James M. Birchfield" email="jmbirchfield@proteus-technologies.com"/>
  		</authors>
  	</header>
  	<body>
  		<s1 title="Description">
  			<p>LdapProcessor is a processor for Cocoon that performs LDAP queries, translates the resultset into an XML fragment, and inserts the fragment in the original document.The Ldap Processor was written for a project where I work, and carried back over into the Cocoon project.  </p>
  		</s1>
  		<s1 title="Installation">
  			<p>Check your cocoon.properties for this line and add it if it's not already there:</p>
  			<source>processor.type.ldap = org.apache.cocoon.processor.ldap.LdapProcessor</source>
  		</s1>
  		<s1 title="Configuration">
  			<p>Add this PI to the XML files to which you wish to add LDAP queries:</p>
  			<source>&lt;?cocoon:process type="ldap"?&gt;</source>
  			<p>You probably want this before any "xslt" processing directives. Then add LDAP connection information to your XML files. The tagset for LDAP server defitions looks like this:</p>
  			<source>&lt;ldap-defs&gt;
   &lt;ldap-server name=foo_server"&gt;
    &lt;initializer&gt;com.sun.jndi.ldap.LdapCtxFactory&lt;/initializer&gt;
    &lt;ldap-serverurl&gt;ldap://ldap.weber.edu&lt;/ldap-serverurl&gt;
   &lt;/ldap-server&gt;
  &lt;/ldap-defs&gt;
  </source>
  			<p>This tagset will be removed from the document after processing.</p>
  			<p>In addition to the ldap-server element, you can also have querydefs tags in your ldap-defs node. A ldap-defs node must have a unique name attribute. ldap-query tags (described below) may reference a querydefs tag in their defs attribute, which causes the ldap-query tag's attributes to default to the attributes of the querydefs tag. This is useful for setting commonly used groups of attributes. You may also specify a default querydefs. Here is an example:</p>
  			<source>&lt;querydefs name="standard" doc-element="options" 
    row-element="option" server="foo"/&gt;
  &lt;query defs="standard"/&gt;</source>
  			<p>is equivalent to</p>
  			<source>&lt;ldap-query doc-element="options" row-element="option" connection="foo"/&gt;</source>
  			<p>You can also flag a querydefs node as the default for all query tags by setting the default attribute to yes. Note that ldap-query tags can always override the defaults.</p>
  		</s1>
  		<s1 title="Usage">
  			<p>Add LDAP queries to your XML files. The tagset looks like this:</p>
  			<source>&lt;ldap-query server="foo_server"&gt;
   sn=*Green*
  &lt;/ldap-query&gt;</source>
  			<p>This will be replaced by a tagset that looks something like this:</p>
  			<source>&lt;ldapsearch&gt;
   &lt;searchresult ID="CN=DGREEN,OU=TBE,OU=AST,OU=ACAD,O=WSU"&gt;
    &lt;telephonenumber&gt;801-626-6821&lt;/telephonenumber&gt;
    &lt;facsimiletelephonenumber&gt;801-626-6650&lt;/facsimiletelephonenumber&gt;
    &lt;title&gt;PROFESSOR/TELECOMMUNICATIONS AND BUSINESS EDUCATION&lt;/title&gt;
    &lt;givenname&gt;Diana&lt;/givenname&gt;
    &lt;sn&gt;Green&lt;/sn&gt;
    &lt;l&gt;B2 218&lt;/l&gt;
    &lt;ou&gt;TELECOM &amp; BUSINESS ED &lt;/ou&gt;
    &lt;mail&gt;DGREEN@weber.edu&lt;/mail&gt;
    &lt;initials&gt;J&lt;/initials&gt;
    &lt;cn&gt;DGREEN&lt;/cn&gt;
    &lt;objectclass&gt;newPilotPerson&lt;/objectclass&gt;
    &lt;objectclass&gt;organizationalPerson&lt;/objectclass&gt;
    &lt;objectclass&gt;person&lt;/objectclass&gt;
    &lt;objectclass&gt;top&lt;/objectclass&gt;
   &lt;/searchresult&gt;
  &lt;/ldapsearch&gt;</source>
  			<p>You can also have the LdapProcessor substitute values from the servlet request into your query. The syntax for that is:</p>
  			<source>&lt;ldap-query name="foo_server"&gt;
   sn=*{@name}*
  &lt;/ldap-query&gt;</source>
  			<p>This is, of course, highly configurable by setting attributes of the query tag. A partial list of attributes is:</p>
  			<dl>
  				<dt>doc-element</dt>
  				<dd>The tag with which to wrap the whole shebang. Default is ldapresults. If an empty string is specified, e.g. doc-element="", the whole shebang will not be wrapped.</dd>
  				<dt>row-element</dt>
  				<dd>The tag with which to wrap each row. Default is searchresult. Same deal as with doc-element.</dd>
  				<dt>id-attribute</dt>
  				<dd>What is the name of the attribute that uniquely identifies the rows? Default is ID. This is, of course, meaningless if row-element is set to an empty string.</dd>
  				<dt>variable-left-delimiter</dt>
  				<dd>What string delimits variables in the query on the left side? Default is {@.</dd>
  				<dt>variable-right-delimiter</dt>
  				<dd>What string delimits variables in the query on the right side? Default is }.</dd>
  			</dl>
  		</s1>
  		<s1 title="Error Handling">
  			<p>In a perfect world, nothing would ever go wrong in your queries but this is not a perfect world. In our world, you can check for Exceptions in your stylesheets and present them to your users in a nice way. The tags used to render the error are configurable using attributes from the query tag. The attributes in question are:</p>
  			<dl>
  				<dt>error-element</dt>
  				<dd>The name of the error-element to create, default is error.</dd>
  				<dt>error-message-attribute</dt>
  				<dd>The name of the attribute of the error-element in which to put the Exception's message. Default is message.</dd>
  				<dt>error-message-element</dt>
  				<dd>The name of the child element of the error-element in which to put the Exception's message. The default is to not do so.</dd>
  				<dt>error-stacktrace-attribute</dt>
  				<dd>The name of the attribute of the error-element in which to put the Exception's stacktrace. The default is to not do so.</dd>
  				<dt>error-stacktrace-element</dt>
  				<dd>The name of the child element of the error-element in which to put the Exception's stacktrace. The default is to not do so.</dd>
  				<dt>error-message-text</dt>
  				<dd>The text to pass out as an error message instead of the Exception's own message. This is useful for displaying user friendly error messages. The default is to use the Exception's message.</dd>
  			</dl>
  			<p>So by default, when an Exception occurs, the processor generates this XML:</p>
  			<source>&lt;error message="The server is on fire."/&gt;</source>
  		</s1>
  		<s1 title="Notes and Disclaimers">
  			<p>The LdapProcessor was written borrowing a lot of ideas and code form Donald Ball's SQLProcessor.  Any similarity to his code is purely intended...:)  Thanks to Donald for writing good, clean code, and being a good sport about me plagerizing in the name of ultimate 'code re-use'.</p>
  		</s1>
  		<s1 title="Planned Features">
  			<ul>
  				<li>support for different context paramaters such as authtype, protocol, and principal.</li>
  				<li>the ability to retrieve binary objects such as certificates and images.</li>
  				<li>the ability to add different Contols such as a SortContorl for server side sorting.</li>
  			</ul>
  		</s1>
  	</body>
  </document>
  
  
  
  1.1                  xml-cocoon/xdocs/license.xml
  
  Index: license.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <!DOCTYPE document SYSTEM "./dtd/document-v10.dtd">
  
  <document>
   <header>
    <title>Cocoon Public License</title>
    <authors>
     <person name="Stefano Mazzocchi" email="stefano@apache.org"/>
    </authors>
   </header>
  
  <body>
  <s1 title="Cocoon Public License">
  <source><![CDATA[
   ============================================================================
                     The Apache Software License, Version 1.1
   ============================================================================
   
      Copyright (C) 1999 The Apache Software Foundation. All rights reserved.
   
   Redistribution and use in source and binary forms, with or without modifica-
   tion, are permitted provided that the following conditions are met:
   
   1. Redistributions of  source code must  retain the above copyright  notice,
      this list of conditions and the following disclaimer.
   
   2. Redistributions in binary form must reproduce the above copyright notice,
      this list of conditions and the following disclaimer in the documentation
      and/or other materials provided with the distribution.
   
   3. The end-user documentation included with the redistribution, if any, must
      include  the following  acknowledgment:  "This product includes  software
      developed  by the  Apache Software Foundation  (http://www.apache.org/)."
      Alternately, this  acknowledgment may  appear in the software itself,  if
      and wherever such third-party acknowledgments normally appear.
   
   4. The names "Cocoon" and  "Apache Software Foundation"  must not be used to
      endorse  or promote  products derived  from this  software without  prior
      written permission. For written permission, please contact
      apache@apache.org.
   
   5. Products  derived from this software may not  be called "Apache", nor may
      "Apache" appear  in their name,  without prior written permission  of the
      Apache Software Foundation.
   
   THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES,
   INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
   FITNESS  FOR A PARTICULAR  PURPOSE ARE  DISCLAIMED.  IN NO  EVENT SHALL  THE
   APACHE SOFTWARE  FOUNDATION  OR ITS CONTRIBUTORS  BE LIABLE FOR  ANY DIRECT,
   INDIRECT, INCIDENTAL, SPECIAL,  EXEMPLARY, OR CONSEQUENTIAL  DAMAGES (INCLU-
   DING, BUT NOT LIMITED TO, PROCUREMENT  OF SUBSTITUTE GOODS OR SERVICES; LOSS
   OF USE, DATA, OR  PROFITS; OR BUSINESS  INTERRUPTION)  HOWEVER CAUSED AND ON
   ANY  THEORY OF LIABILITY,  WHETHER  IN CONTRACT,  STRICT LIABILITY,  OR TORT
   (INCLUDING  NEGLIGENCE OR  OTHERWISE) ARISING IN  ANY WAY OUT OF THE  USE OF
   THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
   
   This software  consists of voluntary contributions made  by many individuals
   on  behalf of the Apache Software  Foundation and was  originally created by
   Stefano Mazzocchi  <stefano@apache.org>. For more  information on the Apache 
   Software Foundation, please see <http://www.apache.org/>.
  
  ]]></source>
  </s1>
  </body>
  </document>
  
  
  1.1                  xml-cocoon/xdocs/site-book.xml
  
  Index: site-book.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <book title="Cocoon documentation" copyright="1999 The Apache Software Foundation">
  
    <external href="../index.html"  label="Back"/>
  <separator/>
    <external href="../dist"  label="Download"/>
  <separator/>
    <page id="index" label="Index" source="index.xml"/>
    <page id="license" label="License" source="license.xml"/>
    <page id="install" label="Install" source="installing.xml"/>
  <separator/>
    <page id="technologies" label="Technologies" source="technologies.xml"/>
    <page id="guide" label="User Guide" source="guide.xml"/>
    <page id="dynamic" label="Dynamic Content" source="dynamic.xml"/>
  <separator/>
    <page id="xsp" label="XSP Processor" source="xspprocessor.xml"/>
    <page id="dcp" label="DCP Processor" source="dcpprocessor.xml"/>
    <page id="sql" label="SQL Processor" source="sqlprocessor.xml"/>
    <page id="ldap" label="LDAP Processor" source="ldapprocessor.xml"/>
  <separator/>
    <spec id="wd-xsp" label="XSP WD" source="WD-xsp.xml"/>
  <separator/>
    <external href="./api/index.html"  label="Javadocs"/>
  <separator/>
    <page id="cocoon2" label="Cocoon 2" source="cocoon2.xml"/>
    <page id="javadoc" label="Javadoc XML" source="javadoc.xml"/>
  <separator/>
    <faqs id="faqs" label="FAQ" source="faq.xml"/>
    <changes id="changes" label="Changes" source="changes.xml"/>
    <todo id="todo" label="Todo" source="todo.xml"/>
   
  </book>
  
  
  
  1.1                  xml-cocoon/xdocs/sqlprocessor.xml
  
  Index: sqlprocessor.xml
  ===================================================================
  <?xml version="1.0" encoding="utf-8"?>
  
  <!DOCTYPE document SYSTEM "./dtd/document-v10.dtd">
  
  <document><header><title>SQL Processor</title><authors><person name="Donald A. Ball Jr." email="balld@webslingerz.com"/></authors></header><body>
  
  	<s1 title="Description">
  		<p>SQLProcessor is a processor for Cocoon that performs SQL queries, translates the resultset into an XML fragment, and inserts the fragment in the original document. I wrote it because I've got quite a bit of "legacy" data in SQL databases that I wanted to be able to easily access from Cocoon. I believe that servers and data structures capable of storing and retrieving large amounts of XML data natively will arise, obviating the need for this type of middleware. I also believe that it's going to take a while for them to achieve the same performance and stability we've come to expect from SQL databases, hence the current need for SQLProcessor or something like it.</p>
  	</s1>
  
  	<s1 title="Installation">
  		<p>Check your cocoon.properties for this line and add it if it's not already there:</p>
  		<source>processor.type.sql = org.apache.cocoon.processor.sql.SQLProcessor</source>
  	</s1>
  
  	<s1 title="Configuration">
  		<p>Add this PI to the XML files to which you wish to add SQL queries:</p>
  		<source>&lt;?cocoon:process type="sql"?&gt;</source>
  		<p>You probably want this before any "xslt" processing directives. Then add SQL connection information to your XML files. The tagset for connection defitions looks like this:</p>
  		<source>&lt;connectiondefs&gt;
   &lt;connection name="foo_connection"&gt;
    &lt;driver&gt;org.gjt.mm.mysql.Driver&lt;/driver&gt;
    &lt;dburl&gt;jdbc:mysql://mysql.example.com/foo_database&lt;/dburl&gt;
    &lt;username&gt;foo_user&lt;/username&gt;
    &lt;password&gt;foo_password&lt;/password&gt;
   &lt;/connection&gt;
   ... other connections if desired ...
  &lt;/connectiondefs&gt;
  </source>
  		<p>Username and password are optional. This tagset will be removed from the document after processing. Multiple connectiondefs should be processed properly, but there's no good reason I can think of to do that. It's probably desirable to put the connectiondefs in a standalone XML file and link it in with external entities. The syntax for that is:</p>
  		<source>&lt;!DOCTYPE page [
   &lt;!ENTITY connection_defs SYSTEM "http://www.example.com/cdefs.xml"&gt;
  ]&gt;
  
  &lt;page&gt;
   &amp;connection_defs;
   ... other XML data ...
  &lt;/page&gt;</source>
  		<p>but this has the significant disadvantage that your database usernames and passwords are by default accessible from the WWW. You may wish to protect the cdefs.xml file by restricting access to the directory it lives in to the ip address(es) of your server(s).</p>
  		<p>The other warning here is that if cocoon is operating on the www.example.com site, it will try to process the cdefs.xml file before giving it to the XML parser. As long as cdefs.xml has no cocoon:process PI, you will not have any trouble but it will be somewhat slower than if cocoon is not involved. A simple trick to get around this is to rename the file to an extension that does not trigger cocoon. I use .sxml, shorthand for Source XML. Those of you with real operating systems can just make a link to the .xml file.</p>
  		<p>In addition to the connection element, you can also have querydefs tags in your connectiondefs node. A querydefs node must have a unique name attribute. query tags (described below) may reference a querydefs tag in their defs attribute, which causes the query tag's attributes to default to the attributes of the querydefs tag. This is useful for setting commonly used groups of attributes. You may also specify a default querydefs. Here is an example:</p>
  <source>&lt;querydefs name="standard" doc-element="options" 
    row-element="option" connection="foo"/&gt;
  &lt;query defs="standard"/&gt;</source>
  		<p>is equivalent to</p>
  		<source>&lt;query doc-element="options" row-element="option" connection="foo"/&gt;</source>
  		<p>You can also flag a querydefs node as the default for all query tags by setting the default attribute to yes. Note that query tags can always override the defaults.</p>
  	</s1>
  
  	<s1 title="Usage">
  		<p>Add SQL queries to your XML files. The tagset looks like this:</p>
  		<source>&lt;query connection="foo_connection"&gt;
   select name,number,message from foo_table order by name
  &lt;/query&gt;</source>
  		<p>This will be replaced by a tagset that looks like this:</p>
  		<source>&lt;ROWSET&gt;
   &lt;ROW ID="0"&gt;
    &lt;NAME&gt;Donald Ball&lt;/NAME&gt;
    &lt;NUMBER&gt;23&lt;/NUMBER&gt;
    &lt;MESSAGE&gt;
     The Illuminati do not exist. 
     This message paid for by the Illuminati.&lt;/MESSAGE
    &gt;
   &lt;/ROW&gt;
   ... other rows ...
  &lt;/ROWSET&gt;</source>
  		<p>You can also have SQLProcessor substitute values from the servlet request into your query. The syntax for that is:</p>
  		<source>&lt;query connection="foo_connection"&gt;
   select name,number,message from foo_table where id={@id} order by name
  &lt;/query&gt;</source>
  		<p>This is, of course, highly configurable by setting attributes of the query tag. A partial list of attributes is:</p>
  		<dl>
  			<dt>doc-element</dt><dd>The tag with which to wrap the whole shebang. Default is ROWSET. If an empty string is specified, e.g. doc-element="", the whole shebang will not be wrapped.</dd>
  			<dt>row-element</dt><dd>The tag with which to wrap each row. Default is ROW. Same deal as with doc-element.</dd>
  			<dt>tag-case</dt><dd>The case in which to present the column name tags. Default is "preserve", meaning use whatever the JDBC driver likes to call the columns. Options are "upper" for forced uppercase (boo) or "lower" for forced lowercase (yay).</dd>
  			<dt>null-indicator</dt><dd>What do we do with null columns. default is to not print anything for null columns, not even a column tag. If this is set to "y" or "yes", we add a NULL="YES" attribute to the column and put an empty string inside.</dd>
  			<dt>id-attribute</dt><dd>What is the name of the attribute that uniquely identifies the rows? Default is ID. This is, of course, meaningless if row-element is set to an empty string.</dd>
  			<dt>id-attribute-column</dt><dd>Which column should we use for the id attribute value (think primary key column). Default is to use the offset of this row in the query's resultset.</dd>
  			<dt>max-rows</dt><dd>How many rows should we display</dd>
  			<dt>skip-rows</dt><dd>How many rows should we skip before starting to display rows</dd>
  			<dt>variable-left-delimiter</dt><dd>What string delimits variables in the query on the left side? Default is {@.</dd>
  			<dt>variable-right-delimiter</dt><dd>What string delimits variables in the query on the right side? Default is }.</dd>
  		</dl>
  	</s1>
  
  	<s1 title="Creating Complex Queries">
  		<p>URL request parameter substitution using {@var} is fine for many situations, but is inadequate for handling queries whose conditions are dependent on the state of many variables. To accomodate these queries, you can specify the name of a subclass of SQLQueryCreator that will create the query string. The method that should be overridden is:</p>
  		<source>public String getQuery(Connection conn, String query, 
    Element query_element, Properties query_props, Hashtable parameters) 
    throws Exception;</source>
  		<p>This looks like a lot of parameters. I didn't figure that it made sense to deny any of the potential information available to the query creator. Just ignore what you don't care about. The parameters that deserve explanation are query_props, which is a Properties object containing all of the attribute values of the query tag, keyed by name. The parameters table is passed from cocoon to its processors, and contains lots of informatin, notable the original HttpServletRequest, keyed by the string "request".</p>
  		<p>You specify the particular subclass of SQLQueryCreator in the creator attribute of the query tag. It's probably easiest if you put your query creators in a package, e.g. com.webslingerZ.cocoon.ComplexQueryCreator.</p>
  		<p>One utility method is provided for your convenience. The SQLEscape method should parse a string for apostrophes and replace them with whichever string their database likes to use instead. It's not working correctly for my database drivers, so the default getQuery method does not use it. If anyone can suggest the correct way to go about doing this, please contact me with your suggestion or, ideally, a patch.</p>
  		<p>This is probably an overly complex way to handle most complex queries. It is hopefully the case that a more sophisticated variable substitution scheme or alternate attribute set will arise that accomodates more common complex queries without the need to write Java code. There is also some rationale for making SQLQueryCreator an interface. I welcome suggestions along these lines.</p>
  	</s1>
  
  	<s1 title="Error Handling">
  		<p>In a perfect world, nothing would ever go wrong in your queries but this is not a perfect world. In our world, you can check for SQLExceptions in your stylesheets and present them to your users in a nice way. The tags used to render the error are configurable using attributes from the query tag. The attributes in question are:</p>
  		<dl>
  			<dt>error-element</dt><dd>The name of the error-element to create, default is sqlerror.</dd>
  			<dt>error-message-attribute</dt><dd>The name of the attribute of the error-element in which to put the Exception's message. Default is message.</dd>
  			<dt>error-message-element</dt><dd>The name of the child element of the error-element in which to put the Exception's message. The default is to not do so.</dd>
  			<dt>error-stacktrace-attribute</dt><dd>The name of the attribute of the error-element in which to put the Exception's stacktrace. The default is to not do so.</dd>
  			<dt>error-stacktrace-element</dt><dd>The name of the child element of the error-element in which to put the Exception's stacktrace. The default is to not do so.</dd>
  			<dt>error-message-text</dt><dd>The text to pass out as an error message instead of the Exception's own message. This is useful for displaying user friendly error messages. The default is to use the Exception's message.</dd>
  		</dl>
  		<p>So by default, when an SQLException occurs, the processor generates this XML:</p>
  		<source>&lt;sqlerror message="The database server is on fire."/&gt;</source>
  	</s1>
  
  	<s1 title="Notes and Disclaimers">
  		<p>I sure hope this is useful to you. It's proving to be very useful to me. The DTD used here is a superset of that used by Oracle's XSQL servlet (which provides no methods for specifying alternate variable delimiters, creating complex queries, query default attributes, or error handling). Technical notes for the XSQL servlet are available - note you apparantly must now fill out an annoying survey to get access to this page. We're sharing the DTD with the tacit approval of Steve Meunch, who kindly pointed me in that direction when he saw a) how similar our methodologies were and b) how horrible my original DTD was. Thanks also go out to Stefano Mazzocchi, who started this whole cocoon business in the first place, and Ricardo Rocha, whose DCP processor provided the framework for SQLProcessor's parent, XMLResultSet. Stefano Malimpensa has suggested many useful features that are beginning to make their way into the code.</p>
  	</s1>
  
  	<s1 title="Planned Features">
  		<ul>
  			<li>support for a &lt;querydefs&gt; tag for setting default query attributes</li>
  			<li>time-based caching of query results</li>
  			<li>simple postprocessing of SQL values (e.g. date formats)</li>
  			<li>error message display</li>
  		</ul>
  	</s1>
  
  </body></document>
  
  
  
  1.1                  xml-cocoon/xdocs/technologies.xml
  
  Index: technologies.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <!DOCTYPE document SYSTEM "./dtd/document-v10.dtd">
  
  <document>
  <header>
    <title>Technologies Used</title>
    <authors>
      <person name="Stefano Mazzocchi" email="stefano@apache.org"/>
      <person name="Keith Visco" email="visco@exoffice.com"/>
    </authors>
  </header>
   
  <body>
  
  <s1 title="Introduction">
  
    <p>Since many people do not seem to understand the big picture of
    the technologies used by Cocoon, I will try to explain my vision of
    them.  I will also provide some information that I hope will enable
    you to jump right in, help with its development, or show your boss
    how much money can be saved using Cocoon.</p>
  
  </s1>
  
  <s1 title="What is this XML?">
  
    <p>XML (<link href="http://www.w3.org/XML/">eXtensible Markup
    Language</link>) is a subset of SGML (<link
    href="http://www.oasis-open.org/cover/general.html">Standard
    Generalized Mark-up Language</link>).  SGML is the grandparent of
    all markup languages and a 15-year-old <link
    href="http://www.iso.ch/">ISO</link> standard for creating
    languages.  You can think of XML as a lighter version of SGML.</p>
  
    <p>The first thing you must understand is that XML is <em>not</em> a
    language (like HTML), but a syntax, in the same way that ASCII
    defines a standard way to map characters to bytes rather than to
    character strings.</p>
  
    <p>XML is usually referred to as <em>portable data</em> in the sense
    that its parsing is <em>application independent</em>.  The same XML
    parser can read every possible XML document: one describing your
    bank account, another describing your favorite Italian meal,
    etc. This is, as you all know, impossible with other text-based or
    binary file formats.  A near-equivalent in the old days was CSV
    (comma separated values) files, which used a very simple syntax (one
    record per line, a comma separating fields, and the values in the
    first row naming the columns).  XML, unlike CSV, is much more
    flexible and structured, even though it's much simpler than SGML.</p>
  
    <p>A particular XML language is defined by its Document Type
    Definition (DTD).  DTDs are described in the XML specification.
    They describe the syntax of a language implemented in XML.  An XML
    document may be validated against a DTD (if present).  If the
    validation is successful the document is said to be <em>valid XML
    based on the particular DTD</em>.  If a DTD is not present and the
    parser does not encounter syntax errors parsing the file, the XML
    document is said to be <em>well-formed</em>. If errors are found,
    the document is not XML compliant.</p>
  
    <p>So, any valid XML document is <em>well-formed</em> and an XML
    document <em>valid</em> for one particular DTD may not necessarily
    be valid for another DTD.  For example, <link
    href="http://www.w3.org/TR/REC-html40/">HTML</link> is not an XML
    language because some tags such as <code>&lt;br&gt;</code> are not
    XML compliant.  In <link
    href="http://www.w3.org/TR/xhtml1/">XHTML</link>, an XML compliant
    reformulation of HTML, <code>&lt;br&gt;</code>, for example, is
    replaced with <code>&lt;br/&gt;</code>. While HTML pages are not
    always well-formed XML documents (some pages might be), XHTML pages
    are always well-formed and valid XML documents if they match the
    XHTML DTD.</p>
  
    <p>So much for the technical differences, but why was HTML not good
    enough?  Let's consider an example.</p>
  
  </s1>
  
  <s1 title="XML shows its power">
  
    <p>Consider how the need for XML came about:</p>
  
    <ul>
      <li>Everyone starts publishing HTML documents on the web.</li>
      <li>Search engines spring up across the net to help find documents.</li>
      <li>Search engines have a difficult time searching specific pieces of a
        document since HTML was designed to represent hierarchically how data
        should be presented, but not what data is being presented.</li>
      <li>Web applications spring up across the net to provide information and
        <em>services</em>.</li>
    </ul>
  
    <p>These services could be web pages that serve up important
    information about an organization or the structure of the
    organization. It could be weather information or travel
    advisories. It could be contact information for people. Stock
    quotes. It could a book on how to grow the perfect Tomato.</p>
  
    <p>So now we have all this information. Tons of it. Great! Now go
    and search all those web pages for specific content, like Author or
    Subject. Find me all abstracts of documents published on the subject
    of <em>Big Tomatoes</em>, since I only want to view abstracts to
    find the document best for me.  An HTML page is not designed for
    this. It was designed for <em>how to present</em> the data.</p>
  
    <p>When I look at a web page I might see that an author chose to
    make every heading bold with <code>&lt;font
    size="+1"&gt;</code>. Yet if I look at another page I might notice
    that every heading was marked up with <code>&lt;H1&gt;</code>.  Yet
    another page may use tables and table headers to format the
    data. Find me every document that has the word <em>potato</em> in
    the first heading.</p>
  
    <p>Suppose I have a web application that serves up weather
    information for different parts of the country. Let's say you live
    in Boston, MA and only want the local weather. Your boss asks you to
    write an application that goes out and grabs the two-to-three
    sentence weather summary from my application and display it on your
    intranet's homepage.</p>
  
    <p>You take a quick jaunt over to my weather application and notice
    that the summary is in what looks like the second paragraph of the
    page. So you take a quick peek at the HTML source that my weather
    application returns. You suddenly realize that it's all on one line
    and is buried deep within tables.</p>
  
    <p>So you start writing your little application to parse my HTML
    code to retrieve only the information you were looking for. You pat
    yourself on the back when&mdash;4 hours later&mdash;you finally get
    the information you were looking for.  Your code looks for the 2nd
    <code>TABLE</code>, the 6th <code>TR</code>, and then the 2nd
    <code>TD</code>. Phew. Your application, which really only wants to
    retrieve weather data, is forced to parse display markup to get
    it.</p>
  
    <p>You run over to your boss and demonstrate the application you are
    so proud of writing. Lo and behold it doesn't work.  What happened?
    The good old page author decided to change the layout and move the
    weather summary to <code>TABLE</code> 1, <code>TR</code> 1,
    <code>TD</code> 1. Your application breaks because it is tied to the
    presentation of the data and not to the data itself. Not very
    effective, since now your app will break every time the page author
    drinks too much coffee.</p>
  
    <p>Then you notice something on the page that interests you. The
    site is automatically generated from XML and you see a link that
    indicates there is an XML DTD for weather information. And another
    link that indicates the availability of an XML stream for weather
    information. Yikes, would you look at that:</p>
    
    <source><![CDATA[
     <weather-information>
      <location>
       <city>Boston</city>
       <state>MA</state>
      </location>
      <summary>
       Beautiful and Sunny, lows 50, highs 65, with the
       chance of a blizzard and gail force winds.
      </summary>
     </weather-information>
    ]]></source>
            
    <p>So you simply download Cocoon and quickly write an XSL stylesheet
    that looks like the following:</p>
    
    <source><![CDATA[
     <xsl:stylesheet>
      <xsl:template match="/">
       ... presentation info here ...
      </xsl:template>
      <xsl:tempate 
        match="weather-information[location/city = 'Boston']">
       <xsl:apply-templates select="summary"/>
      </xsl:template>
     </xsl:stylesheet>  
    ]]></source>
    
    <p>And your boss gives you your job back! ;-)</p>
  
  </s1>
  
  <s1 title="The HTML Model">
  
    <p>As the above example explains, HTML is a language for describing
    graphics, behavior, and hyperlinks on web pages. HTML is
    <em>not</em> able to <em>contextualize</em> (i.e. <em>give meaning
    to some text</em>).  For example, if you look for the <em>title</em>
    of a page, a nice HTML tag gives you that, but if you look for the
    author or version or something more specific like the author's mail
    address&mdash;even if this information is present in the
    text&mdash;you don't have a way to <em>isolate</em> it
    (contextualize it) from the surrounding information.</p>
  
    <p>In HTML like this</p>
  
    <source><![CDATA[
     <html>
      <head>
       <title>This is my article</title>
      </head>
      <body>
       <h1 align="center">This is my article</h1>
       <h3 align="center">
        by <a href="mailto:stefano@apache.org">
            Stefano Mazzocchi
           </a>
       </h3>
       ...
      </body>
     </html> 
    ]]></source>
  
    <p>you don't have a guaranteed way to extract the mail address.
    Whereas in the following XML document</p>
  
    <source><![CDATA[
     <?xml version="1.0"?>
     <page>
      <title>This is my article</title>
      <author>
       <name>Stefano Mazzocchi</name>
       <mail>stefano@apache.org</mail>
      </author>
      ...
     </page>
    ]]></source> 
  
    <p>it's trivial and algorithmically certain.</p>
  
    <p>We don't imagine XML overtaking HTML in web publishing since HTML
    is great for small needs. HTML was born as an SGML-based DTD for
    scientists' homepages, i.e. to parallelize and simplify the
    deployment and management of personal information. HTML was
    <em>not</em> designed for the publishing and processing of large
    quantities of data and complex dynamic information systems.</p>
  
  </s1>
  
  <s1 title="The XSL Language">
  
    <p>As you can see, XML alone is useless without some defined
    semantics: even if an application is able to parse a document, it
    must be able to <em>understand</em> what the markup means. This is
    why XML-only browsers are meaningless and not more useful than text
    editors from a usability point of view.</p>
  
    <p>This is one of the reasons why XSL (the <link
    href="http://www.w3.org/style/xsl/">eXtensible Stylesheet
    Language</link>) was proposed and designed. XSL is divided into two
    parts: <link href="http://www.w3.org/TR/xslt">transformation</link>
    (XSLT) and <link href="http://www.w3.org/TR/WD-xsl/">formatting
    objects</link> (sometimes referred to as FO, XSL:FO, or simply
    XSL). Both are XML DTDs that define a particular XML syntax, so
    every XSL or XSLT document is a well-formed XML document.</p>
  
  </s1>
  
  <s1 title="XSL Transformations (XSLT)">
  
    <p>XSLT is a language for transforming one well-formed XML document
    into something else (which may <em>not</em> necessarily be another
    XML document, although it most often will be). This means that you
    can use it to go from one DTD to another in a procedural way that is
    defined inside your XSLT document.  XSLT can be used in ways its
    name might not imply: a transformation may be applied to a document
    to generate a <em>graphical description</em> of its content. This is
    called <em>styling</em>, but, as you can imagine, it is just one of
    the possible uses of transformation technology.</p>
  
    <p>Back in the earlier example, the HTML file may have been
    generated from an XML file using <em>another</em> XML file as a
    transformation sheet (which in this case is a stylesheet).  The data
    is all there: we just have to tell the transformer how to come up
    with the HTML document once all the data is parsed.</p>
  
    <p>Usually, transformation sheets work from one DTD to another and
    in this way form a chain: transformA goes from DTD1 to DTD2 and
    transformB from DTD2 to DTD3 or graphically</p>
  
    <!-- FIXME (RAW): Any reason not to use &rarr; entities here? -->
    <source>DTD1 ---(transformA)--&gt; DTD2 ---(transformB)---&gt; DTD3</source>
  
    <p>We'll call DTD1 the <em>original DTD</em>, DTD2 some
    <em>intermediate DTD</em>, DTD3 the <em>final DTD</em>.  A
    transformation can always be created to go directly from DTD1 to
    DTD3, but this might be more complicated and less
    human-readable/manageable.</p>
  
  </s1>
  
  <s1 title="XSL Formatting Objects (XSL:FO)">
  
    <p>XSLFO is a language (an XML DTD) for describing 2D layout of text
    in both printed and digital media. I will not concentrate on the
    graphical abilities that formatting objects give you, but rather on
    the fact that it is mostly used as a <em>final DTD</em>, meaning
    that a transformation is used to generate a formatting object
    description of a document starting from a general XML file.</p>
  
    <p>An XSLFO document for our ongoing example would be</p>
  
    <source><![CDATA[
    <?xml version="1.0"?>
    <fo:root xmlns:fo="http://www.w3.org/XSL/Format/1.0">
     ...
     <fo:flow font-size="14pt" line-height="14pt">
      <fo:block 
          text-align="centered" 
          font-size="24pt" 
          line-height="28pt">This is my article</fo:block>
      <fo:block 
          space-before.optimum="12pt" 
          text-align="centered">by Stefano Mazzocchi</fo:block>
     </fo:flow>
    </fo:root>
    ]]></source> 
  
    <p>which tells the formatting object formatter (the rendering
    engine), how to <em>draw</em> and place the text on screen or on
    paper.</p>
  
    <p>XSL formatting objects and transformations are being specified by
    the same working group and have a lot of synergy, even though the
    XSLT specification also includes ways to create HTML and text from
    XML files.</p>
  
  </s1>
  
  <s1 title="The XSP Language">
  
    <p>The Cocoon publishing model is heavily based on the XSLT
    transformation capabilities.  XSLT allows complete separation of
    content and style (something that is much harder to obtain with
    HTML, even using CSS2 or other styling technologies).  But Cocoon
    goes further and defines a way of separating content and style from
    the programming logic that drives server side behavior.</p>
  
    <p>The XSP language (<connect href="WD-xsp.xml">eXtensible Server
    Pages</connect>) defines an XML DTD for separating content and logic
    for compiled server pages.  
  
    <!-- FIXME (RAW): I'm finding this sentence hard to parse and, since
         I don't yet myself have a handle on what exactly is "source"
         and "binary" in this context, I couldn't reformulate it
         effectively. -->
  
    XSP is, like XSLFO, supposed to be a <em>final DTD</em>, in that it
    is the result of one or more transformation steps and must be
    rendered by some formatter into pure source code which can then be
    compiled into binary code.</p>
  
    <p>In dynamic content generation technology, content and logic are
    combined: in every page there is a mix of static content and dynamic
    logic that work together to create the final result, usually using
    run-time or time-dependent input.  XSP is no exception, since it
    defines a syntax to mix static content and programmatic logic in a
    way that is independent of both the programming language used and
    the binary results that the final source-rendering generated.</p>
  
    <p>But it must be understood that XSP is just a piece of the
    framework: exactly like how formatting objects mix style and
    content, XSP objects mix logic and content. On the other hand, since
    both are XML DTDs, XSLT can be used to move from pure content to
    these final DTDs, placing the style and logic on the transformation
    layers and guaranteeing complete separation and easier
    maintenance.</p>
  
  </s1>
  </body>
  </document>
  
  
  
  
  1.1                  xml-cocoon/xdocs/xspprocessor.xml
  
  Index: xspprocessor.xml
  ===================================================================
  <?xml version="1.0"?>
  <!DOCTYPE document SYSTEM "./dtd/document-v10.dtd">
  
  <document>
    <header>
     <title>XSP Processor</title>
      <authors>
       <person name="Ricardo Rocha" email="ricardo@apache.org"/>
      </authors>
    </header>
  
    <body>
      <s1 title="Introduction">
        <p>
          <em>XSP</em>
           (<link href="http://xml.apache.org/cocoon/xsp.html">eXtensible Server Pages</link>)
          is Cocoon's technology for building web applications based on dynamic
          XML content.
        </p>
  
        <p>
          Beyond static content (i. e., hand-written documents produced
          by web authors), web applications demand <em>dynamic content
          generation</em> capabilities, where XML documents or fragments
          are programmatically produced at request time.
        </p>
  
        <p>
          In this context, content is the result of computations based on request
          parameters and, often, on access to external data sources such as
          databases or remote server processes.
        </p>
  
        <p>
          This distinction in content origin extends the &quot;traditional&quot;
          regions of web publishing (<em>content</em> and <em>presentation</em>)
          to also encompass that of <em>logic</em>.
        </p>
  
        <p>
          Dynamic web content generation has traditionally been addressed by
          embedding procedural code into otherwise static markup.
        </p>
  
        <p>
          This approach is fully supported by XSP. Consider the following example:
        </p>
  
        <source>. . .
  &lt;p&gt;
    Good
    &lt;xsp:logic&gt;
      String timeOfDay = (
        new SimpleDateFormat("aa")
      ).format(new Date());
  
      if (timeOfDay.equals("AM")) {
        &lt;xsp:content&gt;Morning&lt;/xsp:content&gt;
      } else {
        &lt;xsp:content&gt;Afternoon&lt;/xsp:content&gt;
      }
    &lt;/xsp:logic&gt;!
  &lt;/p&gt;
  . . .</source>
  
        <p>
          Upon XSP processing, this XML fragment will yield:
        </p>
  
        <source>&lt;p&gt;Good Morning!&lt;/p&gt;</source>
  
        <p>
          before noon and:
        </p>
  
        <source>&lt;p&gt;Good Afternoon!&lt;/p&gt;</source>
  
        <p>
          afterwards.
        </p>
  
        <p>
          While the above may appear simple (to a Java developer,
          that is!), XSP has been conceived to allow web authors
          to generate dynamic content without forcing them to learn
          a programming language.
        </p>
  
        <p>
          Thus, XSP allows us to rephrase our example as:
        </p>
  
        <source>...
  &lt;p&gt;Good &lt;util:time-of-day/&gt;!&lt;/p&gt;
  ...</source>
  
        <p>
          where <code>&lt;util:time-of-day/&gt;</code> is a
          <em>library tag</em> encapsulating dynamic content
          in a simple, transparent way.
        </p>
  
        <p>
          This feature promotes an ideal division of labor
          where:
        </p>
  
        <ul>
          <li>
            <em>Application Developers</em> encapsulate application
            logic in a consistent, intuitive dynamic tagset
          </li>
          <li>
            <em>Content authors</em> use an application-oriented
            markup vocabulary (augmented with dynamic tags) to
            produce XML documents
          </li>
          <li>
            <em>Presentation designers</em> write XSLT stylesheets
            to render the resulting content as visually appealing web
            pages
          </li>
        </ul>
  
        <p>
          Of course, for those of us subject to "real world" constraints,
          XSP also supports the time-honored approach of first using
          embedded logic and then incrementally evolving the resulting
          pages into a well-structured web application.
        </p>
  
        <p>
          These concepts are illustrated in the
  	<link href="http://www.plenix.com/xsp/samples/">XSP Samples</link>
  	included in the distribution.
        </p>
  
      </s1>
  
      <s1 title="What is an XSP Page?">
        <p>
          An XSP page is a Cocoon XML document containing tag-based
          directives that specify how to generate dynamic content
          at request time.
        </p>
  
        <p>
          Upon Cocoon processing, these directives are replaced by
          generated content so that the resulting, augmented XML
          document can be subject to further processing (typically
          an XSLT transformation)
        </p>
  
        <p>
          XSP pages are transformed into Cocoon <em>producers</em>,
          typically as Java classes, though any scripting language
          for which a Java-based processor exists could also be used.
        </p>
  
        <p>
          Directives can be either XSP built-in processing tags or
          user-defined library tags.
          XSP built-in tags are used to embed procedural logic,
          substitute expressions and dynamically build XML nodes.
          User-defined library tags act as templates that dictate
          how program code is generated from information encoded in
          each dynamic tag.
        </p>
      </s1>
  
      <s1 title="A Simple Example: Embedded Logic">
        <p>
          In the following XSP page, the Java language is used to
          generate some dynamic content:
        </p>
  
        <source>&lt;?xml version="1.0"?&gt;
  &lt;?cocoon-process type="xsp"?&gt;
  &lt;?cocoon-process type="xslt"?&gt;
  &lt;?xml-stylesheet href="sample.xsl" type="text/xsl"?&gt;
  
  &lt;xsp:page language="java" xmlns:xsp="http://www.apache.org/1999/XSP/Core"&gt;
    &lt;page title="Time of Day"&gt;
    
      &lt;xsp:logic&gt;
        // Define a variable to hold the time of day
        Date now = new Date();
      &lt;/xsp:logic&gt;
    
      &lt;p&gt;
        To the best of my knowledge, it's now
        &lt;!-- Substitute time of day here --&gt;
        &lt;xsp:expr&gt;now&lt;/xsp:expr&gt;
      &lt;/p&gt;
    &lt;/page&gt;
  &lt;/xsp:page&gt;</source>
  
        <p>
          Upon Cocoon processing, this page should yield something
          like:
        </p>
  
        <source>&lt;html&gt;
  &lt;head&gt;&lt;title&gt;Time of Day&lt;/title&gt;&lt;/head&gt;
  &lt;body&gt;
    &lt;h3 style="color: navy; text-align: center"&gt;Time of Day&lt;/h3&gt;
    &lt;p&gt;It's now Thu Dec 23 20:11:18 PST 1999&lt;/p&gt;
  &lt;/body&gt;
  &lt;/html&gt;</source>
  
        <p>
          Let's dissect this example:
        </p>
  
        <s2 title="The XSP Processing Instruction">
          <p>
            Two processing instructions are used in our example
            to control how Cocoon processes its XML content:
          </p>
  
          <ul>
            <li>
              <code>&lt;?cocoon-process type="xsp"?&gt;</code><br/>
              instructs Cocoon to generate a program (a 
              <em>producer</em>) that rebuilds the static portions
              of the document as augmented by the embedded logic
            </li>
            <li>
              <code>&lt;?cocoon-process type="xslt"?&gt;</code><br/>
              <code>&lt;?xml-stylesheet href="sample.xsl" type="text/xsl"?&gt;</code><br/>
              instructs Cocoon to apply the sample.xsl XSLT stylesheet to
              the XML tree resulting from executing the generated
              XSP producer program
            </li>
          </ul>
  
          <p>
            Note that it is <em>not</em> mandatory for an XSP page to
            be further processed by XSLT. Any (or none) other Cocoon XML
            processing step(s) may be subsequently applied depending on
            application requeriments.
          </p>
        </s2>
  
        <s2 title="The XSP Namespace">
          <p>
            All XSP directives belong to the <code>&lt;xsp:&gt;</code>
            namespace.
          </p>
  
          <p>
            Also, XSP pages are <em>required</em> to have an
            <code>&lt;xsp:page&gt;</code> root element:
          </p>
  
          <source>&lt;xsp:page language="java" xmlns:xsp="http://www.apache.org/1999/XSP/Core"&gt;</source>
  
          <p>
            The <code>&lt;xsp:page&gt;</code> root element can specify
            the programming language used in the XSP page by means of
            the <code>language</code> attribute. If this attribute is
            omitted, <em>java</em> will be used.
          </p>
  
          <p>
            The root element must also specify the XSP namespace URL
            by means of the <code>xmlns:</code> attribute. As will be
            explained later, this attribute is also used to introduce
            user-supplied tag libraries.
          </p>
  
          <p>
            Finaly, the XSP root element must contain <em>only one</em>
            non-XSP nested element. Such element (<code>&lt;page&gt;</code>
            in the above example) will become the root element of the
            generated document.
          </p>
        </s2>
  
        <s2 title="The Logic Tags">
          <p>
            In our example, the "user" root element contains:
          </p>
  
          <source>&lt;page title="Time of Day"&gt;
      &lt;xsp:logic&gt;
        // Define a variable to hold the time of day
        Date now = new Date();
      &lt;/xsp:logic&gt;
      &lt;p&gt;
        To the best of my knowledge, it's now
        &lt;!-- Substitute time of day here --&gt;
        &lt;xsp:expr&gt;now&lt;/xsp:expr&gt;
      &lt;/p&gt;
    &lt;/page&gt;</source>
  
          <p>
            Here, we use the two essential XSP logic tags:
          </p>
  
          <ul>
            <li>
              <code>&lt;xsp:logic&gt;</code>. This tag encloses
              developer-supplied program logic. Such logic will be
              transcribed verbatim into the generated Cocoon
              producer.
            </li>
            <li>
              <code>&lt;xsp:expr&gt;</code>. This tag evaluates
              a program expression and substitutes its value as
              a <code>Text</code> DOM node in the resulting
              document.
            </li>
          </ul>
  
          <p>
            In the fragment:
          </p>
  
          <source>&lt;xsp:logic&gt;
    // Define a variable to hold the time of day
    Date now = new Date();
  &lt;/xsp:logic&gt;</source>
  
          <p>
            a new variable (<code>now</code>) is declared that can
            be subsequently referenced anywhere in the remaining
            page content.
          </p>
  
          <p>
            Note that, in this particular example, it's not necessary
            to fully specify the Java type (<code>java.util.Date</code>)
            because XSP automatically generates <code>import</code>
            statements for the most commonly used Java libraries.
          </p>
  
          <p>
            In the fragment:
          </p>
  
          <source>&lt;!-- Substitute time of day here --&gt;
  &lt;xsp:expr&gt;now&lt;/xsp:expr&gt;</source>
  
          <p>
            the variable <code>now</code> is referenced so that its
            value is inlined in the resulting XML document as a
            <code>Text</code> node.
          </p>
  
          <p>
            Note also that it's not necessary to explicitly cast
            <code>now</code> to <code>String</code>.
            <code>&lt;xsp:expr&gt;</code> takes care
            of converting all Java types so that values are properly
            converted depending on context.
          </p>
  
          <p>
            In general, <code>&lt;xsp:expr&gt;</code> values are inlined
            according to the following rules:
          </p>
  
          <ul>
            <li>
              Primitive Java types (<code>int</code>, <code>long</code>,
              etc) are converted to their <code>String</code> representation
              and wrapped as <code>Text</code>
            </li>
            <li>
              Java objects are wrapped as follows:
                <ul>
                  <li>
                    <code>String</code>s are directly wrapped as
                    <code>Text</code>
                  </li>
                  <li>
                    Arrays are wrapped as <code>DocumentFragments</code>
                    and each element is recursively applied these same
                    transformation rules.
                  </li>
                  <li>
                    Non-string objects are converted to <code>String</code>
                    (by means of their <code>toString</code> method)
                    and subsquently wrapped as <code>Text</code>.
                    Note that some types may not provide a suitable
                    string representation, so they may require a
                    more elaborate expression
                  </li>
                </ul>
            </li>
          </ul>
  
          <p>
            A nice XSP feature (not present in other server pages
            technologies) is that the <code>&lt;xsp:logic&gt;</code>
            element allows for the arbitrary nesting of other markup
            without the need to "prematurely" close it. For example:
          </p>
  
          <source>&lt;table&gt;
    &lt;xsp:logic&gt;
      for (int i = 0; i &amp;lt; countries.length; i++) {
        &lt;tr&gt;
          &lt;td&gt;
            &lt;xsp:expr&gt;countries[i].getName()&lt;/xsp:expr&gt;
          &lt;/td&gt;
          &lt;td&gt;
            &lt;xsp:expr&gt;countries[i].getCurrency()&lt;/xsp:expr&gt;
          &lt;/td&gt;
        &lt;/tr&gt;
      }
    &lt;/table&gt;
  &lt;/xsp:logic&gt;</source>
  
          <p>
            If such nesting was not allowed, the purely programmatic
            alternative would be considerably more complex:
          </p>
  
          <source>
  &lt;table&gt;
    &lt;xsp:logic&gt;
      for (int i = 0; i &amp;lt; countries.length; i++) {
        // &lt;tr&gt;
        xspParentNode = xspCurrentNode;
        xspNodeStack.push(xspParentNode);
        xspCurrentNode = document.createElement("tr");
        xspParentNode.appendChild(xspCurrentNode);
  
        // &lt;td&gt;name&lt;/td&gt;
        xspParentNode = xspCurrentNode;
        xspNodeStack.push(xspParentNode);
        xspCurrentNode = document.createElement("td");
        xspParentNode.appendChild(xspCurrentNode);
        xspCurrentNode.appendChild(
          document.createTextNode(countries[i].getName())
        );
        xspCurrentNode = (Node) xspNodeStack.pop();
  
        // &lt;td&gt;currency&lt;/td&gt;
        xspParentNode = xspCurrentNode;
        xspNodeStack.push(xspParentNode);
        xspCurrentNode = document.createElement("td");
        xspParentNode.appendChild(xspCurrentNode);
        xspCurrentNode.appendChild(
          document.createTextNode(countries[i].getCurrency())
        );
        xspCurrentNode = (Node) xspNodeStack.pop();
  
        // &lt;/tr&gt;
        xspCurrentNode = (Node) xspNodeStack.pop();
      }
    &lt;/xsp:logic&gt;
  &lt;/table&gt;
  </source>
  
  	<p>
  	  Note, however, that it is <em>not</em> allowed to nest 
            <code>&lt;xsp:expr&gt;</code> tags directly inside
            <code>&lt;xsp:logic&gt;</code>. For an expression
  	  to be inlined inside an <code>&lt;xsp:logic&gt;</code>
  	  element, it must be escaped by surrounding it with an
            <code>&lt;xsp:content&gt;</code> tag. Example:
  	</p>
  
  	<source>
  &lt;xsp:logic&gt;
    for (int i = 0; i &amp;lt; parameterValues.length; i++) {
      &lt;xsp:content&gt;
        &lt;xsp:expr&gt;parameterValues[i]&lt;/xsp:expr&gt;
      &lt;/xsp:content&gt;
      &lt;br/&gt;
    }
  &lt;/xsp:logic&gt;
  </source>
  
          <p>
            The observant reader may have noticed a rather
            unpleasant feature in the above code: the
            <em>less-than</em> sign (<code>&lt;</code>)
            must be represented as <code>&amp;lt;</code>!
          </p>
  
          <p>
            This is an undesirable (but unavoidable) consequence
            of the <code>&lt;</code> and <code>&amp;</code>
            characters being special to XML parsers.
          </p>
  
          <p>
            A workaround is to escape code chunks contaning the
            <em>less-than</em> (<code>&lt;</code>) and
            <em>ampersand</em> (<code>&amp;</code>) characters as
            <em>CDATA</em> sections:
          </p>
  
          <source>&lt;table&gt;
    &lt;xsp:logic&gt;&lt;![CDATA[
      for (int i = 0; i &lt; countries.length; i++)]]&gt;
        &lt;tr&gt;
         . . .
        &lt;/tr&gt;
      }
    &lt;/table&gt;
  &lt;/xsp:logic&gt;</source>
  
          <p>
            Caution must be exercised, though, to avoid enclosing
            static markup inside the <code>&lt;![CDATA]]&gt;</code>
            section, as this will result in syntax errors upon
            compiling the generated Cocoon producer!
          </p>
        </s2>
  
      </s1>
  
      <s1 title="Another Example: Tag Libraries">
        <p>
          In the following example, a developer-supplied <em>tag
          library</em> is used instead of embedding procedural code:
        </p>
  
        <source>&lt;?xml version="1.0"?&gt;
  &lt;?cocoon-process type="xsp"?&gt;
  &lt;?cocoon-process type="xslt"?&gt;
  &lt;?xml-stylesheet href="sample.xsl" type="text/xsl"?&gt;
  
  &lt;xsp:page
    language="java"
    xmlns:xsp="http://www.apache.org/1999/XSP/Core"
    xmlns:example="http://www.plenix.com/DTD/XSP/Example"
  &gt;
    &lt;page title="Time of Day"&gt;
      &lt;p&gt;
        To the best of my knowledge, it's now
        &lt;!-- Substitute time of day here --&gt;
        &lt;example:time-of-day format="yy/MM/dd hh:mm:ss aa"/&gt;
      &lt;/p&gt;
    &lt;/page&gt;
  &lt;/xsp:page&gt;</source>
  
        <p>
          Here, the web author is shielded from programming
          complexities at the expense of additional developer
          effort in devising and implementing a proper dynamic
          tagset.
        </p>
  
        <p>
          As mentioned early, this is the "ideal" XSP scenario:
          dynamic content generation requirements are identified
          before hand and represented in reusable tag libraries.
          Web authors can then focus on their their "true"
          purpose in life: producing content.
        </p>
  
        <p>
          XSP uses XSLT stylesheets for source code generation.
          Thus, each dynamic tag in a library is supported by an
          XSLT template containing the program logic to be
          generated. Upon execution, generated logic will yield
          the dynamic content encoded by its underlying dynamic
          tag.
        </p>
  
        <p>
          Without yet delving into the finer details of the XSP
          object model, let's see how the <em>example</em> tag
          library stylesheet looks like:
        </p>
  
        <source>&lt;?xml version="1.0"?&gt;
  &lt;xsl:stylesheet
    xmlns:xsl="http://www.w3.org/XSL/Transform/1.0"
    xmlns:xsp="http://www.apache.org/1999/XSP/Core"
    xmlns:example="http://www.plenix.com/DTD/XSP/Example"
  &gt;
    &lt;xsl:template match="xsp:page"&gt;
      &lt;xsp:page&gt;
        &lt;xsl:copy&gt;
          &lt;xsl:apply-templates select="@*"/&gt;
        &lt;/xsl:copy&gt;
        &lt;xsp:structure&gt;
          &lt;xsp:include&gt;java.util.Date&lt;/xsp:include&gt;
          &lt;xsp:include&gt;java.text.SimpleDateFormat&lt;/xsp:include&gt;
        &lt;/xsp:structure&gt;
        &lt;xsp:logic&gt;
          /* "Example" Class Level Logic */
          private static String formatDate(Date date, String pattern) {
            if (pattern == null || pattern.length() == 0) {
              pattern = "yyyy/MM/dd hh:mm:ss aa";
            }
            return (new SimpleDateFormat(pattern)).format(date);
          }
        &lt;/xsp:logic&gt;
        &lt;xsl:apply-templates/&gt;
      &lt;/xsp:page&gt;
    &lt;/xsl:template&gt;
    &lt;xsl:template match="example:time-of-day"&gt;
      &lt;xsp:expr&gt;
        formatDate(new Date(), "&lt;xsl:value-of select="@format"/&gt;")
      &lt;/xsp:expr&gt;
    &lt;/xsl:template&gt;
    &lt;xsl:template match="@*|node()" priority="-1"&gt;
      &lt;xsl:copy&gt;&lt;xsl:apply-templates select="@*|node()"/&gt;&lt;/xsl:copy&gt;
    &lt;/xsl:template&gt;
  &lt;/xsl:stylesheet&gt;</source>
  
        <p>
          Let's focus our attention on 4 key features of
          this library:
        </p>
  
        <ul>
          <li>Namespace</li>
          <li>Structure</li>
          <li>Class-level logic</li>
          <li>Tag code templates</li>
        </ul>
  
        <s2 title="Library Namespace">
          <p>
            Each XSP library defines a <em>separate</em> XML
            namespace:
          </p>
  
          <source>xmlns:example="http://www.plenix.com/DTD/XSP/Example"</source>
  
          <p>
            Thus, all dynamic tags should belong to the same namespace
            associated with their defining library
          </p>
  
          <source>&lt;example:time-of-day format="hh:mm:ss"/&gt;</source>
  
          <p>
            While this discipline is not enforced by XSP, developers
            are strongly encouraged to follow this pattern because it
            prevents ambiguities and promotes document readability.
          </p>
        </s2>
  
        <s2 title="Program Structure">
          <p>
            The <code>&lt;xsp:structure&gt;</code> section provides
            the context for program-level declarations such
            as the Java <code>import</code> directive.
          </p>
  
          <source>&lt;xsp:structure&gt;
    &lt;xsp:include&gt;java.util.Date&lt;/xsp:include&gt;
    &lt;xsp:include&gt;java.text.SimpleDateFormat&lt;/xsp:include&gt;
  &lt;/xsp:structure&gt;</source>
  
          <p>
            The <code>&lt;xsp:structure&gt;</code> tag may contain
            zero or more <code>&lt;xsp:include&gt;</code> directives,
            each specifying an external program module to be made
            available to the generated XSP program.
          </p>
  
          <p>
            Note that the exact semantics of this elments is
            language-dependent. For Java, it corresponds to
            an <code>import</code> statement. For Fesi
            Javascript, for example, it may be interpreted as
            a <code>load()</code> function call.
          </p>
  
          <p>
            In our example, we're importing the
            <code>java.util.Date</code> and
            <code>java.text.SimpleDateFormat</code>
            class definitions.
          </p>
  
          <p>
            In all honesty, though, including
            <code>java.util.Date</code> is redundant because
            XSP always imports <code>java.util.*</code>. It's
            included here only to emphasize that the
            <em>example</em> library depends on it.
          </p>
  
          <p>
            <code>java.text.SimpleDateFormat</code>, on the other
            hand, <em>must</em> be included, because it's not among
            XSP's "preferred" Java packages.
          </p>
        </s2>
  
        <s2 title="Class-level logic">
          <p>
            In general, XSP class-level declarations (such as instance
            variables or methods) are defined by means of
            <code>&lt;xsp:logic&gt;</code> blocks
            <em>placed outside the user root element</em>.
          </p>
  
          <p>
            XSP libraries exploit this feature to declare class-level
            variables and methods used by code generated in reponse to
            the use of dynamic tags in XSP pages.
          </p>
  
          <p> 
            In our example, the following method is used to generate
            a <code>String</code> representation of the current system
            time:
          </p>
  
          <source>&lt;xsp:logic&gt;
    /* "Example" Class Level Logic */
    private static String formatDate(Date date, String pattern) {
      if (pattern == null || pattern.length() == 0) {
        pattern = "yyyy/MM/dd hh:mm:ss aa";
      }
      return (new SimpleDateFormat(pattern)).format(date);
    }
  &lt;/xsp:logic&gt;</source>
  
          <p>
            Dynamic tag templates may then refer to this method.
          </p>
        </s2>
  
        <s2 title="Tag Code template">
          <p>
            Finally, each dynamic tag must provide an associated
            XSLT template that dictates what source code must be
            generated whenever the tag is encountered in an XSP
            page.
          </p>
  
          <p>
            Note that the source code to be generated must be
            enclosed in either an <code>&lt;xsp:expr&gt;</code>
            or an <code>&lt;xsp:logic&gt;</code> element. This
            is so because these XSP tags will be later evaluated
            by the XSP built-in library (itself an XSLT stylesheet!)
          </p>
  
          <source>&lt;xsl:template match="example:time-of-day"&gt;
    &lt;xsp:expr&gt;
      formatDate(new Date(), "&lt;xsl:value-of select="@format"/&gt;")
    &lt;/xsp:expr&gt;
  &lt;/xsl:template&gt;</source>
  
          <p>
            In this example, each reference to a
            <code>&lt;example:time-of-day&gt;</code> tag
            will be replaced by a corresponding
            <code>&lt;xsp:expr&gt;</code> "call". Thus,
            if an XSP page using the <em>example</em>
            library contains:
          </p>
  
          <source>&lt;example:time-of-day format="hh:mm:ss"/&gt;</source>
  
          <p>
            XSP will expand this reference to:
          </p>
  
          <source>&lt;xsp:expr&gt;formatDate(new Date(), "hh:mm:ss")&lt;/xsp:expr&gt;</source>
  
          <p>
            during library processing. Upon source program
            generation this directive will be finally
            expanded
            to:
          </p>
  
          <source>
  xspCurrentNode.appendChild(
    xspExpr(
      formatDate(new Date(), "hh:mm:ss"),
      document
    )
  );
          </source>
  
          <p>
            where the <code>xspExpr()</code> built-in method is
            overloaded to wrap all possible Java types as a
            <code>Text</code> Node.
          </p>
  
          <p>
            Finicky developers may prefer to map dynamic tags to
            <em>bean</em> method calls, as opposed to inlining
            "raw" Java code.
          </p>
          
          <p>
            While some may consider this a matter of taste, using
            bean properties and methods <em>is</em> certainly
            advisable because it isolates library code from
            implementation details. This would allow, for instance,
            for a complex Enterprise Java Bean to be modified
            without impacting existing XSP pages.
          </p>
        </s2>
  
      </s1>
  
      <s1 title="The XSP Tagset">
        <s2 title="Tag List">
          <ul>
            <li>
              <code>&lt;xsp:page&gt;</code><br/>
              This element is the root of all XSP pages and
              specifies the scripting language and the tag
              libraries used by a particular XSP page
            </li>
            <li>
              <code>&lt;xsp:structure&gt;</code><br/>
              This top-level element encloses source
              program-level declarations such as
              <code>&lt;xsp:include&gt;</code>
            </li>
            <li>
              <code>&lt;xsp:include&gt;</code><br/>
              This element is used to import external
              module definitions in a language-dependent
              way
            </li>
            <li>
              <code>&lt;xsp:logic&gt;</code><br/>
              This element is used to embed procedural
              logic in an XSP page. Enclosed code is
              transcribed verbatim into the generated
              <code>XSPPage</code> producer. Other
              XSP or user markup may be nested inside
              this tag
            </li>
            <li>
              <code>&lt;xsp:content&gt;</code><br/>
              This element is used to embed "regular"
              XML content inside an
              <code>&lt;xsp:logic&gt;</code> block
              so that no nested additional
              <code>&lt;xsp:logic&gt;</code>
              sections are required
            </li>
            <li>
              <code>&lt;xsp:expr&gt;</code><br/>
              This element inlines a program
              expression as a <code>Text</code> node,
              except when used directly inside another
              <code>&lt;xsp:&gt;</code> element,
  	    where it is substituted as an
  	    expression, not a node. If you
  	    want to substitute an
              <code>&lt;xsp:expr&gt;</code> tag
  	    as a node inside another XSP
  	    tag, you must enclose it in an
              <code>&lt;xsp:content&gt;</code> element.
            </li>
            <li>
              <code>&lt;xsp:element&gt;</code><br/>
              This tag is used to dynamically build
              an element when its attribute values
              are not known at compile time
            </li>
            <li>
              <code>&lt;xsp:attribute&gt;</code><br/>
              This element is used to dynamically provide
              attribute values for a given element (which
              can be specified statically as markup or
              dynamically by means of
              <code>&lt;xsp:element&gt;</code>).
              This tag is typically used in conjunction
              with <code>&lt;xsp:expr&gt;</code>,
  	    where the substituted expression is
  	    always cast to <code>String</code>
            </li>
            <li>
              <code>&lt;xsp:pi&gt;</code><br/>
              This element is used to dynamically create
              a processing instruction.
            </li>
            <li>
              <code>&lt;xsp:comment&gt;</code><br/>
              This element is used to dynamically create
              an XML comment.
            </li>
          </ul>
        </s2>
  
        <s2 title="Notes on Tag Usage">
  
          <s3 title="&lt;xsp:page&gt;">
            <p>
              The <code>&lt;xsp:page&gt;</code> root element
              has an optional <code>language</code> attribute
              that defaults to <em>java</em>. Other scripting
              languages (both interpreted and compiled) will
              be supported in the near future.
            </p>
    
            <p>
              The <code>&lt;xsp:page&gt;</code> root element
              requires one or more <code>xmlns:</code> attributes
              specifying tag libraries. These attributes specify
              each tag library's DTD location as a URL.
            </p>
    
            <p>
              At least the built-in XSP (currently,
              <code>xmlns:xsp="http://www.apache.org/1999/XSP/Core"</code>)
              library must be specified.
            </p>
    
            <p>
              The order in which <code>xmlns:</code> attributes appear
              dictates library processing order. The XSP built-in
              library, though, is always applied last, regardless of its
              position in the <code>xmlns:</code> attribute list.
            </p>
      
            <p>
              The <code>&lt;xsp:page&gt;</code> element can only
              have <em>one</em> user element. This element
              becomes the root of the generated XML document.
            </p>
    
            <p>
              Only the following node types are valid as direct
              descendants of the <code>&lt;xsp:page&gt;</code>
              root element:
            </p>
    
            <ul>
              <li>
                Zero or more <code>&lt;xsp:structure&gt;</code>
                elements.
              </li>
              <li>
                Zero or more <code>&lt;xsp:logic&gt;</code>
                elements.
              </li>
              <li>
                The user root element: as in <em>Highlander</em>,
                there can be only one.
              </li>
            </ul>
    
            <p>
              <code>&lt;xsp:logic&gt;</code>
              blocks that are direct descendants of the
              <code>&lt;xsp:page&gt;</code> root element
              (i. e., placed <em>outside</em> the
              user root element) are generated as
              class-level logic. This is used for declaring
              class fields and methods.
            </p>
      
    
            <p>
              Top-level processing instructions (other than
              <code>&lt;?cocoon-process type="xsp"?&gt;</code>)
              are preserved in the generated XML document.
              This is convenient, for example, for subsequent
              XSLT processing.
            </p>
    
            <p>
              Some Java packages are always imported by
              default. As such, they do not require
              explicit <code>&lt;xsp:include&gt;</code>
              directives. These packages are:
            </p>
      
            <ul>
              <li><code>java.io.*;</code></li>
              <li><code>java.util.*;</code></li>
              <li><code>org.w3c.dom.*;</code></li>
              <li><code>org.xml.sax.*;</code></li>
              <li><code>javax.servlet.*;</code></li>
              <li><code>javax.servlet.http.*;</code></li>
              <li><code>org.apache.cocoon.parser.*;</code></li>
              <li><code>org.apache.cocoon.producer.*;</code></li>
              <li><code>org.apache.cocoon.framework.*;</code></li>
              <li><code>org.apache.cocoon.processor.xsp.*;</code></li>
            </ul>
          </s3>
    
          <s3 title="&lt;xsp:logic&gt; and &lt;xsp:content&gt;">
            <p>
              <code>&lt;xsp:content&gt;</code>
              can be used inside
              <code>&lt;xsp:logic&gt;</code>
              blocks to avoid the recursive nesting of
              additional <code>&lt;xsp:logic&gt;</code>
              elements. Thus, the following XSP fragment
              (which contains nested
              <code>&lt;xsp:logic&gt;</code> blocks):
            </p>
    
          <source>. . .
    &lt;p&gt;
      Good
        &lt;xsp:logic&gt;
          String timeOfDay = (new SimpleDateFormat("aa")).format(new Date());
          if (timeOfDay.equals("AM")) {
        &lt;/xsp:logic&gt;
      Morning
        &lt;xsp:logic&gt;
          } else {
        &lt;/xsp:logic&gt;
      Afternoon
        &lt;xsp:logic&gt;
          }
        &lt;/xsp:logic&gt;!
    &lt;/p&gt;
    . . .</source>
    
            <p>
              can be rewritten as:
            </p>
    
          <source>. . .
    &lt;p&gt;
      Good
      &lt;xsp:logic&gt;
        String timeOfDay = (new SimpleDateFormat("aa")).format(new Date());
    
        if (timeOfDay.equals("AM")) {
          &lt;xsp:content&gt;Morning&lt;/xsp:content&gt;
        } else {
          &lt;xsp:content&gt;Afternoon&lt;/xsp:content&gt;
        }
      &lt;/xsp:logic&gt;!
    &lt;/p&gt;
    . . .</source>
      
            <p>
              Note that this does not work in cases where a
              non-empty element would be "truncated" by an
              interspersed <code>&lt;xsp:logic&gt;</code>
              block. Thus, the following example cannot be
              reduced by means of <code>&lt;xsp:content&gt;</code>
            </p>
    
            <source>&lt;xsp:logic&gt;
      Enumeration enum = request.getParameterNames();
      while (enum.hasMoreElements()) {
        String parameterName = (String) enum.nextElement();
        String[] parameterValues =
          request.getParameterValues(parameterName);
      
        &lt;tr&gt;
          &lt;td valign="top"&gt;
            &lt;xsp:expr&gt;parameterName&lt;/xsp:expr&gt;
          &lt;/td&gt;
    
          &lt;!-- Trouble here --&gt;
          &lt;td&gt;
    
          &lt;xsp:logic&gt;
            for (int i = 0; i &amp;lt; parameterValues.length; i++) {
              &lt;xsp:content&gt;
                &lt;xsp:expr&gt;parameterValues[i]&lt;/xsp:expr&gt;
              &lt;/xsp:content&gt;
              &lt;br/&gt;
            }
          &lt;/xsp:logic&gt;
    
          &lt;/td&gt;
          &lt;!-- End trouble --&gt;
    
        &lt;/tr&gt;
      }
    &lt;/xsp:logic&gt;</source>
    
            <p>
              because the second <code>&lt;td&gt;</code> would be
              "cut short" by any intervening
              <code>&lt;xsp:content&gt;</code>.
            </p>
          </s3>
    
          <s3 title="&lt;xsp:element&gt; and &lt;xsp:attribute&gt;">
            <p>
              The <code>&lt;xsp:element&gt;</code> tag
              (which requires a <code>name</code> attribute)
              is used in those cases where the element
              name is known at compile time, but its
              attribute values are not. For example:
            </p>
  
            <source>&lt;xsp:logic&gt;
    for (int i = 0; i &amp;lt; languages.length; i++) {
     &lt;tr&gt;
       &lt;td&gt;
           &lt;img&gt;
             &lt;xsp:attribute name="src"&gt;img/
               &lt;xsp:expr&gt;languages[i].getCode()&lt;/xsp:expr&gt;
             .gif&lt;/xsp:attribute&gt;
           &lt;/img&gt;
       &lt;/td&gt;
       &lt;td&gt;
           &lt;xsp:expr&gt;languages[i].getName()&lt;/xsp:expr&gt;
       &lt;/td&gt;
     &lt;/tr&gt;
    }
  &lt;/xsp:logic&gt;</source>
  
            <p>
              Only XML text and <code>&lt;xsp:expr&gt;</code> are
              valid inside an <code>&lt;xsp:attribute&gt;</code>
              element.
            </p>
  
            <p>
              Note that whitespace is significant inside
              <code>&lt;xsp:attribute&gt;</code>
              so indenting <code>&lt;xsp:attribute&gt;</code>
              content may result in spurious space being
              generated. Unless you <em>really</em> need
              to generate spaces as part of the attribute
              value, resist the temptation to write something
              like:
            </p>
  
            <source>&lt;img&gt;
    &lt;xsp:attribute name="src"&gt;
      img/
      &lt;xsp:expr&gt;
        languages[i].getCode()
      &lt;/xsp:expr&gt;
      .gif
    &lt;/xsp:attribute&gt;
  &lt;/img&gt;</source>
  
            <p>
              Finally, if an element name is <em>not</em>
              known at compile time, you must programatically
              create it:
            </p>
  
            <source>&lt;xsp:logic&gt;
    String tagName = null;
    if (ordered) {
      tagName = "ol";
    } else {
      tagName = "ul";
    }
    xspParentElement = xspCurrentElement;
    xspNodeStack.push(xspParentElement);
    xspCurrentElement = document.createElement(tagName);
  &lt;/xsp:logic&gt;
  
    &lt;li&gt;Item 1&lt;/li&gt;
    &lt;li&gt;Item 2&lt;/li&gt;
    &lt;li&gt;Item 3&lt;/li&gt;
  
  &lt;xsp:logic&gt;
    xspCurrentElement = (Node) xspNodeStack.pop();
  &lt;/xsp:logic&gt;</source>
  
            <p>
              This may be alleviated in future XSP versions
              by introducing an idiom similar to the XSLT way
              of substituting dynamic expressions inside
              attributes values:
            </p>
  
            <source>&lt;xsp:element name='{ordered ? "ol" : "ul"}'&gt;
    &lt;li&gt;Item 1&lt;/li&gt;
    &lt;li&gt;Item 2&lt;/li&gt;
    &lt;li&gt;Item 3&lt;/li&gt;
  &lt;/xsp:element&gt;</source>
      
          </s3>
      
          <s3 title="&lt;xsp:pi&gt;">
            <p>
              The <code>&lt;xsp:pi&gt;</code> element
              requires a <code>target</code> attribute
              specifying the processing instruction name.
            </p>
  
            <p>
              <code>&lt;xsp:expr&gt;</code> is not yet
              supported to provide a value for a processing
              instruction's <em>data</em>. Only textual, constant
              values are allowed:
            </p>
  
            <source>&lt;xsp:pi name="cocoon-process"&gt;type="xslt"&lt;/xsp:pi&gt;</source>
      
            <p>
              In the future, <code>&lt;xsp:pi&gt;</code> may be
              renamed to <code>&lt;xsp:processing-instruction&gt;</code>
              to achieve compatibility with XSLT.
            </p>
          </s3>
      
          <s3 title="&lt;xsp:comment&gt;">
            <p>
              Note that dynamically created comments
              (<code>&lt;xsp:comment&gt;</code>)
              may be removed by subsequent XSLT processing.
            </p>
          </s3>
        </s2>
  
      </s1>
  
      <s1 title="The XSP Object Model">
  
        <s2 title="Processors and Producers">
        <p>
          A <em>processor</em> is a Cocoon Java type that
          takes a DOM tree as input and produces another
          (possibly modified) DOM tree as output. This
          concept is similar to that of a Unix "filter"
          in a command pipeline.
        </p>
  
        <p>
          The XSP engine is implemented as a Cocooon processor
          that accepts an XSP page as input.  The first time a
          given XSP page is processed, it is translated into an
          equivalent source program which is then compiled, loaded
          and executed. Subsequent requests for the same XSP page
          result in the execution of the generated program.
          As you may expect, the output DOM tree returned by the
          XSP engine processor is actually built by the generated
          program.
        </p>
  
        <p>
          XSP pages are compiled into Cocoon producers.
          A <em>producer</em> is a Cocoon Java type normally used to
          "feed" the initial XML content to the Cocoon processing
          pipeline.
          </p>
  
        <p>
            Thus, for example, when Cocoon serves a static, "regular"
            XML document, file contents are actually delivered by
          Cocoon's built-in <code>FileProducer</code>.
        </p>
  
          <p>
          Whereas other related server pages technologies (such as
          JSP) generate <em>servlets</em>, XSP generates producers
          instead. This is so because, among other reasons,
          the servlet model does not yet provide a mechanism for
          portably and efficiently post-processing XML content.
          </p>
        </s2>
  
        <s2 title="XSP Built-in Objects">
        <p>
          XSP defines an abstract producer (<code>XSPPage</code>)
          as the base class for generated programs.
        </p>
  
        <p>
          This class exposes a simple object model that can
          be easily used by XSP developers to programmatically
          control how XML content is generated.
        </p>
  
        <p>
          The following objects are accesible inside an XSP
          page:
        </p>
  
        <ul>
          <li>
            <code>request</code>.
            A Cocoon-supplied wrapper to the standard
            <code>HttpServletRequest</code> object.
            This wrapper provides all the functionality
            defined for its JSDK interface counterpart.
            This object is typically used to retrieve
            Http form parameters as well as to get
            header and cookie information.
          </li>
          <li>
            <code>response</code>.
            A Cocoon-supplied wrapper to the standard
            <code>HttpServletResponse</code> object.
            This wrapper provides most of the
            functionality defined for its JSDK
            interface counterpart,
            <em>except for access to the</em>
            <code>ServletOutputStream</code><em>object
            and its associated writer</em>.
            This restriction
            is necessary to ensure consistent Cocoon
            servlet output and does not impose any
            limitation to XML processing. Other suitable,
            non-output operations (such as setting headers,
            cookies or content types) are allowed
          </li>
          <li>
            <code>session</code>.
            The standard <code>HttpSession</code> servlet
            object. This object is typically used to
            store data associated with a user HTTP session
          </li>
          <li>
            <code>servletContext</code>.
            The standard <code>ServletContext</code>
            object. This object is typically used to
            store application-level data by means
            of its <code>setAttribute</code> and
            <code>getAttribute</code> methods. Other
            uses include determining the real path
            of a URL as dictated by the underlying web
            server virtual directory structure. Note
            that the application-level data sharing
            capabilities offered by this object are
            available only for JSDK version 2.2 and
            higher. To circumvent this for JSDK prior
            to 2.2, use the <code>xspGlobal</code>
            object (explained below)
          </li>
          <li>
            <code>document</code>.
            An XSP-supplied <code>org.w3c.Document</code>
            object.  Initially empty, this object is populated
            by the generated <code>XSPPage</code> producer
            and is typically used as a node factory
            (<code>document.createElement()</code>,
            <code>document.createProcessingInstruction()</code>,
            etc)
          </li>
          <li>
            <code>xspGlobal</code>.
            An XSP-supplied global dictionary offering
            the same <code>setAttribute</code> and
            <code>getAttribute</code> services supported
            by the standard <code>ServletContext</code>
            object. This surrogate exists only to provide
            application-level data sharing for older
            servlet engines (prior to 2.2). Note that,
            while providing a means for application-level
            data sharing for older servlet engines,
            such global data cannot be shared with non-Cocoon
            servlets or JSP pages. For this purpose, use
            the standard <code>servletContext</code> object.
            <code>xspGlobal</code> may be deprecated in future
            XSP versions
          </li>
          <li>
            <code>xspNodeStack</code>.
            A <code>java.util.Stack</code> used to control
            element nesting in the XSP page <code>Document</code>
            object. Extreme caution must be exercised in
            using this object as all DOM manipulations
            take effect on its top element. Note: 
            <code>java.util.Stack</code> was introduced
            in Java2. It should be replaced by an
            equivalent JDK1.1 implementation!
          </li>
          <li>
            <code>xspCurrentNode</code>.
            An <code>org.w3c.Node</code> object corresponding
            to the node being currently populated
          </li>
          <li>
            <code>xspParentNode</code>.
            An <code>org.w3c.Node</code> object corresponding
            to the parent of the node being currently
            populated. This object is normally the top element
            of the <code>xspNodeStack</code>
          </li>
          <li>
            <code>xspParser</code>.
            A Cocoon-supplied DOM parser which may be used
            to create new documents and parse external
            XML documents
          </li>
        </ul>
  
        <p>
          In addition to the above objects, the <code>XSPPage</code>
          contains an <code>xspExpr()</code> method than can be
          used to wrap any Java value as an <code>org.w3c.Text</code>
          object. Example:
        </p>
  
        <source>xspCurrentElement.appendChild(
    document.createTextNode("It's now ")
  );
  xspCurrentElement.appendChild(
    xspExpr(new Date())
  );
  </source>
       </s2>
  
       <s2 title="The XSP Util Class">
         <p>
           In addition to the above infrastructure objects and methods,
           XSP provides a utility class offering a number of DOM, HTTP
           and file manipulation services implemented as public
           static methods:
         </p>
  
         <s3 title="DOM Utility Methods">
           <ul>
             <li>
               <code>Node cloneNode(Node node, Document factory)</code>.<br/>
               This method performs a deep copy of its <code>node</code>
               argument using the <code>factory</code> document as the
               creator for the copied nodes. This is typically used to
               embed external XML documents into the XSP page
               <code>document</code> object. This is required because
               DOM Level 1 parsers do not allow for a node to be
               appended as child to another node if the two belong
               to different document instances
             </li>
             <li>
               <code>String toMarkup(Node node)</code>.<br/>
               This method generates an indented String representation
               of its <code>node</code> argument. This is typically
               used to embed a textual, non-DOM representation of
               external XML files as well as for debugging purposes
             </li>
           </ul>
         </s3>
  
         <s3 title="HTTP Utility Methods">
           <ul>
             <li>
               <code>String encodeMarkup(String string)</code>.<br/>
               This method scans its <code>string</code> argument
               replacing occurrences of markup delimiters as
               follows:<br/>
               1) <code>&lt;</code> is replaced by <code>&amp;lt;</code><br/>
               2) <code>&gt;</code> is replaced by <code>&amp;gt;</code><br/>
               3) <code>&amp;</code> is replaced by <code>&amp;amp;</code><br/>
             </li>
             <li>
               <code>String formEncode(String text)</code>.<br/>
               This method converts its <code>text</code> argument
               to <em>x-www-form-urlencode</em> format, as required
               by HTTP form query strings. This method is actually
               a wrapper for <code>java.net.URLEncoder.encode</code>
             </li>
             <li>
               <code>String formDecode(String text)</code>.<br/>
               This method converts its <code>text</code> argument
               from <em>x-www-form-urlencode</em> format to a
               <code>String</code> representation. This method is
               actually a wrapper for
               <code>java.net.URLDecoder.decode</code> (introduced
               in Java2) and exists solely to provide this
               functionality for JDK1.1
             </li>
           </ul>
         </s3>
    
         <s3 title="File Utility Methods">
           <ul>
             <li>
               <code>String pathComponent(String filename)</code>.<br/>
               This method interprets its <code>filename</code>
               argument as a file name and removes the last
               component to yield only the directory path
               information.
               This conversion is performed in an operating
               system-independent manner
             </li>
             <li>
               <code>String fileComponent(String filename)</code>.<br/>
               This method interprets its <code>filename</code>
               argument as a file name and removes the leading
               path component to yield only the file name
               portion, including the file name extension,
               if any.
               This conversion is performed in an operating
               system-independent manner
             </li>
             <li>
               <code>String baseName(String filename)</code>.<br/>
               This method interprets its <code>filename</code>
               argument as a file name and removes the leading
               path component to yield only the base file name
               <em>excluding</em> the last <em>dot</em> file
               extension, if any.
               This conversion is performed in an operating
               system-independent manner
             </li>
             <li>
               <code>String baseName(String filename, String suffix)</code>.<br/>
               This method interprets its <code>filename</code>
               argument as a file name and removes the leading
               path component to yield only the base file name
               <em>excluding</em> the last occurerence of the
               extension given by its
               <code>suffix</code> argument.
               This conversion is performed in an operating
               system-independent manner
             </li>
             <li>
               <code>String normalizedBaseName(String filename)</code>.<br/>
               This method interprets its <code>filename</code>
               argument as a file name and removes the leading
               path component to yield only the base file name
               <em>excluding</em> the last <em>dot</em> file
               extension, if any. The resulting filename is
               then scanned for non-alphanumeric characters
               which are replaced by <em>underscore</em>
               (<code>_</code>). An underscore is also
               preprended to each directory component.
               This is used to map file names to valid Java
               identifiers.
               This conversion is performed in an operating
               system-independent manner
             </li>
             <li>
               <code>String relativeFilename(String filename, HttpServletRequest request, ServletContext context)</code>.<br/>
               This method is used to build a fully qualified pathname
               for a <code>filename</code> relative to the <code>request</code>
               URI. This is typically used to open operating system files
               given a name relative to the request's virtual path
             </li>
             <li>
               <code>String relativeFilename(String filename, HttpServletRequest request)</code>.<br/>
               This method is used to build a fully qualified pathname
               for a <code>filename</code> relative to the <code>request</code>
               URI. This is typically used to open operating system files
               given a name relative to the request's virtual path. This
               variant depends on the deprecated
               <code>HttpServletRequest.getRealPath</code> method and
               exists only for compatibility with older JSDK's in which
               the <code>ServletContext</code> object did not provide
               a <code>getRealPath()</code> method
             </li>
           </ul>
         </s3>
    
         <s3 title="String Utility Methods">
           <ul>
             <li>
               <code>String[] split(String line)</code>.<br/>
               This method converts its <code>line</code> string
               argument to a <code>String</code> array using
               whitespace (blanks, tabs, carriage returns and
               newlines) as field separators
             </li>
             <li>
               <code>String[] split(String line, String delimiter)</code>.<br/>
               This method converts its <code>line</code> string
               argument to a <code>String</code> array using
               the characters in its <code>delimiter</code>
               argument as field separators
             </li>
             <li>
               <code>boolean isAlphaNumeric(char c)</code>.<br/>
               This method tests its <code>c</code> argument to
               assert whether it is an underscore, a lowercase or
               uppercase letter or a digit
             </li>
           </ul>
         </s3>
  
       </s2>
      </s1>
  
      <s1 title="Other Scripting Languages">
        <p>
          XSP has been designed to support other scripting
  	languages, in addition to Java. In principle, any
  	programming language for which a Java-based
  	interpreter exists could be used to script
  	XSP pages.
        </p>
  
        <p>
          In general, languages supporting compilation to
  	bytecodes, such as Java itself, Netscape's
  	<link href="http://www.mozilla.org/rhino/">Rhino Javascript</link>
  	or IBM's
  	<link href="http://www2.hursley.ibm.com/netrexx/">NetRexx</link>,
  	perform significantly better than interpreted
  	languages like
  	<link href="http://home.worldcom.ch/jmlugrin/fesi/">FESI Javascript</link>
  	or
  	<link href="http://www.research.digital.com/SRC/WebL/">WebL</link>.
        </p>
  
        <p>
          Interpreted languages, however, are expected to
  	play an important role in XSP scripting.
  	This is so because (in addition to their typical
  	ease of use) more and more field-specialized
  	languages are being developed for the JVM.
          Such specialized scripting languages usually
  	offer more expressive power and conciseness
  	than strictly object-oriented languages.
        </p>
  
        <p> 
          For a fairly complete list of such languages
  	see
  	<link href="http://grunge.cs.tu-berlin.de/~tolk/vmlanguages.html">Programming Languages for the Java Virtual Machine</link>.
        </p>
  
        <p>
  	Until recently, Java lacked a well-defined
  	scripting architecture that allowed applications
  	to incorporate scripting easily.
  	IBM's
  	<link href="http://www.alphaworks.ibm.com/tech/bsf">Bean Scripting Framework</link>
  	(BSF) is an Alphaworks project providing such architecture.
        </p>
  
        <p>
          BSF supports a growing number of
  	scripting languages including
  	<link href="http://www.mozilla.org/rhino/">Rhino</link>,
  	<link href="http://www2.hursley.ibm.com/netrexx/">NetRexx</link>,
  	<link href="http://www.scriptics.com/java">Jacl</link>
  	and
  	<link href="http://www.jpython.org">JPython</link>.
  	On the Windows platform,
  	BSF also supports
  	<link href="http://msdn.microsoft.com/scripting/default.htm?/scripting/jscript/default.htm">JScript</link>,
  	<link href="http://msdn.microsoft.com/scripting/default.htm?/scripting/vbscript/default.htm">VBScript</link>,
  	and
  	<link href="http://www.activestate.com/activeperl">PerlScript</link>.
        </p>
  
        <p>
          Currently, XSP only supports Java as a scripting language,
  	though its design allows for an easy integration of
  	other languages.
        </p>
  
        <p>
  	In the near future, BSF will be integrated to XSP's own
  	language abstraction mechanism so that most (if not all)
  	of the above mentioned languages may become available
  	for XSP scripting.
        </p>
  
        <p>
          XSP tag libraries are language-dependent. Thus, the
  	addition of a new language involves (at the very
  	least) porting the XSP built-in libraries. An XSP library is 
  	composed of a code-generation XSLT sylesheet and an 
  	optional <em>library preprocessor</em> class.
        </p>
  
        <p>
          A library's code-generation stylesheet is simply a
  	"regular" XSLT stylesheet responsible for translating
  	user-defined dynamic tags into equivalent XSP tags
  	for a given scripting language (sometimes called <em>logicsheet</em>). 
  	While a preprocessor is an optional library Java class
  	used to augment an XSP page DOM tree prior to
  	applying the library code-generation stylesheet.
        </p>
  
        <p>
          Library preprocessors <em>may</em> be
  	language-dependent. Early experience
  	suggests, though, that the same preprocessor
  	class will be typically shared by different
  	languages for the same dynamic tagset.
        </p>
  
        <p>
          XSLT <em>extension functions</em> and
  	<em>extension elements</em> may replace
  	library preprocessors in the future. In
  	this case, all code-generation logic would
  	reside in the library's stylesheet.
        </p>
        
        <p>
         At this early development stage, we still don't know how the
         implementation will evolve and we look forward for public feedback
         before going any further along with the implementation details.
        </p>
      </s1>
  
      <s1 title="Acknowledgements">
        <p>
          This initial implementation of XSP has
  	been developed by
  	<link href="http://www.exolab.org/">Exolab</link>
  	and is being donated to the
  	Apache project as part of Exoffice's
  	commitment to the open source movement.
        </p>
  
        <p>
          Special thanks must be given to
  	<link href="mailto:ghalimi@exoffice.com">Ismael Ghalimi</link>
  	for sponsoring and supporting XSP development.
        </p>
  
        <p>
          Last, but not least, cheers to
  	<link href="mailto:stefano@apache.org">Stefano Mazzocchi</link>,
  	founder and leader of the Cocoon project and original author of
  	the XSP specification. Thanks!!!
        </p>
      </s1>
  
    </body>
  </document>
  
  
  
  1.1                  xml-cocoon/xdocs/dtd/changes-v10.dtd
  
  Index: changes-v10.dtd
  ===================================================================
  <!-- ===================================================================
       
       Apache Changes DTD (Version 1.0)
  
  PURPOSE:
    This DTD was developed to create a simple yet powerful document 
    type for software development changes for use with the Apache projects.  
    It is an XML-compliant DTD and it's maintained by the Apache XML 
    project.
  
  TYPICAL INVOCATION:
  
    <!DOCTYPE document PUBLIC
         "-//APACHE//DTD Changes Vx.yz//EN"
         "http://xml.apache.org/DTD/changes-vxyz.dtd">
  
    where 
    
      x := major version
      y := minor version
      z := status identifier (optional)
        
  NOTES:  
    It is important, expecially in open developped software projects, to keep
    track of software changes both to give users indications of bugs that might
    have been resolved, as well, and not less important, to provide credits
    for the support given to the project. It is considered vital to provide
    adequate payback using recognition and credits to let users and developers
    feel part of the community, thus increasing development power.
  
  AUTHORS:
    Stefano Mazzocchi <stefano@apache.org>
    
  FIXME:
  
  CHANGE HISTORY:
    19991129 Initial version. (SM)
      
  COPYRIGHT:
    Copyright (c) 1999 The Apache Software Foundation.
    
    Permission to copy in any form is granted provided this notice is 
    included in all copies. Permission to redistribute is granted 
    provided this file is distributed untouched in all its parts and 
    included files.
    
  ==================================================================== -->
  
  <!-- =============================================================== -->
  <!-- Extend the Documentation DTD -->
  <!-- =============================================================== -->
  
  <!-- FIXME (SM): this is hardcoding. Find a better way of doing this
       possibly using public identifiers -->
  <!ENTITY % document-dtd SYSTEM "document-v10.dtd">
  %document-dtd;
  
  <!-- =============================================================== -->
  <!-- Common entities -->
  <!-- =============================================================== -->
  
  <!ENTITY % types "add|remove|update|fix">
  
  <!-- =============================================================== -->
  <!-- Document Type Definition -->
  <!-- =============================================================== -->
  
  <!ELEMENT changes (devs, release*)>
  <!ATTLIST changes %common.att; 
                    %title.att;>
  
      <!ELEMENT devs (person+)>
      <!ATTLIST devs %common.att;>
  
      <!ELEMENT release (action+)>
      <!ATTLIST release %common.att;
                        version  CDATA  #REQUIRED
                        date     CDATA  #REQUIRED>
      
          <!ELEMENT action (%content.mix;)*>
          <!ATTLIST action %common.att;
                           dev  IDREF  #REQUIRED
                           type (%types;)  #IMPLIED
                           due-to CDATA #IMPLIED
                           due-to-email CDATA #IMPLIED>
      
  <!-- =============================================================== -->
  <!-- End of DTD -->
  <!-- =============================================================== -->
  
  
  
  1.1                  xml-cocoon/xdocs/dtd/characters.ent
  
  Index: characters.ent
  ===================================================================
  <!-- 
       Portions (C) International Organization for Standardization 1986
       Permission to copy in any form is granted for use with
       conforming SGML systems and applications as defined in
       ISO 8879, provided this notice is included in all copies.
  -->
  
  <!-- 
       Character entity set.
  -->
  
  <!-- Latin A -->
  <!ENTITY nbsp     "&#160;">  <!-- U+00A0 ISOnum    - no-break space = non-breaking space                                   -->
  <!ENTITY iexcl    "&#161;">  <!-- U+00A1 ISOnum    - inverted exclamation mark                                             -->
  <!ENTITY cent     "&#162;">  <!-- U+00A2 ISOnum    - cent sign                                                             -->
  <!ENTITY pound    "&#163;">  <!-- U+00A3 ISOnum    - pound sign                                                            -->
  <!ENTITY curren   "&#164;">  <!-- U+00A4 ISOnum    - currency sign                                                         -->
  <!ENTITY yen      "&#165;">  <!-- U+00A5 ISOnum    - yen sign = yuan sign                                                  -->
  <!ENTITY brvbar   "&#166;">  <!-- U+00A6 ISOnum    - broken bar = broken vertical bar                                      -->
  <!ENTITY sect     "&#167;">  <!-- U+00A7 ISOnum    - section sign                                                          -->
  <!ENTITY uml      "&#168;">  <!-- U+00A8 ISOdia    - diaeresis = spacing diaeresis                                         -->
  <!ENTITY copy     "&#169;">  <!-- U+00A9 ISOnum    - copyright sign                                                        -->
  <!ENTITY ordf     "&#170;">  <!-- U+00AA ISOnum    - feminine ordinal indicator                                            -->
  <!ENTITY laquo    "&#171;">  <!-- U+00AB ISOnum    - left-pointing double angle quotation mark = left pointing guillemet   -->
  <!ENTITY not      "&#172;">  <!-- U+00AC ISOnum    - not sign                                                              -->
  <!ENTITY shy      "&#173;">  <!-- U+00AD ISOnum    - soft hyphen = discretionary hyphen                                    -->
  <!ENTITY reg      "&#174;">  <!-- U+00AE ISOnum    - registered sign = registered trade mark sign                          -->
  <!ENTITY macr     "&#175;">  <!-- U+00AF ISOdia    - macron = spacing macron = overline = APL overbar                      -->
  <!ENTITY deg      "&#176;">  <!-- U+00B0 ISOnum    - degree sign                                                           -->
  <!ENTITY plusmn   "&#177;">  <!-- U+00B1 ISOnum    - plus-minus sign = plus-or-minus sign                                  -->
  <!ENTITY sup2     "&#178;">  <!-- U+00B2 ISOnum    - superscript two = superscript digit two = squared                     -->
  <!ENTITY sup3     "&#179;">  <!-- U+00B3 ISOnum    - superscript three = superscript digit three = cubed                   -->
  <!ENTITY acute    "&#180;">  <!-- U+00B4 ISOdia    - acute accent = spacing acute                                          -->
  <!ENTITY micro    "&#181;">  <!-- U+00B5 ISOnum    - micro sign                                                            -->
  <!ENTITY para     "&#182;">  <!-- U+00B6 ISOnum    - pilcrow sign = paragraph sign                                         -->
  <!ENTITY middot   "&#183;">  <!-- U+00B7 ISOnum    - middle dot = Georgian comma = Greek middle dot                        -->
  <!ENTITY cedil    "&#184;">  <!-- U+00B8 ISOdia    - cedilla = spacing cedilla                                             -->
  <!ENTITY sup1     "&#185;">  <!-- U+00B9 ISOnum    - superscript one = superscript digit one                               -->
  <!ENTITY ordm     "&#186;">  <!-- U+00BA ISOnum    - masculine ordinal indicator                                           -->
  <!ENTITY raquo    "&#187;">  <!-- U+00BB ISOnum    - right-pointing double angle quotation mark = right pointing guillemet -->
  <!ENTITY frac14   "&#188;">  <!-- U+00BC ISOnum    - vulgar fraction one quarter = fraction one quarter                    -->
  <!ENTITY frac12   "&#189;">  <!-- U+00BD ISOnum    - vulgar fraction one half = fraction one half                          -->
  <!ENTITY frac34   "&#190;">  <!-- U+00BE ISOnum    - vulgar fraction three quarters = fraction three quarters              -->
  <!ENTITY iquest   "&#191;">  <!-- U+00BF ISOnum    - inverted question mark = turned question mark                         -->
  <!ENTITY Agrave   "&#192;">  <!-- U+00C0 ISOlat1   - latin capital letter A with grave = latin capital letter A grave      -->
  <!ENTITY Aacute   "&#193;">  <!-- U+00C1 ISOlat1   - latin capital letter A with acute                                     -->
  <!ENTITY Acirc    "&#194;">  <!-- U+00C2 ISOlat1   - latin capital letter A with circumflex                                -->
  <!ENTITY Atilde   "&#195;">  <!-- U+00C3 ISOlat1   - latin capital letter A with tilde                                     -->
  <!ENTITY Auml     "&#196;">  <!-- U+00C4 ISOlat1   - latin capital letter A with diaeresis                                 -->
  <!ENTITY Aring    "&#197;">  <!-- U+00C5 ISOlat1   - latin capital letter A with ring above = latin capital letter A ring  -->
  <!ENTITY AElig    "&#198;">  <!-- U+00C6 ISOlat1   - latin capital letter AE = latin capital ligature AE                   -->
  <!ENTITY Ccedil   "&#199;">  <!-- U+00C7 ISOlat1   - latin capital letter C with cedilla                                   -->
  <!ENTITY Egrave   "&#200;">  <!-- U+00C8 ISOlat1   - latin capital letter E with grave                                     -->
  <!ENTITY Eacute   "&#201;">  <!-- U+00C9 ISOlat1   - latin capital letter E with acute                                     -->
  <!ENTITY Ecirc    "&#202;">  <!-- U+00CA ISOlat1   - latin capital letter E with circumflex                                -->
  <!ENTITY Euml     "&#203;">  <!-- U+00CB ISOlat1   - latin capital letter E with diaeresis                                 -->
  <!ENTITY Igrave   "&#204;">  <!-- U+00CC ISOlat1   - latin capital letter I with grave                                     -->
  <!ENTITY Iacute   "&#205;">  <!-- U+00CD ISOlat1   - latin capital letter I with acute                                     -->
  <!ENTITY Icirc    "&#206;">  <!-- U+00CE ISOlat1   - latin capital letter I with circumflex                                -->
  <!ENTITY Iuml     "&#207;">  <!-- U+00CF ISOlat1   - latin capital letter I with diaeresis                                 -->
  <!ENTITY ETH      "&#208;">  <!-- U+00D0 ISOlat1   - latin capital letter ETH                                              -->
  <!ENTITY Ntilde   "&#209;">  <!-- U+00D1 ISOlat1   - latin capital letter N with tilde                                     -->
  <!ENTITY Ograve   "&#210;">  <!-- U+00D2 ISOlat1   - latin capital letter O with grave                                     -->
  <!ENTITY Oacute   "&#211;">  <!-- U+00D3 ISOlat1   - latin capital letter O with acute                                     -->
  <!ENTITY Ocirc    "&#212;">  <!-- U+00D4 ISOlat1   - latin capital letter O with circumflex                                -->
  <!ENTITY Otilde   "&#213;">  <!-- U+00D5 ISOlat1   - latin capital letter O with tilde                                     -->
  <!ENTITY Ouml     "&#214;">  <!-- U+00D6 ISOlat1   - latin capital letter O with diaeresis                                 -->
  <!ENTITY times    "&#215;">  <!-- U+00D7 ISOnum    - multiplication sign                                                   -->
  <!ENTITY Oslash   "&#216;">  <!-- U+00D8 ISOlat1   - latin capital letter O with stroke = latin capital letter O slash     -->
  <!ENTITY Ugrave   "&#217;">  <!-- U+00D9 ISOlat1   - latin capital letter U with grave                                     -->
  <!ENTITY Uacute   "&#218;">  <!-- U+00DA ISOlat1   - latin capital letter U with acute                                     -->
  <!ENTITY Ucirc    "&#219;">  <!-- U+00DB ISOlat1   - latin capital letter U with circumflex                                -->
  <!ENTITY Uuml     "&#220;">  <!-- U+00DC ISOlat1   - latin capital letter U with diaeresis                                 -->
  <!ENTITY Yacute   "&#221;">  <!-- U+00DD ISOlat1   - latin capital letter Y with acute                                     -->
  <!ENTITY THORN    "&#222;">  <!-- U+00DE ISOlat1   - latin capital letter THORN                                            -->
  <!ENTITY szlig    "&#223;">  <!-- U+00DF ISOlat1   - latin small letter sharp s = ess-zed                                  -->
  <!ENTITY agrave   "&#224;">  <!-- U+00E0 ISOlat1   - latin small letter a with grave = latin small letter a grave          -->
  <!ENTITY aacute   "&#225;">  <!-- U+00E1 ISOlat1   - latin small letter a with acute                                       -->
  <!ENTITY acirc    "&#226;">  <!-- U+00E2 ISOlat1   - latin small letter a with circumflex                                  -->
  <!ENTITY atilde   "&#227;">  <!-- U+00E3 ISOlat1   - latin small letter a with tilde                                       -->
  <!ENTITY auml     "&#228;">  <!-- U+00E4 ISOlat1   - latin small letter a with diaeresis                                   -->
  <!ENTITY aring    "&#229;">  <!-- U+00E5 ISOlat1   - latin small letter a with ring above = latin small letter a ring      -->
  <!ENTITY aelig    "&#230;">  <!-- U+00E6 ISOlat1   - latin small letter ae = latin small ligature ae                       -->
  <!ENTITY ccedil   "&#231;">  <!-- U+00E7 ISOlat1   - latin small letter c with cedilla                                     -->
  <!ENTITY egrave   "&#232;">  <!-- U+00E8 ISOlat1   - latin small letter e with grave                                       -->
  <!ENTITY eacute   "&#233;">  <!-- U+00E9 ISOlat1   - latin small letter e with acute                                       -->
  <!ENTITY ecirc    "&#234;">  <!-- U+00EA ISOlat1   - latin small letter e with circumflex                                  -->
  <!ENTITY euml     "&#235;">  <!-- U+00EB ISOlat1   - latin small letter e with diaeresis                                   -->
  <!ENTITY igrave   "&#236;">  <!-- U+00EC ISOlat1   - latin small letter i with grave                                       -->
  <!ENTITY iacute   "&#237;">  <!-- U+00ED ISOlat1   - latin small letter i with acute                                       -->
  <!ENTITY icirc    "&#238;">  <!-- U+00EE ISOlat1   - latin small letter i with circumflex                                  -->
  <!ENTITY iuml     "&#239;">  <!-- U+00EF ISOlat1   - latin small letter i with diaeresis                                   -->
  <!ENTITY eth      "&#240;">  <!-- U+00F0 ISOlat1   - latin small letter eth                                                -->
  <!ENTITY ntilde   "&#241;">  <!-- U+00F1 ISOlat1   - latin small letter n with tilde                                       -->
  <!ENTITY ograve   "&#242;">  <!-- U+00F2 ISOlat1   - latin small letter o with grave                                       -->
  <!ENTITY oacute   "&#243;">  <!-- U+00F3 ISOlat1   - latin small letter o with acute                                       -->
  <!ENTITY ocirc    "&#244;">  <!-- U+00F4 ISOlat1   - latin small letter o with circumflex                                  -->
  <!ENTITY otilde   "&#245;">  <!-- U+00F5 ISOlat1   - latin small letter o with tilde                                       -->
  <!ENTITY ouml     "&#246;">  <!-- U+00F6 ISOlat1   - latin small letter o with diaeresis                                   -->
  <!ENTITY divide   "&#247;">  <!-- U+00F7 ISOnum    - division sign                                                         -->
  <!ENTITY oslash   "&#248;">  <!-- U+00F8 ISOlat1   - latin small letter o with stroke = latin small letter o slash         -->
  <!ENTITY ugrave   "&#249;">  <!-- U+00F9 ISOlat1   - latin small letter u with grave                                       -->
  <!ENTITY uacute   "&#250;">  <!-- U+00FA ISOlat1   - latin small letter u with acute                                       -->
  <!ENTITY ucirc    "&#251;">  <!-- U+00FB ISOlat1   - latin small letter u with circumflex                                  -->
  <!ENTITY uuml     "&#252;">  <!-- U+00FC ISOlat1   - latin small letter u with diaeresis                                   -->
  <!ENTITY yacute   "&#253;">  <!-- U+00FD ISOlat1   - latin small letter y with acute                                       -->
  <!ENTITY thorn    "&#254;">  <!-- U+00FE ISOlat1   - latin small letter thorn                                              -->
  <!ENTITY yuml     "&#255;">  <!-- U+00FF ISOlat1   - latin small letter y with diaeresis                                   -->
  
  <!-- Latin Extended-A -->
  <!ENTITY OElig    "&#338;">  <!-- U+0152 ISOlat2   - latin capital ligature OE                                             -->
  <!ENTITY oelig    "&#339;">  <!-- U+0153 ISOlat2   - latin small ligature oe                                               -->
  
  <!-- ligature is a misnomer, this is a separate character in some languages -->
  <!ENTITY Scaron   "&#352;">  <!-- U+0160 ISOlat2   - latin capital letter S with caron                                     -->
  <!ENTITY scaron   "&#353;">  <!-- U+0161 ISOlat2   - latin small letter s with caron                                       -->
  <!ENTITY Yuml     "&#376;">  <!-- U+0178 ISOlat2   - latin capital letter Y with diaeresis                                 -->
  
  <!-- Spacing Modifier Letters -->
  <!ENTITY circ     "&#710;">  <!-- U+02C6 ISOpub    - modifier letter circumflex accent                                     -->
  <!ENTITY tilde    "&#732;">  <!-- U+02DC ISOdia    - small tilde                                                           -->
  
  <!-- General Punctuation -->
  <!ENTITY ensp     "&#8194;"> <!-- U+2002 ISOpub    - en space                                                              -->
  <!ENTITY emsp     "&#8195;"> <!-- U+2003 ISOpub    - em space                                                              -->
  <!ENTITY thinsp   "&#8201;"> <!-- U+2009 ISOpub    - thin space                                                            -->
  <!ENTITY zwnj     "&#8204;"> <!-- U+200C RFC 2070  - zero width non-joiner                                                 -->
  <!ENTITY zwj      "&#8205;"> <!-- U+200D RFC 2070  - zero width joiner                                                     -->
  <!ENTITY lrm      "&#8206;"> <!-- U+200E RFC 2070  - left-to-right mark                                                    -->
  <!ENTITY rlm      "&#8207;"> <!-- U+200F RFC 2070  - right-to-left mark                                                    -->
  <!ENTITY ndash    "&#8211;"> <!-- U+2013 ISOpub    - en dash                                                               -->
  <!ENTITY mdash    "&#8212;"> <!-- U+2014 ISOpub    - em dash                                                               -->
  <!ENTITY lsquo    "&#8216;"> <!-- U+2018 ISOnum    - left single quotation mark                                            -->
  <!ENTITY rsquo    "&#8217;"> <!-- U+2019 ISOnum    - right single quotation mark                                           -->
  <!ENTITY sbquo    "&#8218;"> <!-- U+201A NEW       - single low-9 quotation mark                                           -->
  <!ENTITY ldquo    "&#8220;"> <!-- U+201C ISOnum    - left double quotation mark                                            -->
  <!ENTITY rdquo    "&#8221;"> <!-- U+201D ISOnum    - right double quotation mark,                                          -->
  <!ENTITY bdquo    "&#8222;"> <!-- U+201E NEW       - double low-9 quotation mark                                           -->
  <!ENTITY dagger   "&#8224;"> <!-- U+2020 ISOpub    - dagger                                                                -->
  <!ENTITY Dagger   "&#8225;"> <!-- U+2021 ISOpub    - double dagger                                                         -->
  <!ENTITY permil   "&#8240;"> <!-- U+2030 ISOtech   - per mille sign                                                        -->
  <!ENTITY lsaquo   "&#8249;"> <!-- U+2039 ISO prop. - single left-pointing angle quotation mark                             -->
  
  <!-- lsaquo is proposed but not yet ISO standardized -->
  <!ENTITY rsaquo   "&#8250;"> <!-- U+203A ISO prop. -   single right-pointing angle quotation mark                          -->
  
  <!-- rsaquo is proposed but not yet ISO standardized -->
  <!ENTITY euro     "&#8364;"> <!-- U+20AC NEW       -   euro sign                                                           -->
  
  <!-- Latin Extended-B -->
  <!ENTITY fnof     "&#402;">  <!-- U+0192 ISOtech   - latin small f with hook = function = florin                           -->
  
  <!-- Greek -->
  <!ENTITY Alpha    "&#913;">  <!-- U+0391           - greek capital letter alpha                                            -->
  <!ENTITY Beta     "&#914;">  <!-- U+0392           - greek capital letter beta                                             -->
  <!ENTITY Gamma    "&#915;">  <!-- U+0393 ISOgrk3   - greek capital letter gamma                                            -->
  <!ENTITY Delta    "&#916;">  <!-- U+0394 ISOgrk3   - greek capital letter delta                                            -->
  <!ENTITY Epsilon  "&#917;">  <!-- U+0395           - greek capital letter epsilon                                          -->
  <!ENTITY Zeta     "&#918;">  <!-- U+0396           - greek capital letter zeta                                             -->
  <!ENTITY Eta      "&#919;">  <!-- U+0397           - greek capital letter eta                                              -->
  <!ENTITY Theta    "&#920;">  <!-- U+0398 ISOgrk3   - greek capital letter theta                                            -->
  <!ENTITY Iota     "&#921;">  <!-- U+0399           - greek capital letter iota                                             -->
  <!ENTITY Kappa    "&#922;">  <!-- U+039A           - greek capital letter kappa                                            -->
  <!ENTITY Lambda   "&#923;">  <!-- U+039B ISOgrk3   - greek capital letter lambda                                           -->
  <!ENTITY Mu       "&#924;">  <!-- U+039C           - greek capital letter mu                                               -->
  <!ENTITY Nu       "&#925;">  <!-- U+039D           - greek capital letter nu                                               -->
  <!ENTITY Xi       "&#926;">  <!-- U+039E ISOgrk3   - greek capital letter xi                                               -->
  <!ENTITY Omicron  "&#927;">  <!-- U+039F           - greek capital letter omicron                                          -->
  <!ENTITY Pi       "&#928;">  <!-- U+03A0 ISOgrk3   - greek capital letter pi                                               -->
  <!ENTITY Rho      "&#929;">  <!-- U+03A1           - greek capital letter rho                                              -->
  <!ENTITY Sigma    "&#931;">  <!-- U+03A3 ISOgrk3   - greek capital letter sigma                                            -->
  <!ENTITY Tau      "&#932;">  <!-- U+03A4           - greek capital letter tau                                              -->
  <!ENTITY Upsilon  "&#933;">  <!-- U+03A5 ISOgrk3   - greek capital letter upsilon                                          -->
  <!ENTITY Phi      "&#934;">  <!-- U+03A6 ISOgrk3   - greek capital letter phi                                              -->
  <!ENTITY Chi      "&#935;">  <!-- U+03A7           - greek capital letter chi                                              -->
  <!ENTITY Psi      "&#936;">  <!-- U+03A8 ISOgrk3   - greek capital letter psi                                              -->
  <!ENTITY Omega    "&#937;">  <!-- U+03A9 ISOgrk3   - greek capital letter omega                                            -->
  <!ENTITY alpha    "&#945;">  <!-- U+03B1 ISOgrk3   - greek small letter alpha                                              -->
  <!ENTITY beta     "&#946;">  <!-- U+03B2 ISOgrk3   - greek small letter beta                                               -->
  <!ENTITY gamma    "&#947;">  <!-- U+03B3 ISOgrk3   - greek small letter gamma                                              -->
  <!ENTITY delta    "&#948;">  <!-- U+03B4 ISOgrk3   - greek small letter delta                                              -->
  <!ENTITY epsilon  "&#949;">  <!-- U+03B5 ISOgrk3   - greek small letter epsilon                                            -->
  <!ENTITY zeta     "&#950;">  <!-- U+03B6 ISOgrk3   - greek small letter zeta                                               -->
  <!ENTITY eta      "&#951;">  <!-- U+03B7 ISOgrk3   - greek small letter eta                                                -->
  <!ENTITY theta    "&#952;">  <!-- U+03B8 ISOgrk3   - greek small letter theta                                              -->
  <!ENTITY iota     "&#953;">  <!-- U+03B9 ISOgrk3   - greek small letter iota                                               -->
  <!ENTITY kappa    "&#954;">  <!-- U+03BA ISOgrk3   - greek small letter kappa                                              -->
  <!ENTITY lambda   "&#955;">  <!-- U+03BB ISOgrk3   - greek small letter lambda                                             -->
  <!ENTITY mu       "&#956;">  <!-- U+03BC ISOgrk3   - greek small letter mu                                                 -->
  <!ENTITY nu       "&#957;">  <!-- U+03BD ISOgrk3   - greek small letter nu                                                 -->
  <!ENTITY xi       "&#958;">  <!-- U+03BE ISOgrk3   - greek small letter xi                                                 -->
  <!ENTITY omicron  "&#959;">  <!-- U+03BF NEW       - greek small letter omicron                                            -->
  <!ENTITY pi       "&#960;">  <!-- U+03C0 ISOgrk3   - greek small letter pi                                                 -->
  <!ENTITY rho      "&#961;">  <!-- U+03C1 ISOgrk3   - greek small letter rho                                                -->
  <!ENTITY sigmaf   "&#962;">  <!-- U+03C2 ISOgrk3   - greek small letter final sigma                                        -->
  <!ENTITY sigma    "&#963;">  <!-- U+03C3 ISOgrk3   - greek small letter sigma                                              -->
  <!ENTITY tau      "&#964;">  <!-- U+03C4 ISOgrk3   - greek small letter tau                                                -->
  <!ENTITY upsilon  "&#965;">  <!-- U+03C5 ISOgrk3   - greek small letter upsilon                                            -->
  <!ENTITY phi      "&#966;">  <!-- U+03C6 ISOgrk3   - greek small letter phi                                                -->
  <!ENTITY chi      "&#967;">  <!-- U+03C7 ISOgrk3   - greek small letter chi                                                -->
  <!ENTITY psi      "&#968;">  <!-- U+03C8 ISOgrk3   - greek small letter psi                                                -->
  <!ENTITY omega    "&#969;">  <!-- U+03C9 ISOgrk3   - greek small letter omega                                              -->
  <!ENTITY thetasym "&#977;">  <!-- U+03D1 NEW       - greek small letter theta symbol                                       -->
  <!ENTITY upsih    "&#978;">  <!-- U+03D2 NEW       - greek upsilon with hook symbol                                        -->
  <!ENTITY piv      "&#982;">  <!-- U+03D6 ISOgrk3   - greek pi symbol                                                       -->
  
  <!-- General Punctuation -->
  <!ENTITY bull     "&#8226;"> <!-- U+2022 ISOpub    - bullet = black small circle                                           -->
  <!ENTITY hellip   "&#8230;"> <!-- U+2026 ISOpub    - horizontal ellipsis = three dot leader                                -->
  <!ENTITY prime    "&#8242;"> <!-- U+2032 ISOtech   - prime = minutes = feet                                                -->
  <!ENTITY Prime    "&#8243;"> <!-- U+2033 ISOtech   - double prime = seconds = inches                                       -->
  <!ENTITY oline    "&#8254;"> <!-- U+203E NEW       - overline = spacing overscore                                          -->
  <!ENTITY frasl    "&#8260;"> <!-- U+2044 NEW       - fraction slash                                                        -->
  
  <!-- Letterlike Symbols -->
  <!ENTITY weierp   "&#8472;"> <!-- U+2118 ISOamso   - script capital P = power set = Weierstrass p                          -->
  <!ENTITY image    "&#8465;"> <!-- U+2111 ISOamso   - blackletter capital I = imaginary part                                -->
  <!ENTITY real     "&#8476;"> <!-- U+211C ISOamso   - blackletter capital R = real part symbol                              -->
  <!ENTITY trade    "&#8482;"> <!-- U+2122 ISOnum    - trade mark sign                                                       -->
  <!ENTITY alefsym  "&#8501;"> <!-- U+2135 NEW       - alef symbol = first transfinite cardinal                              -->
  
  <!-- Arrows -->
  <!ENTITY larr     "&#8592;"> <!-- U+2190 ISOnum    - leftwards arrow                                                       -->
  <!ENTITY uarr     "&#8593;"> <!-- U+2191 ISOnum    - upwards arrow                                                         -->
  <!ENTITY rarr     "&#8594;"> <!-- U+2192 ISOnum    - rightwards arrow                                                      -->
  <!ENTITY darr     "&#8595;"> <!-- U+2193 ISOnum    - downwards arrow                                                       -->
  <!ENTITY harr     "&#8596;"> <!-- U+2194 ISOamsa   - left right arrow                                                      -->
  <!ENTITY crarr    "&#8629;"> <!-- U+21B5 NEW       - downwards arrow with corner leftwards = carriage return               -->
  <!ENTITY lArr     "&#8656;"> <!-- U+21D0 ISOtech   - leftwards double arrow                                                -->
  <!ENTITY uArr     "&#8657;"> <!-- U+21D1 ISOamsa   - upwards double arrow                                                  -->
  <!ENTITY rArr     "&#8658;"> <!-- U+21D2 ISOtech   - rightwards double arrow                                               -->
  <!ENTITY dArr     "&#8659;"> <!-- U+21D3 ISOamsa   - downwards double arrow                                                -->
  <!ENTITY hArr     "&#8660;"> <!-- U+21D4 ISOamsa   - left right double arrow                                               -->
  
  <!-- Mathematical Operators -->
  <!ENTITY forall   "&#8704;"> <!-- U+2200 ISOtech   - for all                                                               -->
  <!ENTITY part     "&#8706;"> <!-- U+2202 ISOtech   - partial differential                                                  -->
  <!ENTITY exist    "&#8707;"> <!-- U+2203 ISOtech   - there exists                                                          -->
  <!ENTITY empty    "&#8709;"> <!-- U+2205 ISOamso   - empty set = null set = diameter                                       -->
  <!ENTITY nabla    "&#8711;"> <!-- U+2207 ISOtech   - nabla = backward difference                                           -->
  <!ENTITY isin     "&#8712;"> <!-- U+2208 ISOtech   - element of                                                            -->
  <!ENTITY notin    "&#8713;"> <!-- U+2209 ISOtech   - not an element of                                                     -->
  <!ENTITY ni       "&#8715;"> <!-- U+220B ISOtech   - contains as member                                                    -->
  <!ENTITY prod     "&#8719;"> <!-- U+220F ISOamsb   - n-ary product = product sign                                          -->
  <!ENTITY sum      "&#8721;"> <!-- U+2211 ISOamsb   - n-ary sumation                                                        -->
  <!ENTITY minus    "&#8722;"> <!-- U+2212 ISOtech   - minus sign                                                            -->
  <!ENTITY lowast   "&#8727;"> <!-- U+2217 ISOtech   - asterisk operator                                                     -->
  <!ENTITY radic    "&#8730;"> <!-- U+221A ISOtech   - square root = radical sign                                            -->
  <!ENTITY prop     "&#8733;"> <!-- U+221D ISOtech   - proportional to                                                       -->
  <!ENTITY infin    "&#8734;"> <!-- U+221E ISOtech   - infinity                                                              -->
  <!ENTITY ang      "&#8736;"> <!-- U+2220 ISOamso   - angle                                                                 -->
  <!ENTITY and      "&#8743;"> <!-- U+2227 ISOtech   - logical and = wedge                                                   -->
  <!ENTITY or       "&#8744;"> <!-- U+2228 ISOtech   - logical or = vee                                                      -->
  <!ENTITY cap      "&#8745;"> <!-- U+2229 ISOtech   - intersection = cap                                                    -->
  <!ENTITY cup      "&#8746;"> <!-- U+222A ISOtech   - union = cup                                                           -->
  <!ENTITY int      "&#8747;"> <!-- U+222B ISOtech   - integral                                                              -->
  <!ENTITY there4   "&#8756;"> <!-- U+2234 ISOtech   - therefore                                                             -->
  <!ENTITY sim      "&#8764;"> <!-- U+223C ISOtech   - tilde operator = varies with = similar to                             -->
  <!ENTITY cong     "&#8773;"> <!-- U+2245 ISOtech   - approximately equal to                                                -->
  <!ENTITY asymp    "&#8776;"> <!-- U+2248 ISOamsr   - almost equal to = asymptotic to                                       -->
  <!ENTITY ne       "&#8800;"> <!-- U+2260 ISOtech   - not equal to                                                          -->
  <!ENTITY equiv    "&#8801;"> <!-- U+2261 ISOtech   - identical to                                                          -->
  <!ENTITY le       "&#8804;"> <!-- U+2264 ISOtech   - less-than or equal to                                                 -->
  <!ENTITY ge       "&#8805;"> <!-- U+2265 ISOtech   - greater-than or equal to                                              -->
  <!ENTITY sub      "&#8834;"> <!-- U+2282 ISOtech   - subset of                                                             -->
  <!ENTITY sup      "&#8835;"> <!-- U+2283 ISOtech   - superset of                                                           -->
  <!ENTITY nsub     "&#8836;"> <!-- U+2284 ISOamsn   - not a subset of                                                       -->
  <!ENTITY sube     "&#8838;"> <!-- U+2286 ISOtech   - subset of or equal to                                                 -->
  <!ENTITY supe     "&#8839;"> <!-- U+2287 ISOtech   - superset of or equal to                                               -->
  <!ENTITY oplus    "&#8853;"> <!-- U+2295 ISOamsb   - circled plus = direct sum                                             -->
  <!ENTITY otimes   "&#8855;"> <!-- U+2297 ISOamsb   - circled times = vector product                                        -->
  <!ENTITY perp     "&#8869;"> <!-- U+22A5 ISOtech   - up tack = orthogonal to = perpendicular                               -->
  <!ENTITY sdot     "&#8901;"> <!-- U+22C5 ISOamsb   - dot operator                                                          -->
  
  <!-- Miscellaneous Technical -->
  <!ENTITY lceil    "&#8968;"> <!-- U+2308 ISOamsc   - left ceiling = apl upstile                                            -->
  <!ENTITY rceil    "&#8969;"> <!-- U+2309 ISOamsc   - right ceiling                                                         -->
  <!ENTITY lfloor   "&#8970;"> <!-- U+230A ISOamsc   - left floor = apl downstile                                            -->
  <!ENTITY rfloor   "&#8971;"> <!-- U+230B ISOamsc   - right floor                                                           -->
  <!ENTITY lang     "&#9001;"> <!-- U+2329 ISOtech   - left-pointing angle bracket = bra                                     -->
  <!ENTITY rang     "&#9002;"> <!-- U+232A ISOtech   - right-pointing angle bracket = ket                                    -->
  
  <!-- Geometric Shapes -->
  <!ENTITY loz      "&#9674;"> <!-- U+25CA ISOpub    - lozenge                                                               -->
  
  <!-- Miscellaneous Symbols -->
  <!ENTITY spades   "&#9824;"> <!-- U+2660 ISOpub    - black spade suit                                                      -->
  <!ENTITY clubs    "&#9827;"> <!-- U+2663 ISOpub    - black club suit = shamrock                                            -->
  <!ENTITY hearts   "&#9829;"> <!-- U+2665 ISOpub    - black heart suit = valentine                                          -->
  <!ENTITY diams    "&#9830;"> <!-- U+2666 ISOpub    - black diamond suit                                                    -->
  
  
  
  1.1                  xml-cocoon/xdocs/dtd/document-v10.dtd
  
  Index: document-v10.dtd
  ===================================================================
  <!-- ===================================================================
  
       Apache Documentation DTD (Version 1.0)
  
  PURPOSE:
    This DTD was developed to create a simple yet powerful document
    type for software documentation for use with the Apache projects.
    It is an XML-compliant DTD and it's maintained by the Apache XML
    project.
  
  TYPICAL INVOCATION:
  
    <!DOCTYPE document PUBLIC
         "-//APACHE//DTD Documentation Vx.yz//EN"
         "http://xml.apache.org/DTD/document-vxyz.dtd">
  
    where
  
      x := major version
      y := minor version
      z := status identifier (optional)
  
  NOTES:
    Many of the design patterns used in this DTD were take from the
    W3C XML Specification DTD edited by Eve Maler <elm@arbortext.com>.
  
    Where possible, great care has been used to reutilize HTML tag
    names to reduce learning efforts and to allow HTML editors to be
    used for complex authorings like tables and lists.
  
  AUTHORS:
    Stefano Mazzocchi <stefano@apache.org>
  
  FIXME:
    - how can we include char entities without hardwiring them?
    - should "form" tags be included?
    - should all style-free HTML 4.0 markup tags be included?
    - how do we handle the idea of "soft" xlinks?
    - should we add "soft" links to images?
  
  CHANGE HISTORY:
    19991121 Initial version. (SM)
    19991123 Replaced "res" with more standard "strong" for emphasis. (SM)
    19991124 Added "fork" element for window forking behavior. (SM)
    19991124 Added "img-inline" element to separate from "img". (SM)
    19991129 Removed "affiliation" from "author". (SM)
    19991129 Made "author" empty and moved "name|email" as attributes (SM)
    19991215 Simplified table section (SM)
    19991215 Changed "img-block" in more friendly "figure" (SM)
    20000125 Added the "icon" image (SM)
    20000126 Allowed "anchor" in all levels (SM)
  
  COPYRIGHT:
    Copyright (c) 1999-2000 The Apache Software Foundation.
  
    Permission to copy in any form is granted provided this notice is
    included in all copies. Permission to redistribute is granted
    provided this file is distributed untouched in all its parts and
    included files.
  
  ==================================================================== -->
  
  
  
  
  <!-- =============================================================== -->
  <!-- Common character entities (included from external file) -->
  <!-- =============================================================== -->
  
  <!-- FIXME (SM): this is hardcoding. Find a better way of doing this
       possibly using public identifiers of ISO latin char sets -->
  <!ENTITY % charEntity SYSTEM "characters.ent">
  %charEntity;
  
  
  
  
  <!-- =============================================================== -->
  <!-- Userful entitieis for increased DTD readability -->
  <!-- =============================================================== -->
  
  <!ENTITY % text "#PCDATA">
  
  
  <!-- =============================================================== -->
  <!-- Entities for general XML compliance -->
  <!-- =============================================================== -->
  
  <!-- Common attributes
          Every element has an ID attribute (sometimes required,
          but usually optional) for links, and a Role attribute
          for extending the useful life of the DTD by allowing
          authors to make subclasses for any element. %common.att;
          is for common attributes where the ID is optional, and
          %common-idreq.att; is for common attributes where the
          ID is required.
  -->
  <!ENTITY % common.att
          'id                     ID              #IMPLIED
           xml:lang               NMTOKEN         #IMPLIED
           role                   NMTOKEN         #IMPLIED'>
  <!ENTITY % common-idreq.att
          'id                     ID              #REQUIRED
           xml:lang               NMTOKEN         #IMPLIED
           role                   NMTOKEN         #IMPLIED'>
  
  
  <!-- xml:space attribute ===============================================
          Indicates that the element contains white space
          that the formatter or other application should retain,
          as appropriate to its function.
  ==================================================================== -->
  <!ENTITY % xmlspace.att
          'xml:space (default|preserve) #FIXED "preserve"'>
  
  
  <!-- def attribute =====================================================
          Points to the element where the relevant definition can be
          found, using the IDREF mechanism.  %def.att; is for optional
          def attributes, and %def-req.att; is for required def
          attributes.
  ==================================================================== -->
  <!ENTITY % def.att
          'def                    IDREF           #IMPLIED'>
  <!ENTITY % def-req.att
          'def                    IDREF           #REQUIRED'>
  
  
  
  <!-- ref attribute =====================================================
          Points to the element where more information can be found,
          using the IDREF mechanism.  %ref.att; is for optional
          ref attributes, and %ref-req.att; is for required ref
          attributes.
  ================================================================== -->
  <!ENTITY % ref.att
          'ref                    IDREF           #IMPLIED'>
  <!ENTITY % ref-req.att
          'ref                    IDREF           #REQUIRED'>
  
  
  <!-- =============================================================== -->
  <!-- Entities for XLink compliance -->
  <!-- =============================================================== -->
  
  <!ENTITY % xlink-simple.att
          'type      (simple|extended|locator|arc) #FIXED "simple"
           href      CDATA                         #IMPLIED
           role      CDATA                         #IMPLIED
           title     CDATA                         #IMPLIED '>
  <!--    'xmlns     CDATA                         #FIXED "http://www.w3.org/XML/XLink/0.9" -->
  <!-- FIXME: brain-dead IE5 has broken support for
       namespace validation and since I use it for editing
       I remove this for now -->
  
  <!ENTITY % xlink-user-replace.att
          'show      (new|parsed|replace)   #FIXED "replace"
           actuate   (user|auto)            #FIXED "user" '>
  
  <!ENTITY % xlink-user-new.att
          'show      (new|parsed|replace)   #FIXED "new"
           actuate   (user|auto)            #FIXED "user" '>
  
  <!ENTITY % xlink-auto-parsed.att
          'show      (new|parsed|replace)   #FIXED "parsed"
           actuate   (user|auto)            #FIXED "auto" '>
  
  <!-- FIXME (SM): XLink doesn't yet cover the idea of soft links so
       introducing it here using the same namespace is _somewhat_
       illegal. Should we create it own namespace?
  -->
  <!ENTITY % xlink-soft.att
          'mode      (hard|soft)            #FIXED "soft" '>
  
  
  <!-- =============================================================== -->
  <!-- Entities for general usage -->
  <!-- =============================================================== -->
  
  
  <!-- Key attribute =====================================================
          Optionally provides a sorting or indexing key, for cases when
          the element content is inappropriate for this purpose.
  ==================================================================== -->
  <!ENTITY % key.att
          'key                    CDATA           #IMPLIED'>
  
  
  
  <!-- Title attributes ==================================================
          Indicates that the element requires to have a title.
  ==================================================================== -->
  <!ENTITY % title.att
          'title                  CDATA           #REQUIRED'>
  
  
  
  <!-- Name attributes ==================================================
          Indicates that the element requires to have a name.
  ==================================================================== -->
  <!ENTITY % name.att
          'name                   CDATA           #REQUIRED'>
  
  
  
  <!-- Email attributes ==================================================
          Indicates that the element requires to have an email.
  ==================================================================== -->
  <!ENTITY % email.att
          'email                  CDATA           #REQUIRED'>
  
  
  
  
  
  <!-- =============================================================== -->
  <!-- General definitions -->
  <!-- =============================================================== -->
  
  <!-- A person is a general human entity -->
  <!ELEMENT person EMPTY>
  <!ATTLIST person %common.att;
                   %name.att;
                   %email.att;>
  
  
  
  
  <!-- =============================================================== -->
  <!-- Content definitions -->
  <!-- =============================================================== -->
  
  <!ENTITY % local.content.mix "">
  
  <!ENTITY % markup "strong|em|code|sub|sup">
  
  <!ENTITY % links "link|connect|jump|fork|anchor">
  
  <!ENTITY % special "br|img|icon">
  
  <!ENTITY % link-content.mix "%text;|%markup;|%special;%local.content.mix;">
  
  <!ENTITY % content.mix "%link-content.mix;|%links;">
  
      <!-- ==================================================== -->
      <!-- Phrase Markup -->
      <!-- ==================================================== -->
  
      <!-- Strong (typically bold) -->
      <!ELEMENT strong (%text;)>
      <!ATTLIST strong %common.att;>
  
      <!-- Emphasis (typically italic) -->
      <!ELEMENT em (%text;)>
      <!ATTLIST em %common.att;>
  
      <!-- Code (typically monospaced) -->
      <!ELEMENT code (%text;)>
      <!ATTLIST code %common.att;>
  
      <!-- Superscript (typically smaller and higher) -->
      <!ELEMENT sup (%text;)>
      <!ATTLIST sup %common.att;>
  
      <!-- Subscript (typically smaller and lower) -->
      <!ELEMENT sub (%text;)>
      <!ATTLIST sub %common.att;>
  
      <!-- FIXME (SM): should we add these HTML 4.0 markups
           which are style-free?
  
            -dfn
            -samp
            -kbd
            -var
            -cite
            -abbr
            -acronym
  
       -->
  
      <!-- ==================================================== -->
      <!-- Hypertextual Links -->
      <!-- ==================================================== -->
  
      <!-- hard replacing link (equivalent of <a ...>) -->
      <!ELEMENT link (%link-content.mix;)*>
      <!ATTLIST link %common.att;
                     %xlink-simple.att;
                     %xlink-user-replace.att;>
  
      <!-- Hard window replacing link (equivalent of <a ... target="_top">) -->
      <!ELEMENT jump (%link-content.mix;)*>
      <!ATTLIST jump %common.att;
                     %xlink-simple.att;
                     %xlink-user-new.att;>
  
      <!-- Hard window forking link (equivalent of <a ... target="_new">) -->
      <!ELEMENT fork (%link-content.mix;)*>
      <!ATTLIST fork %common.att;
                     %xlink-simple.att;
                     %xlink-user-new.att;>
  
      <!-- Anchor point (equivalent of <a name="...">) -->
      <!ELEMENT anchor EMPTY>
      <!ATTLIST anchor %common-idreq.att;>
  
      <!-- Soft link between processed pages (no equivalent in HTML) -->
      <!ELEMENT connect (%link-content.mix;)*>
      <!ATTLIST connect %common.att;
                        %xlink-simple.att;
                        %xlink-user-replace.att;
                        %xlink-soft.att;>
  
      <!-- ==================================================== -->
      <!-- Specials -->
      <!-- ==================================================== -->
  
      <!-- Breakline Object (typically forces line break) -->
      <!ELEMENT br EMPTY>
      <!ATTLIST br %common.att;>
  
      <!-- Image Object (typically an inlined image) -->
      <!-- FIXME (SM): should we have the notion of soft links even here
           for inlined objects? -->
      <!ELEMENT img EMPTY>
      <!ATTLIST img src    CDATA  #REQUIRED
                    alt    CDATA  #REQUIRED
                    height CDATA  #IMPLIED
                    width  CDATA  #IMPLIED
                    usemap CDATA  #IMPLIED
                    ismap  (ismap) #IMPLIED
                    %common.att;>
  
      <!-- Image Icon (typically an inlined image placed as graphical item) -->
      <!-- FIXME (SM): should we have the notion of soft links even here
           for inlined objects? -->
      <!ELEMENT icon EMPTY>
      <!ATTLIST icon src    CDATA  #REQUIRED
                     alt    CDATA  #REQUIRED
                     height CDATA  #IMPLIED
                     width  CDATA  #IMPLIED
                     %common.att;>
  
  
  
  
  <!-- =============================================================== -->
  <!-- Blocks definitions -->
  <!-- =============================================================== -->
  
  <!ENTITY % local.blocks "">
  
  <!ENTITY % local.lists "">
  
  <!ENTITY % paragraphs "p|source|note|fixme|figure">
  
  <!ENTITY % tables "table">
  
  <!ENTITY % lists "ol|ul|sl|dl %local.lists;">
  
  <!ENTITY % blocks "anchor|%paragraphs;|%tables;|%lists; %local.blocks;">
  
      <!-- ==================================================== -->
      <!-- Paragraphs -->
      <!-- ==================================================== -->
  
      <!-- Text Paragraph (normally vertically space delimited) -->
      <!ELEMENT p (%content.mix;)*>
      <!ATTLIST p %common.att;>
  
      <!-- Source Paragraph (normally space is preserved) -->
      <!ELEMENT source (%content.mix;)*>
      <!ATTLIST source %common.att;
                       %xmlspace.att;>
  
      <!-- Note Paragraph (normally shown encapsulated) -->
      <!ELEMENT note (%content.mix;)*>
      <!ATTLIST note %common.att;>
  
      <!-- Fixme Paragraph (normally not shown) -->
      <!ELEMENT fixme (%content.mix;)*>
      <!-- the "author" attribute should match the "key" attribute of the
           <author> element -->
      <!ATTLIST fixme author CDATA #REQUIRED
                      %common.att;>
  
      <!-- ==================================================== -->
      <!-- Tables -->
      <!-- ==================================================== -->
  
      <!-- Attributes that indicate the spanning of the table cell -->
      <!ENTITY % cell.span 
          'colspan CDATA "1"
           rowspan CDATA "1"'>
  
      <!-- Table element -->
      <!ELEMENT table (caption?, tr+)>
      <!ATTLIST table %common.att;>
  
          <!-- The table title -->
          <!ELEMENT caption (%content.mix;)*>
          <!ATTLIST caption %common.att;>
  
          <!-- The table row element -->
          <!ELEMENT tr (th|td)+>
          <!ATTLIST tr %common.att;>
  
              <!-- The table row header element -->
              <!ELEMENT th (%content.mix;)*>
              <!ATTLIST th %common.att;
                           %cell.span;>
  
              <!-- The table row description element -->
              <!ELEMENT td (%content.mix;)*>
              <!ATTLIST td %common.att;
                           %cell.span;>
  
      <!-- ==================================================== -->
      <!-- Lists -->
      <!-- ==================================================== -->
  
      <!-- Unordered list (typically bulleted) -->
      <!ELEMENT ul (li|%lists;)+>
      <!--    spacing attribute:
              Use "normal" to get normal vertical spacing for items;
              use "compact" to get less spacing.  The default is dependent
              on the stylesheet. -->
      <!ATTLIST ul
              %common.att;
              spacing         (normal|compact)        #IMPLIED>
  
      <!-- Ordered list (typically numbered) -->
      <!ELEMENT ol (li|%lists;)+>
      <!--    spacing attribute:
              Use "normal" to get normal vertical spacing for items;
              use "compact" to get less spacing.  The default is dependent
              on the stylesheet. -->
      <!ATTLIST ol
              %common.att;
              spacing         (normal|compact)        #IMPLIED>
  
      <!-- Simple list (typically with no mark) -->
      <!ELEMENT sl (li|%lists;)+>
      <!ATTLIST sl %common.att;>
  
          <!-- List item -->
          <!ELEMENT li (%content.mix;|%lists;)*>
          <!ATTLIST li %common.att;>
  
      <!-- Definition list (typically two-column) -->
      <!ELEMENT dl (dt,dd)+>
      <!ATTLIST dl %common.att;>
  
          <!-- Definition term -->
          <!ELEMENT dt (%content.mix;)*>
          <!ATTLIST dt %common.att;>
  
          <!-- Definition description -->
          <!ELEMENT dd (%content.mix;)*>
          <!ATTLIST dd %common.att;>
  
      <!-- ==================================================== -->
      <!-- Special Blocks -->
      <!-- ==================================================== -->
  
      <!-- Image Block (typically a separated and centered image) -->
      <!-- FIXME (SM): should we have the notion of soft links even here
           for inlined objects? -->
      <!ELEMENT figure EMPTY>
      <!ATTLIST figure src    CDATA  #REQUIRED
                       alt    CDATA  #REQUIRED
                       height CDATA  #IMPLIED
                       width  CDATA  #IMPLIED
                       usemap CDATA  #IMPLIED
                       ismap  (ismap) #IMPLIED
                       %common.att;>
  
  
  
  
  
  <!-- =============================================================== -->
  <!-- Document -->
  <!-- =============================================================== -->
  
  <!ELEMENT document (header?, body, footer?)>
  <!ATTLIST document %common.att;>
  
      <!-- ==================================================== -->
      <!-- Header -->
      <!-- ==================================================== -->
  
      <!ENTITY % local.headers "">
  
      <!ELEMENT header (title, subtitle?, version?, type?, authors,
                        notice*, abstract? %local.headers;)>
      <!ATTLIST header %common.att;>
  
      <!ELEMENT title (%text;)>
      <!ATTLIST title %common.att;>
  
      <!ELEMENT subtitle (%text;)>
      <!ATTLIST subtitle %common.att;>
  
      <!ELEMENT version (%text;)>
      <!ATTLIST version %common.att;>
  
      <!ELEMENT type (%text;)>
      <!ATTLIST type %common.att;>
  
      <!ELEMENT authors (person+)>
      <!ATTLIST authors %common.att;>
  
      <!ELEMENT notice (%content.mix;)*>
      <!ATTLIST notice %common.att;>
  
      <!ELEMENT abstract (%content.mix;)*>
      <!ATTLIST abstract %common.att;>
  
      <!-- ==================================================== -->
      <!-- Body -->
      <!-- ==================================================== -->
  
      <!ENTITY % local.sections "">
  
      <!ENTITY % sections "s1|anchor %local.sections;">
  
      <!ELEMENT body (%sections;)+>
      <!ATTLIST body %common.att;>
  
          <!ELEMENT s1 (s2|%blocks;)*>
          <!ATTLIST s1 %title.att; %common.att;>
  
              <!ELEMENT s2 (s3|%blocks;)*>
              <!ATTLIST s2 %title.att; %common.att;>
  
                  <!ELEMENT s3 (s4|%blocks;)*>
                  <!ATTLIST s3 %title.att; %common.att;>
  
                      <!ELEMENT s4 (%blocks;)*>
                      <!ATTLIST s4 %title.att; %common.att;>
  
      <!-- ==================================================== -->
      <!-- Footer -->
      <!-- ==================================================== -->
  
      <!ENTITY % local.footers "">
  
      <!ELEMENT footer (legal %local.footers;)>
  
          <!ELEMENT legal (%content.mix;)*>
          <!ATTLIST legal %common.att;>
  
  <!-- =============================================================== -->
  <!-- End of DTD -->
  <!-- =============================================================== -->
  
  
  
  1.1                  xml-cocoon/xdocs/dtd/faq-v10.dtd
  
  Index: faq-v10.dtd
  ===================================================================
  <!-- ===================================================================
       
       Apache FAQ DTD (Version 1.0)
  
  PURPOSE:
    This DTD was developed to create a simple yet powerful document 
    type for software FAQ's for use with the Apache projects.  
    It is an XML-compliant DTD and it's maintained by the Apache XML 
    project.
  
  TYPICAL INVOCATION:
  
    <!DOCTYPE document PUBLIC
         "-//APACHE//DTD FAQ Vx.yz//EN"
         "http://xml.apache.org/DTD/faq-vxyz.dtd">
  
    where 
    
      x := major version
      y := minor version
      z := status identifier (optional)
        
  NOTES:  
    FAQs represent a powerful knowledge base and a very good way of solving
    common user problems reducing messages on mail lists and reducing the effort
    required for software installation and usage. Thid DTD want to be a common
    format for FAQ interchange to allow FAQ-O-Matic-type workgroup services to 
    be published in other formats as well as enhancing data interchange.
    
  AUTHORS:
    Stefano Mazzocchi <stefano@apache.org>
    
  FIXME:
  
  CHANGE HISTORY:
    19991129 Initial version. (SM)
      
  COPYRIGHT:
    Copyright (c) 1999 The Apache Software Foundation.
    
    Permission to copy in any form is granted provided this notice is 
    included in all copies. Permission to redistribute is granted 
    provided this file is distributed untouched in all its parts and 
    included files.
    
  ==================================================================== -->
  
  <!-- =============================================================== -->
  <!-- Extend the Documentation DTD -->
  <!-- =============================================================== -->
  
  <!-- FIXME (SM): this is hardcoding. Find a better way of doing this
       possibly using public identifiers -->
  <!ENTITY % document-dtd SYSTEM "document-v10.dtd">
  %document-dtd;
  
  
  <!-- =============================================================== -->
  <!-- Document Type Definition -->
  <!-- =============================================================== -->
  
  <!ELEMENT faqs (authors?, faq)+>
  <!ATTLIST faqs %common.att; 
                 %title.att;>
  
      <!ELEMENT faq (question, answer)>
      <!ATTLIST faq %common.att;>
      
          <!ELEMENT question (%content.mix;)*>
          <!ATTLIST question %common.att;>
              
          <!ELEMENT answer (%blocks;)*>
          <!ATTLIST answer author IDREF #IMPLIED>
  
  <!-- =============================================================== -->
  <!-- End of DTD -->
  <!-- =============================================================== -->
  
  
  
  1.1                  xml-cocoon/xdocs/dtd/javadoc-v04draft.dtd
  
  Index: javadoc-v04draft.dtd
  ===================================================================
  <!-- ===================================================================
       
       Apache JavaDoc DTD (version 0.4-draft)
  
  PURPOSE:
    This DTD is designed to capture the output of JavaDoc as an XML document
    through the use of the JavaDocXML Doclet. The hope is that by having the
    JavaDoc documentation in an XML format, it will be easier for application
    developers working with XML to treat their java source documentation in the
    same way they treat any other XML document within their publication framework.
    
    This DTD should reflect the information contained within the RootDoc object 
    passed to the JavaDocXML Doclet by JavaDoc. The RootDoc object and the rest 
    of the javaDoc Doclet API is specified at
    
    http://java.sun.com/products/jdk/1.2/docs/tooldocs/javadoc/doclet/index.html
    
    The only information that appears to be difficult to derive from this DTD
    that is easy to obtain from the RootDoc object is the information about 
    serialization. However, this information should be derivable by manually 
    looking for the correct serialization methods and other related structures.
    
  TYPICAL INVOCATION:
  
    <!DOCTYPE document PUBLIC
         "-//APACHE//DTD JavaDoc Vx.yz//EN"
         "http://xml.apache.org/DTD/javadoc-vxyz.dtd">
  
    where 
    
      x := major version
      y := minor version
      z := status identifier (optional)
        
  NOTES:  
    The authors would like to thank the Cocoon's mail list subscribers for 
    providing such great support and feedback for this DTD.
    
  AUTHORS:
    Kenneth Murphy <murphyk@umsystem.edu>
    
  FIXME:
  
  CHANGE HISTORY:
    199909?? Original idea of XML doclet. (KM)
    199910?? Initial version of this DTD. (KM)
    19991129 Cleaned up DTD. (SM)
      
  COPYRIGHT:
    Copyright (c) 1999 The Apache Software Foundation.
    
    Permission to copy in any form is granted provided this notice is 
    included in all copies. Permission to redistribute is granted 
    provided this file is distributed untouched in all its parts and 
    included files.
    
  ==================================================================== -->
  
  <!-- =============================================================== -->
  <!-- Common Attribute Entities -->
  <!-- =============================================================== -->
  
  <!ENTITY % name 'name CDATA #REQUIRED'>
  <!ENTITY % dimension 'dimension CDATA #REQUIRED'>
  
  <!ENTITY % abstract 'abstract (true | false) "false"'>
  <!ENTITY % anonymous 'anonymous (true | false) "false"'>
  <!ENTITY % synthetic 'synthetic (true | false) "false"'>
  <!ENTITY % static 'static (true | false) "false"'>
  <!ENTITY % final 'final (true | false) "false"'>
  <!ENTITY % transient 'transient (true | false) "false"'>
  <!ENTITY % volatile 'volatile (true | false) "false"'>
  <!ENTITY % native 'native (true | false) "false"'>
  <!ENTITY % synchronized 'synchronized (true | false) "false"'>
  
  <!ENTITY % access 'access (private | package | protected | public) "package"'>
  <!ENTITY % class.access 'access (package | public) "package"'>
  
  <!ENTITY % extensibility 'extensibility (abstract | final | default) "default"'>
  
  
  <!-- =============================================================== -->
  <!-- Javadoc -->
  <!-- =============================================================== -->
  
  <!ELEMENT javadoc (package*, class*, interface*)>
  
  <!-- =============================================================== -->
  <!-- Package -->
  <!-- =============================================================== -->
  
  <!ELEMENT package (doc?, package*, class*, interface*)>
  <!ATTLIST package %name;>
  
  <!-- =============================================================== -->
  <!-- Class -->
  <!-- =============================================================== -->
  
  <!ELEMENT class (doc?,
                   extends_class?,
                   implements?,
                   field*, 
                   constructor*, 
                   method*,
                   innerclass*)>
  <!ATTLIST class
            %name;
            %extensibility;
            %class.access;>
  
  <!ELEMENT extends_class (classref+)>
            
  <!ELEMENT innerclass (doc?,
                        extends?,
                        implements?,
                        field*, 
                        constructor*, 
                        method*)>
  <!ATTLIST innerclass
            %name;
            %access;
            %abstract;
            %anonymous;
            %final;
            %static;>
            
  <!-- =============================================================== -->
  <!-- Interface -->
  <!-- =============================================================== -->
            
  <!ELEMENT interface (doc?,
                       extends_interface?,
                       field*,
                       method*)>
  <!ATTLIST interface
            %name;
            %access;>
            
  <!ELEMENT extends_interface (interfaceref+)>
  
  <!-- =============================================================== -->
  <!-- Elements -->
  <!-- =============================================================== -->
  
  <!ELEMENT implements (interfaceref+)>
  
  <!ELEMENT throws (classref)+>
  
  <!ELEMENT classref EMPTY>
  <!ATTLIST classref %name;>
            
  <!ELEMENT interfaceref EMPTY>
  <!ATTLIST interfaceref %name;>
            
  <!ELEMENT methodref EMPTY>
  <!ATTLIST methodref %name;>
            
  <!ELEMENT packageref EMPTY>
  <!ATTLIST packageref %name;>
            
  <!ELEMENT primitive EMPTY>
  <!ATTLIST primitive
            type (void | boolean | int | long | byte | short | double | float | char) #REQUIRED>
            
  <!ELEMENT field (doc?, (classref | interfaceref | primitive))>
  <!ATTLIST field
            %name;
            %access;
            %dimension;
            %synthetic;
            %static;
            %final;
            %transient;
            %volatile;>
            
  <!ELEMENT constructor (doc?, parameter*, throws*)>
  <!ATTLIST constructor
            %name;
            %access;
            %synthetic;>
            
  <!ELEMENT method (doc?, returns, parameter*, throws*)>
  <!ATTLIST method
            %name;
            %access;
            %extensibility;
            %native;
            %synthetic;
            %static;
            %synchronized;>
            
  <!ELEMENT returns (classref | interfaceref | primitive)>
  <!ATTLIST returns %dimension;>
            
  <!ELEMENT parameter (classref | interfaceref | primitive)>
  <!ATTLIST parameter
            %name;
            %final;
            %dimension;>
            
  <!ELEMENT dimension (#PCDATA)>
  
  <!ELEMENT doc (#PCDATA | 
                 linktag |
                 authortag |
                 versiontag |
                 paramtag |
                 returntag |
                 exceptiontag |
                 throwstag |
                 seetag |
                 sincetag |
                 deprecatedtag |
                 serialtag |
                 serialfieldtag |
                 serialdatatag)*>
                 
  <!ELEMENT linktag (#PCDATA)>
  <!ATTLIST linktag
            src CDATA #REQUIRED>
            
  <!ELEMENT authortag (#PCDATA | linktag)*>
  
  <!ELEMENT versiontag (#PCDATA | linktag)*>
  
  <!ELEMENT paramtag (#PCDATA | linktag)*>
  <!ATTLIST paramtag %name;>
            
  <!ELEMENT returntag (#PCDATA | linktag)*>
  
  <!ELEMENT exceptiontag (#PCDATA | classref | linktag)*>
  
  <!ELEMENT throwstag (#PCDATA | classref | linktag)*>
  
  <!ELEMENT seetag (#PCDATA | linktag)*>
  <!ATTLIST seetag
            src CDATA #REQUIRED>
            
  <!ELEMENT sincetag (#PCDATA | linktag)*>
  
  <!ELEMENT deprecatedtag (#PCDATA | linktag)*>
  
  <!ELEMENT serialtag (#PCDATA | linktag)*>
  
  <!ELEMENT serialfieldtag (#PCDATA | linktag)*>
  <!ATTLIST serialfieldtag
            fieldname CDATA #REQUIRED
            fieldtype CDATA #REQUIRED>
            
  <!ELEMENT serialdatatag (#PCDATA | linktag)*>
  
  <!-- =============================================================== -->
  <!-- End of DTD -->
  <!-- =============================================================== -->
  
  
  
  1.1                  xml-cocoon/xdocs/dtd/specification-v10.dtd
  
  Index: specification-v10.dtd
  ===================================================================
  <!-- ===================================================================
       
       Apache Specification DTD (Version 1.0)
  
  PURPOSE:
    This DTD was developed to create a simple yet powerful document 
    type for software specifications for use with the Apache projects.  
    It is an XML-compliant DTD and it's maintained by the Apache XML 
    project.
  
  TYPICAL INVOCATION:
  
    <!DOCTYPE document PUBLIC
         "-//APACHE//DTD Specification Vx.yz//EN"
         "http://xml.apache.org/DTD/specification-vxyz.dtd">
  
    where 
    
      x := major version
      y := minor version
      z := status identifier (optional)
        
  NOTES:  
  
  AUTHORS:
    Stefano Mazzocchi <stefano@apache.org>
    
  FIXME:
  
  CHANGE HISTORY:
    19991129 Initial version. (SM)
      
  COPYRIGHT:
    Copyright (c) 1999 The Apache Software Foundation.
    
    Permission to copy in any form is granted provided this notice is 
    included in all copies. Permission to redistribute is granted 
    provided this file is distributed untouched in all its parts and 
    included files.
    
  ==================================================================== -->
  
  <!-- =============================================================== -->
  <!-- Extend the Documentation DTD -->
  <!-- =============================================================== -->
  
  <!-- extend the local.xxx entities -->
  <!ENTITY % local.lists "|bl">
  
  <!-- FIXME (SM): this is hardcoding. Find a better way of doing this
       possibly using public identifiers -->
  <!ENTITY % document-dtd SYSTEM "document-v10.dtd">
  %document-dtd;
  
  <!-- =============================================================== -->
  <!-- Document Type Definition -->
  <!-- =============================================================== -->
  
  <!ELEMENT specification (header?, body, appendices?, footer?)>
  <!ATTLIST specification %common.att;>
  
      <!ELEMENT appendices (%sections;)+>
      <!ATTLIST appendices %common.att;>
  
  <!-- =============================================================== -->
  <!-- Bibliography List -->
  <!-- =============================================================== -->
  
      <!-- Bibliography list -->
      <!ELEMENT bl (bi)+>
      <!ATTLIST bl %common.att;>
  
          <!-- Book item -->
          <!ELEMENT bi EMPTY>
          <!ATTLIST bi %common.att;
                       %name.att;
                       %title.att;
                       %xlink-simple.att;
                       %xlink-user-new.att;
                       authors CDATA #REQUIRED
                       date    CDATA #IMPLIED>
  
  <!-- =============================================================== -->
  <!-- End of DTD -->
  <!-- =============================================================== -->
  
  
  
  1.1                  xml-cocoon/xdocs/dtd/todo-v10.dtd
  
  Index: todo-v10.dtd
  ===================================================================
  <!-- ===================================================================
       
       Apache Todos DTD (Version 1.0)
  
  PURPOSE:
    This DTD was developed to create a simple yet powerful document 
    type for software development todo lists for use with the Apache projects.  
    It is an XML-compliant DTD and it's maintained by the Apache XML 
    project.
  
  TYPICAL INVOCATION:
  
    <!DOCTYPE document PUBLIC
         "-//APACHE//DTD Todo Vx.yz//EN"
         "http://xml.apache.org/DTD/todo-vxyz.dtd">
  
    where 
    
      x := major version
      y := minor version
      z := status identifier (optional)
        
  NOTES:  
    It is important, expecially in open developped software projects, to keep
    track of software changes that need to be done, planned features, development
    assignment, etc. in order to allow better work parallelization and create
    an entry point for people that want to help. This DTD wants to provide
    a solid foundation to provide such information and to allow it to be
    published as well as distributed in a common format.
  
  AUTHORS:
    Stefano Mazzocchi <stefano@apache.org>
    
  FIXME:
    - do we need anymore working contexts? (SM)
  
  CHANGE HISTORY:
    19991129 Initial version. (SM)
    19991225 Added actions element for better structure (SM)
      
  COPYRIGHT:
    Copyright (c) 1999 The Apache Software Foundation.
    
    Permission to copy in any form is granted provided this notice is 
    included in all copies. Permission to redistribute is granted 
    provided this file is distributed untouched in all its parts and 
    included files.
    
  ==================================================================== -->
  
  <!-- =============================================================== -->
  <!-- Extend the Documentation DTD -->
  <!-- =============================================================== -->
  
  <!-- FIXME (SM): this is hardcoding. Find a better way of doing this
       possibly using public identifiers -->
  <!ENTITY % document-dtd SYSTEM "document-v10.dtd">
  %document-dtd;
  
  <!-- =============================================================== -->
  <!-- Common entities -->
  <!-- =============================================================== -->
  
  <!ENTITY % priorities "showstopper|high|medium|low|wish|dream">
  
  <!ENTITY % contexts "build|docs|code|admin|design">
  
  <!-- =============================================================== -->
  <!-- Document Type Definition -->
  <!-- =============================================================== -->
  
  <!ELEMENT todo (devs, actions*)>
  <!ATTLIST todo %common.att; 
                 %title.att;>
  
      <!ELEMENT devs (person+)>
      <!ATTLIST devs %common.att;>
  
      <!ELEMENT actions (action+)>
      <!ATTLIST actions %common.att;
                       priority     (%priorities;)  #IMPLIED>
  
          <!ELEMENT action (%content.mix;)*>
          <!ATTLIST action %common.att;
                           assigned-to  IDREF           #IMPLIED
                           context      (%contexts;)    #REQUIRED>
      
  <!-- =============================================================== -->
  <!-- End of DTD -->
  <!-- =============================================================== -->
  
  
  
  1.1                  xml-cocoon/xdocs/images/add.jpg
  
  	<<Binary file>>
  
  
  1.1                  xml-cocoon/xdocs/images/cocoon-small.jpg
  
  	<<Binary file>>
  
  
  1.1                  xml-cocoon/xdocs/images/cocoon.jpg
  
  	<<Binary file>>
  
  
  1.1                  xml-cocoon/xdocs/images/dcp-fig-1.gif
  
  	<<Binary file>>
  
  
  1.1                  xml-cocoon/xdocs/images/dcp-fig-2.gif
  
  	<<Binary file>>
  
  
  1.1                  xml-cocoon/xdocs/images/fix.jpg
  
  	<<Binary file>>
  
  
  1.1                  xml-cocoon/xdocs/images/pyramid-model.gif
  
  	<<Binary file>>
  
  
  1.1                  xml-cocoon/xdocs/images/remove.jpg
  
  	<<Binary file>>
  
  
  1.1                  xml-cocoon/xdocs/images/schema.jpg
  
  	<<Binary file>>
  
  
  1.1                  xml-cocoon/xdocs/images/update.jpg
  
  	<<Binary file>>
  
  
  No                   revision
  
  
  No                   revision
  
  
  No                   revision
  
  
  No                   revision
  
  
  No                   revision
  
  
  No                   revision
  
  
  No                   revision
  
  

Mime
View raw message