cocoon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From bdelacre...@apache.org
Subject svn commit: r159287 - in cocoon/trunk/src/documentation/src/content/xdocs: c21_concepts_index/ c21_concepts_index/content_en.xdoc c21_concepts_index/meta.xml c21_index/ c21_index/content_en.xdoc c21_index/meta.xml c21_introduction/ c21_introduction/content_en.xdoc c21_introduction/meta.xml site.xml tabs.xml
Date Mon, 28 Mar 2005 20:02:45 GMT
Author: bdelacretaz
Date: Mon Mar 28 12:02:42 2005
New Revision: 159287

URL: http://svn.apache.org/viewcvs?view=rev&rev=159287
Log:
added 'legacy' tab as a temporary location for 2.1 docs, while we review them and integrate
their content to the new docs

Added:
    cocoon/trunk/src/documentation/src/content/xdocs/c21_concepts_index/
    cocoon/trunk/src/documentation/src/content/xdocs/c21_concepts_index/content_en.xdoc
    cocoon/trunk/src/documentation/src/content/xdocs/c21_concepts_index/meta.xml
    cocoon/trunk/src/documentation/src/content/xdocs/c21_index/
    cocoon/trunk/src/documentation/src/content/xdocs/c21_index/content_en.xdoc
    cocoon/trunk/src/documentation/src/content/xdocs/c21_index/meta.xml
    cocoon/trunk/src/documentation/src/content/xdocs/c21_introduction/
    cocoon/trunk/src/documentation/src/content/xdocs/c21_introduction/content_en.xdoc
    cocoon/trunk/src/documentation/src/content/xdocs/c21_introduction/meta.xml
Modified:
    cocoon/trunk/src/documentation/src/content/xdocs/site.xml
    cocoon/trunk/src/documentation/src/content/xdocs/tabs.xml

