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="[EMAIL PROTECTED]"/> + <person name="Davanum Srinivas" email="[EMAIL PROTECTED]"/> + </authors> + </header> + + <body> + <s1 title="Overview"> + <p> + This document is intended for both Users and Developers + and presents an overall picture of @[EMAIL PROTECTED] + </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:[EMAIL PROTECTED]:/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="[EMAIL PROTECTED]"/> + </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>