You are viewing a plain text version of this content. The canonical link for it is here.
Posted to svn@forrest.apache.org by cr...@apache.org on 2005/04/11 16:59:16 UTC
svn commit: r160895 [24/28] - in forrest/site/0.7: ./ docs/ docs/howto/
docs/images/ docs/plugins/
Added: forrest/site/0.7/docs/primer.html
URL: http://svn.apache.org/viewcvs/forrest/site/0.7/docs/primer.html?view=auto&rev=160895
==============================================================================
--- forrest/site/0.7/docs/primer.html (added)
+++ forrest/site/0.7/docs/primer.html Mon Apr 11 07:58:59 2005
@@ -0,0 +1,1053 @@
+<!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.7-dev">
+<meta name="Forrest-skin-name" content="pelt">
+<meta-data></meta-data>
+<title>The Forrest Primer (v0.7)</title>
+<link type="text/css" href="../skin/basic.css" rel="stylesheet">
+<link media="screen" type="text/css" href="../skin/screen.css" rel="stylesheet">
+<link media="print" type="text/css" href="../skin/print.css" rel="stylesheet">
+<link type="text/css" href="../skin/profile.css" rel="stylesheet">
+<script src="../skin/getBlank.js" language="javascript" type="text/javascript"></script><script src="../skin/getMenu.js" language="javascript" type="text/javascript"></script><script src="../skin/fontsize.js" language="javascript" type="text/javascript"></script>
+<link rel="shortcut icon" href="../favicon.ico">
+</head>
+<body onload="init()">
+<script type="text/javascript">ndeSetTextSize();</script>
+<div id="top">
+<!--+
+ |breadtrail
+ +-->
+<div class="breadtrail">
+<a href="http://www.apache.org/">apache</a> > <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:');" value="Search the site with google:" size="25" name="q" id="query" type="text">
+ <input name="Search" value="Search" type="submit">
+</form>
+</div>
+<!--+
+ |end search
+ +-->
+<!--+
+ |start Tabs
+ +-->
+<ul id="tabs">
+<li>
+<a class="base-not-selected" href="../index.html">Welcome</a>
+</li>
+<li>
+<a class="base-not-selected" href="../contrib.html">Project</a>
+</li>
+<li class="current">
+<a class="base-selected" href="../docs/index.html">0.7 Docs</a>
+</li>
+<li>
+<a class="base-not-selected" href="../docs/howto/index.html">0.7 How-To</a>
+</li>
+</ul>
+<!--+
+ |end Tabs
+ +-->
+</div>
+</div>
+<div id="main">
+<div id="publishedStrip">
+<!--+
+ |start Subtabs
+ +-->
+<div id="level2tabs">
+<a class="base-not-selected" href="..">Core</a> | <a class="base-not-selected" href="..">ForrestBot</a> | <a class="base-not-selected" href="..">ForrestBar</a>
+</div>
+<!--+
+ |end Endtabs
+ +-->
+<script type="text/javascript" language="JavaScript"><!--
+ document.write("Published: " + document.lastModified);
+ // --></script>
+</div>
+<!--+
+ |breadtrail
+ +-->
+<div class="breadtrail">
+
+
+ </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');">Documentation</div>
+<div id="menu_selected_1.1" class="selectedmenuitemgroup" style="display: block;">
+<div class="menuitem">
+<a title="" href="../docs/index.html">Overview</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/faq.html">FAQs</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/changes.html">Changes</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/todo.html">Todo</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/your-project.html">Using Forrest</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/validation.html">XML Validation</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/linking.html">Menus and Linking</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/searching.html">Searching</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/skins.html">Default Skins</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/skin-package.html">Skin Packages</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/plugins/usingPlugins.html">Plugins</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/views.html">Views-dev</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/forrest-contract.html">Our Contract</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/compliance.html">Standards Compliance</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.15', '../skin/')" id="menu_1.1.15Title" class="menutitle">Advanced Topics</div>
+<div id="menu_1.1.15" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs/build.html">Building Forrest</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/catalog.html">Using DTD Catalogs</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/sitemap-ref.html">Sitemap Reference</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/project-sitemap.html">Project sitemap</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/plugins/pluginInfrastructure.html">Plugin Infrastructure</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/cap.html">Sourcetype Action</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.16', '../skin/')" id="menu_1.1.16Title" class="menutitle">Other versions</div>
+<div id="menu_1.1.16" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs.html">Overview</a>
+</div>
+<div class="menuitem">
+<a title="" href="http://forrest.apache.org/docs/../0.8/">0.8-dev</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/index.html">0.7 (current)</a>
+</div>
+<div class="menuitem">
+<a title="" href="http://forrest.apache.org/docs/../0.6/">0.6</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.17', '../skin/')" id="menu_1.1.17Title" class="menutitle">Upgrading</div>
+<div id="menu_1.1.17" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs/upgrading_07.html">Upgrading to 0.7</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/upgrading_06.html">Upgrading to 0.6</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.18', '../skin/')" id="menu_1.1.18Title" class="menutitle">SubProjects</div>
+<div id="menu_1.1.18" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs/forrestbar.html">ForrestBar</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/forrestbot.html">Forrestbot</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/forrestbot-web-interface.html">Forrestbot Webapp</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.19', '../skin/')" id="menu_1.1.19Title" class="menutitle">Reference docs</div>
+<div id="menu_1.1.19" class="menuitemgroup">
+<div onclick="SwitchMenu('menu_1.1.19.1', '../skin/')" id="menu_1.1.19.1Title" class="menutitle">DTD documentation</div>
+<div id="menu_1.1.19.1" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs/dtd-docs.html">Overview</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/document-v20.dtdx.html">document-v20</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/howto-v20.dtdx.html">howto-v20</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/faq-v20.dtdx.html">faq-v20</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/document-v13.dtdx.html">document-v13</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/howto-v13.dtdx.html">howto-v13</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/faq-v13.dtdx.html">faq-v13</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.19.2', '../skin/')" id="menu_1.1.19.2Title" class="menutitle">Doc samples</div>
+<div id="menu_1.1.19.2" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs/document-v13.html">document-v13</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/document-v20.html">document-v20</a>
+</div>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_selected_1.1.20', '../skin/')" id="menu_selected_1.1.20Title" class="menutitle" style="background-image: url('../skin/images/chapter_open.gif');">Older Docs</div>
+<div id="menu_selected_1.1.20" class="selectedmenuitemgroup" style="display: block;">
+<div class="menupage">
+<div class="menupagetitle">Forrest Primer</div>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/libre-intro.html">Libre</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/dreams.html">Dream list</a>
+</div>
+</div>
+</div>
+<div id="credit">
+<hr>
+ This is documentation for current release v0.7
+ (<a href="http://forrest.apache.org/docs.html">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>
+<!--+
+ |end Menu
+ +-->
+<!--+
+ |start content
+ +-->
+<div id="content">
+<div title="Portable Document Format" class="pdflink">
+<a class="dida" href="primer.pdf"><img alt="PDF -icon" src="../skin/images/pdfdoc.gif" class="skin"><br>
+ PDF</a>
+</div>
+<div class="trail">
+ Font size:
+ <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>The Forrest Primer</h1>
+<h3>Don't panic!</h3>
+<div class="abstract">Forrest is a so-called
+ fledgling
+ project that will have a broad impact on
+ xml.apache.org projects. This document
+ helps you to better understand the vision and scope of Forrest, so that you
+ learn what to expect (or not) from it, and eventually will help you discovering
+ places where your contribution could be valuable to all of us.</div>
+<div id="motd-area">
+ This is documentation for current release v0.7
+ (<a href="http://forrest.apache.org/docs.html">More</a> ...)</div>
+<div id="minitoc-area">
+<ul class="minitoc">
+<li>
+<a href="#History">History</a>
+</li>
+<li>
+<a href="#What+is+Forrest">What is Forrest</a>
+</li>
+<li>
+<a href="#Forrest+roles">Forrest roles</a>
+</li>
+<li>
+<a href="#cvs">Getting your local copy of Forrest through CVS</a>
+<ul class="minitoc">
+<li>
+<a href="#System+requirements">System requirements</a>
+</li>
+<li>
+<a href="#Getting+Forrest">Getting Forrest</a>
+</li>
+<li>
+<a href="#Step-by-step+cvs+instructions+for+Windows">Step-by-step cvs instructions for Windows</a>
+</li>
+<li>
+<a href="#Step-by-step+cvs+instructions+for+Unix">Step-by-step cvs instructions for Unix</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#Forrest+distribution">Forrest distribution</a>
+</li>
+<li>
+<a href="#The+Forrest+DTDs">The Forrest DTDs</a>
+</li>
+<li>
+<a href="#sitemap">Forrest site generation using Cocoon</a>
+</li>
+<li>
+<a href="#Where+we+are+heading+to">Where we are heading to</a>
+</li>
+<li>
+<a href="#Where+you+can+help">Where you can help</a>
+</li>
+</ul>
+</div>
+
+<div class="frame warning">
+<div class="label">Warning</div>
+<div class="content">This document is <em>very</em> out of date. There is a lot of good
+ information here, but the focus of the project has shifted away from the
+ Sourceforge-like project management system described here, towards being a
+ simpler project-centric documentation tool -- JT</div>
+</div>
+
+<a name="N10021"></a><a name="History"></a>
+<h2 class="underlined_10">History</h2>
+<div class="section">
+<p>Forrest has come into existence because of the abysmal state of the
+ <a href="http://xml.apache.org/">xml.apache.org</a> website in comparison
+ with other open source community sites such as Sourceforge. The old site had no
+ consistent visual look and feel, which was largely due to each and every
+ sub-project managing its own site. Furthermore, much information which could
+ potentially support community-based open source development was hidden inside
+ CVS repositories, mailing lists or word of mouth. Once we experienced the
+ usefullness of cross-project collaboration supported by the Jakarta
+ <a href="http://jakarta.apache.org/gump">Gump</a> project, we reckoned
+ having a single application responsible for the management of the
+ xml.apache.org site could be of benefit to our visitors. And if we added
+ aggregated access to other available resources such as download stats or
+ mailing list archives, the new xml.apache.org website could be a true
+ information clearinghouse for interested parties, both users and contributors
+ alike.</p>
+<p>The Forrest vision was articulated by Stefano Mazzocchi and Sam Ruby,
+ both long-time contributors to Apache projects, in the beginning of 2002, and
+ was rapidly picked up by a bunch of other
+ <a href="http://forrest.apache.org/who.html">contributors</a> as well, after a headstart by Nicola Ken
+ Barozzi. So here we are, plenty of work-in-progress to erect what eventually
+ will become a true community website infrastructure for Apache open source
+ development.</p>
+</div>
+
+<a name="N1003A"></a><a name="What+is+Forrest"></a>
+<h2 class="underlined_10">What is Forrest</h2>
+<div class="section">
+<p>Forrest is a framework that supports the cross-project generation and
+ management of development project websites using Cocoon as its XML publishing
+ framework. It not only provides access to project documentation, but also to
+ other types of information that open source developers depend upon daily:
+ source code repositories, mailing lists, contact info and the like. It
+ aggregates all these resources and publishes them on a regular basis to a
+ website, ensuring a consistent look and feel using skins implemented with XSLT
+ stylesheets. While Forrest's primary focus is XML Apache project websites, it
+ can be adapted to other community development projects as well, as long as they
+ are willing to commit to proven best practices such as Ant for build
+ automation, CVS for source code control and XML as a documentation source
+ format.</p>
+<p>Forrest is currently based on an
+ <a href="http://jakarta.apache.org/ant/">Ant</a>-based project build
+ system called <a href="http://www.krysalis.org/centipede/">Centipede</a>
+ that drives a <a href="http://cocoon.apache.org/">Cocoon</a>-based
+ document publication system. It contains a set of standard XML document type
+ declarations (DTDs) for project documentation, and different 'skins' consisting
+ of XSLT stylesheets that produce HTML renditions of XML documents using these
+ DTDs.</p>
+<p>The primary mode of operations for Forrest will be as follows:</p>
+<div class="frame note">
+<div class="label">Note</div>
+<div class="content">This process is not quite ready for prime time yet, but it gives
+ you an idea where we are heading to. Website generation with skins currently
+ works, try using the <span class="codefrag">docs</span> target when invoking the
+ <span class="codefrag">build</span> script. Add a <span class="codefrag">project.skin</span> property when invoking
+ the build script to experience Forrest skins: <span class="codefrag">build{.bat|.sh}
+ -Dproject.skin=<thenameoftheskintouse> docs</span>. Read our
+ <a href="#cvs">CVS crash course</a> to get hold of the current codebase and
+ start playing with it.</div>
+</div>
+<ol>
+
+<li>Forrest will harvest documentation and related source files from
+ each of the projects within the community that uses Forrest for their website,
+ usually direct from the CVS repository. Which projects are included, and how
+ they are retrieved is configured by a project descriptor file. This is an
+ automated process that occurs several times a day to ensure Forrest has the
+ latest information available.</li>
+
+<li>Forrest then uses Cocoon to generate an HTML rendition of each
+ project's website, configured by a generic sitemap. The result is a static
+ collection of HTML documents and related images and stylesheets comprising the
+ project's website. The impact Forrest has on the participating projects should
+ be minimal, i.e. one should simply author XML documents, put them in a
+ well-specified filesystem hierarchy, and Forrest will do its work.</li>
+
+<li>Forrest will enrich the documentation source files with common
+ information: a cross-project navigation structure (and rendition, of course),
+ and useful 'community indicators' such as download statistics, number of
+ contributors with commit access, ...</li>
+
+<li>If the individual project build runs are successful, the project's
+ website is automagically (re-)published to the (Apache) website, also several
+ times day.</li>
+
+</ol>
+<p>The Forrest website and the overall xml.apache.org website are
+ maintained and published using the same mechanism.</p>
+</div>
+
+<a name="N1007B"></a><a name="Forrest+roles"></a>
+<h2 class="underlined_10">Forrest roles</h2>
+<div class="section">
+<p>Depending on your interests, your involvement with Forrest may vary,
+ hence your <em>role</em>. We currently envision three different roles:</p>
+<ul>
+
+<li>
+<strong>User</strong> you want or need to use Forrest for your
+ project because it uses Forrest to manage its documentation.</li>
+
+<li>
+<strong>Adaptor</strong> you want to adapt Forrest to support your
+ individual project needs, presumably outside the XML Apache context, building
+ your own skins or DTDs and the like.</li>
+
+<li>
+<strong>Contributor</strong> you are a fledgling Forresteer and
+ want to contribute to the further development of it. If your contributions are
+ valuable and in true community spirit, you can possibly gain commit access to
+ the Forrest CVS repository and become an Apache committer. The first stage
+ towards becoming a contributor is to join the forrest dev
+ <a href="http://forrest.apache.org/mail-lists.html">mailing list</a>, the second is to download
+ Forrest and start playing with it (see below).</li>
+
+</ul>
+<p>Depending on your role, your potential area of interest in Forrest
+ will vary:</p>
+<table class="ForrestTable" cellspacing="1" cellpadding="4">
+
+<tr>
+
+<th colspan="1" rowspan="1">Role</th>
+ <th colspan="1" rowspan="1">Interests</th>
+
+</tr>
+
+<tr>
+
+<td colspan="1" rowspan="1">User</td>
+ <td colspan="1" rowspan="1">Forrest DTDs and documentation filesystem hierarchy (Cocoon
+ sitemap)</td>
+
+</tr>
+
+<tr>
+
+<td colspan="1" rowspan="1">Adaptor</td>
+ <td colspan="1" rowspan="1">+ skin system and build environment</td>
+
+</tr>
+
+<tr>
+
+<td colspan="1" rowspan="1">Contributor</td>
+ <td colspan="1" rowspan="1">+ the Forrest codebase and runtime environment</td>
+
+</tr>
+
+</table>
+</div>
+
+<a name="N100D8"></a><a name="cvs"></a>
+<h2 class="underlined_10">Getting your local copy of Forrest through CVS</h2>
+<div class="section">
+<a name="N100DE"></a><a name="System+requirements"></a>
+<h3 class="underlined_5">System requirements</h3>
+<p>Forrest requires the following systems to be already installed on
+ your system:</p>
+<ul>
+
+<li>
+<em>Java Virtual Machine</em> A Java virtual machine must be
+ present. Forrest has been tested against the latest Sun 1.3 JDK.</li>
+
+</ul>
+<a name="N100F0"></a><a name="Getting+Forrest"></a>
+<h3 class="underlined_5">Getting Forrest</h3>
+<p>You can retrieve Forrest from its CVS repository or download
+ <a href="http://www.apache.org/dyn/closer.cgi/xml/forrest/">here</a>.
+ <br>Some help with CVS follows (courtesy of our friends of the Cocoon project).</p>
+<a name="N10100"></a><a name="Step-by-step+cvs+instructions+for+Windows"></a>
+<h3 class="underlined_5">Step-by-step cvs instructions for Windows</h3>
+<ol>
+
+<li>Download a recent release of WinCVS (homepage is
+ <a href="http://www.wincvs.org/">http://www.wincvs.org/</a>); </li>
+
+<li>Install it;</li>
+
+<li>Start it;</li>
+
+<li>Click on Admin->Preferences;</li>
+
+<li> In "Enter the CVSROOT:" enter
+ "<span class="codefrag">:pserver:anoncvs@cvs.apache.org:/home/cvspublic</span>" (without
+ quotes);</li>
+
+<li>In "Authentication:" choose "passwd file on the cvs server";</li>
+
+<li>Click "Ok";</li>
+
+<li>Click Admin->Login;</li>
+
+<li> When asked for the password: answer "<span class="codefrag">anoncvs</span>"
+ (without quotes);</li>
+
+<li> Click "Create->Checkout module";</li>
+
+<li>Module name and path on the server is "<span class="codefrag">xml-forrest</span>"
+ (no quotes);</li>
+
+<li>Choose a dir to put the source code in;</li>
+
+<li>Click "Ok";</li>
+
+<li>If everything goes well, messages will start to appear in the log
+ window;</li>
+
+<li>Wait until you see "<span class="codefrag">*****CVS exited normally with code
+ 0*****</span>" in the log window;</li>
+
+<li>The Forrest source is now on your harddrive.</li>
+
+</ol>
+<a name="N1014A"></a><a name="Step-by-step+cvs+instructions+for+Unix"></a>
+<h3 class="underlined_5">Step-by-step cvs instructions for Unix</h3>
+<ol>
+
+<li>Make sure you have a CVS client package installed on your Unix
+ system.</li>
+
+<li>Start the shell of your choice.</li>
+
+<li>Enter "<span class="codefrag">cvs -d
+ :pserver:anoncvs@cvs.apache.org:/home/cvspublic login</span>".</li>
+
+<li>When asked for the password: answer "<span class="codefrag">anoncvs</span>".</li>
+
+<li>Enter "<span class="codefrag">cvs -d
+ :pserver:anoncvs@cvs.apache.org:/home/cvspublic -z3 checkout
+ xml-forrest</span>". This will create a directory called
+ "<span class="codefrag">xml-forrest</span>" where the Forrest source will be stored.</li>
+
+<li>Wait until cvs has finished.</li>
+
+<li>The Forrest source is now on your harddrive.</li>
+
+</ol>
+<p>In case you want to update your Forrest source tree to the current
+ version, change to the "<span class="codefrag">xml-forrest</span>" directory and invoke
+ "<span class="codefrag">cvs -z3 update -d -P</span>".</p>
+</div>
+
+<a name="N1017F"></a><a name="Forrest+distribution"></a>
+<h2 class="underlined_10">Forrest distribution</h2>
+<div class="section">
+<p>Once you retrieved Forrest from its CVS repository, you will end up
+ with a filesystem hierarchy similar to this inside the <span class="codefrag">xml-forrest</span>
+ home directory:</p>
+<div class="frame warning">
+<div class="label">Warning</div>
+<div class="content">This is highly volatile information!</div>
+</div>
+<pre class="code">+---legal various licenses for included projects
++---lib jar library
++---src
+| +---documentation Forrest's documentation (not generally reusable)
+| | +---content content of the Forrest website
+| | | +---xdocs Forrest website XML documents
+| | +---resources Forrest-specific doc resources
+| | | +---images
+| +---resources Generic resources for any Forrest-using project.
+| | +---conf Default (overridable) Forrest config files
+| | +---library common components (not skin-specific)
+| | | +---xslt document format transformers e.g. faq->xdoc
+| | +---convert XSLTs for aiding a transition to Forrest
+| | +---skins Forrest skins
+| | +---basic
+| | +---forrest-site the future xml.apache.org skin
+| | | +---css Cascading Stylesheets
+| | | +---images skin-specific images
+| | | +---xslt the skin stylesheets (per medium)
+| | | +---fo
+| | | +---html html rendering skins
+| | +---jakarta-site
+| | +---scarab-site
+| | +---xml-apache-site
+| | +---schema Generic Forrest DTDs
+| | +---dtd
+| | +---relaxng
+| | +---entity
+| | +---images Reusable skin-agnostic images
+| | +---fresh-site A template project structure
+| | +---forrest-shbat 'shbat' Forrest distribution files
+| | +---forrestbot Ant-based Forrest deployment tool
+| | +---forrestbar Mozilla Forrest toolbar
+| | +---charts charting trials
+| | +---layout HTML page mock-ups
+| | | +---resources
+| | | +---xml.apache.org
+| | | +---images
+|
++---tools Tools used to build Forrest
+ +---ant Ant 1.6-dev scripts and jars
++---stylesheets Stylesheets used for project root XML files
+</pre>
+<p>The <span class="codefrag">xml-forrest</span> home directory consists of the main Ant
+ build script (<span class="codefrag">build.xml</span>) and platform-specific batch files/shell
+ scripts to invoke it. Forrest comes with Ant included, so you do not need to
+ install Ant separately.</p>
+<p>Running Forrest is a batch operation you can start using the provided
+ <span class="codefrag">build.{sh|bat} <targetname></span>. The current main targets
+ are:</p>
+<ul>
+
+<li>
+<strong><span class="codefrag">docs</span></strong> - generates an HTML rendition of
+ the Forrest website using the default <span class="codefrag">forrest-site</span> skin</li>
+
+<li>
+<strong><span class="codefrag">clean</span></strong> - cleans out the
+ <span class="codefrag">build</span> directory</li>
+
+<li>
+<strong><span class="codefrag">webapp</span></strong> - for those who cannot resist
+ running Forrest live instead of its commandline invocation, this target builds
+ a WAR file you can deploy in your servlet container (currently only tested for
+ Tomcat 4.0.1). Mount-point of the web application will be
+ <span class="codefrag">xml-forrest</span>.</li>
+
+</ul>
+<p>After a build run, Forrest creates a <span class="codefrag">build</span> directory. You
+ can find the generated website in the <span class="codefrag">build/xml-forrest/docs/</span>
+ directory. Forrest also creates a <span class="codefrag">tools/tmp/anttasks/</span> upon its
+ first invocation. These are Centipede-specific compiled Ant tasks.</p>
+</div>
+
+<a name="N101CC"></a><a name="The+Forrest+DTDs"></a>
+<h2 class="underlined_10">The Forrest DTDs</h2>
+<div class="section">
+<p>Forrest is the reference repository for the XML Apache documentation
+ DTDs. Special care is taken to provide a set of modular, extensible and
+ well-maintained DTDs for project documentation purposes. This modularity is
+ ensured using the
+ <a href="http://www.oasis-open.org/committees/entity/">OASIS catalog</a>
+ mechanism, extensive use of external parameter entities and an entity resolver
+ capable of resolving entities through the aforementioned catalog mechanism. For
+ the docheads amongst us, this means we adhere to the strict use of
+ <span class="codefrag">PUBLIC</span> entity identifiers both in document instances and DTD
+ modules.</p>
+<p>We have currently identified the following document types:</p>
+<ul>
+
+<li>General documents (<span class="codefrag">document-v11.dtd</span>),</li>
+
+<li>How-Tos (<span class="codefrag">howto-v10.dtd</span>),</li>
+
+<li>Collections of FAQs (<span class="codefrag">faq-v11.dtd)</span>.</li>
+
+</ul>
+<p>Some work is also under its way for other document types, in close
+ collaboration with the Cocoon project. You will also find some older document
+ types such as <span class="codefrag">changes</span>, <span class="codefrag">javadoc</span>,
+ <span class="codefrag">specification</span> and <span class="codefrag">todo</span>, which are currently under
+ consideration for automatic generation and maintenance using Gump or Centipede
+ descriptors and the like. DTDs will be subject of serious version management as
+ soon as Forrest has a 1.0 release: they are made to depend upon.</p>
+<p>The DTDs are located in <span class="codefrag">src/resources/schema/dtd</span> and also
+ refer to some character entity collections stored in the
+ <span class="codefrag">src/resources/schema/entity</span> directory. These are referred to by
+ the declarations found in the <span class="codefrag">src/resources/schema/catalog</span> OASIS
+ Catalog file. Take special care using the correct <span class="codefrag">PUBLIC</span>
+ identifiers in the DTD declaration of your instances:</p>
+<pre class="code"><?xml version="1.0"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://apache.org/forrest/dtd/document-v12.dtd">
+<document>
+ ...
+ </pre>
+<p>The exact local location of the DTD for validation purposes is
+ obtained by the entity resolver evaluating the mapping scheme as defined in the
+ <span class="codefrag">catalog</span> file. This makes sure that you can move and re-arrange
+ your document instances apart from your DTD files. Later on, the DTDs will be
+ web-accessible from the Forrest website for your perusal.</p>
+</div>
+
+<a name="N1021D"></a><a name="sitemap"></a>
+<h2 class="underlined_10">Forrest site generation using Cocoon</h2>
+<div class="section">
+<p>The <span class="codefrag">docs</span> target of the Forrest build environment invokes
+ Cocoon as a command-line application to generate an HTML rendition of the
+ project's documentation. It is not within the scope of this document to explain
+ the Cocoon internals, please read its own
+ <a href="http://cocoon.apache.org/">documentation</a> to fully
+ understand the power of Cocoon.</p>
+<p>Cocoon's site rendition behaviour is configured in a so-called
+ <em>sitemap</em>, a switchboard that binds URLs to an XML processing pipeline.
+ This pipeline typically consists of a Generator, one or more Transformers and a
+ Serializer. Forrest also makes use of Cocoon's aggregation capabilities that
+ merge multiple pipelines into one resulting output document.</p>
+<p>A typical page generated using Forrest looks like this:</p>
+<div style="text-align: center;">
+<img class="figure" alt="Pages areas" src="images/page-areas.png" height="291" width="336"></div>
+<p>This page is currently composed of two XML sources which are
+ transformed by a different XSLT stylesheet, aggregated by Cocoon with a
+ post-aggregation stylesheet adding the overall page grid and look & feel.
+ This simple example is handled by the following <em>sitemap</em> snippets
+ (<span class="codefrag">src/documentation/conf/sitemap.xmap</span>):</p>
+<pre class="code"><map:match pattern="*.html">
+ <map:aggregate element="site">
+ <map:part src="cocoon:/book-{1}.xml"/>
+ <map:part src="cocoon:/body-{1}.xml" label="content"/>
+ </map:aggregate>
+ <map:call resource="skinit">
+ <map:parameter name="type" value="site2xhtml"/>
+ </map:call>
+</map:match></pre>
+<pre class="code"><map:match pattern="**book-**.xml">
+ <map:generate src="content/xdocs/{1}book.xml"/>
+ <map:call resource="skinit">
+ <map:parameter name="type" value="book2menu"/>
+ </map:call>
+</map:match></pre>
+<pre class="code"><map:match pattern="body-**.xml">
+ <map:generate src="content/xdocs/{1}.xml"/>
+ <map:call resource="skinit">
+ <map:parameter name="type" value="document2html"/>
+ </map:call>
+</map:match></pre>
+<pre class="code"><map:resource name="skinit">
+ <map:transform src="skins/@skin@/xslt/html/{type}.xsl">
+ <map:parameter name="isfaq" value="{isfaq}"/>
+ </map:transform>
+ <map:serialize/>
+</map:resource></pre>
+<p>When an URL (e.g.
+ <span class="codefrag">http://forrest.apache.org/index.html</span>) is passed through the
+ Cocoon system to generate the required page, the pipeline flow is basically as
+ follows:</p>
+<ol>
+
+<li>The URL is matched by the <span class="codefrag">*.html</span> pattern</li>
+
+<li>Cocoon responds by aggregating two 'sub-requests'. The first is for
+ the resource <span class="codefrag">book-{1}.xml</span>, the second is for the resource
+ <span class="codefrag">body-{1}.xml</span>. The <span class="codefrag">{1}</span> parameter is replaced by the
+ values of the first wildcard in the matching pattern above. These
+ 'sub-requests' are passed through the Cocoon pipeline just like any other
+ request. This results in the following flow:</li>
+
+<ol>
+
+<li>The first 'sub-request' (for <span class="codefrag">book-index.xml</span> is matched
+ by the <span class="codefrag">**book-**.xml</span> pattern. This results in the file
+ <span class="codefrag">content/xdocs/book.xml</span> being read. This document is then run
+ through the <span class="codefrag">book2menu</span> stylesheet (which produces an HTML fragment
+ comprising the site navigation, the red area in the image above.</li>
+
+<li>The second 'sub-request' is matched by the <span class="codefrag">body-**.xml</span>
+ pattern. This results in the file <span class="codefrag">index.xml</span> being transformed
+ using the <span class="codefrag">document2html</span> stylesheet, the yellow area in the
+ screenshot.</li>
+
+</ol>
+
+<li>The aggregation result is then transformed using the
+ <span class="codefrag">site2xhtml</span> stylesheet which adds the cherries to the cake. The
+ grey zone.</li>
+
+</ol>
+<p>These <em>skin-specific</em> stylesheets are located in
+ <span class="codefrag">src/documentation/skins/<nameoftheskin>/xslt/html</span>, so if you
+ want to add your own skin, this is the place to be. Apart from these, there
+ exist a number of other stylesheets located in
+ <span class="codefrag">src/documentation/library/xslt</span> and more importantly:</p>
+<ul>
+
+<li>
+<span class="codefrag">faq2document</span>: transforms documents following the
+ <span class="codefrag">faq-v11</span> DTD to <span class="codefrag">document-v11</span> grammar</li>
+
+<li>
+<span class="codefrag">howto2document</span>: transforms documents following the
+ <span class="codefrag">howto-v10</span> DTD to <span class="codefrag">document-v11</span> grammar</li>
+
+<li>and some others.</li>
+
+</ul>
+<p>As you see, all documents, regardless of their original DTD, are
+ transformed to the <span class="codefrag">document</span> DTD prior to rendition. This
+ alleviates the burden of adding new skins to implementing 3 simple stylesheets:
+ <span class="codefrag">book2menu</span>, <span class="codefrag">document2html</span> and
+ <span class="codefrag">site2xhtml</span>.</p>
+</div>
+
+<a name="N102CC"></a><a name="Where+we+are+heading+to"></a>
+<h2 class="underlined_10">Where we are heading to</h2>
+<div class="section">
+<p>We have been explaining so far where we are now and what already
+ works. The purpose of this document however is to attract newcomers and entice
+ them to start contributing to Forrest. We have a decent generation system for
+ static project documentation, a nice set of skins and some simple but effective
+ DTDs. Our goals however are much more ambitious: we have compiled a
+ <a href="../docs/dreams.html">dream list</a> that lists most of them.</p>
+<ul>
+
+<li>Our first ambition is to support the project site generation and
+ maintenance of other Apache projects in an automated manner, starting with our
+ own website as a showcase. We are in the process of setting up the shell
+ scripts and Ant tasks for this and will assist projects transitioning to
+ Forrest.</li>
+
+<li>As it is often the case with collaborative open source development,
+ there is no formal planning nor task assignments, and we will stick to that
+ practice. We have however compiled a number of functional work areas:</li>
+
+</ul>
+<table class="ForrestTable" cellspacing="1" cellpadding="4">
+
+<tr>
+
+<th colspan="1" rowspan="1">URI Namespace Management</th>
+ <td colspan="1" rowspan="1">Forrest will offer access to a broad set of information resources
+ using durable URIs: please review
+ <a href="http://www.w3.org/Provider/Style/URI.html">Tim Berners-Lee</a>'s
+ and <a href="http://www.useit.com/alertbox/990321.html">Jakob
+ Nielsen</a>'s opinion on this. We need a unified URI Namespace management
+ approach, bearing in mind mirroring and 'hackable' URIs.</td>
+
+</tr>
+
+<tr>
+
+<th colspan="1" rowspan="1">Skins</th>
+ <td colspan="1" rowspan="1">We currently have a nice set of skins which should be solidified.
+ Furthermore, we need some serious finetuning of the <span class="codefrag">forrest-site</span>
+ skin that will become the new xml.apache.org look&feel.</td>
+
+</tr>
+
+<tr>
+
+<th colspan="1" rowspan="1">Aggregation<br>and Syndication</th>
+ <td colspan="1" rowspan="1">We plan to aggregate on a per-project basis a number of relevant
+ developer resources, such as project-related news, download statistics,
+ committer bio pages (with photos!), navigable source code listings and the
+ like. Some of these resources need to be made available across content
+ syndication methods such as
+ <a href="http://blogspace.com/rss/">RSS</a>.</td>
+
+</tr>
+
+<tr>
+
+<th colspan="1" rowspan="1">Build Management</th>
+ <td colspan="1" rowspan="1">Fool-proof automation of Forrest runs and site publication using
+ secure transfer methods and <span class="codefrag">cron</span> jobs.</td>
+
+</tr>
+
+<tr>
+
+<th colspan="1" rowspan="1">Document Types</th>
+ <td colspan="1" rowspan="1">Expanding the collection of DTDs, documenting them using formal
+ How-Tos and example documents.</td>
+
+</tr>
+
+<tr>
+
+<th colspan="1" rowspan="1">xml.apache.org</th>
+ <td colspan="1" rowspan="1">Formation of an editorial team for the main xml.apache.org website,
+ working in close collaboration with the
+ <a href="http://xml.apache.org/whoweare.html">PMC</a> and the different
+ sub-project leads.</td>
+
+</tr>
+
+<tr>
+
+<th colspan="1" rowspan="1">Integration</th>
+ <td colspan="1" rowspan="1"> Forrest needs to coexist with existing cross-project collaboration
+ tools such as <a href="http://gump.apache.org/">Gump</a>,
+ <a href="http://scarab.tigris.org/">Scarab</a> and
+ <a href="http://eyebrowse.tigris.org/">Eyebrowse</a> and provide
+ integrated access to them.</td>
+
+</tr>
+
+<tr>
+
+<th colspan="1" rowspan="1">Authoring support</th>
+ <td colspan="1" rowspan="1">Supporting document authors with preconfigured XML editing
+ solutions.</td>
+
+</tr>
+
+<tr>
+
+<th colspan="1" rowspan="1">Content Management</th>
+ <td colspan="1" rowspan="1">Establish an efficient content management practice, supporting
+ versioning, remote access and work flow, presumably supported by a CMS such as
+ <a href="http://jakarta.apache.org/slide/">Slide</a>.</td>
+
+</tr>
+
+<tr>
+
+<th colspan="1" rowspan="1">Information Accessibility</th>
+ <td colspan="1" rowspan="1">We need to be accessible using a wide range of browsing devices
+ operating on different platforms. Special care should be taken to support the
+ <a href="http://www.w3.org/WAI/">WAI</a> guidelines.</td>
+
+</tr>
+
+</table>
+</div>
+
+<a name="N10394"></a><a name="Where+you+can+help"></a>
+<h2 class="underlined_10">Where you can help</h2>
+<div class="section">
+<p>By now, you should have a better understanding of Forrest (if that is
+ not the case, consider contributing clarifications to this document).
+ We need more people to get the job done.
+ Forrest is a fun project to work on, and there is something in it for
+ all of us:</p>
+<ul>
+
+<li>XML docheads with skills for document analysis and DTDs
+ development</li>
+
+<li>Cocoon developers creating custom Cocoon components connecting
+ Forrest with external resources</li>
+
+<li>Graphical whizzkids for true cross-browser HTML/CSS
+ development</li>
+
+<li>People who believe XSLT will bring peace to earth (it will, but
+ keep that quiet)</li>
+
+<li>Ant wizards able to compete with Nicola and Stefan</li>
+
+<li>Unix shell scripting / CVS / cron gurus, preferably bearded</li>
+
+</ul>
+<p>Just drop us a line at
+ the forrest-dev <a href="http://forrest.apache.org/mail-lists.html">mail list</a>.
+ </p>
+</div>
+
+<p>That is all, folks.</p>
+
+<table class="ForrestTable" cellspacing="1" cellpadding="4">
+
+<tr>
+
+<th colspan="1" rowspan="1">Revision history</th>
+ <th colspan="1" rowspan="1"></th>
+
+</tr>
+
+<tr>
+
+<td colspan="1" rowspan="1">2002-05-22</td>
+ <td colspan="1" rowspan="1">Initial version, Steven Noels, stevenn.at.apache.org</td>
+
+</tr>
+
+<tr>
+
+<td colspan="1" rowspan="1">2002-05-23</td>
+ <td colspan="1" rowspan="1">Various rephrasings and clarifications thanks to Ross Gardler,
+ ross.at.saafe.org</td>
+
+</tr>
+
+<tr>
+
+<td colspan="1" rowspan="1">2002-09-23</td>
+ <td colspan="1" rowspan="1">Updated the directory outline (jefft.at.apache.org)</td>
+
+</tr>
+
+</table>
+
+</div>
+<!--+
+ |end content
+ +-->
+<div class="clearboth"> </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 © 2002-2005 The Apache Software Foundation.</div>
+<!--+
+ |end bottomstrip
+ +-->
+</div>
+</body>
+</html>
Propchange: forrest/site/0.7/docs/primer.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/0.7/docs/primer.pdf
URL: http://svn.apache.org/viewcvs/forrest/site/0.7/docs/primer.pdf?view=auto&rev=160895
==============================================================================
Binary file - no diff available.
Propchange: forrest/site/0.7/docs/primer.pdf
------------------------------------------------------------------------------
svn:mime-type = application/pdf
Added: forrest/site/0.7/docs/project-sitemap.html
URL: http://svn.apache.org/viewcvs/forrest/site/0.7/docs/project-sitemap.html?view=auto&rev=160895
==============================================================================
--- forrest/site/0.7/docs/project-sitemap.html (added)
+++ forrest/site/0.7/docs/project-sitemap.html Mon Apr 11 07:58:59 2005
@@ -0,0 +1,391 @@
+<!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.7-dev">
+<meta name="Forrest-skin-name" content="pelt">
+<meta-data></meta-data>
+<title>Using project sitemaps (v0.7)</title>
+<link type="text/css" href="../skin/basic.css" rel="stylesheet">
+<link media="screen" type="text/css" href="../skin/screen.css" rel="stylesheet">
+<link media="print" type="text/css" href="../skin/print.css" rel="stylesheet">
+<link type="text/css" href="../skin/profile.css" rel="stylesheet">
+<script src="../skin/getBlank.js" language="javascript" type="text/javascript"></script><script src="../skin/getMenu.js" language="javascript" type="text/javascript"></script><script src="../skin/fontsize.js" language="javascript" type="text/javascript"></script>
+<link rel="shortcut icon" href="../favicon.ico">
+</head>
+<body onload="init()">
+<script type="text/javascript">ndeSetTextSize();</script>
+<div id="top">
+<!--+
+ |breadtrail
+ +-->
+<div class="breadtrail">
+<a href="http://www.apache.org/">apache</a> > <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:');" value="Search the site with google:" size="25" name="q" id="query" type="text">
+ <input name="Search" value="Search" type="submit">
+</form>
+</div>
+<!--+
+ |end search
+ +-->
+<!--+
+ |start Tabs
+ +-->
+<ul id="tabs">
+<li>
+<a class="base-not-selected" href="../index.html">Welcome</a>
+</li>
+<li>
+<a class="base-not-selected" href="../contrib.html">Project</a>
+</li>
+<li class="current">
+<a class="base-selected" href="../docs/index.html">0.7 Docs</a>
+</li>
+<li>
+<a class="base-not-selected" href="../docs/howto/index.html">0.7 How-To</a>
+</li>
+</ul>
+<!--+
+ |end Tabs
+ +-->
+</div>
+</div>
+<div id="main">
+<div id="publishedStrip">
+<!--+
+ |start Subtabs
+ +-->
+<div id="level2tabs">
+<a class="base-not-selected" href="..">Core</a> | <a class="base-not-selected" href="..">ForrestBot</a> | <a class="base-not-selected" href="..">ForrestBar</a>
+</div>
+<!--+
+ |end Endtabs
+ +-->
+<script type="text/javascript" language="JavaScript"><!--
+ document.write("Published: " + document.lastModified);
+ // --></script>
+</div>
+<!--+
+ |breadtrail
+ +-->
+<div class="breadtrail">
+
+
+ </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');">Documentation</div>
+<div id="menu_selected_1.1" class="selectedmenuitemgroup" style="display: block;">
+<div class="menuitem">
+<a title="" href="../docs/index.html">Overview</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/faq.html">FAQs</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/changes.html">Changes</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/todo.html">Todo</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/your-project.html">Using Forrest</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/validation.html">XML Validation</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/linking.html">Menus and Linking</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/searching.html">Searching</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/skins.html">Default Skins</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/skin-package.html">Skin Packages</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/plugins/usingPlugins.html">Plugins</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/views.html">Views-dev</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/forrest-contract.html">Our Contract</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/compliance.html">Standards Compliance</a>
+</div>
+<div onclick="SwitchMenu('menu_selected_1.1.15', '../skin/')" id="menu_selected_1.1.15Title" class="menutitle" style="background-image: url('../skin/images/chapter_open.gif');">Advanced Topics</div>
+<div id="menu_selected_1.1.15" class="selectedmenuitemgroup" style="display: block;">
+<div class="menuitem">
+<a title="" href="../docs/build.html">Building Forrest</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/catalog.html">Using DTD Catalogs</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/sitemap-ref.html">Sitemap Reference</a>
+</div>
+<div class="menupage">
+<div class="menupagetitle">Project sitemap</div>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/plugins/pluginInfrastructure.html">Plugin Infrastructure</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/cap.html">Sourcetype Action</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.16', '../skin/')" id="menu_1.1.16Title" class="menutitle">Other versions</div>
+<div id="menu_1.1.16" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs.html">Overview</a>
+</div>
+<div class="menuitem">
+<a title="" href="http://forrest.apache.org/docs/../0.8/">0.8-dev</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/index.html">0.7 (current)</a>
+</div>
+<div class="menuitem">
+<a title="" href="http://forrest.apache.org/docs/../0.6/">0.6</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.17', '../skin/')" id="menu_1.1.17Title" class="menutitle">Upgrading</div>
+<div id="menu_1.1.17" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs/upgrading_07.html">Upgrading to 0.7</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/upgrading_06.html">Upgrading to 0.6</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.18', '../skin/')" id="menu_1.1.18Title" class="menutitle">SubProjects</div>
+<div id="menu_1.1.18" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs/forrestbar.html">ForrestBar</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/forrestbot.html">Forrestbot</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/forrestbot-web-interface.html">Forrestbot Webapp</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.19', '../skin/')" id="menu_1.1.19Title" class="menutitle">Reference docs</div>
+<div id="menu_1.1.19" class="menuitemgroup">
+<div onclick="SwitchMenu('menu_1.1.19.1', '../skin/')" id="menu_1.1.19.1Title" class="menutitle">DTD documentation</div>
+<div id="menu_1.1.19.1" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs/dtd-docs.html">Overview</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/document-v20.dtdx.html">document-v20</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/howto-v20.dtdx.html">howto-v20</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/faq-v20.dtdx.html">faq-v20</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/document-v13.dtdx.html">document-v13</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/howto-v13.dtdx.html">howto-v13</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/faq-v13.dtdx.html">faq-v13</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.19.2', '../skin/')" id="menu_1.1.19.2Title" class="menutitle">Doc samples</div>
+<div id="menu_1.1.19.2" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs/document-v13.html">document-v13</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/document-v20.html">document-v20</a>
+</div>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.20', '../skin/')" id="menu_1.1.20Title" class="menutitle">Older Docs</div>
+<div id="menu_1.1.20" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs/primer.html">Forrest Primer</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/libre-intro.html">Libre</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/dreams.html">Dream list</a>
+</div>
+</div>
+</div>
+<div id="credit">
+<hr>
+ This is documentation for current release v0.7
+ (<a href="http://forrest.apache.org/docs.html">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>
+<!--+
+ |end Menu
+ +-->
+<!--+
+ |start content
+ +-->
+<div id="content">
+<div title="Portable Document Format" class="pdflink">
+<a class="dida" href="project-sitemap.pdf"><img alt="PDF -icon" src="../skin/images/pdfdoc.gif" class="skin"><br>
+ PDF</a>
+</div>
+<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 project sitemaps</h1>
+<div id="motd-area">
+ This is documentation for current release v0.7
+ (<a href="http://forrest.apache.org/docs.html">More</a> ...)</div>
+<div id="minitoc-area">
+<ul class="minitoc">
+<li>
+<a href="#introduction">Introduction</a>
+</li>
+<li>
+<a href="#how">How does it work?</a>
+</li>
+<li>
+<a href="#examples">Example uses of this technique</a>
+<ul class="minitoc">
+<li>
+<a href="#download">Adding a new content type</a>
+</li>
+</ul>
+</li>
+</ul>
+</div>
+
+<a name="N1000D"></a><a name="introduction"></a>
+<h2 class="underlined_10">Introduction</h2>
+<div class="section">
+<p>With Forrest 0.6 it is now possible for projects to "plugin"
+ to our sitemaps, without needing to copy the main sitemaps and keep
+ them synchonised. This will enable hassle-free update to
+ future Forrest versions.</p>
+<div class="frame 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/sitemap-ref.html">Sitemap Reference</a> for a tour of the
+ default sitemap.
+ </div>
+</div>
+</div>
+
+
+<a name="N10029"></a><a name="how"></a>
+<h2 class="underlined_10">How does it work?</h2>
+<div class="section">
+<p>If a project has a <span class="codefrag">sitemap.xmap</span> file in it's
+ documentation dir, that gets mounted automatically by Forrest and
+ becomes part of the processing: it is a preprocessing step, and
+ is the first one to handle the request. Because of this it can
+ serve any file directly. If it does not want to
+ serve a file, it can simply not match the URL and Forrest will take
+ care of it as usual.</p>
+<p>The cool thing is that if that pipeline serves an xml representation,
+ Forrest will provide a skinned version of it.</p>
+<p>So if the project sitemap matches test.xml and transforms that to a
+ correctly structured Forrest intermediate "document-v*",
+ then the user will see test.html fully rendered by Forrest.</p>
+<p>Of course, to resolve the directories in your sitemap it is important
+ to use the 'project:' and 'forrest:' variables to prevent any possible
+ issue in the future.</p>
+</div>
+
+
+<a name="N1003F"></a><a name="examples"></a>
+<h2 class="underlined_10">Example uses of this technique</h2>
+<div class="section">
+<a name="N10045"></a><a name="download"></a>
+<h3 class="underlined_5">Adding a new content type</h3>
+<p>
+ See the section "Advanced customizations: sitemap.xmap" in
+ the <a href="../docs/your-project.html">Using Forrest</a> document
+ and then follow the
+ <a href="../docs/your-project.html#adding_new_content_type">Example:
+ Adding a new content type</a>.
+ </p>
+</div>
+
+</div>
+<!--+
+ |end content
+ +-->
+<div class="clearboth"> </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 © 2002-2005 The Apache Software Foundation.</div>
+<!--+
+ |end bottomstrip
+ +-->
+</div>
+</body>
+</html>
Propchange: forrest/site/0.7/docs/project-sitemap.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/0.7/docs/project-sitemap.pdf
URL: http://svn.apache.org/viewcvs/forrest/site/0.7/docs/project-sitemap.pdf?view=auto&rev=160895
==============================================================================
Binary file - no diff available.
Propchange: forrest/site/0.7/docs/project-sitemap.pdf
------------------------------------------------------------------------------
svn:mime-type = application/pdf
Added: forrest/site/0.7/docs/searching.html
URL: http://svn.apache.org/viewcvs/forrest/site/0.7/docs/searching.html?view=auto&rev=160895
==============================================================================
--- forrest/site/0.7/docs/searching.html (added)
+++ forrest/site/0.7/docs/searching.html Mon Apr 11 07:58:59 2005
@@ -0,0 +1,444 @@
+<!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.7-dev">
+<meta name="Forrest-skin-name" content="pelt">
+<meta-data></meta-data>
+<title>Searching Forrest-built documentation (v0.7)</title>
+<link type="text/css" href="../skin/basic.css" rel="stylesheet">
+<link media="screen" type="text/css" href="../skin/screen.css" rel="stylesheet">
+<link media="print" type="text/css" href="../skin/print.css" rel="stylesheet">
+<link type="text/css" href="../skin/profile.css" rel="stylesheet">
+<script src="../skin/getBlank.js" language="javascript" type="text/javascript"></script><script src="../skin/getMenu.js" language="javascript" type="text/javascript"></script><script src="../skin/fontsize.js" language="javascript" type="text/javascript"></script>
+<link rel="shortcut icon" href="../favicon.ico">
+</head>
+<body onload="init()">
+<script type="text/javascript">ndeSetTextSize();</script>
+<div id="top">
+<!--+
+ |breadtrail
+ +-->
+<div class="breadtrail">
+<a href="http://www.apache.org/">apache</a> > <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:');" value="Search the site with google:" size="25" name="q" id="query" type="text">
+ <input name="Search" value="Search" type="submit">
+</form>
+</div>
+<!--+
+ |end search
+ +-->
+<!--+
+ |start Tabs
+ +-->
+<ul id="tabs">
+<li>
+<a class="base-not-selected" href="../index.html">Welcome</a>
+</li>
+<li>
+<a class="base-not-selected" href="../contrib.html">Project</a>
+</li>
+<li class="current">
+<a class="base-selected" href="../docs/index.html">0.7 Docs</a>
+</li>
+<li>
+<a class="base-not-selected" href="../docs/howto/index.html">0.7 How-To</a>
+</li>
+</ul>
+<!--+
+ |end Tabs
+ +-->
+</div>
+</div>
+<div id="main">
+<div id="publishedStrip">
+<!--+
+ |start Subtabs
+ +-->
+<div id="level2tabs">
+<a class="base-not-selected" href="..">Core</a> | <a class="base-not-selected" href="..">ForrestBot</a> | <a class="base-not-selected" href="..">ForrestBar</a>
+</div>
+<!--+
+ |end Endtabs
+ +-->
+<script type="text/javascript" language="JavaScript"><!--
+ document.write("Published: " + document.lastModified);
+ // --></script>
+</div>
+<!--+
+ |breadtrail
+ +-->
+<div class="breadtrail">
+
+
+ </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');">Documentation</div>
+<div id="menu_selected_1.1" class="selectedmenuitemgroup" style="display: block;">
+<div class="menuitem">
+<a title="" href="../docs/index.html">Overview</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/faq.html">FAQs</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/changes.html">Changes</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/todo.html">Todo</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/your-project.html">Using Forrest</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/validation.html">XML Validation</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/linking.html">Menus and Linking</a>
+</div>
+<div class="menupage">
+<div class="menupagetitle">Searching</div>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/skins.html">Default Skins</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/skin-package.html">Skin Packages</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/plugins/usingPlugins.html">Plugins</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/views.html">Views-dev</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/forrest-contract.html">Our Contract</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/compliance.html">Standards Compliance</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.15', '../skin/')" id="menu_1.1.15Title" class="menutitle">Advanced Topics</div>
+<div id="menu_1.1.15" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs/build.html">Building Forrest</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/catalog.html">Using DTD Catalogs</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/sitemap-ref.html">Sitemap Reference</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/project-sitemap.html">Project sitemap</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/plugins/pluginInfrastructure.html">Plugin Infrastructure</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/cap.html">Sourcetype Action</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.16', '../skin/')" id="menu_1.1.16Title" class="menutitle">Other versions</div>
+<div id="menu_1.1.16" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs.html">Overview</a>
+</div>
+<div class="menuitem">
+<a title="" href="http://forrest.apache.org/docs/../0.8/">0.8-dev</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/index.html">0.7 (current)</a>
+</div>
+<div class="menuitem">
+<a title="" href="http://forrest.apache.org/docs/../0.6/">0.6</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.17', '../skin/')" id="menu_1.1.17Title" class="menutitle">Upgrading</div>
+<div id="menu_1.1.17" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs/upgrading_07.html">Upgrading to 0.7</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/upgrading_06.html">Upgrading to 0.6</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.18', '../skin/')" id="menu_1.1.18Title" class="menutitle">SubProjects</div>
+<div id="menu_1.1.18" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs/forrestbar.html">ForrestBar</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/forrestbot.html">Forrestbot</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/forrestbot-web-interface.html">Forrestbot Webapp</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.19', '../skin/')" id="menu_1.1.19Title" class="menutitle">Reference docs</div>
+<div id="menu_1.1.19" class="menuitemgroup">
+<div onclick="SwitchMenu('menu_1.1.19.1', '../skin/')" id="menu_1.1.19.1Title" class="menutitle">DTD documentation</div>
+<div id="menu_1.1.19.1" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs/dtd-docs.html">Overview</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/document-v20.dtdx.html">document-v20</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/howto-v20.dtdx.html">howto-v20</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/faq-v20.dtdx.html">faq-v20</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/document-v13.dtdx.html">document-v13</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/howto-v13.dtdx.html">howto-v13</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/faq-v13.dtdx.html">faq-v13</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.19.2', '../skin/')" id="menu_1.1.19.2Title" class="menutitle">Doc samples</div>
+<div id="menu_1.1.19.2" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs/document-v13.html">document-v13</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/document-v20.html">document-v20</a>
+</div>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.20', '../skin/')" id="menu_1.1.20Title" class="menutitle">Older Docs</div>
+<div id="menu_1.1.20" class="menuitemgroup">
+<div class="menuitem">
+<a title="" href="../docs/primer.html">Forrest Primer</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/libre-intro.html">Libre</a>
+</div>
+<div class="menuitem">
+<a title="" href="../docs/dreams.html">Dream list</a>
+</div>
+</div>
+</div>
+<div id="credit">
+<hr>
+ This is documentation for current release v0.7
+ (<a href="http://forrest.apache.org/docs.html">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>
+<!--+
+ |end Menu
+ +-->
+<!--+
+ |start content
+ +-->
+<div id="content">
+<div title="Portable Document Format" class="pdflink">
+<a class="dida" href="searching.pdf"><img alt="PDF -icon" src="../skin/images/pdfdoc.gif" class="skin"><br>
+ PDF</a>
+</div>
+<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>Searching Forrest-built documentation</h1>
+<div id="motd-area">
+ This is documentation for current release v0.7
+ (<a href="http://forrest.apache.org/docs.html">More</a> ...)</div>
+<div id="minitoc-area">
+<ul class="minitoc">
+<li>
+<a href="#Google+SiteSearch">Google SiteSearch</a>
+</li>
+<li>
+<a href="#Lucene+search">Lucene search</a>
+</li>
+<li>
+<a href="#Disabling+full-text+search">Disabling full-text search</a>
+</li>
+</ul>
+</div>
+
+<p>Forrest provides you with two distinct options for making your
+ documentation available through full-text search:</p>
+
+<ul>
+
+<li>Google SiteSearch,</li>
+
+<li>Built-in search using Apache Lucene.</li>
+
+</ul>
+
+<p>Both options have their advantages and disadvantages. The
+ purpose of this document is to outline them, and to help you
+ make a choice. This document also tells you how to disable
+ full-text search completely, if you so choose.</p>
+
+<a name="N1001C"></a><a name="Google+SiteSearch"></a>
+<h2 class="underlined_10">Google SiteSearch</h2>
+<div class="section">
+<p>Forrest provides a simple interface to the Google search
+ engine. It invokes Google Advanced Search and limits the search
+ scope to the domain of your choice. Since the actual search
+ functionality is implemented on Google's end, you do not need
+ any additional capability on your Forrest server (which may
+ well be a simple static web server serving content generated
+ with <span class="codefrag">forrest site</span>).</p>
+<p>To use Google SiteSearch in your Forrest application, open
+ your <span class="codefrag">skinconf.xml</span> file. By default this file is
+ in the <span class="codefrag">src/documentation</span> subdirectory of your
+ Forrest repository root. Find the <span class="codefrag"><search></span>
+ element; it should be near the top of the file. If the element
+ does not exist, create it below the
+ <span class="codefrag"><skinconfig></span> opening tag. If there is any
+ attribute named <span class="codefrag">provider</span>, remove it. The element
+ should look similar to this:</p>
+<pre class="code"><search name="MyProject"
+ domain="myproject.com"/></pre>
+<p>Then, build your Forrest documentation and open it using your
+ favorite web browser. You are now invited to peruse the search
+ box (most skins render this in the top-right corner). Google's
+ search results will be displayed in a new browser window.</p>
+<p>Needless to say, for this to work your content must be
+ accessible to Google's indexing robot. It can't be stored on a
+ server which is only locally accessible, or which requires
+ authentication. In addition, the content index is created and
+ updated at a time of Google's choosing. However, the search is fast
+ and search precision is usually excellent. So if your
+ Forrest content is placed on a busy, popular public web
+ server, Google search is probably the best choice.</p>
+</div>
+
+<a name="N10045"></a><a name="Lucene+search"></a>
+<h2 class="underlined_10">Lucene search</h2>
+<div class="section">
+<p>Lucene is a high-performance, full-text search engine built
+ entirely in Java. To use Lucene-based search with your Forrest
+ documentation, you will need to run Forrest in a Java servlet
+ environment (such as Tomcat or Jetty). Lucene-based searching
+ will not work in a static site generated with the '<span class="codefrag">forrest
+ site</span>' command.</p>
+<p>In order to enable Lucene-based full-text search in your
+ Forrest application, you must first edit your
+ <span class="codefrag">skinconf.xml</span> file. Locate the
+ <span class="codefrag"><search></span> element. If the element does not
+ exist, insert it right underneath the
+ <span class="codefrag"><skinconfig></span> opening tag. Add an attribute
+ named <span class="codefrag">provider</span> with a value of
+ <span class="codefrag">lucene</span>, so that the element looks similar to
+ this:</p>
+<pre class="code"><search name="MyProject" domain="myproject.com"
+ provider="lucene"/></pre>
+<p>Next, create and run your Forrest webapp. This may mean
+ simply invoking <span class="codefrag">forrest run</span>, or building and
+ bundling a servlet webapp (with <span class="codefrag">forrest webapp</span>),
+ and then deploying it to your servlet container.</p>
+<p>You can now build a Lucene search index by pointing your web
+ browser at
+ <span class="codefrag">http://localhost:8888/lucene-update.html</span>. This
+ generates the search index and provides some information about
+ the index generation process.</p>
+<div class="frame note">
+<div class="label">Note</div>
+<div class="content">You may have to substitute a different hostname, port, or
+ path, depending on your configuration. The path mentioned here
+ reflects Forrest's default settings when invoked as
+ <span class="codefrag">forrest run</span>.</div>
+</div>
+<p>Now you can utilize the full-text search box, located in the
+ top-right corner of the rendered Forrest pages. Search results
+ will be displayed in the same browser window and will look
+ remarkably similar to the rest of your Forrest documents.</p>
+<p>Unlike with Google SiteSearch, the indexing information
+ retrieved by Lucene is stored on your own server, access to
+ which you may limit to users in your own organization.
+ Likewise, you may update or recreate the Lucene index at any
+ time and at your own discretion. So if you aren't making your
+ Forrest-built documentation publicly available, and you're
+ able to run Forrest on a Java-enabled web server, Lucene
+ search is probably right for you.</p>
+</div>
+
+<a name="N10083"></a><a name="Disabling+full-text+search"></a>
+<h2 class="underlined_10">Disabling full-text search</h2>
+<div class="section">
+<p>If you are convinced your users don't need any full-text
+ search capability whatsoever, you may disallow displaying the
+ search box entirely. You may also wish to do so if you're
+ keeping Forrest-built content on a restricted server (meaning
+ you can't use Google), while at the same time not having any
+ usable servlet-capable web server at your disposal (meaning
+ you can't use Lucene, either).</p>
+<p>To disable full-text search completely, open the
+ <span class="codefrag">skinconf.xml</span> file and remove (or comment out) the
+ entire <span class="codefrag"><search></span> element.</p>
+</div>
+
+</div>
+<!--+
+ |end content
+ +-->
+<div class="clearboth"> </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 © 2002-2005 The Apache Software Foundation.</div>
+<!--+
+ |end bottomstrip
+ +-->
+</div>
+</body>
+</html>
Propchange: forrest/site/0.7/docs/searching.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/0.7/docs/searching.pdf
URL: http://svn.apache.org/viewcvs/forrest/site/0.7/docs/searching.pdf?view=auto&rev=160895
==============================================================================
Binary file - no diff available.
Propchange: forrest/site/0.7/docs/searching.pdf
------------------------------------------------------------------------------
svn:mime-type = application/pdf