blob: 952c6db3d78601ea23c701634419b87079dace58 [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta content="Apache Forrest" name="Generator">
<meta name="Forrest-version" content="0.8-dev">
<meta name="Forrest-skin-name" content="pelt">
<title>Using Forrest (v0.8-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_70/index.html">0.70 (current)</a><a class="selected" href="../docs_0_80/index.html">0.80-dev (under development)</a><a class="unselected" href="../docs_0_60/index.html">0.60 (past)</a>
</div>
<!--+
|end Endtabs
+-->
<script type="text/javascript"><!--
document.write("Last Published: " + document.lastModified);
// --></script>
</div>
<!--+
|breadtrail
+-->
<div class="breadtrail">
&nbsp;
</div>
<!--+
|start Menu, mainarea
+-->
<!--+
|start Menu
+-->
<div id="menu">
<div onclick="SwitchMenu('menu_selected_1.1', '../skin/')" id="menu_selected_1.1Title" class="menutitle" style="background-image: url('../skin/images/chapter_open.gif');">0.80-dev</div>
<div id="menu_selected_1.1" class="selectedmenuitemgroup" style="display: block;">
<div class="menuitem">
<a href="../docs_0_80/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_80/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_80/build.html" title="Build and install the current unreleased version">Building Forrest from Source</a>
</div>
</div>
<div class="menuitem">
<a href="../docs_0_80/upgrading_08.html">Upgrading to 0.8</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_80/sitemap-explain.html">Sitemaps explained</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/howto/howto-custom-html-source.html">Custom html source</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/project-sitemap.html">Project sitemap</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/howto/howto-editcss.html">Edit CSS (WYSIWYG)</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/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_80/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_80/howto/howto-forrest-from-maven.html">Maven Integration</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/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_80/howto/howto-buildPlugin.html">Build a Plugin</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/skin-package.html">Package new Skins</a>
</div>
</div>
<div class="menuitem">
<a href="../docs_0_80/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_80/howto/multi/howto-multi.html">Introduction</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/howto/multi/step1.html">Step 1</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/howto/multi/step2.html">Step 2</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/howto/multi/step3.html">Step 3</a>
</div>
</div>
</div>
</div>
<div class="menuitem">
<a href="../docs_0_80/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_80/linking.html">Menus and Linking</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/searching.html">Search Options in Forrest</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/locationmap.html">Locationmap</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/sitemap-ref.html">Sitemap Reference</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/skins.html" title="About default skins, their naming and features">Skins</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/status-themes.html">Dispatcher versus Skins</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/cap.html">Sourcetype Action</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/validation.html">XML validation and entity resolution</a>
</div>
</div>
<div class="menuitem">
<a href="../docs_0_80/changes.html">Changes</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/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_80/primer.html">Forrest Primer</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/libre-intro.html">Libre</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/dreams.html">Dream list</a>
</div>
<div class="menuitem">
<a href="../docs_0_80/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.8
(<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.8
(<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_80/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_80/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_80/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_80/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_80/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_80/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_80/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_80/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_80/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_80/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_80/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_80/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: 527010 $ $Date: 2007-04-10 13:48:52 +1000 (Tue, 10 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>