bdelacretaz 2003/09/04 07:08:33
Modified: src/documentation/xdocs book.xml index.xml
src/documentation/xdocs/howto book.xml index.xml
Added: src/documentation/xdocs/howto howto-explore-samples.xml
src/documentation/xdocs/tracks book.xml
first-steps-track.xml index.xml
web-publishing-track.xml
Log:
first documentation tracks created
Revision Changes Path
1.12 +7 -6 cocoon-2.1/src/documentation/xdocs/book.xml
Index: book.xml
===================================================================
RCS file: /home/cvs/cocoon-2.1/src/documentation/xdocs/book.xml,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -r1.11 -r1.12
--- book.xml 2 Sep 2003 12:03:19 -0000 1.11
+++ book.xml 4 Sep 2003 14:08:32 -0000 1.12
@@ -2,8 +2,8 @@
<!DOCTYPE book PUBLIC "-//APACHE//DTD Cocoon Documentation Book V1.0//EN"
"dtd/book-cocoon-v10.dtd">
-<book software="Apache Cocoon"
- title="Apache Cocoon Documentation"
+<book software="Apache Cocoon"
+ title="Apache Cocoon Documentation"
copyright="1999-2003 The Apache Software Foundation"
xmlns:xlink="http://www.w3.org/1999/xlink";>
@@ -16,6 +16,7 @@
<menu label="Documentation">
<menu-item label="Introduction" href="introduction.html"/>
+ <menu-item label="Tracks" href="tracks/index.html"/>
<menu-item label="Installing" href="userdocs/installation/index.html"/>
<menu-item label="Overview" href="overview.html"/>
<menu-item label="Manual" href="userdocs/intro.html"/>
@@ -37,7 +38,7 @@
<menu-item label="Hall of Fame" href="who.html"/>
<external label="Contributing"
href="http://cocoon.apache.org/community/contrib.html"/>
<external label="Mail Lists"
href="http://cocoon.apache.org/community/mail-lists.html"/>
- <external label="Mail Archives"
href="http://cocoon.apache.org/community/mail-archives.html"/>
+ <external label="Mail Archives"
href="http://cocoon.apache.org/community/mail-archives.html"/>
</menu>
<menu label="Project">
@@ -47,13 +48,13 @@
</menu>
<menu label="Links">
- <external label="Cocoon Links"
href="http://cocoon.apache.org/link/index.html"/>
+ <external label="Cocoon Links"
href="http://cocoon.apache.org/link/index.html"/>
<external label="Live Sites"
href="http://cocoon.apache.org/link/livesites-2.1.html"/>
<external label="Cocoon Hosting"
href="http://cocoon.apache.org/link/hosting.html"/>
</menu>
<menu label="Other Releases">
- <external label="Cocoon 1.x" href="http://cocoon.apache.org/1.x/"/>
- <external label="Cocoon 2.0" href="http://cocoon.apache.org/2.0/"/>
+ <external label="Cocoon 1.x" href="http://cocoon.apache.org/1.x/"/>
+ <external label="Cocoon 2.0" href="http://cocoon.apache.org/2.0/"/>
</menu>
</book>
1.10 +21 -8 cocoon-2.1/src/documentation/xdocs/index.xml
Index: index.xml
===================================================================
RCS file: /home/cvs/cocoon-2.1/src/documentation/xdocs/index.xml,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- index.xml 3 Sep 2003 06:51:45 -0000 1.9
+++ index.xml 4 Sep 2003 14:08:32 -0000 1.10
@@ -9,7 +9,7 @@
</authors>
</header>
<body>
-
+
<figure src="images/cocoon.gif" alt="Cocoon"/>
<s1 title="News">
<note>
@@ -54,22 +54,35 @@
</p>
<p>
Cocoon interacts with many data sources, including filesystems,
RDBMS,
- LDAP, native XML databases, SAP® systems and network-based data
sources.
+ LDAP, native XML databases, SAP® systems and network-based data
sources.
It adapts content delivery to the capabilities of different devices
like HTML, WML,
PDF, SVG, and RTF, to name just a few. You can run Cocoon as a
Servlet as well as
- through a powerful, commandline interface. The deliberate design of
its abstract
- environment gives you the freedom to extend its functionality to
meet your
+ through a powerful, commandline interface. The deliberate design of
its abstract
+ environment gives you the freedom to extend its functionality to
meet your
special needs in a highly modular fashion.
- </p>
+ </p>
</s1>
<s1 title="Where can I find it?">
<p>
- To download the latest release @released.version@ of Apache Cocoon, go to
the
+ To download the latest release @released.version@ of Apache Cocoon, go to
the
<link href="http://cocoon.apache.org/mirror.cgi";>download area.</link>
</p>
<p>
- If you are looking for a past generation of Cocoon (no longer supported
but still available),
- go to the <link href="http://cocoon.apache.org/1.x/";>Cocoon 1.x
area</link>.
+ If you are looking for a past generation of Cocoon (no longer supported
but still available),
+ go to the <link href="http://cocoon.apache.org/1.x/";>Cocoon 1.x
area</link>.
+ </p>
+ </s1>
+ <s1 title="Where to start?">
+ <p>
+ With a large serving of core components and more than 45
additional "blocks", this has
+ become a big project and it is often hard for newcomers to find
their way through the
+ (wonderful) world of Cocoon.
+ </p>
+ <p>
+ To make it easier, we have started to create <link
href="./tracks/index.html">documentation tracks</link>
+ to help you locate the parts of the documentation that are the
most relevant for your needs.
+ There are few tracks at the moment, but we hope to create more of
them depending
+ on the feedback and help that we can get.
</p>
</s1>
<s1 title="More News about Cocoon">
1.3 +1 -0 cocoon-2.1/src/documentation/xdocs/howto/book.xml
Index: book.xml
===================================================================
RCS file: /home/cvs/cocoon-2.1/src/documentation/xdocs/howto/book.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- book.xml 3 Sep 2003 08:01:34 -0000 1.2
+++ book.xml 4 Sep 2003 14:08:32 -0000 1.3
@@ -8,6 +8,7 @@
<menu-item label="Index" href="index.html"/>
</menu>
<menu label="Using Cocoon">
+ <menu-item label="Samples" href="howto-explore-samples.html"/>
<menu-item label="XMLForm"
href="xmlform-wizard/howto-xmlform-wizard.html"/>
<menu-item label="Paginator" href="howto-paginator-transformer.html"/>
<menu-item label="HTML-PDF" href="howto-html-pdf-publishing.html"/>
1.3 +1 -0 cocoon-2.1/src/documentation/xdocs/howto/index.xml
Index: index.xml
===================================================================
RCS file: /home/cvs/cocoon-2.1/src/documentation/xdocs/howto/index.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- index.xml 31 May 2003 05:25:18 -0000 1.2
+++ index.xml 4 Sep 2003 14:08:32 -0000 1.3
@@ -26,6 +26,7 @@
and the list is certainly incomplete, e.g. Cocoon now has various
"forms" frameworks.</p>
<ul>
+<li><link href="howto-explore-samples.html">Exploring the samples</link></li>
<li><link href="xmlform-wizard/howto-xmlform-wizard.html">XMLForm
Wizard</link></li>
<li><link href="howto-paginator-transformer.html">Paginator
Transformer</link></li>
<li><link href="howto-html-pdf-publishing.html">HTML-PDF
Publishing</link></li>
1.1
cocoon-2.1/src/documentation/xdocs/howto/howto-explore-samples.xml
Index: howto-explore-samples.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN"
"../dtd/document-v10.dtd">
<document>
<header>
<title>How to run and explore the Cocoon samples</title>
<authors>
<person name="Bertrand Delacrétaz" email="[EMAIL
PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="Overview">
<p>
This How-To shows you how to run and explore the Cocoon
samples. It requires no
prior knowledge of Cocoon.
</p>
</s1>
<s1 title="Purpose">
<p>
You will learn how install and run Cocoon in the simplest
way, in order to run the Cocoon samples, and
also how to study the samples from the inside to see how
their are built.
</p>
</s1>
<s1 title="Intended Audience">
<p>
Beginning Cocoon users or people evaluating Cocoon for the
first time.
</p>
</s1>
<s1 title="Prerequisites">
<p>You only need a JDK (1.3 or later) installed on your computer,
and an Internet connection
to download Cocoon.</p>
</s1>
<s1 title="Steps">
<p>
Here's how to proceed.
</p>
<s2 title="1. Get Cocoon">
<p>
Download Cocoon from the location listed on the
<link
href="http://cocoon.apache.org";>cocoon.apache.org</link>
web site.
</p>
<note>
If you want the latest bleeding edge version, you can get
it from CVS, this is described on
the site as well, but more complicated if you're not
familiar with CVS.
</note>
</s2>
<s2 title="2. Build and start Cocoon">
<p>
Unpack the Cocoon distribution and follow the
instructions found in the
<em>INSTALL.txt</em> file to build
Cocoon.
</p>
<note>
If you have done this previously, make sure to remove any
local.* configuration files that you
might have created. You usually want to activate all
Cocoon components to look at the samples,
and local.* files might disable some components or even
disable the samples.
</note>
<note>
Also, if you have already built Cocoon with a different
configuration before, you might need to
do a "build clean" first, to prevent any conflicts
between different configurations.
</note>
<p>
The INSTALL.txt file also contains instructions for
starting Cocoon with the <em>cocoon.sh</em> or
<em>cocoon.bat</em> script, which is the simplest way and
is sufficient to explore the samples.
</p>
</s2>
<s2 title="3. Access the samples">
<p>
Once Cocoon starts (and assuming you have kept the
standard configuration), point your browser
at http://localhost:8888, this should show the "Welcome
to Apache Cocoon" page. On this page,
click the
<em>samples</em> link.
</p>
<p>
You should now see a page with links to many samples (
<em>Hello World!</em>, etc.), which show you what Cocoon
is about.
Note that there are several categories of samples: do not
forget to look at the
<em>blocks
with samples</em> page, which contains samples based
on components which are not part of the Cocoon core.
</p>
<p>
Another category is the
<em>scratchpad</em> samples , these are based on
experimental
components that might or might not be included later in
the Cocoon core or in a Cocoon block.
</p>
</s2>
<s2 title="4. Study the samples">
<p>
Now comes the interesting part: looking at the samples
innards to find out how they are built.
</p>
<p>
This is fairly simple as the directory structure of the
samples is similar to the URLs
used to access the samples. These simple rules should
help you find out much more about
the samples:
<ul>
<li>If using the standard build configuration,
samples are found under the
<em>build/webapp/samples</em> directory. That's
where you want to look
to find out how a particular sample works.
</li>
<li>Under this directory, the pathnames are the same
than after the
<em>http://localhost:8888/samples</em> base URL.
The
midi block samples, for example, are accessed from
<em>http://localhost:8888/samples/midi</em>
and the corresponding files are found under
<em>build/webapp/samples/midi</em>.
</li>
<li>
When studying how a sample is built, it is
recommended to first study its <em>sitemap.xmap</em>
files, which map incoming requests to pipelines.
</li>
</ul>
</p>
</s2>
</s1>
<s1 title="Conclusion">
<p>
We hope that this How-To will help you explore the samples
yourself, as this
is probably the best way of learning about Cocoon.
</p>
<p>
Do not forget to look at the reference documentation though,
once you have found
out which Cocoon components you need for your application.
</p>
</s1>
<s1 title="Comments">
<p>
Care to comment on this How-To?
Help keep this document relevant by passing along any
constructive feedback to the
<link href="mailto:[EMAIL PROTECTED]:">cocoon-docs</link>
mailing list.
</p>
</s1>
</body>
</document>
1.1 cocoon-2.1/src/documentation/xdocs/tracks/book.xml
Index: book.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//APACHE//DTD Cocoon Documentation Book V1.0//EN"
"../dtd/book-cocoon-v10.dtd">
<book software="Apache Cocoon"
title="Apache Cocoon User Guide - Apendix"
copyright="@year@ The Apache Software Foundation">
<menu label="Navigation">
<menu-item label="Main" href="../index.html"/>
</menu>
<menu label="Tracks">
<menu-item label="Introduction" href="index.html"/>
<menu-item label="First steps" href="first-steps-track.html"/>
<menu-item label="Web publishing" href="web-publishing-track.html"/>
</menu>
</book>
1.1
cocoon-2.1/src/documentation/xdocs/tracks/first-steps-track.xml
Index: first-steps-track.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN"
"dtd/document-v10.dtd">
<document>
<header>
<title>Apache Cocoon User Guide</title>
<subtitle>First Steps track</subtitle>
<authors>
<person name="Bertrand Delacrétaz" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="What's in this track?">
<p>This track is meant to help you take your first steps with Cocoon,
by running
and exploring the samples.</p>
</s1>
<s1 title="Prerequisites">
<p>You will need a JDK (Java Development Kit) installed on your
computer,
and (obviously) an Internet connection to download Cocoon.</p>
<p>No prior knowledge of Cocoon is needed to study this track.</p>
</s1>
<s1 title="First Steps Track">
<p>
Here's our suggestion for your first steps with Cocoon:
</p>
<s2 title="Have a look at the samples">
<p>
Start by reading
<link href="../howto/howto-explore-samples.html">How to run
and explore the Cocoon samples</link>
and taking a first look at the Cocoon samples. At this
point you might not understand much about how they work,
but this will give you a feel of what Cocoon is about.
</p>
</s2>
<s2 title="Study the pipeline and sitemap concepts">
<p>
Next, we suggest that you study the <link
href="../userdocs/user/preface.html">basics</link> to find
out more about how Cocoon works. You should concentrate on
understanding the <em>pipeline</em> and <em>sitemap</em>
concepts, you don't need much more at this point.
</p>
</s2>
<s2 title="Study selected samples in more detail">
<p>
Once you understand a bit more about how Cocoon works, we
suggest that you go back
to a few selected samples that might be of interest to you,
to study them in more detail.
</p>
</s2>
<p>
Going through several iterations of looking at the samples and
studying the corresponding
documentation will help you focus on what you need to
understand about Cocoon.
</p>
<p>
With more than 45 blocks as of this writing, the samples
use a wide variety of tools and
technologies, and attempting to understand everything will most
probably leave you frustrated, so
it is better to limit yourself to a subset of the samples.
<note>
<em>Blocks</em> are components which are largely
independent of each other, and which are
optional when installing Cocoon.
</note>
</p>
</s1>
<s1 title="Comments">
<p>
Care to comment on this Track?
Help keep this document relevant by passing along any
constructive feedback to the
<link href="mailto:[EMAIL PROTECTED]:">cocoon-docs</link>
mailing list.
</p>
</s1>
</body>
</document>
1.1 cocoon-2.1/src/documentation/xdocs/tracks/index.xml
Index: index.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN"
"dtd/document-v10.dtd">
<document>
<header>
<title>Apache Cocoon User Guide</title>
<subtitle>Documentation tracks</subtitle>
<authors>
<person name="Bertrand Delacrétaz" email="[EMAIL
PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="Introduction">
<p>
The
<em>documentation tracks</em> are meant to help you find your
way
through the Cocoon documentation.
</p>
<p>
Tracks are like reading lists which point
you to the relevant sections of the documentation, depending
on what you want to learn.
</p>
</s1>
</body>
</document>
1.1
cocoon-2.1/src/documentation/xdocs/tracks/web-publishing-track.xml
Index: web-publishing-track.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN"
"dtd/document-v10.dtd">
<document>
<header>
<title>Apache Cocoon User Guide</title>
<subtitle>Web publishing track</subtitle>
<authors>
<person name="Bertrand Delacrétaz" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="What's in this track?">
<p>
This track points to Cocoon documentation and external
references which will
help you to use Cocoon for <em>web publishing</em>.
</p>
<p>
By <em>web publishing</em>, we mean generating various formats
(HTML, PDF, RTF, etc.) out
of XML documents, as opposed to <em>web applications</em> which
include transactions,
database storage, etc.
</p>
</s1>
<s1 title="Prerequisites">
<p>
If you have not installed Cocoon yet, have a look at
the <link href="first-steps-track.html">First steps
track</link>.
</p>
</s1>
<s1 title="Web Publishing Track">
<s2 title="HTML/PDF How-To">
<p>
The <link href="../howto/howto-html-pdf-publishing.html">
HTML/PDF How-To
</link> shows some simple examples of HTML and PDF
publishing, it is a good
start to find out how this is done with Cocoon.
</p>
</s2>
<s2 title="XSLT">
<p>
Although there are many options for web publishing with
Cocoon, XSLT
transforms are probably the most common way of
transforming XML documents into the target
XML vocabularies required to generate the various formats.
The above How-To document points to some reference
material about XSLT, which
you might want to study if you decide to use this option.
</p>
</s2>
<s2 title="Generators">
<p>
If you need to convert different data sources to XML, you
will have to study
the available Cocoon
<link
href="../userdocs/components/generators/generators.html">Generators</link>,
to see what options are available. We hope to have a
<em>database queries</em> track
soon, to give more detail about the available options to
access databases.
</p>
</s2>
<s2 title="Serializers">
<p>
At the other end of the pipeline, you will need a
Serializer
to generate the target formats. Have a look a the
<link
href="../userdocs/components/serializers/serializers.html">available
Serializers</link>
and the corresponding samples to find out which ones you
need to to generate your target
output formats.
</p>
</s2>
<s2 title="Samples">
<p>
While looking for Generators and Serializers, do not
forget to look at the samples.
Searching the sitemap files for the names of components
will tell you which samples
use which components.
</p>
</s2>
</s1>
<s1 title="Comments">
<p>
Care to comment on this Track?
Help keep this document relevant by passing along any
constructive feedback to the
<link href="mailto:[EMAIL PROTECTED]:">cocoon-docs</link>
mailing list.
</p>
</s1>
</body>
</document>
