cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From stef...@hyperreal.org
Subject cvs commit: xml-cocoon/docs/stylesheets javadoc.html.css
Date Sat, 20 Nov 1999 01:16:55 GMT
stefano     99/11/19 17:16:53

  Added:       docs     cocoon2.xml dcpprocessor.xml dynamic.xml faq.xml
                        guide.xml index.xml installing.xml license.xml
                        sqlprocessor.xml technologies.xml
               docs/dtd blocks.ent changes.dtd characters.ent faq.dtd
                        page.dtd todo.dtd
               docs/stylesheets javadoc.html.css
  Removed:     docs     api.html changes.html cocoon2.html dcp.html
                        dynamic.html faq.html guide.html index.html
                        installing.html license.html sqlprocessor.html
                        stylesheet.css technologies.html todo.html
  Log:
  Cleaning up and moving to total XML docs
  
  Revision  Changes    Path
  1.1                  xml-cocoon/docs/cocoon2.xml
  
  Index: cocoon2.xml
  ===================================================================
  <?xml version="1.0" encoding="utf-8"?>
  
  <!DOCTYPE page SYSTEM "./dtd/page.dtd">
  
  <page title="Cocoon 2">
   <authors>
    <author name="Stefano Mazzocchi" email="stefano@apache.org"/>
   </authors>
  
  <section 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>
  </section>
  
  <section 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>
    
    <list>
      <item name="">
        <p><em>incremental operation</em>: 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.</item>
      <item name="">
        <p><em>lowered memory consumption</em>: 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.</item>
      <item name="">
        <p><em>easier scalability</em>: reduce memory needs allow more
        concurrent operation to be possible, thus allowing the publishing system
        to scale as the load increases.</item>
      <item name="">
        <p><em>more optimizable code model</em>: 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.</item>
      <item name="">
        <p><em>reduced garbage collection</em>: 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.</item>
    </list>
    
    <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>
  </section>
  
  <section 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>
  </section>
  
  <section 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>
    
    <image src="images/pyramid-model.gif" title="The Cocoon2 Pyramid Model of Contracts">
    
    <p>and is composed by four different working contexts (the rectangles)</p>
    
    <list>
      <item name="Management">
        the people that decide what the site should
        contain, how it should behave and how it should appear</item>
      <item name="Conten">
        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.</item>
      <item name="Logi">
        the people responsible for integration with dynamic
        content generation technologies and database systems.</item>
      <item name="Style">
        the people responsible for information
        presentation, look &amp; feel, site graphics and its maintenance.</item>
    </list>
    
    <p>and five contracts contexts (the lines)</p>
    
    <list>
      <item>management - content</item>
      <item>management - logic</item>
      <item>management - style</item>
      <item>content - logic</item>
      <item>content - style</item>
    </list>
  </section>
  
  <section 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>
  </section>
  
  <section 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>
  </section>
  
  <section 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>
  </section>
  </page>
  
  
  
  1.1                  xml-cocoon/docs/dcpprocessor.xml
  
  Index: dcpprocessor.xml
  ===================================================================
  <?xml version="1.0" encoding="utf-8"?>
  
  <!DOCTYPE page SYSTEM "./dtd/page.dtd">
  
  <page title="DCPProcessor User Guide">
   <authors>
    <author name="Ricardo Rocha" email="ricardo@apache.org"/>
   </authors>
  
   <section title="Introduction">
    <p>Yet to be XML-ized!</p>
   </section>
  </page>
  
  
  1.1                  xml-cocoon/docs/dynamic.xml
  
  Index: dynamic.xml
  ===================================================================
  <?xml version="1.0" encoding="utf-8"?>
  
  <!DOCTYPE page SYSTEM "./dtd/page.dtd">
  
  <page title="Dynamic XML in Cocoon">
   <linkuthors>
    <linkuthor name="Stefano Mazzocchi" email="stefano@apache.org"/>
   </authors>
  
  <section 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>
  </section>
  
  <section 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>
  </section>
  
  <section 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>
  </section>
  
  <section 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>
  </section>
  
  <section 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>
    
    <list>
      <item name="Production">where XML content is generated based on Request parameters (servlet equivalent)</item>
      <item name="Processing">where the produced XML content is transformed/evaluated</item>
      <item name="Formatting">where the XML content is finally formatted into the wanted output format for client use.</item>
    </list>
    
    <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>
  </section>
  
  <section 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 <link href="guide.html">user guide</link> on how to install and
    use your own producers.</p>
  </section>
  
  <section 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 <link href="guide.html">user guide</link> on how to install and
    use your own processors.</p>
  </section>
  
  <section 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>
    
    <list>
      <item name="The XSLT processor">
        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.</item>
      <item name="The DCP processor">
        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 <link href="dcpprocessor.html">DCP
        user guide</link> for more information.</item>
      <item name="The SQL processor">
        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 <link href="sqlprocessor.html">SQL
        processor user guide</link> for more information.</item>
    </ul>
  </section>
  
  <section title="Future plans">
    <p>While the above represents a complete set of usable components
    for dynamic XML content generation, the Cocoon project aims to separate all
    three layers (content, logic and style). While XSLT transformations allow a
    perfect separation between content and style with the use of stylesheets, the
    separation between content and logic in dynamically generated XML pages is not
    achieved with current Cocoon features.</p>
    
    <p>To fill this whole, the <link href="xsp/WD-xsp.html">XSP
    (eXtensible Server Pages) technology</link> was proposed. While in the <em>working
    draft</em> stage, we strongly believe that some of the issues expressed in that
    specification will be keys to the future of dynamic XML.</p>
  </section>
  </page>
  
  
  
  1.1                  xml-cocoon/docs/faq.xml
  
  Index: faq.xml
  ===================================================================
  <?xml version="1.0" encoding="utf-8"?>
  
  <!DOCTYPE faq SYSTEM "./dtd/faq.dtd">
  
  <faqs title="Cocoon Frequently Asked Questions">
  
  <faq>
  <q>I don't find my question answered here, what do I do?</q>
  <a author="Stefano">
    <p>First, checkout the Java Apache <a href="http://java.apache.org/faq/?file=54">FAQ-O-Matic</a>
    that contains a Cocoon section. You may find what you're looking for there. If
    not, you may consult the <a href="http://java.apache.org/main/mail.html#cocoon">mail
    list digests and archives</a> (we are aware of the problems regarding lack of
    searching capabilities in the mail list archive and, yes, we <i>are</i> trying
    to solve them). Then, if your problem is still unresolved, you should send a
    message describing your problem with very detailed information about your
    system, your status and your issues and asking for advice.</p>
    <p>Please, keep in mind that nobody gets paid to answer your questions and be
    respectful of the time others are investing to answer you. Also, please,
    respect individual privacy and time by submitting help requests only to the
    mail lists and not directly to developers or individuals.</p>
    <p>At the end, if you come up with a solution for your problem, please, don't
    throw away your effort, share it with us by directly adding it to the FAQ-O-Matic
    and post it to the mail list. Thanks.</p>
  </answer>
  
  <question>How do I pipe my servlet output into Cocoon?</strong></p>
  <answer>
    <p>
      Simple answer: <em>you don't!!!</em> read <a href="dynamic.html">this</a>
      instead to find out equivalent ways to do what you need.<em><br>
      <br>
      </em>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&nbsp; to call
      your servlet and&nbsp; to process its output.<br>
      <br>
      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 try to include
      post-processing hooks 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>
  <strong>Where do I get more information on XSL and XML?</strong>
  <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><a href="http://www.xml.org">http://www.xml.org</a> - A very nice site for XML
        information.</li>
      <li><a href="http://www.w3.org/markup/xml/">http://www.w3.org/markup/xml/</a> - The XML
        official home page at W3C</li>
      <li><a href="http://www.w3.org/style/xsl">http://www.w3.org/style/xsl</a> - The XSL official
        home page W3C</li>
      <li><a href="http://www.software.ibm.com/xml/education/tutorial-prog/abstract.html">http://www.software.ibm.com/xml/education/tutorial-prog/abstract.html</a>
        - XML Tutorial from IBM</li>
      <li><a href="http://www.webtechniques.com/features/1999/01/walsh/walsh.shtml">http://www.webtechniques.com/features/1999/01/walsh/walsh.shtml</a>
        - XSL Tutorial</li>
      <li><a href="http://www.oasis-open.org/cover/xml.html">http://www.oasis-open.org/cover/xml.html</a>
        -&nbsp; XML Resource Listing</li>
      <li><a href="http://www.oasis-open.org/cover/xsl.html">http://www.oasis-open.org/cover/xsl.html</a>
        - XSL Resource Listing</li>
      <li><a href="http://www.xmlsoftware.com">http://www.xmlsoftware.com</a> -
        XML software listing</li>
      <li><a href="http://www.xmlinfo.com">http://www.xmlinfo.com</a> - XML
        information updates on W3C status and others</li>
      <li><a href="http://www.xslinfo.com">http://www.xslinfo.com</a> - XSL
        information, updates, example stylesheets</li>
      <li><a href="http://www.schema.net">http://www.schema.net</a> - Repository
        of standard DTDs</li>
    </ul>
  </answer>
  <strong>The XSL book I found 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?</strong>
  <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.<br>
    <br>
    The current and proper way to associate a stylesheet with an XML document can be found at <a
    href="http://www.w3.org/TR/xml-stylesheet">http://www.w3.org/TR/xml-stylesheet</a> and
    clearly indicates that <code>&lt;?xml-stylesheet ...?&gt;</code> is the proper way.</p>
  </answer>
  <strong>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?</strong>
  <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).<br>
      <br>
      The proposed solution (as you read in the <a href="cocoon2.html">Cocoon2
      outline</a>) is to have a regular expression based 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.<br>
      <br>
      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>
  <strong>What is WAP and I do I browse WML?</strong>
  <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 <a href="http://www.wapforum.org">WAP
      Forum</a>. For a client able to browse WML 1.1 look for the <a href="http://www.nokia.com">Nokia
      WAP Toolkit</a>.</p>
  </answer>
  <strong>When I compile Cocoon on my system, I get all a bunch of errors. What's wrong?</strong>
  <answer>
    <p>You probably didn't add all the needed packages to your compiler's
      classpath or used the wrong version of the servlet classes (Cocoon is
      compiled with the Servlet 2.1 classes).
      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>
  </answer>
    <p><em>External XML entities don't get included in my documents. What's wrong?</em></p>
  <answer>
    <p>This is a well known bug in Cocoon. External entities don't work if not
    used in an absolute URL format, so you should either use an http:// or file://
    URL with absolution location.</p>
  </answer>
  <p><em>My stylesheet doesn't sense the presence of my request parameters. How do
  I pass them to it?</em></p>
  <answer>
    <p>&nbsp;Another well known bug. Cocoon is not yet able to pass request
    parameters to the stylesheets. It will be fixed in future releases.</p>
  </answer>
  <strong>Why the name &quot;Cocoon&quot;?</strong>
  <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 and I woke up 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 Cocoon 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. :-)<br>
    </p>
  </answer>
  
  </faqs>
  
  
  1.1                  xml-cocoon/docs/guide.xml
  
  Index: guide.xml
  ===================================================================
  <?xml version="1.0" encoding="utf-8"?>
  
  <!DOCTYPE page SYSTEM "./dtd/page.dtd">
  
  <page title="User Guide">
   <authors>
    <author name="Stefano Mazzocchi" email="stefano@apache.org"/>
   </authors>
  
  <section 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>
  </section>
  
  <section 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!</pre>
  </source>
  </section>
  
  <section 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><![CDATA[<ml-stylesheet href"hello.xsl" type="text/xsl">]]></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/XSL/Transform/1.0">
  </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>
  
  </section>
  
  <section 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>
    
    <list>
      <item name="explorer">any Microsoft Internet Explorer, searches for <em>MSIE</em> (before
        searching for Mozilla, since they include it too)</item>
      <item name="opera">the Opera browser (before searching for Mozilla, since
        they include it too)</item>
      <item name="lynx">the text-only Lynx browser</item>
      <item name="java">any Java code using standard URL classes</item>
      <item name="wap">the Nokia WAP Toolkit browser</item>
      <item name="netscape">any Netscape Navigator, searches for <em>Mozilla</em></item>
    </list>
    
    <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><![[CDATA[
  browser.0=explorer=MSIE
  browser.1=opera=Opera
  browser.2=lynx=Lynx
  browser.3=java=Java
  browser.4=wap=Wapsody
  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>
  </section>
  
   <section 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>
    
    <image src="images/schema.jpg" title="Cocoon Schema">
    
    <p>Let's describe the components that appear on the schema:</p>
    
    <list>
     <item name="Request">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.</item>
     <item name="Producer"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.</item>
     <item name="Reactor">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.</item>
     <item name="Formatter">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.</item>
     <item name="Response">encapsulates the formatted document along
       with its properties (such as length, MIME type, etc..)</item>
     <item name="Loader">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. [this part is not yet
       implemented]</item>
     </list>
    </section>
    
  <section 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><![[CDATA[
  <?cocoon-process type="xxx"?> for processing
  
        and
  
  <?cocoon-format type="yyy"?> 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/XSL/Format/1.0">
   <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>  
   
    <p>Cocoon comes with a number of processors and formatters which are
    configured as follows</p>
    
    <table>
     <row>
        <element>type</element>
        <element>class</element>
        <element></element>
     </row>
     <row>
        <element rowspan="3">Processors</element>
        <element><em>xslt</em></element>
        <element>org.apache.cocoon.processor.xslt.XSLPProcessor</element>
        <element>The XSLT Processor</element>
      </row>
      <row>
        <element><em>dcp</em></element>
        <element>org.apache.cocoon.processor.dcp.DCPProcessor</element>
        <element>The <link href="dcpprocessor.html">DCP</link> Processor</element>
      </row>
      <row>
        <element><em>sql</em></element>
        <element>org.apache.cocoon.processor.sql.SQLProcessor</element>
        <element>The <link href="sqlprocessor.html">SQL</link> Processor</element>
      </row>
      <row>
        <element rowspan="5">Formatters</element>
        <element><em>text/xml</em></element>
        <element>org.apache.cocoon.formatter.xml.OpenXMLXMLFormatter</element>
        <element>General XML Formatter</element>
      </row>
      <row>
        <element><em>text/html</em></element>
        <element>org.apache.cocoon.formatter.html.OpenXMLHTMLFormatter</element>
        <element>HTML 4.0 Formatter</element>
      </row>
      <row>
        <element><em>text/xhtml</em></element>
        <element>org.apache.cocoon.formatter.xhtml.OpenXMLXHTMLFormatter</element>
        <element>XHTML Formatter</element>
      </row>
      <row>
        <element><em>text/wml</em></element>
        <element>org.apache.cocoon.formatter.wml.OpenXMLWMLFormatter</element>
        <element>WML 1.1 Formatter</element>
      </row>
      <row>
        <element><em>text/xslfo</em></element>
        <element>org.apache.cocoon.formatter.pdf.FOPFormatter</element>
        <element>PDF Formatter</element>
      </row>
     </table>
  </section>
  
  <section 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>
    
    <list>
     <item>when the request comes, the cache is searched.
      <list>
       <item>if the request is found;
        <list>
         <item>its <em>changeable</em> points are evaluated</item>
         <item>if all changeable points are unchanged
          <list>
           <item>the page is served directly from the cache</item>
          </list>
         </item>
         <item>if a single point has changed and requires reprocessing
          <list>
           <item>the page is invalidated and continues as if it wasn't found</item>
          </list>
         </item>
        </list>
       </item>
       <item>if the request is not found:
        <list>
         <item>the page is normally processed</item>
         <item>it's sent to the client</item>
         <item>it's stored into the cache</item>
        </list>
       </item>
      </list>
     </item>
    </list>
    
    <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. [this part is not yet implemented]</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>
  </section>
  </page>
  
  
  
  1.1                  xml-cocoon/docs/index.xml
  
  Index: index.xml
  ===================================================================
  <?xml version="1.0" encoding="utf-8"?>
  
  <!DOCTYPE page SYSTEM "./dtd/page.dtd">
  
  <page title="Cocoon">
   <authors>
    <author name="Stefano Mazzocchi" email="stefano@apache.org"/>
   </authors>
  
   <section title="What is it?">
    <p>
     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 <link href="technologies.html">Introduction on Cocoon
     technologies</link> white paper to find out more on the subject.
    </p>
   </section>
   
   <section 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>
   </section>
   
   <section 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:
     <list>
      <item name="XML creation">
       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.
      </item>
      <item name="XML processing">
       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.
      </item>
      <item name="XSL rendering">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)
      </item>
     </list>
    </p>
   </section>
  
   <section 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>
     In this direction it must be understood that Cocoon 1.x should
     be considered a proof of concept rather than a software usable for real web
     sites. In fact, the Cocoon projects aims to gather as much information as
     possible during it's first generation while its second generation, starting
     from Cocoon 2.0, will aim to be a usable and real-life publishing framework.
     See the <link href="cocoon2.html">Cocoon 2 outline</link> to understand the 
     design plans already established.
    </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>
   </section>
  
   <section title="Where do I get it?">
    <p>
     Go to the <link href="http://java.apache.org/cocoon/dist/">download area</link>
     and be sure you read the release note in that page.
    </p>
   </section>
   
   <section 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/???">Cocoon mail list</link> 
     (follow the link for information on how to subscribe and to access the mail 
     list archives), to checkout the <link href="http://www.apache.com/cvsweb/index.cgi/cocoon/">
     latest and greatest code</link> (which you found in the xml-cocoon module in 
     the xml.apache.org CVS code repository), control the <link href="todo.html">todo</link>
     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 other may wish to
     contribute, so, please, help us by placing the cocoon logo somewhere in your
     site to indicate that you are using uses and supporting the Cocoon Project.
    </p>
    <p>
     Thank you very much.
    </p>
   </section>
  </page>
  
  
  
  1.1                  xml-cocoon/docs/installing.xml
  
  Index: installing.xml
  ===================================================================
  <?xml version="1.0" encoding="utf-8"?>
  
  <!DOCTYPE page SYSTEM "./dtd/page.dtd">
  
  <page title="Installing Cocoon">
  
   <authors>
    <author name="Stefano Mazzocchi" email="stefano@apache.org"/>
   </authors>
   
   <section title="System Requirements">
    <p>
     Cocoon requires the following systems to be already installed in your
     system:
    </p>
    
    <list>
     <item name="Java Virtual Machine">
      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.
     </item>
     <item name="Servlet Engine">
      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.
     </item>
    </list>
     
   </section>
   
   <section 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>
     Cocoon uses an XML parser and an XSLT processor has its basic components and
     uses the DOM API to access work with them. For this reason, you need both
     DOM-enabled XML parser and XSLT processor. Also, for complex formatting,
     Cocoon uses a formatting object renderer and a set of printing classes
     to send the page to the client.
    </p>
    
    <p>
     Being an Apache project, Cocoon focues on Apache technologies and comes
     configured to operate with Xerces, Xalan and FOP, but other DOM-aware 
     components are supported as well (see the <code>cocoon.properties</code>
     file for more information on other components supported).
    </p>
    
    <p>
     For this reason, in order to work out of the box and have complete operation, 
     you need to download all three packages (Xerces-J, Xalan-J and FOP) from the
     <link href="http://xml.apache.org/dist/">xml.apache.org</link>. Once you have
     all three jar packages required and all other packages that may be required
     by these projects, go ahead and follow the instructions for your servlet
     engine.
    </p>
   
   </section>
    
   <section 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>
    
    <section 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 the components needed by Cocoon (and
      explained in the above paragraphs) 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>
      <em>Note:</em> do not add the <code>cocoon.jar</code> package here since
      this might corrupt it's normal operation. Here, you should add all the 
      required packages <em>but</em> Cocoon itself.
     </p>
     
     <p>
      At this point, you must tell the servlet engine to locate Cocoon (since
      you didn't do this in the step right above!). To do this, you should choose
      the servlet zone where you want Cocoon to reside. 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. Now add the 
      <code>cocoon.jar</code> package to your servlet zone by making sure
      a line like this is present in your zone property file.
     </p>
     
     <source>repositories=...,[path-to-cocoon]/bin/cocoon.jar</source>
     
     <p>
      where ... stands for any other servlet repository the servlet zone already
      contains (or might be empty if no other repository is used by this zone) and
      <em>[path-to-cocoon]</em> is substitued by the actual path to the <code>
      cocoon.jar</code> file.
     </p>
     
     <p>
      Now the servlet engine knows where to locate the Cocoon servlet
      but Cocoon must need to know its configurations to be able to start. 
      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:
     </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, 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>ApJServAction .xml /servlet/org.apache.cocoon.Cocoon</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>
      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.
     </p>
    </section>
    
    <section title="Installing Cocoon on Apache Tomcat">
     <p>Yet to be written! <em>Volunteers welcome!</em></p>
    </section>
    
    <section title="Installing Cocoon on Allaire JRun">
     <p>Yet to be written! <em>Volunteers welcome!</em></p>
    </section>
    
    <section title="Installing Cocoon on NewAtlanta ServletExec">
     <p>Yet to be written! <em>Volunteers welcome!</em></p>
    </section>  
  
   </section>
   
   <section title="Working Systems">
    <p>
     Cocoon has been reported to be working on these systems:
    </p>
    
    <list>
      <item>RedHat Linux 6.0 + Apache 1.3.9 + Apache JServ 1.0 + IBM JDK 1.1.8</item>
      <item>RedHat Linux 6.0 + Apache 1.3.9 + Apache JServ 1.1b3 + IBM JDK 1.1.8</item>
      <item>RedHat Linux 6.0 + Apache 1.3.9 + Apache JServ 1.0 + Blackdown JDK 1.2pre2</item>    
      <item>RedHat Linux 6.1 + Apache 1.3.9 + JRun 2.3.3 + IBM JRE 1.1.8</item>
      <item>Windows 98 + Apache 1.3.9 + Apache JServ 1.0 + IBM JDK 1.1.7</item>
      <item>Windows 98 + Apache 1.3.9 + Apache JServ 1.1b3 + IBM JDK 1.1.7</item>
      <item>Windows 98 + Apache 1.3.9 + Apache JServ 1.0 + Sun JDK 1.2.2</item>
      <item>Windows 98 + Apache 1.3.9 + Apache JServ 1.1b3 + Sun JDK 1.2.2</item>
      <item>Windows 98 + MS Personal Web Server + ServletExec 2.2 + Sun JDK 1.2.1</item>
      <item>Windows NT 4.0 + IIS 4.0 + ServletExec 2.2 + Sun JDK 1.2.1</item>
      <item>Windows NT 4.0 + IIS 4.0 + JRun 2.3.3 + Sun JDK 1.2.1</item>
      <item>MacOS 8.6 + WebSTAR 4.0 + JRun 2.3 + MrJ 2.1.4</item>
      <item>MacOS 8.6 + WebSTAR 4.0 + ServletExec 2.1 + Mrj 2.1.4</item>
      <item>SunOS Netria 5.6 + Apache 1.3.9 + Apache JServ 1.1b3 + Sun JDK 1.1.7</item>
    </list>
    
    <p>
     <em>Note:</em> 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.
    </p>
    <p>
     Please, submit your feedback if you were able to install Cocoon on a
     different combination not listed above. Thanks.
    </p>
   </section>
  </page>
  
  
  
  
  1.1                  xml-cocoon/docs/license.xml
  
  Index: license.xml
  ===================================================================
  <?xml version="1.0" encoding="utf-8"?>
  
  <!DOCTYPE page SYSTEM "./dtd/page.dtd">
  
  <page title="Installing Cocoon">
  
   <authors>
    <author name="Stefano Mazzocchi" email="stefano@apache.org"/>
   </authors>
   
  <section 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>
  </section>
  </page>
  
  
  1.1                  xml-cocoon/docs/sqlprocessor.xml
  
  Index: sqlprocessor.xml
  ===================================================================
  <?xml version="1.0" encoding="utf-8"?>
  
  <!DOCTYPE page SYSTEM "./dtd/page.dtd">
  
  <page title="SQLProcessor User Guide">
   <authors>
    <author name="Donald A. Ball Jr." email="balld@webslingerz.com"/>
   </authors>
  
   <section title="Introduction">
    <p>Yet to be XML-ized!</p>
   </section>
  </page>
  
  
  1.1                  xml-cocoon/docs/technologies.xml
  
  Index: technologies.xml
  ===================================================================
  <?xml version="1.0" encoding="utf-8"?>
  
  <!DOCTYPE page SYSTEM "./dtd/page.dtd">
  
  <page title="Introduction on Cocoon Technologies">
  
   <authors>
    <author name="Stefano Mazzocchi" email="stefano@apache.org"/>
    <author name="Keith Visco" email="visco@exoffice.com"/>
   </authors>
   
   <section title="Introduction">
  
  <p>Many people do not seem to understand the global picture about the
  technologies used by Cocoon, I will try to explain my vision of these
  technologies as well as some information that might be useful to you to jump in,
  help with its development or show your boss how much money he can save.</p>
  
   </section>
  
  <section title="What is this XML?">
  
    <p>XML (<link href="http://www.w3.org/markup/">eXtended Markup Language</link>) is an SGML subset. SGML is the father of all
    markup languages and its a 15-years old ISO standard for creating languages.
    XML is a lighter version of SGML.</p>
  
    <p>First thing to understand: XML is NOT a language (like HTML), but a syntax.
    Exactly like ASCII that defines a standard way to map characters to bytes and
    not a bunch of character strings.</p>
  
  <p>XML is usually referred to as &quot;portable data&quot; in the sense that its
  parsing is &quot;application independent&quot; and one 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 file
  formats which are text based or binary. Some sort of equivalent in the old days
  are CSV (comma separated values) files which use a very simple syntax (use comma
  to separate values and the first raw to outline the content of the columns) and
  are portable to every implementation. XML, unlike CSV, is much more flexible and
  structured even if it's much simpler than SGML.</p>
  
  <p>A particular XML language is defined by its Document Type Definition (DTD)
  which is described inside the XML specification. An XML document may be
  validated against a DTD (if present) and if the validation is successful the
  document is said &quot;valid XML based on the particular DTD&quot;, if a DTD is
  not present and the parser does not encounter syntax errors parsing the file,
  the XML document is said &quot;well-formed&quot;. 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 necessary be valid for another DTD.
  For example, HTML is not an XML language because the <code>&lt;br&gt;</code> tag
  is not XML compliant. XHTML (where <code>&lt;br&gt;</code> is replaced by <code>&lt;br/&gt;</code>)
  is XML compliant. While HTML pages are not always XML documents (some pages
  might be), XHTML pages are always well-formed and valid if matched against the
  XHTML DTD.</p>
  
    <p>So far for the technical differences, but why HTML was not good enough?
    Let's make an example.</p>
  
  </section>
  
  <section title="XML shows its power">
    <p>Consider why the need for XML came about:</p>
    <list>
      <item>Everyone starts pubitemshing HTML documents on the web.</item>
      <item>Search engines spring up across the net to help find documents.</item>
      <item>Search engines have a difficult time searching specific pieces of a
        document since HTML was designed to hierarchically represent how data
        should be presented, but not what the data being presented is.</item>
      <item>Web appitemcations spring up across the net to provide information and
        &quot;services&quot;.</item>
    </list>
    <p>These services could be web pages that serve up important information about
    an organization or the structure of the organization. They could be weather
    information, or travel advisories. They 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 these web pages for specific content, like Author or Subject. Find me all
    abstracts of any documents published that have a subject of &quot;Big Tomatoes&quot;,
    since I only want to view abstracts to find out which document is 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 choose to make every
    paragraph heading bold with <code>&lt;font size+1&gt;</code>. Yet if I look at
    another page I might notice that every paragraph 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 &quot;potato&quot; in the paragraph heading
    of the first paragraph.</p>
    <p>Suppose I have a weather web-based application that servers up weather
    information for different parts of the country. Let's say you live in Boston,
    MA and only want the weather for Boston. Your boss asks you to write an
    application that goes out and grabs the two-three sentence weather summary
    from my application and display this 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 returned. 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 that parses my HTML code to
    retrieve just the information you were looking for. You pat yourself on the
    back when 4 hours later you finally get the information you were look for.
    Your code looks for the 2nd Table, the 6th TR and then the 2nd TD. Phew. Your
    application, that only wants weather data, is forced to parse display markup
    to get the data it needs.</p>
    <p>You run over to your boss and show him your application that you are so
    proud that you wrote. Low and behold it doesn't work. What happened? Good old
    path author decided to change his display and put the weather summary in Table
    1, TR 1, TD 1. Your application broke because it was 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. This site was
    automatically generated from XML and you see a link that says XML DTD for
    weather information. And another link that says XML stream for weather
    information available. 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 download Cocoon, simply write an XSL stylesheet that looks the 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>
   </section>
  
  <section title="The HTML Model">
  
  <p>As the above example explains very well, HTML is a language for describing
  graphics, behavior and hyperlinks on web pages. HTML is NOT able to <em>contextualize</em>
  (means &quot;give meaning to some text&quot;) in the sense that if you look for
  the &quot;title&quot; of your page, a nice HTML tag gives you that, but if you
  look at the author or version or something more specific like the author mail
  address, even if this information is present in the text you don't have a way to
  &quot;isolate&quot; this (contextualize it) from the surrounding information.</p>
  
  <p>In some 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, while 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 picture XML take over HTML in web publishing since HTML is great for
  small needs. HTML was born as an SGML-based DTD for scientists homepages. HTML
  was NOT designed for publishing and treatment of large quantity of data and
  complex dynamic information systems, but only to parallelize and simplify the
  deployment and management of personal information.</p>
  
  </section>
  
  <section title="The XSL Language">
  
  <p>As you see, XML alone is useless without some defined semantics: even if an
  application is able to parse a document in memory, it must be able to <em>understand</em>
  that the markup means. This is why XML-only browsers are meaningless and not
  more useful than text editors from an usability point of view.</p>
  
  <p>This is one of the reasons why the XSL language (<link href="http://www.w3.org/style/xsl/">eXtensible Stylesheet
  Language</link>) was proposed and designed. XSL is divided in two parts: transformation (XSLT) and
  formatting objects (sometimes referred to FO, XSL:FO or simply XSL). Both are
  XML DTDs that define a particular XML syntax. So every XSL and XSLT document is
  a well-formed XML document.</p>
  
  </section>
  
  <section title="XSL Transformations (XSLT)">
  
  <p>XSLT is a language for transforming one well-formed XML document into
  something else. This means that you may use it to go from one DTD to another in an procedural way
  that is defined inside your XSLT document. Even if the name tells the opposite,
  this language can be used for document styling as well as for many other useful
  transformations: in fact, transformations may be applied to one particular XML
  DTD and come up with some &quot;graphical description&quot; of the original
  content. This is called &quot;styling&quot;, but, as you can see, this is just
  one of the possible uses of the technology.</p>
  
  <p>For example, the above HTML example may be created from the second XML file
  given a particular transformation sheet (which in this case becomes a
  stylesheet). As you can see, 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 in
  memory.</p>
  
  <p>Usually, transformation sheets work from one DTD to another and for this
  reason may be used in chain: transformA goes from DTD1 to DTD2 and transformB
  from DTD2 to DTD3 or graphically</p>
  
  <source>DTD1 ---(transformA)--&gt; DTD2 ---(transformB)---&gt; DTD3</source>
  
  <p>We'll call DTD1 the <em>original DTD</em> (because its the origin), DTD2 some <em>intermediate
  DTD</em>, DTD3 the <em>final DTD</em>. It can be shown that 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>
  
  </section>
  
  <section title="XSL Formatting Objects (XSL:FO)">
  
  <p>XSLFO is a language (an XML DTD) for describing 2D graphics of text in both
  printed and digital media. I will not concentrate on the graphical abilities
  that formatting objects gives you, but rather on the fact that it is most of the
  time used as a &quot;final DTD&quot;, meaning that a transformation is used to
  generate a formatting object description of a document starting from a general
  XML file.</p>
  
  <p>The example above would lead:</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
    &quot;draw&quot; and place the text on the screen or on paper. Formatting
    objects and transformations are created by the same working group and show
    very high synergies even if the XSLT specification also includes way to create
    HTML and text out of XML files as well.</p>
  
  </section>
  
  
  <section title="The XSP Language">
  
    <p>The Cocoon publishing model is heavily based on the XSLT transformation
    capabilities that allow complete separation of content and style (something
    that is much harder to obtain with HTML even using CSS2 or other styling
    technologies) but it moved on to defined a way to separate page content and
    document tags from the programming logic that drive their server side
    behavior.</p>
  
    <p>The XSP language (<link href="xsp/WD-xsp.html">eXtensible Server Pages</link>) languages defines an XML DTD for
    separating content and logic for compiled server pages. 
    XSP (eXtensible Server Pages) is, like XSLFO, supposed to be a &quot;final
    DTD&quot; in the sense that is the result of one or more transformation steps
    and must be rendered by some formatter into pure source code that can then be
    compiled into binary code.</p>
  
    <p>In every dynamic page, there is a mix of static content and logic that work
    together to create the final result, usually using run-time or
    time-dependent input. In dynamic content generation technology, content and
    logic are mixed in the same page. XSP is no exception since it defines a
    syntax to mix static content and programmatic logic in a way that is independent
    of the programming language used and on the binary results that the final
    source-rendering gives.</p>
  
    <p>But it must be understood that XSP is just a piece of the framework:
    exactly like formatting objects mix style and content, XSP mix logic and
    content. On the other hand, being both 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>
  
  </section>
  </page>
  
  
  
  
  1.1                  xml-cocoon/docs/dtd/blocks.ent
  
  Index: blocks.ent
  ===================================================================
  <?xml version="1.0" encoding="utf-8"?>
  
  <!ENTITY % charEntity SYSTEM "characters.ent">%charEntity;
  
  <!ENTITY % links "link">
  
  <!ELEMENT link (#PCDATA)*>
  <!ATTLIST link href CDATA #REQUIRED>
  
  <!ENTITY % markup "em|ref|code">
  
  <!ELEMENT em (#PCDATA)>
  <!ELEMENT ref (#PCDATA)>
  <!ELEMENT code (#PCDATA)>
  
  <!ENTITY % content "#PCDATA|%markup;|%links;">
  
  <!ENTITY % blocks "p|note|table|source|list|image">
  
  <!ELEMENT p (%content;)*>
  
  <!ELEMENT note (%content;)*>
  
  <!ELEMENT table (row)+>
  <!ELEMENT row (element)+>
  <!ELEMENT element (%content;)*>
  <!ATTLIST element colspan CDATA #IMPLIED
                    rowspan CDATA #IMPLIED>
  
  <!ELEMENT source (#PCDATA|highlight)*>
  <!ATTLIST source xml:space (default|preserve) "preserve">
  <!ELEMENT highlight (#PCDATA)>
  <!ATTLIST highlight type CDATA #REQUIRED>
  
  <!ELEMENT list (item)+>
  <!ELEMENT item (%content;|list)*>
  <!ATTLIST item name CDATA #IMPLIED>
  
  <!ELEMENT image EMPTY>
  <!ATTLIST image src CDATA #REQUIRED
                  title CDATA #IMPLIED>
  
  
  1.1                  xml-cocoon/docs/dtd/changes.dtd
  
  Index: changes.dtd
  ===================================================================
  <?xml version="1.0" encoding='utf-8'?>
  
  <!ENTITY % blocksEntity SYSTEM "blocks.ent">
  %blocksEntity;
  
  <!ELEMENT changes (release)+>
  <!ATTLIST changes title CDATA #IMPLIED>
  
  <!ELEMENT release (devs,action+)>
  <!ATTLIST release date CDATA #IMPLIED
                    vers CDATA #IMPLIED>
  
  <!ELEMENT devs (dev+)>
  <!ELEMENT dev EMPTY>
  <!ATTLIST dev name  CDATA #REQUIRED
                id    CDATA #REQUIRED
                email CDATA #IMPLIED>
  
  <!ELEMENT action %content;>
  <!ATTLIST action dev CDATA #IMPLIED
                   type (add|update|fix|remove) #IMPLIED
                   due-to CDATA #IMPLIED
                   due-to-email CDATA #IMPLIED>
  
  
  
  
  1.1                  xml-cocoon/docs/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. Typical invocation:
       <!ENTITY % HTMLlat1 PUBLIC
         "-//W3C//ENTITIES Latin 1//EN//HTML">
       %HTMLlat1;
  -->
  
  <!-- C0 Controls and Basic Latin -->
  <!-- WARNING: due to a bug in IE5, these are removed for now -->
  <!-- <!ENTITY quot     "&#34;"> --> <!-- U+0022 ISOnum    - quotation mark = APL quote                                            -->
  <!-- <!ENTITY amp      "&#38;"> -->  <!-- U+0026 ISOnum    - ampersand                                                             -->
  <!-- <!ENTITY lt       "&#60;"> -->  <!-- U+003C ISOnum    - less-than sign                                                        -->
  <!-- <!ENTITY gt       "&#62;"> -->  <!-- U+003E ISOnum    - greater-than sign                                                     -->
  
  <!-- 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/docs/dtd/faq.dtd
  
  Index: faq.dtd
  ===================================================================
  <?xml version="1.0" encoding="utf-8"?>
  
  <!ENTITY % blocksEntity SYSTEM "blocks.ent">
  %blocksEntity;
  
  <!ELEMENT faqs (faq)+>
  <!ATTLIST faqs title CDATA #REQUIRED>
  
  <!ELEMENT faq (q,a)>
  <!ATTLIST faq title CDATA #IMPLIED>
  
  <!ELEMENT q (#PCDATA)>
  <!ELEMENT a (%blocks;)+>
  <!ATTLIST a author CDATA #IMPLIED>
  
  
  
  
  1.1                  xml-cocoon/docs/dtd/page.dtd
  
  Index: page.dtd
  ===================================================================
  <?xml version="1.0" encoding="utf-8"?>
  
  <!ENTITY % blocksEntity SYSTEM "blocks.ent">
  %blocksEntity;
  
  <!ELEMENT page (authors?,section*)>
  <!ATTLIST page title CDATA #IMPLIED>
  
  <!ELEMENT authors (author)+>
  <!ELEMENT author EMPTY>
  <!ATTLIST author name CDATA #REQUIRED
                   email CDATA #IMPLIED>
  
  <!ELEMENT section (section|%blocks;)*>
  <!ATTLIST section title CDATA #REQUIRED>
  
  
  
  1.1                  xml-cocoon/docs/dtd/todo.dtd
  
  Index: todo.dtd
  ===================================================================
  <?xml version="1.0" encoding='utf-8'?>
  
  <!ENTITY % blocksEntity SYSTEM "blocks.ent">
  %blocksEntity;
  
  <!ELEMENT todo (action)+>
  <!ATTLIST todo title CDATA #IMPLIED>
  
  <!ELEMENT action %content;>
  <!ATTLIST action priority CDATA #REQUIRED
                   assigned-to CDATA #IMPLIED>
  
  
  
  
  1.1                  xml-cocoon/docs/stylesheets/javadoc.html.css
  
  Index: javadoc.html.css
  ===================================================================
  /* Apache Javadoc style sheet */
  
  /* Page background color */
  body { background-color: #FFFFFF }
  
  /* Table colors */
  .TableHeadingColor     { background: #D0D0D0 }
  .TableSubHeadingColor  { background: #E0E0E0 }
  .TableRowColor         { background: #F9F9F9 }
  
  /* Navigation bar fonts and colors */
  .NavBarCell1    { background-color:#D0D0D0;}
  .NavBarCell1Rev { background-color:#A0A0A0;}
  .NavBarFont1    { font-family: Arial, Helvetica, sans-serif; color:#000000;}
  .NavBarFont1Rev { font-family: Arial, Helvetica, sans-serif; color:#FFFFFF;}
  .NavBarCell2    { font-family: Arial, Helvetica, sans-serif; background-color:#E0E0E0;}
  .NavBarCell3    { font-family: Arial, Helvetica, sans-serif; background-color:#F0F0F0;}
  
  /* Font used in left-hand frame lists */
  .FrameTitleFont   { font-size: normal; font-family: Helvetica, Arial, sans-serif }
  .FrameHeadingFont { font-size: normal; font-family: Helvetica, Arial, sans-serif }
  .FrameItemFont    { font-size: 10pt; font-family: Helvetica, Arial, sans-serif }
  
  /* Link colors styling */
  A:link { color: #0000A0 }          /* unvisited link */
  A:visited { color: #A00000 }       /* visited links */
  A:active { color: #00A000 }        /* active links */
  
  
  

Mime
View raw message