Added: cocoon/trunk/src/documentation/src/content/xdocs/c21_concepts_index/content_en.xdoc
URL: http://svn.apache.org/viewcvs/cocoon/trunk/src/documentation/src/content/xdocs/c21_concepts_index/content_en.xdoc?view=auto&rev=159287
==============================================================================
--- cocoon/trunk/src/documentation/src/content/xdocs/c21_concepts_index/content_en.xdoc (added)
+++ cocoon/trunk/src/documentation/src/content/xdocs/c21_concepts_index/content_en.xdoc Mon
Mar 28 12:02:42 2005
@@ -0,0 +1,563 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  Copyright 1999-2004 The Apache Software Foundation
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+-->
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "document-v10.dtd">
+
+<document> 
+ <header>
+  <title>Understanding Apache Cocoon</title>
+  <authors>
+   <person name="Pankaj Kumar" email="pankaj_kumar@hp.com"/>
+   <person name="Davanum Srinivas" email="dims@yahoo.com"/>
+  </authors>
+ </header>
+
+ <body>
+   <s1 title="Overview">
+     <p>
+     This document is intended for both Users and Developers 
+     and presents an overall picture of @Name@.
+     </p>
+
+     <ul>
+       <li>
+         <link href="#pre-requisites">
+           Prerequisites
+         </link>
+       </li>
+       <li>
+         <link href="#a-little-history">
+           A Little History
+         </link>
+       </li>
+       <li>
+         <link href="#what-problems">
+           What problem does Cocoon solve?
+         </link>
+       </li>
+       <li>
+         <link href="#basic-mechanisms">
+           Basic Mechanisms.
+         </link>
+       </li>
+       <li>
+         <link href="#c2-architecture">
+           Architecture.
+         </link>
+       </li>
+       <li>
+         <link href="#c2-abstractions">
+           Abstraction.
+         </link>
+       </li>
+       <li>
+         <link href="#cocoon-configuration">
+           @Name@ Configuration.
+         </link>
+       </li>
+       <li>
+         <link href="#work-area">
+           @Name@ Work Area.
+         </link>
+       </li>
+       <li>
+         <link href="#use-with-tomcat">
+           Use with Tomcat
+         </link>
+       </li>
+     </ul>
+  </s1>
+
+  <anchor id="pre-requisites"/>
+  <s1 title="Prerequisites">
+    <p>What You Should know:</p> 
+    <ul> 
+         <li>XML, XML Namespaces</li>
+         <li>Basics of XPath, XSLT</li>
+         <li>Java language</li>
+         <li>Servlets, HTTP</li>
+    </ul> 
+    <p>What You need not know:</p> 
+    <ul> 
+         <li>Cocoon 1</li>
+    </ul> 
+  </s1>
+  <anchor id="a-little-history"/>
+  <s1 title="A Little History">
+    <s2 title="Cocoon 1">
+      <ul> 
+            <li>Cocoon project was founded in Jan. 1999 by Stefano Mazzocchi as an
open source project under Apache Software Foundation.</li>
+            <li>Started as a simple servlet for XSL styling of XML content.</li>
+            <li>Was based on DOM level 1 API. This choice turned out to be quite limiting
for speed/memory efficiency.</li>
+            <li>Used reactor pattern to connect components. This allowed the reaction
instructions to be placed inside the documents.  Though appealing, it caused difficulties
in managing highly dynamic web-sites.</li>
+            <li>Allowed context overlap to happen by having processing instructions
in documents/stylesheets.</li>
+      </ul> 
+    </s2>
+    <s2 title="Apache Cocoon">
+      <ul> 
+            <li>A separate codebase to incorporate Cocoon 1 learnings.</li>
+            <li>Designed for execution speed/memory efficiency and scalability to process
very large documents by switching processing model from DOM to SAX.</li>
+            <li>Centralizes the management functions by allowing processing pipeline
specification in a sitemap (an XML file), replacing the embedded processing instruction model.</li>
+            <li>Better support for pre-compilation, pre-generation and caching for
better performance.</li>
+      </ul>
+    </s2>
+  </s1>
+  <anchor id="what-problems"/>
+  <s1 title="What problem does Cocoon solve?">
+    <p>Basic problem to be solved:</p>
+    <s2 title="Separation of content, style, logic and management functions in an XML
content based web site (and web services).">
+      <figure src="images/pyramid-model.gif"
+              alt="The @Name@ Pyramid Model of Contracts"
+              width="313" height="159"/>
+    </s2>
+    <s2 title="Data Mapping">
+      <figure src="images/data-mapping.gif" alt="The @Name@ Data Mapping"
+              width="339" height="174"/>
+    </s2>
+  </s1>
+  <anchor id="basic-mechanisms"/>
+  <s1 title="Basic Mechanisms.">
+    <p>Basic mechanisms for processing XML documents:</p>
+    <ul>
+      <li>Dispatching based on Matchers.</li>
+      <li>Generation of XML documents (from content, logic, Relation DB, objects or
any combination) through Generators</li>
+      <li>Transformation (to another XML, objects or any combination) of XML documents
through Transformers</li>
+      <li>Aggregation of XML documents through Aggregators</li>
+      <li>Rendering XML through Serializers</li>
+    </ul>
+    <figure src="images/basic-mechanism.gif" alt="Basic Mechanisms"
+            width="288" height="386"/>
+    <s2 title="Pipeline Processing">
+        <p>Sequence of Interactions</p>
+        <figure src="images/interaction-sequence.gif"
+                alt="Interaction Sequence"
+                width="613" height="347"/>
+        <p>Pipeline</p>
+        <figure src="images/pipeline.gif" alt="Pipeline"
+                width="713" height="223"/>
+    </s2>
+  </s1>
+  <anchor id="c2-architecture"/>
+  <s1 title="Architecture.">
+    <figure src="images/architecture.gif" alt="Architecture"
+            width="430" height="349"/>
+    <s2 title="Core Cocoon">
+      <ul>
+        <li>Avalon framework for logging, configuration, threading, context etc.</li>
+        <li>Caching mechanism</li>
+        <li>Pipeline handling</li>
+        <li>Program generation, compilation, loading and execution.</li>
+        <li>Base classes for generation, transformation, serialization, components.</li>
+        <li>...</li>
+      </ul>
+    </s2>
+    <s2 title="Cocoon Components">
+      <ul>
+        <li>Specific generators</li>
+        <li>Specific transformers</li>
+        <li>Specific matchers</li>
+        <li>Specific serializers</li>
+        <li>...</li>
+      </ul>
+    </s2>
+    <s2 title="Built-in Logicsheets">
+      <ul>
+        <li>sitemap.xsl</li>
+        <li>xsp.xsl</li>
+        <li>esql.xsl</li>
+        <li>request.xsl</li>
+        <li>response.xsl</li>
+        <li>...</li>
+      </ul>
+    </s2>
+    <s2 title="Site specific configuration, components, logicsheets and content">
+      <ul>
+        <li>...</li>
+      </ul>
+    </s2>
+  </s1>
+  <anchor id="c2-abstractions"/>
+  <s1 title="Abstraction.">
+    <s2 title="eXtensible Server Pages (XSPs)">
+      <p>An XSP page is an XML page with following requirements:</p>
+        <ul>
+          <li>The document root must be <code>&lt;xsp:page&gt;</code></li>
+          <li>It must have language declaration as an attribute in the <code>&lt;xsp:page&gt;</code>
element.</li>
+          <li>It must have namespace declaration for xsp as an attribute in the <code>&lt;xsp:page&gt;</code>
element.</li>
+          <li>For an XSP to be useful, it must also require at least an <code>&lt;xsp:logic&gt;</code>
and an <code>&lt;xsp:expr&gt;</code> element.</li>
+        </ul>
+<source><![CDATA[
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<xsp:page language="java" xmlns:xsp="http://apache.org/xsp">
+
+  <xsp:logic>
+  static private int counter = 0;
+  private synchronized int count()
+  {
+    return counter++;
+  }
+  </xsp:logic>
+
+  <page>
+  <p>I have been requested <xsp:expr>count()</xsp:expr> times.</p>
+  </page>
+
+</xsp:page>
+]]></source>
+
+      <p>An XSP page is used by a generator to generate XML document.</p>
+    </s2>
+    <s2 title="XSP Processing (Code Generation)">
+<source><![CDATA[
+package org.apache.cocoon.www.docs.samples.xsp;
+
+import java.io.File;
+// A bunch of other imports 
+
+public class counter_xsp extends XSPGenerator {
+   // .. Bookkeeping stuff commented out.
+  /* User Class Declarations */
+  static private int counter = 0;
+  private synchronized int count() {
+    return counter++;
+  }
+  /* Generate XML data. */
+  public void generate() throws SAXException {
+    this.contentHandler.startDocument();
+    AttributesImpl xspAttr = new AttributesImpl();
+    this.contentHandler.startPrefixMapping("xsp", "http://apache.org/xsp");
+    this.contentHandler.startElement("", "page", "page", xspAttr);
+    // Statements to build the XML document (Omitted)
+    this.contentHandler.endElement("", "page", "page");
+    this.contentHandler.endPrefixMapping("xsp");
+    this.contentHandler.endDocument();
+  }
+]]></source>
+    </s2>
+    <s2 title="Ways of Creating XSPs">
+      <s3 title="Embedded Logic">
+      <ul>
+        <li>Code is embedded in the XML page</li>
+        <li>No separation of content and logic</li>
+        <li>Okay for small examples but terrible for large systems.</li>
+      </ul>
+      <figure src="images/xsp-way.gif" alt="ways of creating xsp's"
+              width="323" height="384"/>
+      </s3>
+      <s3 title="Included Logicsheet">
+      <ul>
+        <li>Code is in a separate logicsheet (an XSL file)</li>
+        <li>Effective separation of content and logic</li>
+        <li>Preferred way to create XSPs</li>
+      </ul>
+      <figure src="images/xsp-way2.gif" alt="ways of creating xsp's"
+              width="318" height="403"/>
+      </s3>
+      <s3 title="Logicsheet as tag library">
+      <ul>
+        <li>The logicsheet is packaged as a reusable tag library and registered with
Cocoon in cocoon.xconf file.</li>
+        <li>Tag library has a namespace declaration, declared in the original logicsheet
and matched in <code>&lt;xsp:page&gt;</code> xmlns:... attribute.</li>
+        <li>Effective separation of content, logic and management</li>
+      </ul>
+      <figure src="images/xsp-way3.gif" alt="ways of creating xsp's"
+              width="344" height="409"/>
+      </s3>
+    </s2>
+    <s2 title="Sitemap">
+<source><![CDATA[
+<?xml version="1.0"?>
+<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
+
+<map:components>
+...
+</map:components>
+
+<map:views>
+...
+</map:views>
+<map:pipelines>
+<map:pipeline>
+<map:match> 
+...
+</map:match>
+...
+</map:pipeline>
+...
+</map:pipelines>
+...
+</map:sitemap>
+]]></source>
+      <p>Sitemap contains configuration information for a Cocoon engine:</p>
+        <ul>
+           <li>list of matchers</li>
+           <li>list of generators</li>
+           <li>list of transformers</li>
+           <li>list of readers</li>
+           <li>list of serializers</li>
+           <li>list of selectors</li>
+           <li>list of processing pipelines with match patterns</li>
+           <li>...</li>
+        </ul>
+      <p>Sitemap is an XML file corresponding to a sitemap DTD.</p>
+      <p>Sitemap can be edited to add new elements.</p>
+      <p>Sitemap is generated into a program and is compiled into an executable unit.</p>
+    </s2>
+    <s2 title="Matchers">
+      <p>A Matcher attempts to match an URI with a specified pattern for dispatching
the request to a specific processing pipeline.</p>
+      <p>Different types of matchers:</p>
+        <ul>
+           <li>wildcard matcher</li>
+           <li>regexp matcher</li>
+        </ul>
+      <p>More matchers can be added without modifying Cocoon.</p>
+      <p>Matchers help in specifying a specific pipeline processing for a group of
URIs.</p>
+      <p>Sitemap entries for different types of matchers</p>
+<source><![CDATA[
+<map:matchers default="wildcard">
+ <map:matcher name="wildcard" factory="org.apache.cocoon.matching.WildcardURIMatcher"/>
+ <map:matcher name="regexp" factory="org.apache.cocoon.matching.RegexpURIMatcher"/>
+</map:matchers>
+]]></source>
+      <p>Pipeline entries in sitemap file</p>
+<source><![CDATA[
+<map:match pattern="jsp/*">
+  <map:generate type="jsp" src="/docs/samples/jsp/{1}.jsp"/>
+  ...
+  </map:match>
+<map:match pattern="hello.pdf">
+</map:match
+]]></source>
+    </s2>
+    <s2 title="Generators">
+      <p>A Generator is used to create an XML structure from an input source (file,
directory, stream ...)</p>
+      <figure src="images/xsp-way3.gif" alt="ways of creating xsp's"
+              width="344" height="409"/>
+      <p>Different types of generators:</p>
+        <ul>
+           <li>file generator</li>
+           <li>directory generator</li>
+           <li>XSP generator</li>
+           <li>JSP generator</li>
+           <li>Request generator</li>
+           <li>...</li>
+        </ul>
+      <p>More generators can be added without modifying Cocoon.</p>
+      <p>Sitemap entries for different types of generators</p>
+<source><![CDATA[
+<map:generators default="file">
+ <map:generator name="file"
+                src="org.apache.cocoon.generation.FileGenerator"
+                label="content"/>
+ <map:generator name="directory"
+                src="org.apache.cocoon.generation.DirectoryGenerator"
+                label="content"/>
+ <map:generator name="serverpages"
+                src="org.apache.cocoon.generation.ServerPagesGenerator"
+                label="content"/>
+ <map:generator name="request"
+                src="org.apache.cocoon.generation.RequestGenerator"/>
+ ...
+</map:generators>
+]]></source>
+      <p>A sample generator entries in a pipeline</p>
+<source><![CDATA[
+<map:match pattern="hello.html">
+    <map:generate src="docs/samples/hello-page.xml"/>
+    <map:transform src="stylesheets/page/simple-page2html.xsl"/>
+    <map:serialize type="html"/>
+</map:match>
+]]></source>
+
+      <p>A Generator turns an XML document, after applying appropriate transformations,
into a compiled program whose output is an XML document.</p>
+      <p>An XSP generator applies all the logicsheets specified in the source XML file
before generating the program.</p>
+      <p>Generators cache the compiled programs for better runtime efficiency.</p>
+    </s2>
+    <s2 title="Transformers">
+      <p>A Transformer is used to map an input XML structure into another XML structure.</p>
+      <p>Different types of transformers:</p>
+        <ul>
+           <li>XSLT Transformer</li>
+           <li>Log Transformer</li>
+           <li>SQL Transformer</li>
+           <li>I18N Transformer</li>
+           <li>...</li>
+        </ul>
+      <p>Log Transformer is a good debugging tool.</p>
+      <p>More transformers can be added without modifying Cocoon.</p>
+      <p>Sitemap entries for different types of transformers</p>
+<source><![CDATA[
+<map:transformers default="xslt">
+   <map:transformer name="xslt" src="org.apache.cocoon.transformation.TraxTransformer">
+    <use-request-parameters>false</use-request-parameters>
+    <use-browser-capabilities-db>false</use-browser-capabilities-db>
+   </map:transformer>
+   <map:transformer name="log" src="org.apache.cocoon.transformation.LogTransformer"/>
+...
+
+</map:transformers>
+]]></source>
+      <p>A sample transformer entry in a pipeline</p>
+<source><![CDATA[
+<map:match pattern="hello.html">
+ <map:generate src="docs/samples/hello-page.xml"/>
+ <map:transform src="stylesheets/page/simple-page2html.xsl"/>
+ <map:serialize type="html"/>
+</map:match>
+]]></source>
+    </s2>
+    <s2 title="Serializers">
+      <p>A Serializer is used to render an input XML structure into some other format
(not necessarily XML)</p>
+      <p>Different types of serializers:</p>
+        <ul>
+           <li>HTML Serializer</li>
+           <li>FOP Serializer</li>
+           <li>Text Serializer</li>
+           <li>XML Serializer</li>
+           <li>...</li>
+        </ul>
+      <p>More serializers can be added without modifying Cocoon.</p>
+      <p>Sitemap entries for different types of serializers</p>
+<source><![CDATA[
+<map:serializers default="html">
+ <map:serializer name="xml"
+                 mime-type="text/xml"
+                 src="org.apache.cocoon.serialization.XMLSerializer"/>
+ <map:serializer name="html"
+                 mime-type="text/html"
+                 src="org.apache.cocoon.serialization.HTMLSerializer"/>
+ <map:serializer name="fo2pdf"
+                 mime-type="application/pdf"
+                 src="org.apache.cocoon.serialization.FOPSerializer"/>
+ <map:serializer name="vrml"
+                 mime-type="model/vrml"
+                 src="org.apache.cocoon.serialization.TextSerializer"/>
+ ...
+</map:serializers>
+]]></source>
+      <p>A sample serializer entry in a pipeline</p>
+<source><![CDATA[
+ <map:match pattern="hello.html">
+    <map:generate src="docs/samples/hello-page.xml"/>
+    <map:transform src="stylesheets/page/simple-page2html.xsl"/>
+    <map:serialize type="html"/>
+   </map:match>
+]]></source>
+    </s2>
+    <s2 title="Pipeline Processing">
+      <p>The sitemap configuration allows dynamic setup of processing pipelines consisting
of a generator, multiple transformers and a serializer.</p>
+      <p>Requests are dispatched to a pipeline based on request URI and the pipeline
matching pattern (either with wildcards or as a regexp)</p>
+      <p>The pipeline is setup in the generated file <code>sitemap_xmap.java</code>
(This file gets generated [possibly asynchronously] everytime the <code>sitemap.xmap</code>
is modified.</p>
+      <figure src="images/pipeline2.gif" alt="Pipeline Entry"
+              width="379" height="341"/>
+    </s2>
+    <s2 title="Logicsheets">
+      <p>Logicsheets are XSL files with an associated namespace.</p>
+      <p>Primary mechanism to add program logic (code) to XSPs.</p>
+      <p>These need to be registered in configuration file cocoon.xconf.</p>
+      <p>Logicsheets are used by the generator to transform XML structure before generating
program.</p>
+      <p>Cocoon comes with a no. of built-in logic sheets:</p>
+        <ul>
+           <li>request.xsl</li>
+           <li>response.xsl</li>
+           <li>session.xsl</li>
+           <li>cookie.xsl</li>
+           <li>esql.xsl</li>
+           <li>log.xsl</li>
+           <li>...</li>
+        </ul>
+      <p>Log.xsl structure</p>
+<source><![CDATA[
+<xsl:stylesheet  version="1.0"
+                 xmlns:xsp="http://apache.org/xsp"
+                 xmlns:log="http://apache.org/xsp/log"
+                 xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+
+<xsl:template match="log:logger">
+... variable and xsp:logic statements ...
+</xsl:template>
+
+<xsl:template match="log:debug">
+  <xsp:logic>
+   if(getLogger() != null)
+     getLogger().debug("<xsl:value-of select="."/>");    
+  </xsp:logic>  
+</xsl:template>
+<xsl:template match="log:error">
+...  
+</xsl:template>
+</xsl:stylesheet>
+]]></source>
+      <p>A sample use</p>
+<source><![CDATA[
+<xsp:page language="java"
+          xmlns:xsp="http://apache.org/xsp"
+          xmlns:log="http://apache.org/xsp/log">
+
+  <page>
+  <log:logger name="test" filename="test.log"/>
+  <log:debug>Test Message</log:debug>
+  </page>
+</xsp:page>
+]]></source>
+    </s2>
+  </s1>
+  <anchor id="cocoon-configuration"/>
+  <s1 title="@Name@ Configuration.">
+    <p>Cocoon is highly configurable. Main configuration files, assuming Cocoon deployment
as a servlet in a servlet container, are (directory locations assume Tomcat servlet container):</p>
+    <ul>
+       <li><code>sitemap.xmap</code>: the sitemap file. By default, located
in <code>$TOMCAT_HOME/webapps/cocoon</code> directory.</li>
+       <li><code>cocoon.xconf</code>: configuration file having logicsheet
registrations. Specifies, sitemap.xmap location and other such parameters. By default, located
in <code>$TOMCAT_HOME/webapps/cocoon</code> directory.</li>
+       <li><code>web.xml</code>: servlet deployment descriptor. Specifies
location of cocoon.xconf, log file location and other such parameters. Located in <code>$TOMCAT_HOME/webapps/cocoon/WEB-INF</code>
directory.</li>
+       <li><code>cocoon.roles</code>: mapping file for Core Cocoon components
name and implementation classes. For example, if you want to use a parser other than the default
one, you need to modify this file.</li>
+    </ul>
+  </s1>
+  <anchor id="work-area"/>
+  <s1 title="@Name@ Work Area">
+    <p>Cocoon produces execution log entries for debugging/auditing.</p>
+    <ul>
+       <li>The amount of data to be logged can be controlled by
+       log-level parameter in web.xml file. The default is DEBUG
+       (maximum data).</li>
+       <li>By default, the log file is:
+       <code>$TOMCAT_HOME/webapps/cocoon/WEB-INF/logs/cocoon.log</code>.</li>
+    </ul>
+
+    <p>Cocoon keeps the generated .java files in a directory tree
+    starting at (by default):<br/>
+    <code>$TOMCAT_HOME/webapps/work/localhost_8080%2Fcocoon/org/apache/cocoon/www</code>.</p>
+
+<p>You can find sitemap_xmap.java here.</p>
+
+    <p>Files created by LogTransformer are kept (by default) in <code>$TOMCAT_HOME</code>
directory.</p>
+  </s1>
+  <anchor id="use-with-tomcat"/>
+  <s1 title="Use with Tomcat">
+    <p>Download Tomcat from Apache site.</p>
+    <p>Download Cocoon sources from Apache CVS. [Command assume UNIX Bourne shell]</p>
+<source><![CDATA[
+export CVSROOT=:pserver:anoncvs@cvs.apache.org:/home/cvspublic 
+cvs login 
+Password: anoncvs 
+cvs checkout cocoon-2.1
+]]></source>
+    <p>Build sources as per instruction in Install file.</p>
+    <p>Move the <code>cocoon.war</code> file to <code>$TOMCAT_HOME/webapps</code>
directory.</p>
+    <p>Start the servlet engine. Type-in the URL <code>http://localhost:8080/cocoon</code>
in your browser. You should see the Cocoon welcome message.</p>
+    <p>Consult Install file if you face problems.</p>
+  </s1>
+</body>
+</document>

Added: cocoon/trunk/src/documentation/src/content/xdocs/c21_concepts_index/meta.xml
URL: http://svn.apache.org/viewcvs/cocoon/trunk/src/documentation/src/content/xdocs/c21_concepts_index/meta.xml?view=auto&rev=159287
==============================================================================
--- cocoon/trunk/src/documentation/src/content/xdocs/c21_concepts_index/meta.xml (added)
+++ cocoon/trunk/src/documentation/src/content/xdocs/c21_concepts_index/meta.xml Mon Mar 28
12:02:42 2005
@@ -0,0 +1,7 @@
+<?xml version="1.0"?>
+<meta>
+  <authors>
+    <author contact="dev@cocoon.apache.org">The Cocoon community</author>
+  </authors>
+  <source>legacy.21</source>
+</meta>

Added: cocoon/trunk/src/documentation/src/content/xdocs/c21_index/content_en.xdoc
URL: http://svn.apache.org/viewcvs/cocoon/trunk/src/documentation/src/content/xdocs/c21_index/content_en.xdoc?view=auto&rev=159287
==============================================================================
--- cocoon/trunk/src/documentation/src/content/xdocs/c21_index/content_en.xdoc (added)
+++ cocoon/trunk/src/documentation/src/content/xdocs/c21_index/content_en.xdoc Mon Mar 28
12:02:42 2005
@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  Copyright 1999-2004 The Apache Software Foundation
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+-->
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "document-v10.dtd">
+
+<document> 
+ <header>
+  <title>2.1 legacy documentation</title>
+  <authors/>
+ </header>
+
+ <body>
+   <section>
+     <p>
+      These documents have been copied here from the Cocoon 2.1
+       source tree, but have not been reviewed yet.
+     </p>
+    <fixme author="BD">
+      Add more info about how to handle them, how to indicate
+      sections that have move to new docs, etc.
+    </fixme>
+   </section>
+
+</body>
+</document>

Added: cocoon/trunk/src/documentation/src/content/xdocs/c21_index/meta.xml
URL: http://svn.apache.org/viewcvs/cocoon/trunk/src/documentation/src/content/xdocs/c21_index/meta.xml?view=auto&rev=159287
==============================================================================
--- cocoon/trunk/src/documentation/src/content/xdocs/c21_index/meta.xml (added)
+++ cocoon/trunk/src/documentation/src/content/xdocs/c21_index/meta.xml Mon Mar 28 12:02:42
2005
@@ -0,0 +1,6 @@
+<?xml version="1.0"?>
+<meta>
+  <authors>
+    <author contact="dev@cocoon.apache.org">The Cocoon community</author>
+  </authors>
+</meta>

Added: cocoon/trunk/src/documentation/src/content/xdocs/c21_introduction/content_en.xdoc
URL: http://svn.apache.org/viewcvs/cocoon/trunk/src/documentation/src/content/xdocs/c21_introduction/content_en.xdoc?view=auto&rev=159287
==============================================================================
--- cocoon/trunk/src/documentation/src/content/xdocs/c21_introduction/content_en.xdoc (added)
+++ cocoon/trunk/src/documentation/src/content/xdocs/c21_introduction/content_en.xdoc Mon
Mar 28 12:02:42 2005
@@ -0,0 +1,346 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  Copyright 1999-2004 The Apache Software Foundation
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+-->
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "document-v10.dtd">
+
+<document>
+
+  <header>
+    <title>Introducing Cocoon</title>
+    <authors>
+      <person name="Stefano Mazzocchi" email="stefano@apache.org"/>
+    </authors>
+  </header>
+
+  <body>
+
+    <s1 title="The XML Hype">
+
+<p>
+Everybody talks about XML. XML here, XML there. All application servers
+support XML, everybody wants to do B2B using XML, web services using
+XML, even databases using XML.
+</p>
+
+<p>
+Should you care about it? Given the amount of hype, you can't afford to
+go around ignoring XML, for that would be like ignoring the World Wide
+Web 10 years ago: a clear mistake. But why is this so for XML? What is
+this "magic" that XML seems to have in solving your problems? Isn't this
+another hype to change once again the IT infrastructure that you spent
+so much time implementing and fixing in the last few years? Isn't
+another way to spill money out of your pockets?
+</p>
+
+<p>
+If you ever asked yourself one of the above questions, this paper is for
+you. You won't find singing-and-dancing marketing hype, you won't find
+boring and useless feature lists, you won't find the usual acronym
+bombing or those good looking vaporware schemas that connect your
+databases to your coffee machines via CORBA or stuff like that.
+</p>
+
+<p>
+This document will explain you what the Cocoon project is about and what we are
+doing to solve the problems that we encountered in our web engineering
+experiences, but from an executive perspective, yes, because we all had
+the problems of managing a web site, dealing with our colleagues, rushing
+to the graphical guru to have the little GIF with the new title, or
+calling the web administrator at night because the database is returning
+errors without reasons.
+</p>
+
+<p>
+It was frustrating to see the best and most clever information
+technology ever invented--the Web--ruined by the lack of engineering
+practices, tortured by those "let's-reinvent-the-wheel-once-again"
+craftsmen who were great at doing their jobs as individuals but
+could not scale within teams, imposing a growth saturation to their projects.
+</p>
+
+<p>
+There had to be a better way of doing things.
+</p>
+
+    </s1>
+
+
+    <s1 title="Personal Experiences">
+
+<p>
+In 1998, Stefano Mazzocchi volunteered to create the documentation infrastructure for
+the java.apache.org project, which is composed of a bunch of different
+codebases, maintained by a bunch of different people, with different
+skills, different geographical locations and different degree of will
+and time to dedicate to the documentation effort.
+</p>
+
+<p>
+But pretty soon he realized that no matter how great and well designed the
+system was, HTML was a problem: it was *not* designed for those kinds of
+things. By looking at the main page (<link href="http://java.apache.org/">http://java.apache.org/</link>)
from the
+browser, you can clearly identify the areas of the screen: sidebar,
+topbar, news, status. But if you viewed the underlying HTML, boom: a nightmare of
+table tags and nesting and small little tricks to make the HTML appear
+the same on every browser.
+</p>
+
+<p>
+So he looked around for alternative technologies, but *all* of them were
+trying to add more complexity at the GUI level (Microsoft Frontpage,
+Macromedia Dreamweaver, Adobe GoLive, etc...) hoping to "hide" the
+design problems of HTML under a thick layer of WYSIWYG looks.
+</p>
+
+<p>
+What you see is what you get.
+</p>
+
+<p>
+But what you see is all you've got.
+</p>
+
+<p>
+How can you tell your web server to extract the information contained within the
+sidebar? How can you tell it to find the news articles within a complex HTML page?
+</p>
+
+<p>
+It's certainly easy for a human reader: just look at the page and you should have
+no problem distinguishing between a sidebar, a banner, a news and a stock
+quote. Why is it so hard for a machine?
+</p>
+
+    </s1>
+
+    <s1 title="The HTML Model">
+
+<p>
+HTML is a language that tells your browser how to "draw" things on its
+window. An image here, a letter there, a color down here. Nothing more.
+The browser doesn't have the "higher level" notion of "sidebar": it
+lacks the ability to perform "semantic analysis" of the HTML content.
+</p>
+
+<p>
+Semantic analysis? Yeah, it's the kind of thing the human brain is
+simply great at doing, while computer programs simply fail at big time.
+</p>
+
+<p>
+So, with HTML, we went a step up and created a highly visual and
+appealing web of HTML content, but we went two steps back by removing
+all the higher level semantic information from the content itself.
+</p>
+
+<p>
+Ok, let's make an example...  most of you have seen an HTML
+page... if not, here is an example:
+</p>
+
+<source><![CDATA[
+ <html>
+  <body>
+   <p>Hi, I'm an HTML page</p>
+   <p align="center">Written by Stefano</p>
+  </body>
+ </html>
+]]></source>
+
+<p>
+which says to the browser:
+</p>
+
+<ul>
+ <li>I'm a HTML page</li>
+ <li>I have a body</li>
+ <li>I have a paragraph</li>
+ <li>I contain the sentence "Hi, I'm an HTML page."</li>
+ <li>I contain the sentence "Written by Stefano"</li>
+</ul>
+
+<p>
+Suppose you are a Chinese guy that doesn't understand our alphabet, try
+to answer the following question:
+</p>
+
+<p>
+Who wrote the page?
+</p>
+
+<p>
+You can't perform semantic analysis, you are as blind as a web browser.
+The only thing you can do is draw it on the screen since this is what
+you were programmed to do. In other words, your semantic capacity is
+fixed to the drawing capabilities and a few other things (like linking),
+thus limited.
+</p>
+
+    </s1>
+
+    <s1 title="Semantic Markup">
+    <moved author="BD" href="site:concepts.html">
+      This section has moved to the "concepts" document - if the
+      linking works, there should be a link to the new location
+      at the beginning of his note.
+    </moved>
+    </s1>
+
+    <s1 title="The XML Language">
+
+<p>
+XML is most of the times referred to as the "eXtensible Markup Language"
+specification. A fairly small yet complex specification that indicates
+how to write languages. It's a syntax. To tell you the truth, nothing fancy at all. So
+</p>
+
+<source><![CDATA[
+ <hello></hello>
+]]></source>
+
+<p>
+is correct, while
+</p>
+
+<source><![CDATA[
+ <hello></hi>
+]]></source>
+
+<p>
+is not, but
+</p>
+
+<source><![CDATA[
+ <hello><hi/></hello>
+]]></source>
+
+<p>
+is correct. That's more than this, but I'll skip the technical details here.
+</p>
+
+<p>
+XML is the ASCII for the new millenium, it's a step forward from ASCII
+or UNICODE (the international extension to ASCII that includes all
+characters from all modern languages). It defines a "lingua franca" for
+textual languages.
+</p>
+
+<p>
+Ok, great, so now instead of having one uniform language with visual
+semantics (HTML) we have a babel of languages each with its own
+semantics. How this can possibly help you?
+</p>
+
+    </s1>
+
+    <s1 title="XML Transformations">
+
+<p>
+This was the point where Stefano was more or less two years ago for
+java.apache.org: I could use XML and define my own semantics with
+<![CDATA[<sidebar>]]>, <![CDATA[<news>]]>, <![CDATA[<status>]]>

+and all that and I'm sure people would have
+found those XML documents much easier to write (since the XML syntax is
+very similar to the HTML one and very user friendly)... but I would have
+moved from "all browsers" to "no browser".
+</p>
+
+<p>
+And having documentation that nobody can browse is totally useless.
+</p>
+
+<p>
+The turning point was the creation of the XSL specification which
+included a way to "transform" an XML page into something else. (It's
+more complex than this, but, again, I'll skip the technical details).
+</p>
+
+<p>
+So now you have:
+</p>
+
+<source><![CDATA[
+ XML page ---(transformation)--> HTML page
+                    ^
+                    |
+          transformation rules
+]]></source>
+
+<p>
+that allows you to write your pages in XML, create your "graphics" as
+transformation rules and generate HTML pages on the fly directly from your
+web server.
+</p>
+
+<p>
+Apache Cocoon 1.0 did exactly this.
+</p>
+
+    </s1>
+
+    <s1 title="The Model Evolves">
+
+<p>
+If XML is a lingua franca, it means that XML software can work on almost
+anything without caring about what it is. So, if a cell phone requests
+the page, Cocoon just has to change transformation rules and send the
+WAP page to the phone. Or, if you want a nice PDF to printout your
+monthly report, you change the transformation rules and Cocoon creates
+the PDF for you, or the VRML, or the VoiceML, or your own proprietary
+B2B markup.
+</p>
+
+<p>
+Anything without changing the basic architecture that is simply based on
+the simple "angle bracket" XML syntax.
+</p>
+
+    </s1>
+
+    <s1 title="Separation of Concerns (SoC)">
+      <moved author="BD" href="site:concepts.html">
+        This section has moved to the "concepts" document - if the
+        linking works, there should be a link to the new location
+        at the beginning of his note.
+      </moved>
+
+    </s1>
+
+    <s1 title="Here we go">
+
+<p>
+If you've reached this far in my text, you should be able to grasp the
+value of the Cocoon Project as well as distinguish most of the marketing
+hype that surrounds XML and friends.
+</p>
+
+<p>
+Just like you shouldn't care if somebody offers you software that is
+"ASCII compliant" or "ASCII based", you shouldn't care about "XML
+compliant" or "XML based": it doesn't mean anything.
+</p>
+
+<p>
+Cocoon uses XML as a core piece of its framework, but improves the model
+to give you the tools you need and is designed to be flexible enough to
+follow your current needs as well as paradigm shifts that may happen in the
+future.
+</p>
+
+    </s1>
+
+  </body>
+</document>

Added: cocoon/trunk/src/documentation/src/content/xdocs/c21_introduction/meta.xml
URL: http://svn.apache.org/viewcvs/cocoon/trunk/src/documentation/src/content/xdocs/c21_introduction/meta.xml?view=auto&rev=159287
==============================================================================
--- cocoon/trunk/src/documentation/src/content/xdocs/c21_introduction/meta.xml (added)
+++ cocoon/trunk/src/documentation/src/content/xdocs/c21_introduction/meta.xml Mon Mar 28
12:02:42 2005
@@ -0,0 +1,7 @@
+<?xml version="1.0"?>
+<meta>
+  <authors>
+    <author contact="dev@cocoon.apache.org">The Cocoon community</author>
+  </authors>
+  <source>legacy.21</source>
+</meta>

Modified: cocoon/trunk/src/documentation/src/content/xdocs/site.xml
URL: http://svn.apache.org/viewcvs/cocoon/trunk/src/documentation/src/content/xdocs/site.xml?view=diff&r1=159286&r2=159287
==============================================================================
--- cocoon/trunk/src/documentation/src/content/xdocs/site.xml (original)
+++ cocoon/trunk/src/documentation/src/content/xdocs/site.xml Mon Mar 28 12:02:42 2005
@@ -148,5 +148,14 @@
       <doc label="List"/>    
     </doc>      
   </doc>
-  
+
+  <legacy label="Legacy" tab="legacy">
+    <doc label="Overview" href="c21_index.html"/>
+    <doc label="Misc.">
+      <doc label="introduction" href="c21_introduction.html"/>
+    </doc>
+    <doc label="Concepts">
+      <doc label="index" href="c21_concepts_index.html"/>
+    </doc>
+  </legacy>
 </site>

Modified: cocoon/trunk/src/documentation/src/content/xdocs/tabs.xml
URL: http://svn.apache.org/viewcvs/cocoon/trunk/src/documentation/src/content/xdocs/tabs.xml?view=diff&r1=159286&r2=159287
==============================================================================
--- cocoon/trunk/src/documentation/src/content/xdocs/tabs.xml (original)
+++ cocoon/trunk/src/documentation/src/content/xdocs/tabs.xml Mon Mar 28 12:02:42 2005
@@ -42,5 +42,6 @@
     <tab id="docs-2.0" label="2.0 docs" href="http://not-available-yet/index.html"/>
   
   </tab>
   <tab id="blocks" label="Blocks" dir="" indexfile="blocks.html"/>
-  
+  <tab id="legacy" label="Legacy" dir="" indexfile="c21_index.html"/>
+
 </tabs>



Mime
View raw message