forrest-site-svn mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cross...@apache.org
Subject svn commit: r529910 [20/22] - in /forrest/site: docs_0_90/ docs_0_90/howto/ docs_0_90/howto/cvs-ssh/ docs_0_90/howto/multi/ docs_0_90/images/ pluginDocs/plugins_0_90/
Date Wed, 18 Apr 2007 08:11:05 GMT
Added: forrest/site/docs_0_90/your-project.html
URL: http://svn.apache.org/viewvc/forrest/site/docs_0_90/your-project.html?view=auto&rev=529910
==============================================================================
--- forrest/site/docs_0_90/your-project.html (added)
+++ forrest/site/docs_0_90/your-project.html Wed Apr 18 01:10:58 2007
@@ -0,0 +1,1723 @@
+<!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.9-dev">
+<meta name="Forrest-skin-name" content="pelt">
+<title>Using Forrest (v0.9-dev)</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="unselected" href="../docs_0_80/index.html">0.80 (current)</a><a class="selected" href="../docs_0_90/index.html">0.90-dev (under development)</a><a class="unselected" href="../docs_0_70/index.html">0.70 (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.90-dev</div>
+<div id="menu_selected_1.1" class="selectedmenuitemgroup" style="display: block;">
+<div class="menuitem">
+<a href="../docs_0_90/index.html">Overview</a>
+</div>
+<div class="menupage">
+<div class="menupagetitle">Using Forrest</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3', '../skin/')" id="menu_1.1.3Title" class="menutitle">How-To</div>
+<div id="menu_1.1.3" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_90/howto/index.html">Overview</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3.2', '../skin/')" id="menu_1.1.3.2Title" class="menutitle">Install Forrest</div>
+<div id="menu_1.1.3.2" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_90/build.html" title="Build and install the current                     unreleased version">Building Forrest from Source</a>
+</div>
+</div>
+<div class="menuitem">
+<a href="../docs_0_90/upgrading_09.html">Upgrading to 0.9</a>
+</div>
+<div class="menuitem">
+<a href="">Use Forrest</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3.5', '../skin/')" id="menu_1.1.3.5Title" class="menutitle">Customize Forrest</div>
+<div id="menu_1.1.3.5" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_90/sitemap-explain.html">Sitemaps explained</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_90/howto/howto-custom-html-source.html">Custom html source</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_90/project-sitemap.html">Project sitemap</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_90/howto/howto-editcss.html">Edit CSS (WYSIWYG)</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_90/howto/howto-pdf-tab.html" title="Generate one pdf-document for all pages of a tab">Create tab PDF</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_90/howto/howto-corner-images.html">CSS corner SVG</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3.6', '../skin/')" id="menu_1.1.3.6Title" class="menutitle">Integrate Forrest with tools</div>
+<div id="menu_1.1.3.6" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_90/howto/howto-forrest-from-maven.html">Maven Integration</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_90/catalog.html">Using DTD Catalogs</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3.7', '../skin/')" id="menu_1.1.3.7Title" class="menutitle">Extend Forrest</div>
+<div id="menu_1.1.3.7" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_90/howto/howto-buildPlugin.html">Build a Plugin</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_90/skin-package.html">Package new Skins</a>
+</div>
+</div>
+<div class="menuitem">
+<a href="../docs_0_90/howto/howto-asf-mirror.html">Download mirror</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3.9', '../skin/')" id="menu_1.1.3.9Title" class="menutitle">Adding Documentation</div>
+<div id="menu_1.1.3.9" class="menuitemgroup">
+<div class="menuitem">
+<a href="../howto-howto.html" title="Instructions for writing                 a new howto-document">Write a How-to</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3.9.2', '../skin/')" id="menu_1.1.3.9.2Title" class="menutitle">Multipage HowTo</div>
+<div id="menu_1.1.3.9.2" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_90/howto/multi/howto-multi.html">Introduction</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_90/howto/multi/step1.html">Step 1</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_90/howto/multi/step2.html">Step 2</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_90/howto/multi/step3.html">Step 3</a>
+</div>
+</div>
+</div>
+</div>
+<div class="menuitem">
+<a href="../docs_0_90/faq.html">FAQs</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.5', '../skin/')" id="menu_1.1.5Title" class="menutitle">Background</div>
+<div id="menu_1.1.5" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_90/linking.html">Menus and Linking</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_90/searching.html">Search Options in Forrest</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_90/locationmap.html">Locationmap</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_90/sitemap-ref.html">Sitemap Reference</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_90/skins.html" title="About default skins, their naming and features">Skins</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_90/status-themes.html">Dispatcher versus Skins</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_90/cap.html">Sourcetype Action</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_90/validation.html">XML validation and entity resolution</a>
+</div>
+</div>
+<div class="menuitem">
+<a href="../docs_0_90/changes.html">Changes</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_90/glossary.html">Glossary</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.8', '../skin/')" id="menu_1.1.8Title" class="menutitle">Reference docs</div>
+<div id="menu_1.1.8" class="menuitemgroup">
+<div onclick="SwitchMenu('menu_1.1.8.1', '../skin/')" id="menu_1.1.8.1Title" class="menutitle">DTD documentation</div>
+<div id="menu_1.1.8.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.8.2', '../skin/')" id="menu_1.1.8.2Title" class="menutitle">Doc samples</div>
+<div id="menu_1.1.8.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_1.1.9', '../skin/')" id="menu_1.1.9Title" class="menutitle">Older Docs</div>
+<div id="menu_1.1.9" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_90/primer.html">Forrest Primer</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_90/libre-intro.html">Libre</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_90/dreams.html">Dream list</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_90/howto/cvs-ssh/howto-cvs-ssh.html">CVS over SSH</a>
+</div>
+</div>
+</div>
+<div id="credit">
+<hr>
+        This is documentation for development version v0.9-dev
+       (<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="your-project.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>Using Forrest</h1>
+<h3>A tutorial on how to use Forrest in your own projects</h3>
+<div id="motd-area">
+        This is documentation for development version v0.9-dev
+       (<a href="http://forrest.apache.org/versions/">More</a>)</div>
+<div id="minitoc-area">
+<ul class="minitoc">
+<li>
+<a href="#intro">Introduction</a>
+</li>
+<li>
+<a href="#installing">Installing Forrest</a>
+<ul class="minitoc">
+<li>
+<a href="#Setting+up+the+Environment">Setting up the Environment</a>
+<ul class="minitoc">
+<li>
+<a href="#In+Unix%2FLinux%3A">In Unix/Linux:</a>
+</li>
+<li>
+<a href="#Windows+2000">Windows 2000</a>
+</li>
+<li>
+<a href="#In+Windows+XP%3A">In Windows XP:</a>
+</li>
+</ul>
+</li>
+</ul>
+</li>
+<li>
+<a href="#The+%27forrest%27+Command">The 'forrest' Command</a>
+</li>
+<li>
+<a href="#seeding_new">Seeding a new project</a>
+</li>
+<li>
+<a href="#seeding_existing">Seeding an existing project</a>
+</li>
+<li>
+<a href="#customizing">Customizing your project</a>
+<ul class="minitoc">
+<li>
+<a href="#skinconf.xml">Configuring the Forrest skin: skinconf.xml</a>
+</li>
+<li>
+<a href="#Changing_the_layout">Changing the layout: forrest.properties</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#adding_content">Adding content</a>
+<ul class="minitoc">
+<li>
+<a href="#site.xml">site.xml</a>
+</li>
+<li>
+<a href="#tabs.xml">tabs.xml</a>
+</li>
+<li>
+<a href="#images">Images</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#sitemap.xmap">Advanced customizations: sitemap.xmap</a>
+<ul class="minitoc">
+<li>
+<a href="#adding_new_content_type">Example: Adding a new content type</a>
+<ul class="minitoc">
+<li>
+<a href="#new_dtd">Registering a new DTD</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#adding_new_content_type_2">Example: Adding a new content type (advanced)</a>
+</li>
+<li>
+<a href="#integrating_rss">Example: integrating external RSS content</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#skins">Forrest skins</a>
+<ul class="minitoc">
+<li>
+<a href="#skin-configuration">Configuration of skins</a>
+</li>
+<li>
+<a href="#new_skin">Defining a new skin</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#webapp">Interactive Forrest: faster turnaround when developing your docs</a>
+<ul class="minitoc">
+<li>
+<a href="#forrest_run">Running as a webapp</a>
+<ul class="minitoc">
+<li>
+<a href="#using_webapp">Using the webapp</a>
+</li>
+</ul>
+</li>
+</ul>
+</li>
+<li>
+<a href="#invoking_from_ant">Invoking Forrest from Ant</a>
+</li>
+</ul>
+</div>
+    
+<a name="N10013"></a><a name="intro"></a>
+<h2 class="underlined_10">Introduction</h2>
+<div class="section">
+<p>
+        This tutorial will lead you through the process of installing Forrest,
+        and using it to create a new project, or add Forrest-based docs to an
+        existing project.
+      </p>
+</div>
+    
+<a name="N1001D"></a><a name="installing"></a>
+<h2 class="underlined_10">Installing Forrest</h2>
+<div class="section">
+<p>
+        
+<a href="http://forrest.apache.org/mirrors.cgi">Download</a> the latest release of
+        Forrest and follow the index.html in the top-level, or if you want to
+        try the development version, then <a href="../docs_0_90/howto/../build.html">build
+        Forrest</a> from source.
+      </p>
+<a name="N1002E"></a><a name="Setting+up+the+Environment"></a>
+<h3 class="underlined_5">Setting up the Environment</h3>
+<p>
+          After downloading and extracting Forrest, you need to add environment
+          variables. The reason for this is so that the 'forrest' command is
+          available everywhere and it can locate its home directory and
+          resources. It is beyond the scope of Forrest to explain how to manage
+          your operating system. Some tips are listed below and this
+          <a href="http://mail-archives.apache.org/mod_mbox/forrest-user/200610.mbox/%3ceab855560610181625u6e49b49at7df6c0c5e6812c74@mail.gmail.com%3e">message</a>
+          explains further and provides other tips about using Windows.
+        </p>
+<a name="N1003B"></a><a name="In+Unix%2FLinux%3A"></a>
+<h4>In Unix/Linux:</h4>
+<p class="instruction">
+            change directory to the top-level of the forrest distribution and do
+            ...
+          </p>
+<p class="instruction">
+            ~/apache-forrest$ export FORREST_HOME=`pwd`
+          </p>
+<p class="instruction">
+            ~/apache-forrest$ export PATH=$PATH:$FORREST_HOME/bin
+          </p>
+<a name="N1004D"></a><a name="Permanently+Setting+The+Environment+Variables+for+Linux%2FUnix"></a>
+<h5>Permanently Setting The Environment Variables for Linux/Unix</h5>
+<p>
+              Export only changes the variables during that terminal session for
+              that user, this is useful for testing. To permanently add the
+              variable edit either <span class="codefrag">/etc/bash.bashrc</span> (for all users)
+              or <span class="codefrag">~/.bash_profile</span> (for individual users). Add these
+              lines to the end of the file you edit:
+            </p>
+<pre class="code">
+      FORREST_HOME=/full/path/to/forrest
+      export FORREST_HOME
+      
+      PATH=$PATH:$FORREST_HOME/bin
+      export PATH
+          </pre>
+<a name="N10062"></a><a name="Windows+2000"></a>
+<h4>Windows 2000</h4>
+<p class="instruction">
+            Go to "My Computer", "Properties", "Advanced", "Environment
+            Variables"
+          </p>
+<p class="instruction">
+            add a new variable <span class="codefrag">FORREST_HOME</span> as
+            <span class="codefrag">C:\full\path\to\apache-forrest</span>
+          
+</p>
+<p class="instruction">
+            edit <span class="codefrag">PATH</span> as <span class="codefrag">%PATH%;%FORREST_HOME%\bin</span>
+          
+</p>
+<a name="N10081"></a><a name="In+Windows+XP%3A"></a>
+<h4>In Windows XP:</h4>
+<p class="instruction">
+            Go to "My Computer", "Properties", "Advanced", "Environment
+            Variables"
+          </p>
+<p class="instruction">
+            Create a New variable with name: FORREST_HOME value:
+            C:\full\path\to\apache-forrest
+          </p>
+<p class="instruction">
+            Edit PATH by adding ;%FORREST_HOME%\bin to the end of the current
+            value.
+          </p>
+</div>
+    
+<a name="N10096"></a><a name="The+%27forrest%27+Command"></a>
+<h2 class="underlined_10">The 'forrest' Command</h2>
+<div class="section">
+<p>
+        To see what the 'forrest' command can do, type 'forrest -projecthelp'.
+        The build targets that are marked with * are the commonly used ones.
+      </p>
+<pre class="code">
+  Apache Forrest.  Run 'forrest -projecthelp' to list options
+  
+  Buildfile: /usr/local/svn/forrest/src/core/bin/../forrest.build.xml
+  
+      *=======================================================*
+      |                 Forrest Site Builder                  |
+      |                        X.Y-dev                        |
+      *=======================================================*
+    
+               Call this through the 'forrest' command
+    
+  Main targets:
+  
+   available-plugins     What plugins are available?
+   available-skins       What skins are available?
+   clean                 * Clean all directories and files generated during
+                          the build
+   init-plugins          Ensure the required plugins are available locally,
+                         if any are not, download them automatically
+   install-skin          Install the needed skin from the remote repository
+   package-skin          Make a package of an existing skin
+   run                   * Run Jetty (instant live webapp)
+   run_custom_jetty      Run Jetty with configuration file found in the project
+   run_default_jetty     Run Jetty with configuration file found in Forrest
+   seed                  * Seeds a directory with a template project doc structure
+   site                  * Generates a static HTML website for this project
+   validate              Validate all: xdocs, skins, sitemap, etc
+   validate-sitemap      Validate the project sitemaps
+   validate-skinchoice   Validate skin choice
+   validate-skinconf     Validate skinconf
+   validate-skins        Validate skins
+   validate-stylesheets  Validate XSL files
+   validate-xdocs        Validate the project xdocs
+   war                   * Generates a dynamic servlet-based website
+                           (a packaged .war file)
+   webapp                Generates a dynamic servlet-based website
+                           (an unpackaged webapp).
+   webapp-local          Generates a dynamic servlet-based website
+                           (an unpackaged webapp). Note this webapp is suitable
+                           for local execution only, use the 'war' or 'webapp'
+                           target if you wish to deploy remotely.
+  Default target: site
+       </pre>
+<p>
+        As 'site' is the default target, just running 'forrest' without options
+        will generate a "static HTML website". For example, typing 'forrest' in
+        the top-level "forrest/site-author" directory would build Forrest's own
+        website. But we're going to be building a new site for your project, so
+        read on.
+      </p>
+</div>
+    
+<a name="N100A7"></a><a name="seeding_new"></a>
+<h2 class="underlined_10">Seeding a new project</h2>
+<div class="section">
+<p>
+        'Seeding' a project is our own arborial term for adding a template
+        documentation set to your project, which you can then customize.
+      </p>
+<p>
+        To try this out, create a completely new directory (outside the Forrest
+        distribution), then change directory to it, and do 'forrest seed'. This
+        will give you a new site with lots of demonstration documents. You can
+        also do "forrest seed-business", this will ask you a number of questions
+        about the site and will create a smaller site without all the
+        demonstration pages of the standard seed site.
+      </p>
+<div class="note">
+<div class="label">Note</div>
+<div class="content">
+        
+<span class="codefrag">forrest seed</span> is useful to see what is possible within
+        Forrest, but if you are creating a real site <span class="codefrag">forrest
+        seed-business</span> has less content initially, and is therefore easier
+        to edit (even if it is not a business site). We hope to include more
+        seed sites in the future.
+      </div>
+</div>
+<p>
+        If you run <span class="codefrag">forrest seed</span> you should see output like this
+        below:
+      </p>
+<pre class="code">
+[/home/me/forrest/my-test]$ forrest seed
+
+Apache Forrest.  Run 'forrest -projecthelp' to list options
+
+Buildfile: /usr/local/svn/forrest/src/core/bin/../forrest.build.xml
+
+init-props:
+Loading project specific properties from
+ /home/me/forrest/my-test/forrest.properties
+...
+echo-settings:
+
+check-contentdir:
+
+ensure-nocontent:
+
+seed:
+Copying 41 files to /home/me/forrest/my-test
+
+-------------------------------
+~~ Template project created! ~~
+
+Here is an outline of the generated files:
+
+/                        # /home/me/forrest/my-test
+/forrest.properties      # Optional file describing your site layout
+/src/documentation/      # Doc-specific files
+/src/documentation/skinconf.xml    # Info about your project used by the skin
+/src/documentation/content         # Site content.
+/src/documentation/content/xdocs   # XML content.
+/src/documentation/content/xdocs/index.xml # Home page
+/src/documentation/content/xdocs/site.xml  # Navigation file for site structure
+/src/documentation/content/xdocs/tabs.xml  # Skin-specific 'tabs' file.
+/src/documentation/content/xdocs/*.html,pdf # Static content files, may have subdirs
+/src/documentation/resources/images   # Project images (logos, etc)
+# you can create other directories as needed (see forrest.properties)
+
+
+What to do now?
+
+- Render this template to static HTML by typing 'forrest'.
+  View the generated HTML in a browser to make sure everything works.
+- Alternatively 'forrest run' and browse to http://localhost:8888/ live demo.
+- Start adding content in xdocs/ remembering to declare new files in site.xml
+- Follow the document http://forrest.apache.org/docs/your-project.html
+- Provide any feedback to dev@forrest.apache.org
+
+Thanks for using Apache Forrest
+-------------------------------
+
+BUILD SUCCESSFUL
+Total time: 5 seconds
+      </pre>
+<div class="note">
+<div class="label">Note</div>
+<div class="content">
+        As you have probably noticed, we like to document things right in the
+        script, on the theory that people only read online docs when desperate
+        :)
+      </div>
+</div>
+<p>
+        You now have a template documentation structure all set up:
+      </p>
+<pre class="code">
+[/home/me/forrest/my-test]$ tree
+.
+|-- build
+|   `-- tmp
+|       `-- projfilters.properties
+|-- forrest.properties
+|-- src
+|   `-- documentation
+|       |-- README.txt
+|       |-- classes
+|       |   `-- CatalogManager.properties
+|       |-- content
+|       |   `-- xdocs
+|       |       |-- images
+|       |       |   |-- group-logo.gif
+|       |       |   |-- group.svg
+|       |       |   |-- icon.png
+|       |       |   |-- project-logo.gif
+|       |       |   `-- project.svg
+|       |       |-- index.xml
+|       |       |-- samples
+|       |       |   |-- ascii-art.xml
+|       |       |   |-- cocoon-pyramid.aart
+|       |       |   |-- faq.xml
+|       |       |   |-- ihtml-sample.ihtml
+|       |       |   |-- index.xml
+|       |       |   |-- openoffice-writer.sxw
+|       |       |   |-- sample.xml
+|       |       |   |-- sample2.xml
+|       |       |   |-- sdocbook.xml
+|       |       |   |-- subdir
+|       |       |   |   |-- book-sample.xml
+|       |       |   |   `-- index.xml
+|       |       |-- site.xml
+|       |       |-- tabs.xml
+|       |       |-- hello.pdf
+|       |       |-- test1.html
+|       |       `-- test2.html
+|       `-- resources
+|           `-- images
+|           `-- schema
+|           `-- stylesheets
+|       |-- sitemap.xmap
+|       |-- skinconf.xml
+|       `-- translations
+|           |-- langcode.xml
+|           |-- languages_en.xml
+|           |-- languages_es.xml
+|           |-- menu.xml
+|           |-- menu_af.xml
+|           |-- menu_de.xml
+|           |-- menu_es.xml
+|           |-- menu_it.xml
+|           |-- menu_no.xml
+|           |-- menu_ru.xml
+|           |-- menu_sk.xml
+|           |-- tabs.xml
+|           `-- tabs_es.xml
+      </pre>
+<p>
+        To render this to HTML, type 'forrest'. You should have a HTML site
+        rendered into the <span class="codefrag">build/site</span> directory:
+      </p>
+<div id="" style="text-align: center;">
+<img id="" class="figure" alt="New project" src="images/new-project.png" height="356" width="500"></div>
+<p>
+        Practise with adding new content. Change to the directory
+        <span class="codefrag">src/documentation/content/xdocs</span> and copy the file
+        <span class="codefrag">index.xml</span> to create <span class="codefrag">my-new-file.xml</span> as a new
+        document. Edit it to change some text. Add an entry to
+        <span class="codefrag">site.xml</span> by copying one of the other entries and changing
+        it to suit. Now do 'forrest' to see the result.
+      </p>
+</div>
+    
+<a name="N100EC"></a><a name="seeding_existing"></a>
+<h2 class="underlined_10">Seeding an existing project</h2>
+<div class="section">
+<p>
+        In the section above, we have run 'forrest seed' in an empty directory
+        to create a new project. If you have an existing codebase to which you
+        want to add Forrest docs, then run 'forrest seed' in your project base
+        directory, and the Forrest doc structure will be grafted onto your
+        project. This procedure only needs to be done once.
+      </p>
+<p>
+        If your project already has XML documentation, it may be easier to tell
+        Forrest where the XML sources are, rather than rearrange your project
+        directories to accommodate Forrest. This can be done by editing
+        <span class="codefrag">forrest.properties</span> (consult the
+        <a href="#Changing_the_layout">Changing the layout</a> section for
+        more details).
+      </p>
+</div>
+    
+<a name="N10100"></a><a name="customizing"></a>
+<h2 class="underlined_10">Customizing your project</h2>
+<div class="section">
+<p>
+        Having seeded a project with template docs, you will now want to
+        customize it to your project's needs. Here we will deal with configuring
+        the skin, and changing the project layout.
+      </p>
+<a name="N10109"></a><a name="skinconf.xml"></a>
+<h3 class="underlined_5">Configuring the Forrest skin: skinconf.xml</h3>
+<p>
+          Most Forrest skins can be customized through a single XML file,
+          <span class="codefrag">src/documentation/skinconf.xml</span>, which looks like this:
+        </p>
+<pre class="code">
+
+&lt;!--
+Skin configuration file. This file contains details of your project,
+which will be used to configure the chosen Forrest skin.
+--&gt;
+
+ &lt;!DOCTYPE skinconfig PUBLIC
+        "-//APACHE//DTD Skin Configuration V0.6-3//EN"
+        "skinconfig-v06-3.dtd"&gt;
+
+&lt;skinconfig&gt;
+  &lt;!-- To enable lucene search add provider="lucene"
+    Add box-location="alt" to move the search box to an alternate location
+    (if the skin supports it) and box-location="all" to show it in all
+    available locations on the page.  Remove the &lt;search&gt; element to show
+    no search box.
+  --&gt;
+  &lt;search name="MyProject" domain="mydomain"/&gt;
+
+  &lt;!-- Disable the print link? If enabled, invalid HTML 4.0.1 --&gt;
+  &lt;disable-print-link&gt;true&lt;/disable-print-link&gt;  
+  &lt;!-- Disable the PDF link? --&gt;
+  &lt;disable-pdf-link&gt;false&lt;/disable-pdf-link&gt;
+  &lt;!-- Disable the xml source link? --&gt;
+  &lt;!-- The xml source link makes it possible to access the xml rendition
+    of the source frim the html page, and to have it generated statically.
+    This can be used to enable other sites and services to reuse the
+    xml format for their uses. Keep this disabled if you don't want other
+    sites to easily reuse your pages.--&gt;
+  &lt;disable-xml-link&gt;true&lt;/disable-xml-link&gt;
+  
+  &lt;!-- Disable navigation icons on all external links? --&gt;
+  &lt;disable-external-link-image&gt;false&lt;/disable-external-link-image&gt;
+  
+  &lt;!-- Disable w3c compliance links? --&gt;
+  &lt;disable-compliance-links&gt;false&lt;/disable-compliance-links&gt;
+  &lt;!-- Render mailto: links unrecognisable by spam harvesters? --&gt;
+  &lt;obfuscate-mail-links&gt;true&lt;/obfuscate-mail-links&gt;
+
+  &lt;!-- mandatory project logo
+       skin: forrest-site renders it at the top --&gt;
+  &lt;project-name&gt;MyProject&lt;/project-name&gt;
+  &lt;project-description&gt;MyProject Description&lt;/project-description&gt;
+  &lt;project-url&gt;http://myproj.mygroup.org/&lt;/project-url&gt;
+  &lt;project-logo&gt;images/project.png&lt;/project-logo&gt;
+  &lt;!-- Alternative static image:
+  &lt;project-logo&gt;images/project-logo.gif&lt;/project-logo&gt; --&gt;
+
+  &lt;!-- optional group logo
+       skin: forrest-site renders it at the top-left corner --&gt;
+  &lt;group-name&gt;MyGroup&lt;/group-name&gt;
+  &lt;group-description&gt;MyGroup Description&lt;/group-description&gt;
+  &lt;group-url&gt;http://mygroup.org&lt;/group-url&gt;
+  &lt;group-logo&gt;images/group.png&lt;/group-logo&gt;
+  &lt;!-- Alternative static image:
+  &lt;group-logo&gt;images/group-logo.gif&lt;/group-logo&gt; --&gt;
+
+  &lt;!-- optional host logo (e.g. sourceforge logo)
+       skin: forrest-site renders it at the bottom-left corner --&gt;
+  &lt;host-url&gt;&lt;/host-url&gt;
+  &lt;host-logo&gt;&lt;/host-logo&gt;
+  
+  &lt;!-- relative url of a favicon file, normally favicon.ico --&gt;
+  &lt;favicon-url&gt;&lt;/favicon-url&gt;
+
+  &lt;!-- The following are used to construct a copyright statement --&gt;
+  &lt;year&gt;2005&lt;/year&gt;
+  &lt;vendor&gt;The Acme Software Foundation.&lt;/vendor&gt;
+  &lt;!-- The optional copyright-link URL will used as a link in the
+    copyright statement
+  &lt;copyright-link&gt;http://www.apache.org/licenses/&lt;/copyright-link&gt;
+  --&gt;
+
+  &lt;!-- Some skins use this to form a 'breadcrumb trail' of links.
+    If you don't want these, then set the attributes to blank.
+    The DTD purposefully requires them.
+    Use location="alt" to move the trail to an alternate location
+    (if the skin supports it).
+  --&gt;
+  &lt;trail&gt;
+    &lt;link1 name="myGroup" href="http://www.apache.org/"/&gt;
+    &lt;link2 name="myProject" href="http://forrest.apache.org/"/&gt;
+    &lt;link3 name="" href=""/&gt;
+  &lt;/trail&gt;
+
+  &lt;!-- Configure the TOC, i.e. the Table of Contents.
+  @max-depth
+   how many "section" levels need to be included in the
+   generated Table of Contents (TOC). 
+  @min-sections
+   Minimum required to create a TOC.
+  @location ("page","menu","page,menu")
+   Where to show the TOC.
+  --&gt;
+  &lt;toc max-depth="2" min-sections="1" location="page"/&gt;
+
+  &lt;!-- Heading types can be clean|underlined|boxed  --&gt;
+  &lt;headings type="boxed"/&gt;
+
+  &lt;extra-css&gt;
+    &lt;!-- A sample to show how the class attribute can be used --&gt;
+    p.quote {
+      margin-left: 2em;
+      padding: .5em;
+      background-color: #f0f0f0;
+      font-family: monospace;
+    }
+  &lt;/extra-css&gt;
+
+  &lt;colors&gt;
+  &lt;!-- CSS coloring examples omitted for brevity --&gt;
+  &lt;/colors&gt;
+ 
+  &lt;!-- Settings specific to PDF output.  --&gt;
+  &lt;pdf&gt;
+    &lt;!-- 
+       Supported page sizes are a0, a1, a2, a3, a4, a5, executive,
+       folio, legal, ledger, letter, quarto, tabloid (default letter).
+       Supported page orientations are portrait, landscape (default
+       portrait).
+       Supported text alignments are left, right, justify (default left).
+    --&gt;
+    &lt;page size="letter" orientation="portrait" text-align="left"/&gt;
+
+    &lt;!--
+       Margins can be specified for top, bottom, inner, and outer
+       edges. If double-sided="false", the inner edge is always left
+       and the outer is always right. If double-sided="true", the
+       inner edge will be left on odd pages, right on even pages,
+       the outer edge vice versa.
+       Specified below are the default settings.
+    --&gt;
+    &lt;margins double-sided="false"&gt;
+      &lt;top&gt;1in&lt;/top&gt;
+      &lt;bottom&gt;1in&lt;/bottom&gt;
+      &lt;inner&gt;1.25in&lt;/inner&gt;
+      &lt;outer&gt;1in&lt;/outer&gt;
+    &lt;/margins&gt;
+
+    &lt;!--
+      Print the URL text next to all links going outside the file
+    --&gt;
+    &lt;show-external-urls&gt;false&lt;/show-external-urls&gt;
+  &lt;/pdf&gt;
+
+  &lt;!-- Credits are typically rendered as a set of small clickable
+    images in the page footer --&gt;
+  &lt;credits&gt;
+    &lt;credit&gt;
+      &lt;name&gt;Built with Apache Forrest&lt;/name&gt;
+      &lt;url&gt;http://forrest.apache.org/&lt;/url&gt;
+      &lt;image&gt;images/built-with-forrest-button.png&lt;/image&gt;
+      &lt;width&gt;88&lt;/width&gt;
+      &lt;height&gt;31&lt;/height&gt;
+    &lt;/credit&gt;
+    &lt;!-- A credit with @role='pdf' will have its name and url
+      displayed in the PDF page's footer. --&gt;
+  &lt;/credits&gt;
+
+&lt;/skinconfig&gt;
+
+        </pre>
+<p>
+          Customise this file for your project. The <span class="codefrag">images/</span>
+          directory mentioned in 'project-logo' and 'group-logo' elements
+          corresponds to the <span class="codefrag">src/documentation/resources/images</span>
+          directory (this mapping is done automatically by the sitemap).
+        </p>
+<p>
+          Having edited this file (and ensured it is valid XML), re-run the
+          'forrest' command in the site root, and the site would be updated.
+        </p>
+<a name="N10126"></a><a name="Changing_the_layout"></a>
+<h3 class="underlined_5">Changing the layout: forrest.properties</h3>
+<p>
+          Forrest allows you to place files anywhere you want in your project,
+          so long as you tell Forrest where you have placed the major file
+          types.
+        </p>
+<p>
+          The <span class="codefrag">forrest.properties</span> file maps from your directory
+          layout to Forrest's. If you generated your site with 'forrest seed',
+          you will have one pre-written, with all the entries commented out.
+        </p>
+<div class="note">
+<div class="label">Note</div>
+<div class="content">
+          You only need to un-comment entries if you are going to change them to
+          something different. If you keep in synchronisation with the 'forrest
+          seed' defaults, then it is easy to diff each time that you update.
+        </div>
+</div>
+<p>
+          The main entries (with default values) are:
+        </p>
+<pre class="code">
+# Properties that must be set to override the default locations
+#
+# Parent properties must be set. This usually means uncommenting
+# project.content-dir if any other property using it is uncommented
+
+#project.content-dir=src/documentation
+#project.conf-dir=${project.content-dir}/conf
+#project.sitemap-dir=${project.content-dir}
+#project.xdocs-dir=${project.content-dir}/content/xdocs
+#project.resources-dir=${project.content-dir}/resources
+#project.stylesheets-dir=${project.resources-dir}/stylesheets
+#project.images-dir=${project.resources-dir}/images
+#project.schema-dir=${project.resources-dir}/schema
+#project.skins-dir=${project.content-dir}/skins
+#project.skinconf=${project.content-dir}/skinconf.xml
+#project.lib-dir=${project.content-dir}/lib
+#project.classes-dir=${project.content-dir}/classes
+       </pre>
+<p>
+          For example, if you wish to keep XML documentation in src/xdocs rather
+          than <span class="codefrag">src/documentation/content/xdocs</span> simply change the
+          definition for project.xdocs-dir
+        </p>
+<pre class="code">project.xdocs-dir=src/xdocs</pre>
+<p>
+          For example, to emulate the simple
+          <a href="http://maven.apache.org/">Maven</a> format:
+        </p>
+<pre class="code">
+         /xdocs
+         /xdocs/images
+         /xdocs/stylesheets
+       </pre>
+<p>
+          Here are the required property definitions:
+        </p>
+<pre class="code">
+project.content-dir=xdocs
+project.sitemap-dir=${project.content-dir}
+project.xdocs-dir=${project.content-dir}
+project.stylesheets-dir=${project.content-dir}/stylesheets
+project.images-dir=${project.content-dir}/images
+project.skinconf=${project.content-dir}/skinconf.xml
+         </pre>
+<div class="note">
+<div class="label">Note</div>
+<div class="content">
+          Internally, Forrest rearranges the specified directory into the
+          default <span class="codefrag">src/documentation/content/xdocs</span> structure. In the
+          layout above, we have overlapping directories, so you will end up with
+          duplicate files. This small glitch doesn't usually cause problems;
+          just always remember that all links are resolved through the sitemap.
+        </div>
+</div>
+</div>
+    
+<a name="N10165"></a><a name="adding_content"></a>
+<h2 class="underlined_10">Adding content</h2>
+<div class="section">
+<p>
+        Now you can start adding content of your own, in
+        <span class="codefrag">src/documentation/content/xdocs</span>
+      
+</p>
+<a name="N10171"></a><a name="site.xml"></a>
+<h3 class="underlined_5">site.xml</h3>
+<p>
+          When adding a new xml document, you would add an entry to the
+          project's <span class="codefrag">site.xml</span> file. This site.xml is like a site
+          index, and is rendered as the vertical column of links in the default
+          skin. Look at Forrest's own xdocs for an example. More detailed info
+          about site.xml is provided in the document
+          <a href="../docs_0_90/linking.html">Menus and Linking</a>.
+        </p>
+<a name="N10182"></a><a name="tabs.xml"></a>
+<h3 class="underlined_5">tabs.xml</h3>
+<p>
+          The <span class="codefrag">tabs.xml</span> file is used to produce the 'tabs'. which
+          enable users to quickly jump to sections of your site. See the
+          <a href="../docs_0_90/linking.html#menu_generation">menu generation</a> documentation
+          for more details, and again, consult Forrest's own docs for a usage
+          example.
+        </p>
+<div id="" style="text-align: center;">
+<img id="" class="figure" alt="Tabs" src="images/tabs.png"></div>
+<p>
+          You can have one or two levels of tabs. The images above show a single
+          level. However, you can create a second level that will only be
+          displayed when its parent tab is selected. For example, the
+          <span class="codefrag">tabs.xml</span> snippet below will display either one or two
+          rows of tabs, depending on which of the top level tabs is selected.
+          The first row will have two tabs: one labelled <span class="codefrag">How-Tos</span>
+          and the other labelled <span class="codefrag">Apache XML Projects</span>. When the
+          <span class="codefrag">How-Tos</span> tab is selected there will be no second row of
+          tabs. However, when the <span class="codefrag">Apache XML Projects</span> tab is
+          selected, a second row of tabs will be displayed below the first.
+        </p>
+<pre class="code">
+
+  &lt;tab label="How-Tos" dir="community/howto/"/&gt;
+  &lt;tab label="Apache XML Projects" href="http://xml.apache.org"&gt;
+    &lt;tab label="Forrest" href="http://forrest.apache.org/"/&gt;
+    &lt;tab label="Xerces" href="http://xml.apache.org/xerces"/&gt;
+  &lt;/tab&gt;
+
+        </pre>
+<a name="N101AD"></a><a name="images"></a>
+<h3 class="underlined_5">Images</h3>
+<p>
+          Images usually go in the <span class="codefrag">resources/images/</span> directory. The
+          default sitemap maps this directory to <span class="codefrag">images/</span> so image
+          tags will typically look like <span class="codefrag">&lt;figure
+          src="images/project-logo.png" alt="Project Logo"/&gt;</span>
+        
+</p>
+</div>
+    
+<a name="N101C1"></a><a name="sitemap.xmap"></a>
+<h2 class="underlined_10">Advanced customizations: sitemap.xmap</h2>
+<div class="section">
+<p>
+        The Cocoon sitemap is a set of rules for generating content (HTML, PDFs
+        etc) from XML sources. Forrest has a default sitemap, which is adequate
+        for everyday sites. For example, the <a href="http://forrest.apache.org/">Forrest
+        website</a> itself uses the default sitemap.
+      </p>
+<p>
+        Sometimes, one needs to go beyond the default set of rules. This is
+        where Forrest really shines, because its Cocoon backend allows virtually
+        any processing pipeline to be defined. For example, one can:
+      </p>
+<ul>
+        
+<li>Transform custom XML content types with XSLT stylesheets.</li>
+        
+<li>Generate PNG or JPEG images from 
+        <a href="http://www.w3.org/TR/SVG/">SVG</a> XML files.
+          (<strong>Note:</strong> Forrest's sitemap now does this natively.)</li>
+        
+<li>Integrate external XML feeds (e.g. RSS) into your site's content.
+          (<strong>Note:</strong> See issues.xmap for an example.)</li>
+        
+<li>Merge XML sources via aggregation, or make content from large XML
+          sources available as "virtual" files.
+          (<strong>Note:</strong> Forrest makes extensive use of aggregation
+          in the default sitemaps. It also defines a whole-site HTML
+          and PDF, available as the standard names <span class="codefrag">wholesite.html</span>
+          and <span class="codefrag">wholesite.pdf</span>.)</li>
+        
+<li>Read content from exotic sources like
+        <a href="http://www.rpbourret.com/xml/XMLDBLinks.htm">XML
+            databases</a>.</li>
+        
+<li>Integrate any of <a href="http://cocoon.apache.org/2.1/">Cocoon's</a> vast array
+          of capabilities.  The possibilities are best appreciated by
+          downloading the latest Cocoon distribution and playing with the
+          samples.</li>
+      
+</ul>
+<p>
+        The Forrest sitemaps are at <span class="codefrag">main/webapp/*.xmap</span>
+      
+</p>
+<p>
+        You can add pre-processing sitemaps to your project
+        <span class="codefrag">src/documentation</span> directory (or wherever
+        <span class="codefrag">${project.sitemap-dir}</span> points to). Get a copy of a simple
+        sitemap.xmap from a 'forrest seed site'.
+      </p>
+<p>
+        Any match that is not handled, passes through to be handled by the
+        default Forrest sitemaps - obviously extremely powerful. The capability
+        is described in "<a href="../docs_0_90/project-sitemap.html">Using project
+        sitemaps</a>" and some worked examples are shown in the following
+        sections here.
+      </p>
+<div class="note">
+<div class="label">Note</div>
+<div class="content">
+        We advise you to spend time to understand the Apache Cocoon sitemap. See
+        <a href="http://cocoon.apache.org/2.1/userdocs/concepts/sitemap.html">Cocoon sitemap</a> and
+        <a href="http://cocoon.apache.org/2.1/userdocs/concepts/">Cocoon concepts</a> and related
+        component documentation. The Forrest sitemap is broken into multiple
+        files. The main one is <strong>sitemap.xmap</strong> which delegates to
+        others. See the <a href="../docs_0_90/sitemap-ref.html">Sitemap Reference</a>
+        for a tour of the default sitemap.
+      </div>
+</div>
+<a name="N10229"></a><a name="adding_new_content_type"></a>
+<h3 class="underlined_5">Example: Adding a new content type</h3>
+<p>
+          There are two methods for detecting types of documents and doing
+          special handling. The more complete solution is
+          <a href="#adding_new_content_type_2">described</a> in the
+          advanced section below. However, this basic method is also worth
+          understanding.
+        </p>
+<p>
+          Follow this worked example. In a fresh directory do 'forrest seed'
+          then follow the steps described in this section.
+        </p>
+<p>
+          An example scenario is that we have a specialised list of downloads
+          for a certain software package. It would be best to represent the
+          download information in a custom XML format. This means that it will
+          have its own document type declaration. We will need to detect this
+          new document type via our project sitemap and also provide a mapping
+          to a local copy of this DTD.
+        </p>
+<pre class="code">
+&lt;?xml version="1.0" encoding="utf-8"?&gt;
+&lt;!DOCTYPE document PUBLIC "-//Acme//DTD Download Documentation V1.0//EN"
+  "dtd/download-v10.dtd"&gt;
+&lt;document&gt; 
+  &lt;header&gt;
+    &lt;title&gt;Downloading Binaries&lt;/title&gt;
+  &lt;/header&gt;
+  &lt;body&gt;
+    &lt;section id="download"&gt;
+      &lt;title&gt;Downloading binaries&lt;/title&gt;
+      &lt;p&gt;
+        Here are the binaries for FooProject
+      &lt;/p&gt;
+      &lt;release version="0.9.13" date="2002-10-11"&gt;
+        &lt;downloads&gt;
+          &lt;file
+            url="http://prdownloads.sf.net/aft/fooproj-0.9.13-bin.zip?download"
+            name="fooproj-0.9.13-bin.zip"
+            size="5738322"/&gt;
+          &lt;file
+            url="http://prdownloads.sf.net/aft/fooproj-0.9.13-src.zip?download"
+            name="fooproj-0.9.13-src.zip"
+            size="10239777"/&gt;
+        &lt;/downloads&gt;
+      &lt;/release&gt;
+      &lt;release version="0.9.12" date="2002-10-08"&gt;
+        &lt;downloads&gt;
+          &lt;file
+            url="http://prdownloads.sf.net/aft/fooproj-0.9.12-src.zip?download"
+            name="fooproj-0.9.12-src.zip"
+            size="10022737"/&gt;
+         &lt;/downloads&gt;
+       &lt;/release&gt;
+    &lt;/section&gt;
+    &lt;section id="cvs"&gt;
+      &lt;title&gt;Getting FooProject from CVS&lt;/title&gt;
+      &lt;p&gt;....&lt;/p&gt;
+    &lt;/section&gt;
+  &lt;/body&gt;
+&lt;/document&gt;
+        </pre>
+<p>
+          This file called "<span class="codefrag">download.xml</span>" would be placed in your
+          content directory (typically
+          <span class="codefrag">src/documentation/content/xdocs</span>) and an entry added to
+          <span class="codefrag">site.xml</span>
+        
+</p>
+<p>
+          To handle these special tags, one would write a stylesheet to convert
+          them to the intermediate Forrest xdocs structure. Here is such a
+          stylesheet, called "<span class="codefrag">download-to-document.xsl</span>" ...
+        </p>
+<pre class="code">
+&lt;?xml version="1.0" encoding="utf-8"?&gt;
+&lt;xsl:stylesheet
+  version="1.0"
+  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"&gt;
+
+  &lt;xsl:template match="release"&gt;
+    &lt;section id="{@version}"&gt;
+      &lt;title&gt;Version &lt;xsl:value-of select="@version"/&gt; (released
+          &lt;xsl:value-of select="@date"/&gt;)&lt;/title&gt;
+      &lt;table&gt;
+        &lt;tr&gt;&lt;th&gt;File&lt;/th&gt;&lt;th&gt;Size&lt;/th&gt;&lt;/tr&gt;
+        &lt;xsl:apply-templates select="downloads/*"/&gt;
+      &lt;/table&gt;
+    &lt;/section&gt;
+  &lt;/xsl:template&gt;
+
+  &lt;xsl:template match="file"&gt;
+    &lt;tr&gt;
+      &lt;td&gt;&lt;link href="{@url}"&gt;&lt;xsl:value-of select="@name"/&gt;&lt;/link&gt;&lt;/td&gt;
+      &lt;td&gt;&lt;xsl:value-of
+           select="format-number(@size div (1024*1024), '##.##')"/&gt; MB&lt;/td&gt;
+    &lt;/tr&gt;
+  &lt;/xsl:template&gt;
+
+  &lt;xsl:template match="@* | node() | comment()"&gt;
+    &lt;xsl:copy&gt;
+      &lt;xsl:apply-templates select="@*"/&gt;
+      &lt;xsl:apply-templates/&gt;
+    &lt;/xsl:copy&gt;
+  &lt;/xsl:template&gt;
+
+&lt;/xsl:stylesheet&gt;
+
+        </pre>
+<p>
+          Place this file in the default stylesheets directory,
+          <span class="codefrag">src/documentation/resources/stylesheets</span> (or wherever
+          ${project.stylesheets-dir} points).
+        </p>
+<p>
+          Now we will create a project sitemap to control the transformation of
+          our custom xml structure into the Forrest intermediate xdocs
+          structure.
+        </p>
+<div class="note">
+<div class="label">Note</div>
+<div class="content">
+          The <a href="../docs_0_90/sitemap-ref.html">Sitemap Reference</a> provides
+          details about how the sitemap works.
+        </div>
+</div>
+<p>
+          Add the following match to the file
+          <span class="codefrag">src/documentation/sitemap.xmap</span> ...
+        </p>
+<pre class="code">
+&lt;?xml version="1.0"?&gt;
+&lt;map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0"&gt;
+ &lt;map:pipelines&gt;
+  &lt;map:pipeline&gt;
+  ...
+  <strong>
+
+   &lt;map:match pattern="**download.xml"&gt;
+    &lt;map:generate src="{properties:content.xdocs}{1}download.xml" /&gt;
+    &lt;map:transform src="{properties:resources.stylesheets}/download-to-document.xsl" /&gt;
+    &lt;map:serialize type="xml"/&gt;
+   &lt;/map:match&gt;
+</strong>
+
+  &lt;/map:pipeline&gt;
+ &lt;/map:pipelines&gt;
+&lt;/map:sitemap&gt;
+
+        </pre>
+<p>
+          That will intercept the request for the body content, for only this
+          specific "download" document, and will transform it into the
+          intermediate Forrest "document" format. The normal Forrest machinery
+          will handle the aggregation with navigation menus etc. and will apply
+          the normal skin.
+        </p>
+<a name="N10276"></a><a name="new_dtd"></a>
+<h4>Registering a new DTD</h4>
+<p>
+            By default, Forrest requires that all XML files be valid, i.e. they
+            must have a DOCTYPE declaration and associated DTD, and validate
+            against it. Our new 'downloads' document type is no exception. The
+            <a href="../docs_0_90/validation.html">XML Validation</a> document
+            continues this example, showing how to register a new document type.
+            Briefly, this involves:
+          </p>
+<ul>
+            
+<li>Create a new DTD or (in our case) extend an existing
+                   one.</li>
+            
+<li>Place the new DTD in the
+                   <span class="codefrag">${project.schema-dir}/dtd</span> directory.</li>
+            
+<li>Add an XML Catalog to enable a mapping from the
+                   DOCTYPE public id to the relevant DTD file.</li>
+            
+<li>Tell the system about your catalog.</li>
+          
+</ul>
+<div class="note">
+<div class="label">Note</div>
+<div class="content">
+            Please see <a href="../docs_0_90/validation.html">XML Validation</a> for
+            the complete description for those steps.
+          </div>
+</div>
+<a name="N1029E"></a><a name="adding_new_content_type_2"></a>
+<h3 class="underlined_5">Example: Adding a new content type (advanced)</h3>
+<p>
+          The simple user sitemap in the previous example is fine for simple
+          situations. For a complete solution to the "Download DTD" issue we
+          need a more advanced sitemap which will do different processing
+          depending on the type of the source document.
+        </p>
+<p>
+          We need to digress and explain the powerful
+          <a href="../docs_0_90/cap.html">SourceTypeAction (content aware
+          pipelines)</a>. It is a Cocoon sitemap component that peeks at the
+          top-part of a document to look for hints about the type of the
+          document. It has four methods: document-declaration, document-element
+          and namespace, processing-instruction, w3c-xml-schema.
+        </p>
+<p>
+          Now to return to our specific example which uses SourceTypeAction to
+          detect the Document Type Declaration. Let us show the sitemap and then
+          explain it.
+        </p>
+<pre class="code">
+&lt;?xml version="1.0"?&gt;
+&lt;map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0"&gt;
+
+ &lt;map:components&gt;
+  &lt;map:selectors default="parameter"&gt;
+   &lt;map:selector logger="sitemap.selector.parameter"
+       name="parameter" src="org.apache.cocoon.selection.ParameterSelector" /&gt;
+  &lt;/map:selectors&gt;
+  &lt;map:actions&gt;
+   &lt;map:action logger="sitemap.action.sourcetype" name="sourcetype"
+       src="org.apache.forrest.sourcetype.SourceTypeAction"&gt;
+    &lt;sourcetype name="download-v1.0"&gt;
+     &lt;document-declaration
+        public-id="-//Acme//DTD Download Documentation V1.0//EN" /&gt;
+    &lt;/sourcetype&gt;      
+    &lt;sourcetype name="download-v1.1"&gt;
+     &lt;document-declaration
+        public-id="-//Acme//DTD Download Documentation V1.1//EN" /&gt;
+    &lt;/sourcetype&gt;      
+   &lt;/map:action&gt;
+  &lt;/map:actions&gt;
+ &lt;/map:components&gt;
+
+ &lt;map:pipelines&gt;
+  &lt;map:pipeline&gt;
+   &lt;map:match pattern="**download.xml"&gt;
+    &lt;map:generate src="{properties:content.xdocs}{1}download.xml" /&gt;
+    &lt;map:act type="sourcetype" src="{properties:content.xdocs}{1}download.xml"&gt;
+     &lt;map:select type="parameter"&gt;
+      &lt;map:parameter name="parameter-selector-test" value="{sourcetype}" /&gt;
+      &lt;map:when test="download-v1.0"&gt;
+       &lt;map:transform
+          src="{properties:resources.stylesheets}/download-to-document.xsl" /&gt;
+      &lt;/map:when&gt;
+      &lt;map:when test="download-v1.1"&gt;
+       &lt;map:transform
+          src="{properties:resources.stylesheets}/downloadv11-to-document.xsl" /&gt;
+      &lt;/map:when&gt;
+     &lt;/map:select&gt;
+    &lt;/map:act&gt;
+    &lt;map:serialize type="xml"/&gt;
+   &lt;/map:match&gt;
+  &lt;/map:pipeline&gt;
+ &lt;/map:pipelines&gt;
+&lt;/map:sitemap&gt;
+
+        </pre>
+<p>
+          This is the type of processing that happens in the main
+          <span class="codefrag">main/webapp/forrest.xmap</span> sitemap. We have added similar
+          handling to our project sitemap. Basically, this uses the
+          <a href="../docs_0_90/cap.html">SourceTypeAction (content aware
+          pipelines)</a> to detect the doctype. The new document-v11.dtd
+          needs to be also added to your project Catalog as
+          <a href="#new_dtd">described above</a>.
+        </p>
+<p>
+          Note that any sitemap component must be declared before it can be
+          used, because the project sitemap is the first sitemap to be
+          consulted.
+        </p>
+<a name="N102C7"></a><a name="integrating_rss"></a>
+<h3 class="underlined_5">Example: integrating external RSS content</h3>
+<p>
+          Similar to the previous example, we can integrate RSS into our site
+          simply by providing a match in our project sitemap.xmap ...
+        </p>
+<pre class="code">
+&lt;?xml version="1.0"?&gt;
+&lt;map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0"&gt;
+ &lt;map:pipelines&gt;
+  &lt;map:pipeline&gt;<strong>
+
+   &lt;map:match pattern="**weblog.xml"&gt;
+    &lt;map:generate src="http://blogs.cocoondev.org/stevenn/index.rss"/&gt;
+    &lt;map:transform src="{forrest:forrest.stylesheets}/rss-to-document.xsl"/&gt;
+    &lt;map:serialize type="xml"/&gt;
+   &lt;/map:match&gt;
+</strong>
+
+   &lt;map:match pattern="......."&gt;
+    &lt;!-- handle other project-specific matches --&gt;
+   &lt;/map:match&gt;
+  &lt;/map:pipeline&gt;
+ &lt;/map:pipelines&gt;
+&lt;/map:sitemap&gt;
+
+        </pre>
+<p>
+          You will probably want to copy the core Forrest
+          <span class="codefrag">rss-to-document.xsl</span> to your project, customise it to your
+          needs, and refer to it with
+          <span class="codefrag">src="{properties:resources.stylesheets}/rss-to-document.xsl"</span>.
+          Then of course you would add an entry to site.xml to link to
+          weblog.html
+        </p>
+</div>
+    
+<a name="N102E2"></a><a name="skins"></a>
+<h2 class="underlined_10">Forrest skins</h2>
+<div class="section">
+<p>
+        As Forrest separates content from presentation, we can plug in different
+        "skins" to instantly change a site's look and feel. Forrest provides one
+        primary skin, <span class="codefrag">pelt</span>, and some others in various states of
+        development.
+      </p>
+<p>
+        To change the skin, edit the <span class="codefrag">forrest.properties</span> file to set
+        <span class="codefrag">project.skin=pelt</span> or some other skin name. If running in
+        dynamic mode you need to restart Forrest in order to see the new skin.
+      </p>
+<div class="note">
+<div class="label">Note</div>
+<div class="content">
+        Forrest supplies a collection of <a href="../docs_0_90/your-project.html#skins">default
+        skins</a> which are configurable and so should meet the needs of most
+        projects. The aim is to provide many capabilities so that extra skins
+        are not needed.
+      </div>
+</div>
+<a name="N102FE"></a><a name="skin-configuration"></a>
+<h3 class="underlined_5">Configuration of skins</h3>
+<p>
+          All configuration is done via your project
+          <span class="codefrag">src/documentation/skinconf.xml</span> file. It contains many
+          comments to describe each capability. Please read those, there is no
+          point repeating here.
+        </p>
+<a name="N1030B"></a><a name="new_skin"></a>
+<h3 class="underlined_5">Defining a new skin</h3>
+<p>
+          Consider discussing your needs on the mailing lists. There may be
+          planned enhancements to the core skins. Also consider contributing
+          your extensions to the core skins, rather than write your own skin.
+          Bear in mind that you could be creating an update and management
+          issue. Anyway, ...
+        </p>
+<p>
+          Projects can define their own skin in the
+          <span class="codefrag">src/documentation/skins</span> directory (or wherever
+          <span class="codefrag">${project.skins-dir}</span> points). The default sitemap assumes
+          a certain skin layout, so the easiest way to create a new skin is by
+          copying an existing Forrest skin. For example, copy
+          <span class="codefrag">main/webapp/skins/pelt</span> to your project area at
+          <span class="codefrag">src/documentation/skins/my-fancy-skin</span> and add
+          <span class="codefrag">project.skin=my-fancy-skin</span> to forrest.properties
+        </p>
+<p>
+          The two most interesting XSLT stylesheets involved are:
+        </p>
+<dl>
+          
+<dt>
+<span class="codefrag">xslt/html/document-to-html.xsl</span>
+</dt>
+          
+<dd>
+              This stylesheet is applied to individual Forrest xdocs XML files, and
+              converts them to HTML suitable for embedding in a larger HTML page.
+            </dd>
+          
+<dt>
+<span class="codefrag">xslt/html/site-to-xhtml.xsl</span>
+</dt>
+          
+<dd>
+              This stylesheet generates the final HTML file from an intermediate
+              'site' structure produced by the other stylesheets. It defines the general
+              layout, and adds the header and footer.
+            </dd>
+        
+</dl>
+<p>
+          Typically there is a lot of commonality between skins. XSLT provides
+          an 'import' mechanism whereby one XSLT can extend another. Forrest
+          XSLTs typically 'import' from a common base:
+        </p>
+<pre class="code">
+
+&lt;xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"&gt;
+
+  &lt;xsl:import href="../../../common/xslt/html/document-to-html.xsl"/&gt;
+
+  <strong>... overrides of default templates ...</strong>
+ 
+&lt;/xsl:stylesheet&gt;
+        </pre>
+<p>
+          In order to use this feature in your custom skins you must copy the
+          common skin from the forrest distribution into your custom skins
+          directory (from <span class="codefrag">main/webapp/skins/common</span>). This will
+          protect your skin from changes in the Forrest common skin, but you
+          must remember to update this skin in order to take advantage of new
+          features added over time by the Forrest team.
+        </p>
+<div class="note">
+<div class="label">Note</div>
+<div class="content">
+          The above paragraph means that if you do copy an existing skin as this
+          section recomends you will also need to copy the common skin since all
+          existing skins import the common skin.
+        </div>
+</div>
+<p>
+          This is particularly relevant for menu rendering (book-to-menu.xsl),
+          where the common stylesheet does the 'logic' of which item is
+          selected, and over-riding stylesheets define the presentation.
+        </p>
+</div>
+    
+<a name="N10352"></a><a name="webapp"></a>
+<h2 class="underlined_10">Interactive Forrest: faster turnaround when developing your docs</h2>
+<div class="section">
+<p>
+        In comparison to simpler tools (like
+        <a href="http://jakarta.apache.org/velocity/anakia.html">Anakia</a>) the Cocoon command-line mode (and
+        hence Forrest command-line mode) is slow. As the
+        <a href="../docs_0_90/dreams.html">dream list</a> notes, Forrest was originally
+        intended to be used for dynamic sites, and the Cocoon crawler used only
+        to create static snapshots for mirroring. This section describes how, by
+        using a "live" Forrest webapp instance, the Forrest-based documentation
+        development can be faster and easier than with comparable tools.
+      </p>
+<a name="N10363"></a><a name="forrest_run"></a>
+<h3 class="underlined_5">Running as a webapp</h3>
+<p>
+          Type '<span class="codefrag">forrest run</span>' in your project root to start
+          Forrest's built-in Jetty web server. Once it has started, point your
+          browser at
+          <a href="http://localhost:8888/">http://localhost:8888/</a>,
+          which will show your website, rendered on demand as each link is
+          followed.
+        </p>
+<p>
+          (Alternatively, if you wish to run Forrest from within an existing
+          servlet container, type <span class="codefrag">forrest webapp</span> to build an open
+          webapp in <span class="codefrag">build/webapp/</span>)
+        </p>
+<a name="N1037C"></a><a name="using_webapp"></a>
+<h4>Using the webapp</h4>
+<p>
+            You can now edit the XML content in
+            <span class="codefrag">build/webapp/content/xdocs</span> and see the changes
+            immediately in the browser.
+          </p>
+</div>
+    
+<a name="N1038B"></a><a name="invoking_from_ant"></a>
+<h2 class="underlined_10">Invoking Forrest from Ant</h2>
+<div class="section">
+<p>
+        Ant has an
+        <a href="http://ant.apache.org/manual/CoreTasks/import.html">&lt;import&gt;</a>
+        task which can be used to invoke Forrest from Ant. All targets and
+        properties are imported and can be used in your project build. Here is a
+        simple example:
+      </p>
+<pre class="code">
+
+&lt;project name="myproject" default="hello"&gt;
+     &lt;!-- FORREST_HOME must be set as an environment variable --&gt;
+     &lt;property environment="env"/&gt;
+     &lt;property name="forrest.home" value="${env.FORREST_HOME}"/&gt;
+     &lt;import file="${env.FORREST_HOME}/main/forrest.build.xml"/&gt;
+
+     &lt;!-- 'site' is a target imported from forrest.build.xml --&gt;
+     &lt;target name="post-build" depends="site"&gt;
+       &lt;echo&gt;something here&lt;/echo&gt;
+     &lt;/target&gt;
+&lt;/project&gt;
+        
+      </pre>
+<div class="warning">
+<div class="label">Warning</div>
+<div class="content">
+        See issue
+        <a href="http://issues.apache.org/jira/browse/FOR-145">FOR-145</a>
+        which causes clashes of Ant target names.
+      </div>
+</div>
+<div class="warning">
+<div class="label">Warning</div>
+<div class="content">
+        There is a bug in the plugin download mechanism in Forrest 0.7 that may
+        prevent your plugins being installed correctly when calling Forrest from
+        ANT. You can work around this bug by either ensuring a version number is
+        defined for the plugin in forrest.properties or by manually installing
+        the required plugins.
+      </div>
+</div>
+<p>
+        Because you are using your own version of Ant to do Forrest's work, you
+        will need to provide the supporting catalog entity resolver: '<span class="codefrag">cp
+        forrest/lib/core/xml-commons-resolver-1.1.jar $ANT_HOME/lib</span>'
+      </p>
+<p>
+        Note: The technique described above requires Ant 1.6+ otherwise the
+        &lt;import&gt; task will not be available for you to use. Forrest
+        bundles the latest version of Ant, so you can invoke your project like
+        this: '<span class="codefrag">forrest -f myproject.xml</span>'. This will not run the
+        '<span class="codefrag">forrest</span>' command. It will just use Forrest's Ant and
+        resolver to execute your buildfile.
+      </p>
+<p>
+        Another option is to use the Forrest Antlet from the Krysalis Project's
+        <a href="http://antworks.sourceforge.net/importer/">Antworks
+        Importer</a>.
+      </p>
+<p>
+        The <a href="../tools/forrestbot.html">Forrestbot</a> provides workstages
+        to get source, build, deploy, and notify. This is very useful for
+        automating builds; you may want to consider using the Forrestbot.
+      </p>
+</div>
+  
+<span class="version">SVN: $Revision: 529825 $ $Date: 2007-04-18 11:56:53 +1000 (Wed, 18 Apr 2007) $</span>
+</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>

Propchange: forrest/site/docs_0_90/your-project.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: forrest/site/docs_0_90/your-project.pdf
URL: http://svn.apache.org/viewvc/forrest/site/docs_0_90/your-project.pdf?view=auto&rev=529910
==============================================================================
Binary file - no diff available.

Propchange: forrest/site/docs_0_90/your-project.pdf
------------------------------------------------------------------------------
    svn:mime-type = application/pdf



Mime
View raw message