You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@cocoon.apache.org by bd...@apache.org on 2005/03/28 22:02:45 UTC
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
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><xsp:page></code></li>
+ <li>It must have language declaration as an attribute in the <code><xsp:page></code> element.</li>
+ <li>It must have namespace declaration for xsp as an attribute in the <code><xsp:page></code> element.</li>
+ <li>For an XSP to be useful, it must also require at least an <code><xsp:logic></code> and an <code><xsp:expr></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><xsp:page></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>