Google Git
Sign in
apache / forrest / refs/tags/forrest_08_release_site / . / docs_0_70 / primer.html
blob: 22a705fd681b66f34f3771e79c3c4a5b3f18a3fd [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta content="Apache Forrest" name="Generator">
<meta name="Forrest-version" content="0.8-dev">
<meta name="Forrest-skin-name" content="pelt">
<title>The Forrest Primer (v0.7)</title>
<link type="text/css" href="../skin/basic.css" rel="stylesheet">
<link media="screen" type="text/css" href="../skin/screen.css" rel="stylesheet">
<link media="print" type="text/css" href="../skin/print.css" rel="stylesheet">
<link type="text/css" href="../skin/profile.css" rel="stylesheet">
<script src="../skin/getBlank.js" language="javascript" type="text/javascript"></script><script src="../skin/getMenu.js" language="javascript" type="text/javascript"></script><script src="../skin/fontsize.js" language="javascript" type="text/javascript"></script>
<link rel="shortcut icon" href="../favicon.ico">
</head>
<body onload="init()">
<script type="text/javascript">ndeSetTextSize();</script>
<div id="top">
<!--+
|breadtrail
+-->
<div class="breadtrail">
<a href="http://www.apache.org/">apache</a> &gt; <a href="http://forrest.apache.org/">forrest</a><script src="../skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script>
</div>
<!--+
|header
+-->
<div class="header">
<!--+
|start group logo
+-->
<div class="grouplogo">
<a href="http://www.apache.org/"><img class="logoImage" alt="Apache" src="../images/apache-forrest.png" title="The Apache Software Foundation"></a>
</div>
<!--+
|end group logo
+-->
<!--+
|start Project Logo
+-->
<div class="projectlogo">
<a href="http://forrest.apache.org/"><img class="logoImage" alt="Forrest" src="../images/project-logo.gif" title="Apache Forrest"></a>
</div>
<!--+
|end Project Logo
+-->
<!--+
|start Search
+-->
<div class="searchbox">
<form action="http://www.google.com/search" method="get" class="roundtopsmall">
<input value="forrest.apache.org" name="sitesearch" type="hidden"><input onFocus="getBlank (this, 'Search the site with google');" size="25" name="q" id="query" type="text" value="Search the site with google">&nbsp;
<input name="Search" value="Search" type="submit">
</form>
</div>
<!--+
|end search
+-->
<!--+
|start Tabs
+-->
<ul id="tabs">
<li>
<a class="unselected" href="../index.html">Welcome</a>
</li>
<li>
<a class="unselected" href="../contrib.html">Developers</a>
</li>
<li class="current">
<a class="selected" href="../versions/index.html">Versioned Docs</a>
</li>
<li>
<a class="unselected" href="../pluginDocs/index.html">Plugins</a>
</li>
<li>
<a class="unselected" href="../tools/index.html">Tools</a>
</li>
</ul>
<!--+
|end Tabs
+-->
</div>
</div>
<div id="main">
<div id="publishedStrip">
<!--+
|start Subtabs
+-->
<div id="level2tabs">
<a class="selected" href="../docs_0_70/index.html">0.70 (current)</a><a class="unselected" href="../docs_0_80/index.html">0.80-dev (under development)</a><a class="unselected" href="../docs_0_60/index.html">0.60 (past)</a>
</div>
<!--+
|end Endtabs
+-->
<script type="text/javascript"><!--
document.write("Last Published: " + document.lastModified);
// --></script>
</div>
<!--+
|breadtrail
+-->
<div class="breadtrail">
&nbsp;
</div>
<!--+
|start Menu, mainarea
+-->
<!--+
|start Menu
+-->
<div id="menu">
<div onclick="SwitchMenu('menu_selected_1.1', '../skin/')" id="menu_selected_1.1Title" class="menutitle" style="background-image: url('../skin/images/chapter_open.gif');">0.70</div>
<div id="menu_selected_1.1" class="selectedmenuitemgroup" style="display: block;">
<div class="menuitem">
<a href="../docs_0_70/index.html">Overview</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/faq.html">FAQs</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/changes.html">Changes</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/todo.html">Todo</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/your-project.html">Using Forrest</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/validation.html">XML Validation</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/linking.html">Menus and Linking</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/searching.html">Searching</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/skins.html">Default Skins</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/skin-package.html">Skin Packages</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/views.html">Views-dev</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/forrest-contract.html">Our Contract</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/compliance.html">Standards Compliance</a>
</div>
<div onclick="SwitchMenu('menu_1.1.14', '../skin/')" id="menu_1.1.14Title" class="menutitle">How-To</div>
<div id="menu_1.1.14" class="menuitemgroup">
<div class="menuitem">
<a href="../docs_0_70/howto/index.html">Overview</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/howto/howto-howto.html">Write a How-to</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/howto/howto-asf-mirror.html">Download mirror</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/howto/howto-pdf-tab.html">Create tab PDF</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/howto/howto-editcss.html">Edit CSS (WYSIWYG)</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/howto/howto-corner-images.html">CSS corner SVG</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/howto/howto-forrest-from-maven.html">Maven Integration</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/howto/howto-buildPlugin.html">Build a Plugin</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/howto/howto-custom-html-source.html">Custom html source</a>
</div>
<div onclick="SwitchMenu('menu_1.1.14.10', '../skin/')" id="menu_1.1.14.10Title" class="menutitle">Multipage HowTo</div>
<div id="menu_1.1.14.10" class="menuitemgroup">
<div class="menuitem">
<a href="../docs_0_70/howto/multi/howto-multi.html">Introduction</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/howto/multi/step1.html">Step 1</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/howto/multi/step2.html">Step 2</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/howto/multi/step3.html">Step 3</a>
</div>
</div>
<div onclick="SwitchMenu('menu_1.1.14.11', '../skin/')" id="menu_1.1.14.11Title" class="menutitle">Views</div>
<div id="menu_1.1.14.11" class="menuitemgroup">
<div class="menuitem">
<a href="../docs_0_70/howto/howto-view-install.html">Install views</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/howto/howto-view-dsl.html">forrest:view DSL</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/howto/howto-view-contracts.html">contract implementations</a>
</div>
</div>
</div>
<div onclick="SwitchMenu('menu_1.1.15', '../skin/')" id="menu_1.1.15Title" class="menutitle">Advanced Topics</div>
<div id="menu_1.1.15" class="menuitemgroup">
<div class="menuitem">
<a href="../docs_0_70/build.html">Building Forrest</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/catalog.html">Using DTD Catalogs</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/sitemap-ref.html">Sitemap Reference</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/project-sitemap.html">Project sitemap</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/cap.html">Sourcetype Action</a>
</div>
</div>
<div class="menuitem">
<a href="../docs_0_70/upgrading_07.html">Upgrading to 0.7</a>
</div>
<div onclick="SwitchMenu('menu_1.1.17', '../skin/')" id="menu_1.1.17Title" class="menutitle">Reference docs</div>
<div id="menu_1.1.17" class="menuitemgroup">
<div onclick="SwitchMenu('menu_1.1.17.1', '../skin/')" id="menu_1.1.17.1Title" class="menutitle">DTD documentation</div>
<div id="menu_1.1.17.1" class="menuitemgroup">
<div class="menuitem">
<a href="../dtdx/dtd-docs.html">Overview</a>
</div>
<div class="menuitem">
<a href="../dtdx/document-v20.dtdx.html">document-v20</a>
</div>
<div class="menuitem">
<a href="../dtdx/howto-v20.dtdx.html">howto-v20</a>
</div>
<div class="menuitem">
<a href="../dtdx/faq-v20.dtdx.html">faq-v20</a>
</div>
<div class="menuitem">
<a href="../dtdx/document-v13.dtdx.html">document-v13</a>
</div>
<div class="menuitem">
<a href="../dtdx/howto-v13.dtdx.html">howto-v13</a>
</div>
<div class="menuitem">
<a href="../dtdx/faq-v13.dtdx.html">faq-v13</a>
</div>
</div>
<div onclick="SwitchMenu('menu_1.1.17.2', '../skin/')" id="menu_1.1.17.2Title" class="menutitle">Doc samples</div>
<div id="menu_1.1.17.2" class="menuitemgroup">
<div class="menuitem">
<a href="../dtdx/document-v13.html">document-v13</a>
</div>
<div class="menuitem">
<a href="../dtdx/document-v20.html">document-v20</a>
</div>
</div>
</div>
<div onclick="SwitchMenu('menu_selected_1.1.18', '../skin/')" id="menu_selected_1.1.18Title" class="menutitle" style="background-image: url('../skin/images/chapter_open.gif');">Older Docs</div>
<div id="menu_selected_1.1.18" class="selectedmenuitemgroup" style="display: block;">
<div class="menupage">
<div class="menupagetitle">Forrest Primer</div>
</div>
<div class="menuitem">
<a href="../docs_0_70/libre-intro.html">Libre</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/dreams.html">Dream list</a>
</div>
<div class="menuitem">
<a href="../docs_0_70/howto/cvs-ssh/howto-cvs-ssh.html">CVS over SSH</a>
</div>
</div>
</div>
<div id="credit">
<hr>
This is documentation for current version v0.7
(<a href="http://forrest.apache.org/versions/">More</a>)</div>
<div id="roundbottom">
<img style="display: none" class="corner" height="15" width="15" alt="" src="../skin/images/rc-b-l-15-1body-2menu-3menu.png"></div>
<!--+
|alternative credits
+-->
<div id="credit2">
<a href="http://apachecon.com/2007/EU/"><img border="0" title="ApacheCon Europe 2007" alt="ApacheCon Europe 2007 - logo" src="http://apache.org/ads/ApacheCon/2007-europe-125x125.png" style="width: 125px;height: 125px;"></a><a href="http://people.apache.org/calendar.html#200711"><img border="0" title="ApacheCon US 2007" alt="ApacheCon US 2007 - logo" src="http://apache.org/ads/ApacheCon/2007-usa-125x125.png" style="width: 125px;height: 125px;"></a>
</div>
</div>
<!--+
|end Menu
+-->
<!--+
|start content
+-->
<div id="content">
<div title="Portable Document Format" class="pdflink">
<a class="dida" href="primer.pdf"><img alt="PDF -icon" src="../skin/images/pdfdoc.gif" class="skin"><br>
PDF</a>
</div>
<div class="trail">Font size:
&nbsp;<input value="Reset" class="resetfont" title="Reset text" onclick="ndeSetTextSize('reset'); return false;" type="button">
&nbsp;<input value="-a" class="smallerfont" title="Shrink text" onclick="ndeSetTextSize('decr'); return false;" type="button">
&nbsp;<input value="+a" class="biggerfont" title="Enlarge text" onclick="ndeSetTextSize('incr'); return false;" type="button">
</div>
<h1>The Forrest Primer</h1>
<h3>Don't panic!</h3>
<div class="abstract">Forrest is a so-called
fledgling
project that will have a broad impact on
xml.apache.org projects. This document
helps you to better understand the vision and scope of Forrest, so that you
learn what to expect (or not) from it, and eventually will help you discovering
places where your contribution could be valuable to all of us.</div>
<div id="motd-area">
This is documentation for current version v0.7
(<a href="http://forrest.apache.org/versions/">More</a>)</div>
<div id="minitoc-area">
<ul class="minitoc">
<li>
<a href="#History">History</a>
</li>
<li>
<a href="#What+is+Forrest">What is Forrest</a>
</li>
<li>
<a href="#Forrest+roles">Forrest roles</a>
</li>
<li>
<a href="#cvs">Getting your local copy of Forrest through CVS</a>
<ul class="minitoc">
<li>
<a href="#System+requirements">System requirements</a>
</li>
<li>
<a href="#Getting+Forrest">Getting Forrest</a>
</li>
<li>
<a href="#Step-by-step+cvs+instructions+for+Windows">Step-by-step cvs instructions for Windows</a>
</li>
<li>
<a href="#Step-by-step+cvs+instructions+for+Unix">Step-by-step cvs instructions for Unix</a>
</li>
</ul>
</li>
<li>
<a href="#Forrest+distribution">Forrest distribution</a>
</li>
<li>
<a href="#The+Forrest+DTDs">The Forrest DTDs</a>
</li>
<li>
<a href="#sitemap">Forrest site generation using Cocoon</a>
</li>
<li>
<a href="#Where+we+are+heading+to">Where we are heading to</a>
</li>
<li>
<a href="#Where+you+can+help">Where you can help</a>
</li>
</ul>
</div>
<div class="warning">
<div class="label">Warning</div>
<div class="content">This document is <em>very</em> out of date. There is a lot of good
information here, but the focus of the project has shifted away from the
Sourceforge-like project management system described here, towards being a
simpler project-centric documentation tool -- JT</div>
</div>
<a name="N10021"></a><a name="History"></a>
<h2 class="underlined_10">History</h2>
<div class="section">
<p>Forrest has come into existence because of the abysmal state of the
<a href="http://xml.apache.org/">xml.apache.org</a> website in comparison
with other open source community sites such as Sourceforge. The old site had no
consistent visual look and feel, which was largely due to each and every
sub-project managing its own site. Furthermore, much information which could
potentially support community-based open source development was hidden inside
CVS repositories, mailing lists or word of mouth. Once we experienced the
usefullness of cross-project collaboration supported by the Jakarta
<a href="http://jakarta.apache.org/gump">Gump</a> project, we reckoned
having a single application responsible for the management of the
xml.apache.org site could be of benefit to our visitors. And if we added
aggregated access to other available resources such as download stats or
mailing list archives, the new xml.apache.org website could be a true
information clearinghouse for interested parties, both users and contributors
alike.</p>
<p>The Forrest vision was articulated by Stefano Mazzocchi and Sam Ruby,
both long-time contributors to Apache projects, in the beginning of 2002, and
was rapidly picked up by a bunch of other
<a href="../who.html">contributors</a> as well, after a headstart by Nicola Ken
Barozzi. So here we are, plenty of work-in-progress to erect what eventually
will become a true community website infrastructure for Apache open source
development.</p>
</div>
<a name="N1003A"></a><a name="What+is+Forrest"></a>
<h2 class="underlined_10">What is Forrest</h2>
<div class="section">
<p>Forrest is a framework that supports the cross-project generation and
management of development project websites using Cocoon as its XML publishing
framework. It not only provides access to project documentation, but also to
other types of information that open source developers depend upon daily:
source code repositories, mailing lists, contact info and the like. It
aggregates all these resources and publishes them on a regular basis to a
website, ensuring a consistent look and feel using skins implemented with XSLT
stylesheets. While Forrest's primary focus is XML Apache project websites, it
can be adapted to other community development projects as well, as long as they
are willing to commit to proven best practices such as Ant for build
automation, CVS for source code control and XML as a documentation source
format.</p>
<p>Forrest is currently based on an
<a href="http://jakarta.apache.org/ant/">Ant</a>-based project build
system called <a href="http://www.krysalis.org/centipede/">Centipede</a>
that drives a <a href="http://cocoon.apache.org/">Cocoon</a>-based
document publication system. It contains a set of standard XML document type
declarations (DTDs) for project documentation, and different 'skins' consisting
of XSLT stylesheets that produce HTML renditions of XML documents using these
DTDs.</p>
<p>The primary mode of operations for Forrest will be as follows:</p>
<div class="note">
<div class="label">Note</div>
<div class="content">This process is not quite ready for prime time yet, but it gives
you an idea where we are heading to. Website generation with skins currently
works, try using the <span class="codefrag">docs</span> target when invoking the
<span class="codefrag">build</span> script. Add a <span class="codefrag">project.skin</span> property when invoking
the build script to experience Forrest skins: <span class="codefrag">build{.bat|.sh}
-Dproject.skin=&lt;thenameoftheskintouse&gt; docs</span>. Read our
<a href="#cvs">CVS crash course</a> to get hold of the current codebase and
start playing with it.</div>
</div>
<ol>
<li>Forrest will harvest documentation and related source files from
each of the projects within the community that uses Forrest for their website,
usually direct from the CVS repository. Which projects are included, and how
they are retrieved is configured by a project descriptor file. This is an
automated process that occurs several times a day to ensure Forrest has the
latest information available.</li>
<li>Forrest then uses Cocoon to generate an HTML rendition of each
project's website, configured by a generic sitemap. The result is a static
collection of HTML documents and related images and stylesheets comprising the
project's website. The impact Forrest has on the participating projects should
be minimal, i.e. one should simply author XML documents, put them in a
well-specified filesystem hierarchy, and Forrest will do its work.</li>
<li>Forrest will enrich the documentation source files with common
information: a cross-project navigation structure (and rendition, of course),
and useful 'community indicators' such as download statistics, number of
contributors with commit access, ...</li>
<li>If the individual project build runs are successful, the project's
website is automagically (re-)published to the (Apache) website, also several
times day.</li>
</ol>
<p>The Forrest website and the overall xml.apache.org website are
maintained and published using the same mechanism.</p>
</div>
<a name="N1007B"></a><a name="Forrest+roles"></a>
<h2 class="underlined_10">Forrest roles</h2>
<div class="section">
<p>Depending on your interests, your involvement with Forrest may vary,
hence your <em>role</em>. We currently envision three different roles:</p>
<ul>
<li>
<strong>User</strong> you want or need to use Forrest for your
project because it uses Forrest to manage its documentation.</li>
<li>
<strong>Adaptor</strong> you want to adapt Forrest to support your
individual project needs, presumably outside the XML Apache context, building
your own skins or DTDs and the like.</li>
<li>
<strong>Contributor</strong> you are a fledgling Forresteer and
want to contribute to the further development of it. If your contributions are
valuable and in true community spirit, you can possibly gain commit access to
the Forrest CVS repository and become an Apache committer. The first stage
towards becoming a contributor is to join the forrest dev
<a href="../mail-lists.html">mailing list</a>, the second is to download
Forrest and start playing with it (see below).</li>
</ul>
<p>Depending on your role, your potential area of interest in Forrest
will vary:</p>
<table class="ForrestTable" cellspacing="1" cellpadding="4">
<tr>
<th colspan="1" rowspan="1">Role</th>
<th colspan="1" rowspan="1">Interests</th>
</tr>
<tr>
<td colspan="1" rowspan="1">User</td>
<td colspan="1" rowspan="1">Forrest DTDs and documentation filesystem hierarchy (Cocoon
sitemap)</td>
</tr>
<tr>
<td colspan="1" rowspan="1">Adaptor</td>
<td colspan="1" rowspan="1">+ skin system and build environment</td>
</tr>
<tr>
<td colspan="1" rowspan="1">Contributor</td>
<td colspan="1" rowspan="1">+ the Forrest codebase and runtime environment</td>
</tr>
</table>
</div>
<a name="N100D8"></a><a name="cvs"></a>
<h2 class="underlined_10">Getting your local copy of Forrest through CVS</h2>
<div class="section">
<a name="N100DE"></a><a name="System+requirements"></a>
<h3 class="underlined_5">System requirements</h3>
<p>Forrest requires the following systems to be already installed on
your system:</p>
<ul>
<li>
<em>Java Virtual Machine</em> A Java virtual machine must be
present. Forrest has been tested against the latest Sun 1.3 JDK.</li>
</ul>
<a name="N100F0"></a><a name="Getting+Forrest"></a>
<h3 class="underlined_5">Getting Forrest</h3>
<p>You can retrieve Forrest from its CVS repository or download
<a href="http://www.apache.org/dyn/closer.cgi/xml/forrest/">here</a>.
<br>Some help with CVS follows (courtesy of our friends of the Cocoon project).</p>
<a name="N10100"></a><a name="Step-by-step+cvs+instructions+for+Windows"></a>
<h3 class="underlined_5">Step-by-step cvs instructions for Windows</h3>
<ol>
<li>Download a recent release of WinCVS (homepage is
<a href="http://www.wincvs.org/">http://www.wincvs.org/</a>); </li>
<li>Install it;</li>
<li>Start it;</li>
<li>Click on Admin-&gt;Preferences;</li>
<li> In "Enter the CVSROOT:" enter
"<span class="codefrag">:pserver:anoncvs@cvs.apache.org:/home/cvspublic</span>" (without
quotes);</li>
<li>In "Authentication:" choose "passwd file on the cvs server";</li>
<li>Click "Ok";</li>
<li>Click Admin-&gt;Login;</li>
<li> When asked for the password: answer "<span class="codefrag">anoncvs</span>"
(without quotes);</li>
<li> Click "Create-&gt;Checkout module";</li>
<li>Module name and path on the server is "<span class="codefrag">xml-forrest</span>"
(no quotes);</li>
<li>Choose a dir to put the source code in;</li>
<li>Click "Ok";</li>
<li>If everything goes well, messages will start to appear in the log
window;</li>
<li>Wait until you see "<span class="codefrag">*****CVS exited normally with code
0*****</span>" in the log window;</li>
<li>The Forrest source is now on your harddrive.</li>
</ol>
<a name="N1014A"></a><a name="Step-by-step+cvs+instructions+for+Unix"></a>
<h3 class="underlined_5">Step-by-step cvs instructions for Unix</h3>
<ol>
<li>Make sure you have a CVS client package installed on your Unix
system.</li>
<li>Start the shell of your choice.</li>
<li>Enter "<span class="codefrag">cvs -d
:pserver:anoncvs@cvs.apache.org:/home/cvspublic login</span>".</li>
<li>When asked for the password: answer "<span class="codefrag">anoncvs</span>".</li>
<li>Enter "<span class="codefrag">cvs -d
:pserver:anoncvs@cvs.apache.org:/home/cvspublic -z3 checkout
xml-forrest</span>". This will create a directory called
"<span class="codefrag">xml-forrest</span>" where the Forrest source will be stored.</li>
<li>Wait until cvs has finished.</li>
<li>The Forrest source is now on your harddrive.</li>
</ol>
<p>In case you want to update your Forrest source tree to the current
version, change to the "<span class="codefrag">xml-forrest</span>" directory and invoke
"<span class="codefrag">cvs -z3 update -d -P</span>".</p>
</div>
<a name="N1017F"></a><a name="Forrest+distribution"></a>
<h2 class="underlined_10">Forrest distribution</h2>
<div class="section">
<p>Once you retrieved Forrest from its CVS repository, you will end up
with a filesystem hierarchy similar to this inside the <span class="codefrag">xml-forrest</span>
home directory:</p>
<div class="warning">
<div class="label">Warning</div>
<div class="content">This is highly volatile information!</div>
</div>
<pre class="code">+---legal various licenses for included projects
+---lib jar library
+---src
| +---documentation Forrest's documentation (not generally reusable)
| | +---content content of the Forrest website
| | | +---xdocs Forrest website XML documents
| | +---resources Forrest-specific doc resources
| | | +---images
| +---resources Generic resources for any Forrest-using project.
| | +---conf Default (overridable) Forrest config files
| | +---library common components (not skin-specific)
| | | +---xslt document format transformers e.g. faq-&gt;xdoc
| | +---convert XSLTs for aiding a transition to Forrest
| | +---skins Forrest skins
| | +---basic
| | +---forrest-site the future xml.apache.org skin
| | | +---css Cascading Stylesheets
| | | +---images skin-specific images
| | | +---xslt the skin stylesheets (per medium)
| | | +---fo
| | | +---html html rendering skins
| | +---jakarta-site
| | +---scarab-site
| | +---xml-apache-site
| | +---schema Generic Forrest DTDs
| | +---dtd
| | +---relaxng
| | +---entity
| | +---images Reusable skin-agnostic images
| | +---fresh-site A template project structure
| | +---forrest-shbat 'shbat' Forrest distribution files
| | +---forrestbot Ant-based Forrest deployment tool
| | +---forrestbar Mozilla Forrest toolbar
| | +---charts charting trials
| | +---layout HTML page mock-ups
| | | +---resources
| | | +---xml.apache.org
| | | +---images
|
+---tools Tools used to build Forrest
+---ant Ant 1.6-dev scripts and jars
+---stylesheets Stylesheets used for project root XML files
</pre>
<p>The <span class="codefrag">xml-forrest</span> home directory consists of the main Ant
build script (<span class="codefrag">build.xml</span>) and platform-specific batch files/shell
scripts to invoke it. Forrest comes with Ant included, so you do not need to
install Ant separately.</p>
<p>Running Forrest is a batch operation you can start using the provided
<span class="codefrag">build.{sh|bat} &lt;targetname&gt;</span>. The current main targets
are:</p>
<ul>
<li>
<strong><span class="codefrag">docs</span></strong> - generates an HTML rendition of
the Forrest website using the default <span class="codefrag">forrest-site</span> skin</li>
<li>
<strong><span class="codefrag">clean</span></strong> - cleans out the
<span class="codefrag">build</span> directory</li>
<li>
<strong><span class="codefrag">webapp</span></strong> - for those who cannot resist
running Forrest live instead of its commandline invocation, this target builds
a WAR file you can deploy in your servlet container (currently only tested for
Tomcat 4.0.1). Mount-point of the web application will be
<span class="codefrag">xml-forrest</span>.</li>
</ul>
<p>After a build run, Forrest creates a <span class="codefrag">build</span> directory. You
can find the generated website in the <span class="codefrag">build/xml-forrest/docs/</span>
directory. Forrest also creates a <span class="codefrag">tools/tmp/anttasks/</span> upon its
first invocation. These are Centipede-specific compiled Ant tasks.</p>
</div>
<a name="N101CC"></a><a name="The+Forrest+DTDs"></a>
<h2 class="underlined_10">The Forrest DTDs</h2>
<div class="section">
<p>Forrest is the reference repository for the XML Apache documentation
DTDs. Special care is taken to provide a set of modular, extensible and
well-maintained DTDs for project documentation purposes. This modularity is
ensured using the
<a href="http://www.oasis-open.org/committees/entity/">OASIS catalog</a>
mechanism, extensive use of external parameter entities and an entity resolver
capable of resolving entities through the aforementioned catalog mechanism. For
the docheads amongst us, this means we adhere to the strict use of
<span class="codefrag">PUBLIC</span> entity identifiers both in document instances and DTD
modules.</p>
<p>We have currently identified the following document types:</p>
<ul>
<li>General documents (<span class="codefrag">document-v11.dtd</span>),</li>
<li>How-Tos (<span class="codefrag">howto-v10.dtd</span>),</li>
<li>Collections of FAQs (<span class="codefrag">faq-v11.dtd)</span>.</li>
</ul>
<p>Some work is also under its way for other document types, in close
collaboration with the Cocoon project. You will also find some older document
types such as <span class="codefrag">changes</span>, <span class="codefrag">javadoc</span>,
<span class="codefrag">specification</span> and <span class="codefrag">todo</span>, which are currently under
consideration for automatic generation and maintenance using Gump or Centipede
descriptors and the like. DTDs will be subject of serious version management as
soon as Forrest has a 1.0 release: they are made to depend upon.</p>
<p>The DTDs are located in <span class="codefrag">src/resources/schema/dtd</span> and also
refer to some character entity collections stored in the
<span class="codefrag">src/resources/schema/entity</span> directory. These are referred to by
the declarations found in the <span class="codefrag">src/resources/schema/catalog</span> OASIS
Catalog file. Take special care using the correct <span class="codefrag">PUBLIC</span>
identifiers in the DTD declaration of your instances:</p>
<pre class="code">&lt;?xml version="1.0"?&gt;
&lt;!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://apache.org/forrest/dtd/document-v12.dtd"&gt;
&lt;document&gt;
...
</pre>
<p>The exact local location of the DTD for validation purposes is
obtained by the entity resolver evaluating the mapping scheme as defined in the
<span class="codefrag">catalog</span> file. This makes sure that you can move and re-arrange
your document instances apart from your DTD files. Later on, the DTDs will be
web-accessible from the Forrest website for your perusal.</p>
</div>
<a name="N1021D"></a><a name="sitemap"></a>
<h2 class="underlined_10">Forrest site generation using Cocoon</h2>
<div class="section">
<p>The <span class="codefrag">docs</span> target of the Forrest build environment invokes
Cocoon as a command-line application to generate an HTML rendition of the
project's documentation. It is not within the scope of this document to explain
the Cocoon internals, please read its own
<a href="http://cocoon.apache.org/">documentation</a> to fully
understand the power of Cocoon.</p>
<p>Cocoon's site rendition behaviour is configured in a so-called
<em>sitemap</em>, a switchboard that binds URLs to an XML processing pipeline.
This pipeline typically consists of a Generator, one or more Transformers and a
Serializer. Forrest also makes use of Cocoon's aggregation capabilities that
merge multiple pipelines into one resulting output document.</p>
<p>A typical page generated using Forrest looks like this:</p>
<div id="" style="text-align: center;">
<img id="" class="figure" alt="Pages areas" src="images/page-areas.png" height="291" width="336"></div>
<p>This page is currently composed of two XML sources which are
transformed by a different XSLT stylesheet, aggregated by Cocoon with a
post-aggregation stylesheet adding the overall page grid and look &amp; feel.
This simple example is handled by the following <em>sitemap</em> snippets
(<span class="codefrag">src/documentation/conf/sitemap.xmap</span>):</p>
<pre class="code">&lt;map:match pattern="*.html"&gt;
&lt;map:aggregate element="site"&gt;
&lt;map:part src="cocoon:/book-{1}.xml"/&gt;
&lt;map:part src="cocoon:/body-{1}.xml" label="content"/&gt;
&lt;/map:aggregate&gt;
&lt;map:call resource="skinit"&gt;
&lt;map:parameter name="type" value="site2xhtml"/&gt;
&lt;/map:call&gt;
&lt;/map:match&gt;</pre>
<pre class="code">&lt;map:match pattern="**book-**.xml"&gt;
&lt;map:generate src="content/xdocs/{1}book.xml"/&gt;
&lt;map:call resource="skinit"&gt;
&lt;map:parameter name="type" value="book2menu"/&gt;
&lt;/map:call&gt;
&lt;/map:match&gt;</pre>
<pre class="code">&lt;map:match pattern="body-**.xml"&gt;
&lt;map:generate src="content/xdocs/{1}.xml"/&gt;
&lt;map:call resource="skinit"&gt;
&lt;map:parameter name="type" value="document2html"/&gt;
&lt;/map:call&gt;
&lt;/map:match&gt;</pre>
<pre class="code">&lt;map:resource name="skinit"&gt;
&lt;map:transform src="skins/@skin@/xslt/html/{type}.xsl"&gt;
&lt;map:parameter name="isfaq" value="{isfaq}"/&gt;
&lt;/map:transform&gt;
&lt;map:serialize/&gt;
&lt;/map:resource&gt;</pre>
<p>When an URL (e.g.
<span class="codefrag">http://forrest.apache.org/index.html</span>) is passed through the
Cocoon system to generate the required page, the pipeline flow is basically as
follows:</p>
<ol>
<li>The URL is matched by the <span class="codefrag">*.html</span> pattern</li>
<li>Cocoon responds by aggregating two 'sub-requests'. The first is for
the resource <span class="codefrag">book-{1}.xml</span>, the second is for the resource
<span class="codefrag">body-{1}.xml</span>. The <span class="codefrag">{1}</span> parameter is replaced by the
values of the first wildcard in the matching pattern above. These
'sub-requests' are passed through the Cocoon pipeline just like any other
request. This results in the following flow:</li>
<ol>
<li>The first 'sub-request' (for <span class="codefrag">book-index.xml</span> is matched
by the <span class="codefrag">**book-**.xml</span> pattern. This results in the file
<span class="codefrag">content/xdocs/book.xml</span> being read. This document is then run
through the <span class="codefrag">book2menu</span> stylesheet (which produces an HTML fragment
comprising the site navigation, the red area in the image above.</li>
<li>The second 'sub-request' is matched by the <span class="codefrag">body-**.xml</span>
pattern. This results in the file <span class="codefrag">index.xml</span> being transformed
using the <span class="codefrag">document2html</span> stylesheet, the yellow area in the
screenshot.</li>
</ol>
<li>The aggregation result is then transformed using the
<span class="codefrag">site2xhtml</span> stylesheet which adds the cherries to the cake. The
grey zone.</li>
</ol>
<p>These <em>skin-specific</em> stylesheets are located in
<span class="codefrag">src/documentation/skins/&lt;nameoftheskin&gt;/xslt/html</span>, so if you
want to add your own skin, this is the place to be. Apart from these, there
exist a number of other stylesheets located in
<span class="codefrag">src/documentation/library/xslt</span> and more importantly:</p>
<ul>
<li>
<span class="codefrag">faq2document</span>: transforms documents following the
<span class="codefrag">faq-v11</span> DTD to <span class="codefrag">document-v11</span> grammar</li>
<li>
<span class="codefrag">howto2document</span>: transforms documents following the
<span class="codefrag">howto-v10</span> DTD to <span class="codefrag">document-v11</span> grammar</li>
<li>and some others.</li>
</ul>
<p>As you see, all documents, regardless of their original DTD, are
transformed to the <span class="codefrag">document</span> DTD prior to rendition. This
alleviates the burden of adding new skins to implementing 3 simple stylesheets:
<span class="codefrag">book2menu</span>, <span class="codefrag">document2html</span> and
<span class="codefrag">site2xhtml</span>.</p>
</div>
<a name="N102CC"></a><a name="Where+we+are+heading+to"></a>
<h2 class="underlined_10">Where we are heading to</h2>
<div class="section">
<p>We have been explaining so far where we are now and what already
works. The purpose of this document however is to attract newcomers and entice
them to start contributing to Forrest. We have a decent generation system for
static project documentation, a nice set of skins and some simple but effective
DTDs. Our goals however are much more ambitious: we have compiled a
<a href="../docs_0_70/dreams.html">dream list</a> that lists most of them.</p>
<ul>
<li>Our first ambition is to support the project site generation and
maintenance of other Apache projects in an automated manner, starting with our
own website as a showcase. We are in the process of setting up the shell
scripts and Ant tasks for this and will assist projects transitioning to
Forrest.</li>
<li>As it is often the case with collaborative open source development,
there is no formal planning nor task assignments, and we will stick to that
practice. We have however compiled a number of functional work areas:</li>
</ul>
<table class="ForrestTable" cellspacing="1" cellpadding="4">
<tr>
<th colspan="1" rowspan="1">URI Namespace Management</th>
<td colspan="1" rowspan="1">Forrest will offer access to a broad set of information resources
using durable URIs: please review
<a href="http://www.w3.org/Provider/Style/URI.html">Tim Berners-Lee</a>'s
and <a href="http://www.useit.com/alertbox/990321.html">Jakob
Nielsen</a>'s opinion on this. We need a unified URI Namespace management
approach, bearing in mind mirroring and 'hackable' URIs.</td>
</tr>
<tr>
<th colspan="1" rowspan="1">Skins</th>
<td colspan="1" rowspan="1">We currently have a nice set of skins which should be solidified.
Furthermore, we need some serious finetuning of the <span class="codefrag">forrest-site</span>
skin that will become the new xml.apache.org look&amp;feel.</td>
</tr>
<tr>
<th colspan="1" rowspan="1">Aggregation<br>and Syndication</th>
<td colspan="1" rowspan="1">We plan to aggregate on a per-project basis a number of relevant
developer resources, such as project-related news, download statistics,
committer bio pages (with photos!), navigable source code listings and the
like. Some of these resources need to be made available across content
syndication methods such as
<a href="http://blogspace.com/rss/">RSS</a>.</td>
</tr>
<tr>
<th colspan="1" rowspan="1">Build Management</th>
<td colspan="1" rowspan="1">Fool-proof automation of Forrest runs and site publication using
secure transfer methods and <span class="codefrag">cron</span> jobs.</td>
</tr>
<tr>
<th colspan="1" rowspan="1">Document Types</th>
<td colspan="1" rowspan="1">Expanding the collection of DTDs, documenting them using formal
How-Tos and example documents.</td>
</tr>
<tr>
<th colspan="1" rowspan="1">xml.apache.org</th>
<td colspan="1" rowspan="1">Formation of an editorial team for the main xml.apache.org website,
working in close collaboration with the
<a href="http://xml.apache.org/whoweare.html">PMC</a> and the different
sub-project leads.</td>
</tr>
<tr>
<th colspan="1" rowspan="1">Integration</th>
<td colspan="1" rowspan="1"> Forrest needs to coexist with existing cross-project collaboration
tools such as <a href="http://gump.apache.org/">Gump</a>,
<a href="http://scarab.tigris.org/">Scarab</a> and
<a href="http://eyebrowse.tigris.org/">Eyebrowse</a> and provide
integrated access to them.</td>
</tr>
<tr>
<th colspan="1" rowspan="1">Authoring support</th>
<td colspan="1" rowspan="1">Supporting document authors with preconfigured XML editing
solutions.</td>
</tr>
<tr>
<th colspan="1" rowspan="1">Content Management</th>
<td colspan="1" rowspan="1">Establish an efficient content management practice, supporting
versioning, remote access and work flow, presumably supported by a CMS such as
<a href="http://jakarta.apache.org/slide/">Slide</a>.</td>
</tr>
<tr>
<th colspan="1" rowspan="1">Information Accessibility</th>
<td colspan="1" rowspan="1">We need to be accessible using a wide range of browsing devices
operating on different platforms. Special care should be taken to support the
<a href="http://www.w3.org/WAI/">WAI</a> guidelines.</td>
</tr>
</table>
</div>
<a name="N10394"></a><a name="Where+you+can+help"></a>
<h2 class="underlined_10">Where you can help</h2>
<div class="section">
<p>By now, you should have a better understanding of Forrest (if that is
not the case, consider contributing clarifications to this document).
We need more people to get the job done.
Forrest is a fun project to work on, and there is something in it for
all of us:</p>
<ul>
<li>XML docheads with skills for document analysis and DTDs
development</li>
<li>Cocoon developers creating custom Cocoon components connecting
Forrest with external resources</li>
<li>Graphical whizzkids for true cross-browser HTML/CSS
development</li>
<li>People who believe XSLT will bring peace to earth (it will, but
keep that quiet)</li>
<li>Ant wizards able to compete with Nicola and Stefan</li>
<li>Unix shell scripting / CVS / cron gurus, preferably bearded</li>
</ul>
<p>Just drop us a line at
the forrest-dev <a href="../mail-lists.html">mail list</a>.
</p>
</div>
<p>That is all, folks.</p>
<table class="ForrestTable" cellspacing="1" cellpadding="4">
<tr>
<th colspan="1" rowspan="1">Revision history</th>
<th colspan="1" rowspan="1"></th>
</tr>
<tr>
<td colspan="1" rowspan="1">2002-05-22</td>
<td colspan="1" rowspan="1">Initial version, Steven Noels, stevenn.at.apache.org</td>
</tr>
<tr>
<td colspan="1" rowspan="1">2002-05-23</td>
<td colspan="1" rowspan="1">Various rephrasings and clarifications thanks to Ross Gardler,
ross.at.saafe.org</td>
</tr>
<tr>
<td colspan="1" rowspan="1">2002-09-23</td>
<td colspan="1" rowspan="1">Updated the directory outline (jefft.at.apache.org)</td>
</tr>
</table>
</div>
<!--+
|end content
+-->
<div class="clearboth">&nbsp;</div>
</div>
<div id="footer">
<!--+
|start bottomstrip
+-->
<div class="lastmodified">
<script type="text/javascript"><!--
document.write("Last Published: " + document.lastModified);
// --></script>
</div>
<div class="copyright">
Copyright &copy;
2002-2007 <a href="http://www.apache.org/licenses/">The Apache Software Foundation.</a>
</div>
<!--+
|end bottomstrip
+-->
</div>
</body>
</html>