Mailing List Archive: svn commit: r1068306 [20/22] - in /forrest/site: docs_0_100/ docs_0_100/howto/ docs_0_100/howto/cvs-ssh/ docs_0_100/howto/multi/ docs_0_100/images/ pluginDocs/plugins_0_100/ trash/ trash/docs_0_50/ trash/docs_0

Added: forrest/site/docs_0_100/your-project.html
URL: http://svn.apache.org/viewvc/forrest/site/docs_0_100/your-project.html?rev=1068306&view=auto
==============================================================================
--- forrest/site/docs_0_100/your-project.html (added)
+++ forrest/site/docs_0_100/your-project.html Tue Feb 8 09:44:46 2011
@@ -0,0 +1,1767 @@
+<!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.10-dev">
+<meta name="Forrest-skin-name" content="pelt">
+<title>Using Forrest (v0.10-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">
+
+<div class="breadtrail">
+<a href="http://www.apache.org/">Apache Software Foundation</a> > <a href="http://forrest.apache.org/">Apache Forrest</a><script src="../skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script>
+</div>
+
+<div class="header">
+
+<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>
+
+
+<div class="projectlogo">
+<a href="http://forrest.apache.org/"><img class="logoImage" alt="Forrest" src="../images/project-logo.gif" title="Apache Forrest"></a>
+</div>
+
+
+<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"> 
+ <input name="Search" value="Search" type="submit">
+</form>
+</div>
+
+
+<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>
+
+</div>
+</div>
+<div id="main">
+<div id="publishedStrip">
+
+<div id="level2tabs">
+<a class="unselected" href="../docs_0_90/index.html">0.90 (current)</a><a class="selected" href="../docs_0_100/index.html">0.100-dev (under development)</a><a class="unselected" href="../docs_0_80/index.html">0.80 (past)</a>
+</div>
+
+<script type="text/javascript"></script>
+</div>
+
+<div class="breadtrail">
+
+  
+ </div>
+
+
+<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.100-dev</div>
+<div id="menu_selected_1.1" class="selectedmenuitemgroup" style="display: block;">
+<div class="menuitem">
+<a href="../docs_0_100/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_100/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_100/build.html" title="Build and install the current unreleased version">Building Forrest from Source</a>
+</div>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/upgrading_010.html">Upgrading to 0.10-dev</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3.4', '../skin/')" id="menu_1.1.3.4Title" class="menutitle">Customize Forrest</div>
+<div id="menu_1.1.3.4" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_100/sitemap-explain.html">Sitemaps explained</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/howto/howto-custom-html-source.html">Custom html source</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/project-sitemap.html">Project sitemap</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/howto/howto-editcss.html">Edit CSS (WYSIWYG)</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/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_100/howto/howto-corner-images.html">CSS corner SVG</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3.5', '../skin/')" id="menu_1.1.3.5Title" class="menutitle">Integrate Forrest with tools</div>
+<div id="menu_1.1.3.5" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_100/howto/howto-forrest-from-maven.html">Maven Integration</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/catalog.html">Using DTD Catalogs</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3.6', '../skin/')" id="menu_1.1.3.6Title" class="menutitle">Extend Forrest</div>
+<div id="menu_1.1.3.6" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_100/howto/howto-buildPlugin.html">Build a Plugin</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/skin-package.html">Package new Skins</a>
+</div>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/howto/howto-asf-mirror.html">Download mirror</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3.8', '../skin/')" id="menu_1.1.3.8Title" class="menutitle">Adding Documentation</div>
+<div id="menu_1.1.3.8" 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.8.2', '../skin/')" id="menu_1.1.3.8.2Title" class="menutitle">Multipage HowTo</div>
+<div id="menu_1.1.3.8.2" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_100/howto/multi/howto-multi.html">Introduction</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/howto/multi/step1.html">Step 1</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/howto/multi/step2.html">Step 2</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/howto/multi/step3.html">Step 3</a>
+</div>
+</div>
+</div>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/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_100/linking.html">Menus and Linking</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/searching.html">Search Options in Forrest</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/locationmap.html">Locationmap</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/properties.html">Properties system</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/sitemap-ref.html">Sitemap Reference</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/skins.html" title="About default skins, their naming and features">Skins</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/status-themes.html">Dispatcher versus Skins</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/cap.html">Sourcetype Action</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/validation.html">XML validation and entity resolution</a>
+</div>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/changes.html">Changes</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/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_100/primer.html">Forrest Primer</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/libre-intro.html">Libre</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/dreams.html">Dream list</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/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.10-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>
+
+<div id="credit2">
+<a href="http://www.apache.org/events/current-event.html"><img border="0" title="ApacheCon" alt="ApacheCon - logo" src="http://www.apache.org/events/current-event-125x125.png" style="width: 125px;height: 125px;"></a>
+</div>
+</div>
+
+
+<div id="content">
+<div class="trail">Font size:
+  <input value="Reset" class="resetfont" title="Reset text" onclick="ndeSetTextSize('reset'); return false;" type="button">
+  <input value="-a" class="smallerfont" title="Shrink text" onclick="ndeSetTextSize('decr'); return false;" type="button">
+  <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="front-matter">
+<div id="motd-area">
+ This is documentation for development version v0.10-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>
+<li>
+<a href="#forrestbar">ForrestBar</a>
+</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>
+</div>
+
+<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="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_100/howto/../build.html">build
+ Forrest</a> from source.
+ </p>
+<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" rel="nofollow">message</a>
+ explains further and provides other tips about using Windows.
+ </p>
+<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="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="The+Debian+update-alternatives+system"></a>
+<h5>The Debian update-alternatives system</h5>
+<p>If your system uses the alternatives system to manage application binaries and their locations, you may use that to link Forrest into your system's binary directory, instead of explicitly exporting environment variables. To check if your system has the alternatives system installed, execute this command: </p>
+<p>
+<span class="codefrag">update-alternatives --version </span>
+</p>
+<p>Update-alternatives will print its version if it is installed. If so, you may then add an entry for Forrest. Installing an update-alternatives entry may need to be run with root privileges. On some systems, that can be achieved with the "sudo" command, which executes single commands as the super user: for example, Ubuntu's GNU/Linux system uses this feature. Or you may need to contact a system administrator to install. </p>
+<p>To install a Forrest entry, first, gather the path to Forrest's executable, and also note its version. In this example, Forrest has been unpacked and placed into '/opt/Apache/apache-forrest-0.8' (the executable is at bin/forrest). Then execute this command (here we use sudo to execute update-alternatives with root privileges): </p>
+<p>
+<span class="codefrag">sudo update-alternatives --install /usr/bin/forrest forrest '/opt/Apache/apache-forrest-0.8/bin/forrest' 800 </span>
+</p>
+<p>The arguments to this command include '/usr/bin/forrest' as the system's location for the binary link, 'forrest' as the update-alternatives short name for this entry, '/opt/Apache/apache-forrest-0.8/bin/forrest' as the actual binary's location, and '800' as the priority. </p>
+<p>Alternatives entries have a priority because you may install other versions of Forrest, and switch among them using update-alternatives: the highest priority entry will be selected as the default until you explicitly select another one to become active. Here, we have chosen a number based on Forrest's version: version 0.8 is installed, and priority 800 leaves room for adding several other versions; for instance, 0.90 may use priority 900, and 1.0 may be 1000. </p>
+<p>Forrest should now be available on your command line. Execute: <span class="codefrag">forrest --help</span>
+</p>
+<p>Forrest should print its help text. For more help with the alternatives system, use:</p>
+<p>
+<span class="codefrag">update-alternatives --help</span> or <span class="codefrag">man update-alternatives</span>
+</p>
+<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="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>
+<a name="forrestbar"></a>
+<h3 class="underlined_5">ForrestBar</h3>
+<p>
+ Install the
+ <a href="../tools/forrestbar.html">ForrestBar</a>
+ a toolbar extension for the Firefox browser. It provides
+ assisted navigation and search of various Forrest resources.
+ </p>
+</div>
+
+<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="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 style="text-align: center;">
+<img 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="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="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="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 the
+ following example. Warning: The following example might be out-of-date.
+ Obtain a recent configuration file from a new 'forrest seed' site.
+ </p>
+<pre class="code">
+
+
+
+ <!DOCTYPE skinconfig PUBLIC
+ "-//APACHE//DTD Skin Configuration V0.8-2//EN"
+ "skinconfig-v08-2.dtd">
+
+<skinconfig>
+ 
+ <search name="MyProject" domain="example.org"/>
+
+ 
+ <disable-print-link>true</disable-print-link>
+ 
+ <disable-pdf-link>false</disable-pdf-link>
+ 
+ 
+ <disable-xml-link>true</disable-xml-link>
+
+ 
+ <disable-external-link-image>false</disable-external-link-image>
+
+ 
+ <disable-compliance-links>false</disable-compliance-links>
+ 
+ <obfuscate-mail-links>true</obfuscate-mail-links>
+
+ 
+ <project-name>MyProject</project-name>
+ <project-description>MyProject Description</project-description>
+ <project-url>http://example.org/myproj/</project-url>
+ <project-logo>images/project.png</project-logo>
+ 
+
+ 
+ <group-name>MyGroup</group-name>
+ <group-description>MyGroup Description</group-description>
+ <group-url>http://example.org</group-url>
+ <group-logo>images/group.png</group-logo>
+ 
+
+ 
+ <host-url></host-url>
+ <host-logo></host-logo>
+
+ 
+ <favicon-url></favicon-url>
+
+ 
+ <year>2005</year>
+ <vendor>The Acme Software Foundation.</vendor>
+ 
+
+ 
+ <trail>
+ <a1 name="myGroup" href="http://www.apache.org/"/>
+ <a2 name="myProject" href="http://forrest.apache.org/"/>
+ <a3 name="" href=""/>
+ </trail>
+
+ 
+ <toc max-depth="2" min-sections="1" location="page"/>
+
+ 
+ <headings type="boxed"/>
+
+ <extra-css>
+ 
+ p.quote {
+ margin-left: 2em;
+ padding: .5em;
+ background-color: #f0f0f0;
+ font-family: monospace;
+ }
+ </extra-css>
+
+ <colors>
+ 
+ </colors>
+
+ 
+ <pdf>
+ 
+ <page size="letter" orientation="portrait" text-align="left"/>
+
+ 
+ <margins double-sided="false">
+ <top>1in</top>
+ <bottom>1in</bottom>
+ <inner>1.25in</inner>
+ <outer>1in</outer>
+ </margins>
+
+ 
+ <show-external-urls>false</show-external-urls>
+ </pdf>
+
+ 
+ <credits>
+ <credit>
+ <name>Built with Apache Forrest</name>
+ <url>http://forrest.apache.org/</url>
+ <image>images/built-with-forrest-button.png</image>
+ <width>88</width>
+ <height>31</height>
+ </credit>
+ 
+ </credits>
+
+</skinconfig>
+
+ </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="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="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="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_100/linking.html">Menus and Linking</a>.
+ </p>
+<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_100/linking.html#menu_generation">menu generation</a> documentation
+ for more details, and again, consult Forrest's own docs for a usage
+ example.
+ </p>
+<div style="text-align: center;">
+<img 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">
+
+ <tab label="How-Tos" dir="community/howto/"/>
+ <tab label="Apache XML Projects" href="http://xml.apache.org">
+ <tab label="Forrest" href="http://forrest.apache.org/"/>
+ <tab label="Xerces" href="http://xml.apache.org/xerces"/>
+ </tab>
+
+ </pre>
+<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"><figure
+ src="images/project-logo.png" alt="Project Logo"/></span>
+
+</p>
+</div>
+
+<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/" rel="nofollow">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" rel="nofollow">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_100/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_100/sitemap-ref.html">Sitemap Reference</a>
+ for a tour of the default sitemap.
+ </div>
+</div>
+<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">
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE document PUBLIC "-//Acme//DTD Download Documentation V1.0//EN"
+ "dtd/download-v10.dtd">
+<document>
+ <header>
+ <title>Downloading Binaries</title>
+ </header>
+ <body>
+ <section id="download">
+ <title>Downloading binaries</title>
+ <p>
+ Here are the binaries for FooProject
+ </p>
+ <release version="0.9.13" date="2002-10-11">
+ <downloads>
+ <file
+ url="http://prdownloads.sf.net/aft/fooproj-0.9.13-bin.zip?download"
+ name="fooproj-0.9.13-bin.zip"
+ size="5738322"/>
+ <file
+ url="http://prdownloads.sf.net/aft/fooproj-0.9.13-src.zip?download"
+ name="fooproj-0.9.13-src.zip"
+ size="10239777"/>
+ </downloads>
+ </release>
+ <release version="0.9.12" date="2002-10-08">
+ <downloads>
+ <file
+ url="http://prdownloads.sf.net/aft/fooproj-0.9.12-src.zip?download"
+ name="fooproj-0.9.12-src.zip"
+ size="10022737"/>
+ </downloads>
+ </release>
+ </section>
+ <section id="cvs">
+ <title>Getting FooProject from CVS</title>
+ <p>....</p>
+ </section>
+ </body>
+</document>
+ </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">
+<?xml version="1.0" encoding="utf-8"?>
+<xsl:stylesheet
+ version="1.0"
+ xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+
+ <xsl:template match="release">
+ <section id="{@version}">
+ <title>Version <xsl:value-of select="@version"/> (released
+ <xsl:value-of select="@date"/>)</title>
+ <table>
+ <tr><th>File</th><th>Size</th></tr>
+ <xsl:apply-templates select="downloads/*"/>
+ </table>
+ </section>
+ </xsl:template>
+
+ <xsl:template match="file">
+ <tr>
+ <td><a href="{@url}"><xsl:value-of select="@name"/></a></td>
+ <td><xsl:value-of
+ select="format-number(@size div (1024*1024), '##.##')"/> MB</td>
+ </tr>
+ </xsl:template>
+
+ <xsl:template match="@* | node() | comment()">
+ <xsl:copy>
+ <xsl:apply-templates select="@*"/>
+ <xsl:apply-templates/>
+ </xsl:copy>
+ </xsl:template>
+
+</xsl:stylesheet>
+
+ </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_100/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">
+<?xml version="1.0"?>
+<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
+ <map:pipelines>
+ <map:pipeline>
+ ...
+ <strong>
+
+ <map:match pattern="**download.xml">
+ <map:generate src="{properties:content.xdocs}{1}download.xml" />
+ <map:transform src="{properties:resources.stylesheets}/download-to-document.xsl" />
+ <map:serialize type="xml"/>
+ </map:match>
+</strong>
+
+ </map:pipeline>
+ </map:pipelines>
+</map:sitemap>
+
+ </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="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_100/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_100/validation.html">XML Validation</a> for
+ the complete description for those steps.
+ </div>
+</div>
+<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_100/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">
+<?xml version="1.0"?>
+<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
+
+ <map:components>
+ <map:selectors default="parameter">
+ <map:selector logger="sitemap.selector.parameter"
+ name="parameter" src="org.apache.cocoon.selection.ParameterSelector" />
+ </map:selectors>
+ <map:actions>
+ <map:action logger="sitemap.action.sourcetype" name="sourcetype"
+ src="org.apache.forrest.sourcetype.SourceTypeAction">
+ <sourcetype name="download-v1.0">
+ <document-declaration
+ public-id="-//Acme//DTD Download Documentation V1.0//EN" />
+ </sourcetype>
+ <sourcetype name="download-v1.1">
+ <document-declaration
+ public-id="-//Acme//DTD Download Documentation V1.1//EN" />
+ </sourcetype>
+ </map:action>
+ </map:actions>
+ </map:components>
+
+ <map:pipelines>
+ <map:pipeline>
+ <map:match pattern="**download.xml">
+ <map:generate src="{properties:content.xdocs}{1}download.xml" />
+ <map:act type="sourcetype" src="{properties:content.xdocs}{1}download.xml">
+ <map:select type="parameter">
+ <map:parameter name="parameter-selector-test" value="{sourcetype}" />
+ <map:when test="download-v1.0">
+ <map:transform
+ src="{properties:resources.stylesheets}/download-to-document.xsl" />
+ </map:when>
+ <map:when test="download-v1.1">
+ <map:transform
+ src="{properties:resources.stylesheets}/downloadv11-to-document.xsl" />
+ </map:when>
+ </map:select>
+ </map:act>
+ <map:serialize type="xml"/>
+ </map:match>
+ </map:pipeline>
+ </map:pipelines>
+</map:sitemap>
+
+ </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_100/cap.html">SourceTypeAction (content aware
+ pipelines)</a> to detect the doctype. The new download-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="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">
+<?xml version="1.0"?>
+<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
+ <map:pipelines>
+ <map:pipeline><strong>
+
+ <map:match pattern="**weblog.xml">
+ <map:generate src="http://blogs.cocoondev.org/stevenn/index.rss"/>
+ <map:transform src="{forrest:forrest.stylesheets}/rss-to-document.xsl"/>
+ <map:serialize type="xml"/>
+ </map:match>
+</strong>
+
+ <map:match pattern=".......">
+ 
+ </map:match>
+ </map:pipeline>
+ </map:pipelines>
+</map:sitemap>
+
+ </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="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_100/skins.html">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="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="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">
+
+<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+
+ <xsl:import href="lm://transform.skin.common.html.document-to-html"/>
+
+ <strong>... overrides of default templates ...</strong>
+
+</xsl:stylesheet>
+ </pre>
+<p>
+ Notice the use of the <em>lm</em> protocol in the import statement.
+ The <em>lm</em> protocol directs Forrest to use the
+ <a href="../docs_0_100/locationmap.html">locationmap</a> to resolve the
+ location of the indicated stylesheet. If you trace this
+ call through the sitemap, you will find the following section of
+ <span class="codefrag">main/webapp/locationmap-transforms.xml</span>:
+ </p>
+<pre class="code">
+
+ <match pattern="transform.skin.*.*.*">
+ <select>
+ <location src="{properties:skins-dir}/{1}/xslt/{2}/{3}.xsl"/>
+ <location src="{forrest:forrest.context}/skins/{1}/xslt/{2}/{3}.xsl"/>
+ </select>
+ </match>
+
+ </pre>
+<p>
+ This means that the locationmap first checks your project space
+ (according to the <span class="codefrag">${project.skins-dir}</span> property of
+ your <span class="codefrag">forrest.properties</span> file) and, if the file is
+ not found there, it then checks in your installation of Forrest.
+ </p>
+<div class="note">
+<div class="label">Note</div>
+<div class="content">
+ It has been necessary in the past to copy the common skin to
+ your project when creating a custom skin. This is no longer the
+ case.
+ </div>
+</div>
+</div>
+
+<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_100/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="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="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="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"><import></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">
+
+<project name="myproject" default="hello">
+ 
+ <property environment="env"/>
+ <property name="forrest.home" value="${env.FORREST_HOME}"/>
+ <import file="${env.FORREST_HOME}/main/forrest.build.xml"/>
+
+ 
+ <target name="post-build" depends="site">
+ <echo>something here</echo>
+ </target>
+</project>
+
+ </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
+ <import> 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: 1068265 $ $Date: 2011-02-08 15:13:42 +1100 (Tue, 08 Feb 2011) $</span>
+</div>
+
+<div class="clearboth"> </div>
+</div>
+<div id="footer">
+
+<div class="lastmodified">
+<script type="text/javascript"></script>
+</div>
+<div class="copyright">
+ Copyright ©
+ 2002-2011 <a href="http://www.apache.org/licenses/">The Apache Software Foundation. Licensed under Apache License 2.0</a>
+<br>
+ Apache Forrest, Forrest, Apache, the Apache feather logo, and the Apache Forrest
+ logos are trademarks of The Apache Software Foundation.
+ </div>
+
+</div>
+</body>
+</html>

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