You are viewing a plain text version of this content. The canonical link for it is here.
Posted to site-svn@forrest.apache.org by th...@apache.org on 2007/05/10 20:06:19 UTC
svn commit: r536953 [8/14] - in /forrest/site: ./ docs_0_60/
docs_0_60/howto/ docs_0_60/howto/bugzilla-patch/
docs_0_60/howto/bugzilla-patch/my-images/ docs_0_60/howto/multi/
docs_0_60/images/ docs_0_90/ docs_0_90/howto/ docs_0_90/howto/cvs-ssh/
docs_0...
Added: forrest/site/docs_0_60/linking.html
URL: http://svn.apache.org/viewvc/forrest/site/docs_0_60/linking.html?view=auto&rev=536953
==============================================================================
--- forrest/site/docs_0_60/linking.html (added)
+++ forrest/site/docs_0_60/linking.html Thu May 10 11:06:09 2007
@@ -0,0 +1,951 @@
+<!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>Menus and Linking (v0.6)</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');" size="25" name="q" id="query" type="text" value="Search the site with google">
+ <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="unselected" href="../docs_0_80/index.html">0.80-dev (under development)</a><a class="selected" 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">
+
+
+ </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.60</div>
+<div id="menu_selected_1.1" class="selectedmenuitemgroup" style="display: block;">
+<div class="menuitem">
+<a href="../docs_0_60/index.html">Overview</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/faq.html">FAQs</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/changes.html">Changes</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/todo.html">Todo</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/your-project.html">Using Forrest</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/upgrading_06.html">Upgrading to 0.6</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/validation.html">XML Validation</a>
+</div>
+<div class="menupage">
+<div class="menupagetitle">Menus and Linking</div>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/searching.html">Searching</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/skins.html">Default Skins</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/skin-package.html">Skin Packages</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/forrest-contract.html">Our Contract</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/compliance.html">Standards Compliance</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.14', '../skin/')" id="menu_1.1.14Title" class="menutitle">How-To</div>
+<div id="menu_1.1.14" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_60/howto/index.html">Overview</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/howto/howto-howto.html">Single Page</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.14.3', '../skin/')" id="menu_1.1.14.3Title" class="menutitle">Multi-Page</div>
+<div id="menu_1.1.14.3" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_60/howto/multi/howto-multi.html">Intro</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/howto/multi/step1.html">Step 1</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/howto/multi/step2.html">Step 2</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/howto/multi/step3.html">Step 3</a>
+</div>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/howto/bugzilla-patch/howto-bugzilla-patch.html">With Images</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/howto/howto-howto.html">Write a How-to</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/howto/howto-asf-mirror.html">Download mirror</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/howto/howto-pdf-tab.html">Create tab PDF</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.15', '../skin/')" id="menu_1.1.15Title" class="menutitle">Advanced Topics</div>
+<div id="menu_1.1.15" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_60/build.html">Building Forrest</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/catalog.html">Using DTD Catalogs</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/sitemap-ref.html">Sitemap Reference</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/project-sitemap.html">Project sitemap</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/cap.html">Sourcetype Action</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.16', '../skin/')" id="menu_1.1.16Title" class="menutitle">Reference docs</div>
+<div id="menu_1.1.16" class="menuitemgroup">
+<div onclick="SwitchMenu('menu_1.1.16.1', '../skin/')" id="menu_1.1.16.1Title" class="menutitle">DTD documentation</div>
+<div id="menu_1.1.16.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.16.2', '../skin/')" id="menu_1.1.16.2Title" class="menutitle">Doc samples</div>
+<div id="menu_1.1.16.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>
+<div id="credit">
+<hr>
+ This is documentation for past version v0.6
+ (<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://www.asia.apachecon.com/"><img border="0" title="ApacheCon Asia 2006 (14-17 August 2006)" alt="ApacheCon Asia 2006 (14-17 August 2006) - logo" src="../images/apache_con_asia_header.png" style="width: 150px;height: 50px;"></a><a href="http://www.us.apachecon.com/"><img border="0" title="ApacheCon US 2006 (9-13 October 2006)" alt="ApacheCon US 2006 (9-13 October 2006) - logo" src="../images/ASF-us-2006-web_masthead.jpg" style="width: 150px;height: 50px;"></a>
+</div>
+</div>
+<!--+
+ |end Menu
+ +-->
+<!--+
+ |start content
+ +-->
+<div id="content">
+<div title="Portable Document Format" class="pdflink">
+<a class="dida" href="linking.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>Menus and Linking</h1>
+<div id="motd-area">
+ This is documentation for past version v0.6
+ (<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="#site">site.xml</a>
+</li>
+<li>
+<a href="#menu_generation">Generating Menus</a>
+<ul class="minitoc">
+<li>
+<a href="#tabs-external">Tabs for External Resources</a>
+</li>
+<li>
+<a href="#selecting-entries">Selecting menu entries</a>
+</li>
+<li>
+<a href="#other-menu-selection">Alternative menu selection mechanisms.</a>
+<ul class="minitoc">
+<li>
+<a href="#dir-menu-selection">Directory-based selection</a>
+</li>
+<li>
+<a href="#book-menu-selection">Specifying menus with book.xml</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#tab-selection">Selecting the current tab</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#toc-generation">Table of Contents Generation</a>
+</li>
+<li>
+<a href="#linking">Linking systems</a>
+<ul class="minitoc">
+<li>
+<a href="#direct-linking">Direct linking</a>
+</li>
+<li>
+<a href="#indirect-linking">Indirect linking</a>
+<ul class="minitoc">
+<li>
+<a href="#resolve-site-uris">Resolving site: URIs</a>
+</li>
+<li>
+<a href="#resolve-ext-uris">ext: URIs: linking to external URLs</a>
+</li>
+<li>
+<a href="#source-uris">Theory: source URIs</a>
+</li>
+<li>
+<a href="#future-schemes">Future schemes</a>
+</li>
+</ul>
+</li>
+</ul>
+</li>
+<li>
+<a href="#concept">Concept</a>
+</li>
+<li>
+<a href="#implementation">Implementation</a>
+</li>
+</ul>
+</div>
+
+<a name="N1000D"></a><a name="intro"></a>
+<h2 class="underlined_10">Introduction</h2>
+<div class="section">
+<p>
+ This document describes Forrest's internal URI space; how it is managed
+ with the "<span class="codefrag">site.xml</span>" configuration file, how menus are generated,
+ and how various link schemes (site: and ext:) operate.
+ An overview of the implementation is also provided.
+ </p>
+</div>
+
+
+<a name="N1001A"></a><a name="site"></a>
+<h2 class="underlined_10">site.xml</h2>
+<div class="section">
+<p>
+ The "<span class="codefrag">site.xml</span>" configuration file is what we would call a "site map"
+ if Cocoon hadn't already claimed that term.
+ The "<span class="codefrag">site.xml</span>" is a loosely structured XML file, acting as a map of the
+ site's contents. It provides a unique identifier (an XPath address)
+ for "nodes" of information in the website. A "node" of site information
+ can be:
+ </p>
+<ul>
+
+<li>A category of information, like "the user guide". A category may
+ correspond to a directory, but that is not required.</li>
+
+<li>A specific page, e.g. "the FAQ page"</li>
+
+<li>A specific section in a page, e.g. the "general" section of the FAQ
+ page (identified by <span class="codefrag">id="general"</span> attribute)</li>
+
+</ul>
+<p>
+ In addition to providing fine-grained addressing of site info, the <span class="codefrag">site.xml</span>
+ allows <em>metadata</em> to be associated with each node, using
+ attributes or child elements. Most commonly, a <span class="codefrag">label</span>
+ attribute is used to provide a text description of the node.
+ </p>
+<p>
+ There are currently two applications of <span class="codefrag">site.xml</span>
+
+</p>
+<dl>
+
+<dt>
+<a href="#menu_generation">Menu generation</a>
+</dt>
+
+<dd>
+<span class="codefrag">site.xml</span> is used to generate the menus for the HTML website.</dd>
+
+<dt>
+<a href="#semantic_linking">Indirect linking</a>
+</dt>
+
+<dd>
+<span class="codefrag">site.xml</span> provides a basic aliasing mechanism for linking, e.g. one
+ can write <link href="site:v0.60//changes"> from anywhere in the site, and
+ link to the "changes" information node (translated to changes.html).
+ More on this below.</dd>
+
+</dl>
+<p>
+ Here is a sample <span class="codefrag">site.xml</span> ... a modified version from Forrest's
+ own <a href="http://forrest.apache.org/">website</a>:
+ </p>
+<pre class="code">
+<?xml version="1.0"?>
+<site label="Forrest" href="" tab="home"
+ xmlns="http://apache.org/forrest/linkmap/1.0">
+
+ <about label="About">
+ <index label="Index" href="index.html"/>
+ <license label="License" href="license.html"/>
+ <your-project label="Using Forrest" href="your-project.html">
+ <new_content_type href="#adding_new_content_type"/>
+ </your-project>
+ <linking label="Linking" href="linking.html"/>
+ <changes label="Changes" href="changes.html"/>
+ <todo label="Todo" href="todo.html"/>
+ <live-sites label="Live sites" href="live-sites.html"/>
+ </about>
+
+ <community label="Community" href="community/" tab="community">
+ <index label="About" href="index.html"/>
+ <howto-samples label="How-To Samples" href="howto/" tab="howto">
+ <overview label="Overview" href="index.html"/>
+ <single-page label="Single Page" href="v10/howto-v10.html"/>
+ <multi-page label="Multi-Page" href="multi/">
+ <intro label="Intro" href="howto-multi.html"/>
+ <step1 label="Step 1" href="step1.html"/>
+ <step2 label="Step 2" href="step2.html"/>
+ </multi-page>
+ </howto-samples>
+ </community>
+
+ <references label="References">
+ <gump label="Apache Gump" href="http://gump.apache.org/"/>
+ <cocoon label="Apache Cocoon" href="http://cocoon.apache.org/"/>
+ </references>
+
+ <external-refs>
+ <mail-archive href="http://marc.theaimsgroup.com"/>
+ <xml.apache.org href="http://xml.apache.org/">
+ <commons href="commons/">
+ <resolver href="components/resolver/"/>
+ </commons>
+ <fop href="fop/"/>
+ <batik href="batik/"/>
+ </xml.apache.org>
+
+ <mail>
+ <semantic-linking href="http://marc.theaimsgroup.com/?l=forrest-dev
+ &amp;m=103097808318773&amp;w=2"/>
+ </mail>
+ <cool-uris href="www.w3.org/Provider/Style/URI.html"/>
+ <uri-rfc href="http://zvon.org/tmRFC/RFC2396/Output/index.html"/>
+
+ </external-refs>
+</site>
+ </pre>
+<p>As you can see, things are quite free-form. The rules are as follows:</p>
+<ul>
+
+<li>The root element must be "site", and normal content should be in the
+ namespace <span class="codefrag">http://apache.org/forrest/linkmap/1.0</span> (Feel
+ free to mix in your own content (RDF, dublin core, etc) under new
+ namespaces)</li>
+
+<li>Element names are used as identifiers. The "<span class="codefrag">foo</span>" in
+ "<span class="codefrag">site:foo</span>" must therefore be a valid NMTOKEN.</li>
+
+<li>Elements with <span class="codefrag">href</span> attributes can be used as identifiers
+ in "<span class="codefrag">site:</span>" URIs</li>
+
+<li>Relative href attribute contents are "accumulated" by prepending hrefs
+ from ancestor nodes</li>
+
+<li>Elements without <span class="codefrag">label</span> attributes (and their children)
+ are not displayed in the menu.</li>
+
+<li>Elements below <span class="codefrag">external-refs</span> are mapped to the
+ "<span class="codefrag">ext:</span>" scheme. So "<span class="codefrag">ext:commons/resolver/</span>" becomes
+ "<span class="codefrag">http://xml.apache.org/commons/resolver/</span>"</li>
+
+</ul>
+</div>
+
+
+<a name="N100A6"></a><a name="menu_generation"></a>
+<h2 class="underlined_10">Generating Menus</h2>
+<div class="section">
+<p>
+ Two files are used to define a site's tabs and menu (<span class="codefrag">site.xml</span> and
+ <span class="codefrag">tabs.xml</span>). Both files are located in
+ <span class="codefrag">src/documentation/content/xdocs/</span>
+</p>
+<p>Assume that our <span class="codefrag">tabs.xml</span> looks like this:</p>
+<pre class="code">
+<tabs ...>
+ <tab id="home" label="Home" dir=""/>
+ <tab id="community" label="Community" dir="community" indexfile="mailLists.html"/>
+ <tab id="howto" label="How-Tos" dir="community/howto"/>
+</tabs>
+ </pre>
+<p>Using the "<span class="codefrag">site.xml</span>" listed above, we would get these menus:</p>
+<p>
+
+<img alt="Menu generated from site.xml" src="images/menu.png">
+ <img alt="Community menu generated from site.xml" src="images/menu2.png">
+ <img alt="Howto menu generated from site.xml" src="images/menu3.png">
+ </p>
+<p>When using the "<span class="codefrag">dir</span>" attribute as above the value of the
+ "<span class="codefrag">indexfile</span>" parameter is appended to the value of the
+ "<span class="codefrag">dir</span>" attribute (together with a preceding '/'). For example,
+ the link for the community tab above is
+ <span class="codefrag">community/mailLists.html</span>. Note that "<span class="codefrag">indexfile</span>"
+ defaults to "<span class="codefrag">index.html</span>" if no value is supplied. Therefore the
+ link for the howto tab is <span class="codefrag">community/howto/index.html</span>
+</p>
+<a name="N100ED"></a><a name="tabs-external"></a>
+<h3 class="underlined_5">Tabs for External Resources</h3>
+<p>A tab can refer to an external resource by using the
+ "<span class="codefrag">href</span>" attribute instead of the "<span class="codefrag">dir</span>" attribute.
+ The value of "<span class="codefrag">href</span>" should be the URI of the resource you wish
+ to link to. For example:</p>
+<pre class="code">
+<tab id="apache" label="XML Apache" href="http://xml.apache.org/"/>
+ </pre>
+<p>Unlike the "<span class="codefrag">dir</span>" attribute, the value of "<span class="codefrag">href</span>"
+ is left unmodified by Forrest unless it is root-relative and obviously
+ specifies a directory (ends in '/'). In which case /index.html will be
+ added.</p>
+<a name="N1010D"></a><a name="selecting-entries"></a>
+<h3 class="underlined_5">Selecting menu entries</h3>
+<p>Forrest decides which menu entries to display, by examining the
+ "<span class="codefrag">tab</span>" attributes in the <span class="codefrag">site.xml</span> file. The children of
+ all <span class="codefrag">site.xml</span> entries with a
+ "<span class="codefrag">tab</span>" which is equal to that of the current page, are
+ added to the menu, whilst the element itself forms the root of that
+ part of the menu (see the "<span class="codefrag">community</span>" element in the
+ example below). Child elements that have a different
+ "<span class="codefrag">tab</span>" attribute value will appear in the menu for their
+ parents, and will also form the root of a new menu for a tab with
+ the appropriate name (see the "<span class="codefrag">howto-samples</span>" element
+ below).</p>
+<p>Consider our <span class="codefrag">site.xml</span> example:</p>
+<pre class="code">
+<site label="Forrest" href="" <strong>tab="home"</strong>
+ xmlns="http://apache.org/forrest/linkmap/1.0">
+
+ <about label="About">
+ <index label="Index" href="index.html"/>
+ <license label="License" href="license.html"/>
+ <your-project label="Using Forrest" href="your-project.html">
+ <new_content_type href="#adding_new_content_type"/>
+ </your-project>
+ <linking label="Linking" href="linking.html"/>
+ ....
+ </about>
+
+ <community label="Community" href="community/" <strong>tab="community"</strong>>
+ <index label="About" href="index.html"/>
+ <howto-samples label="How-To Samples" href="howto/" <strong>tab="howto"</strong>>
+ <overview label="Overview" href="index.html"/>
+ <single-page label="Single Page" href="v10/howto-v10.html"/>
+ <multi label="Multi-Page" href="multi/">
+ <intro label="Intro" href="howto-multi.html"/>
+ <step1 label="Step 1" href="step1.html"/>
+ ...</pre>
+<p>
+ Every <span class="codefrag">site.xml</span> node can potentially have a "<span class="codefrag">tab</span>" attribute. If
+ unspecified, nodes inherit the "<span class="codefrag">tab</span>" of their parent. Thus
+ everything in the <strong><about></strong> section has an implicit
+ <span class="codefrag">tab="home" </span>attribute.</p>
+<div class="note">
+<div class="label">Note</div>
+<div class="content">You can see this by viewing your site's
+ <a href="../abs-menulinks">abs-menulinks</a> pipeline in a
+ browser.</div>
+</div>
+<p>Say that the user is viewing the <span class="codefrag">linking.html</span>
+ page. The <strong><linking></strong> node has an implicit tab
+ value of "<span class="codefrag">home</span>". Forrest will select <em>all nodes with
+ tab="home"</em> and put them in the menu.
+ </p>
+<a name="N10167"></a><a name="other-menu-selection"></a>
+<h3 class="underlined_5">Alternative menu selection mechanisms.</h3>
+<p>
+ The "<span class="codefrag">tab</span>" attribute-based scheme for selecting a menu's
+ entries is not the only one, although it is the most flexible. Here
+ we describe a few alternatives.
+ </p>
+<a name="N10173"></a><a name="dir-menu-selection"></a>
+<h4>Directory-based selection</h4>
+<p>In this scheme, each tab corresponds to a directory within the
+ site. All content below that directory is included in the menu.</p>
+<p>
+
+<img alt="Directory-based site menu" src="images/dir-menu.png">
+ <img alt="community/ directory menu" src="images/dir-menu2.png">
+ <img alt="community/howto/ directory menu" src="images/dir-menu3.png">
+ </p>
+<p>
+ To use this scheme:
+ </p>
+<ul>
+
+<li>Edit <span class="codefrag">forrest.properties</span> and set
+ <span class="codefrag">project.menu-scheme=directories</span>
+</li>
+
+<li>Remove the "<span class="codefrag">id</span>" attributes from <span class="codefrag">tabs.xml</span>
+ entries.</li>
+
+</ul>
+<a name="N101A3"></a><a name="book-menu-selection"></a>
+<h4>Specifying menus with book.xml</h4>
+<p>
+ Historically, menus in Forrest have been generated from a
+ <span class="codefrag">book.xml</span> file, one per directory. This mechanism is
+ still available, and if a <span class="codefrag">book.xml</span> is found, it will be
+ used in preference to the menu generated by the <span class="codefrag">site.xml</span> file. The <span class="codefrag">book.xml</span>
+ files can use "<span class="codefrag">site:</span>" URIs to ease the maintenance burden
+ that led to obsolescence of book.xml files. In general, however, we
+ recommend that users avoid <span class="codefrag">book.xml</span> files.
+ </p>
+<a name="N101C0"></a><a name="tab-selection"></a>
+<h3 class="underlined_5">Selecting the current tab</h3>
+<p>
+ The tab selection algorithm is quite simple: the tab with the
+ "<span class="codefrag">id</span>" which matches that of the current <span class="codefrag">site.xml</span>
+ node is "selected". If you experience any problems, try to add a
+ <span class="codefrag"><foo label="Foo" href="index.html"/></span> to the
+ <span class="codefrag">site.xml</span> configuration.
+ </p>
+</div>
+
+
+<a name="N101D7"></a><a name="toc-generation"></a>
+<h2 class="underlined_10">Table of Contents Generation</h2>
+<div class="section">
+<p>Each page can have an automatically generated table of contents. This
+ is created from the titles of each section in your xdoc. By default only
+ sections up to two levels deep are included and the table of contents is
+ displayed at the top of the page. However, you can configure this
+ behaviour in <span class="codefrag">src/documentation/skinconf.xml</span> using the
+ "<span class="codefrag">toc</span>" element.</p>
+<pre class="code">
+<toc level="2" location="page"/>
+ </pre>
+<ul>
+
+<li>
+<strong><span class="codefrag">level</span></strong> - is the depth to which you
+ want your table of contents to go. Setting it to "3" will therefore
+ include sections nested to 3 levels. Setting this to "0" will result in
+ no table of contents being generated.</li>
+
+<li>
+<strong><span class="codefrag">location</span></strong> - indicates where you
+ want the table of contents to be rendered. It can be set to one of
+ three values:
+ <ul>
+
+<li>
+<span class="codefrag">page</span> - the table of contents will be rendered
+ at the top of the body of your page</li>
+
+<li>
+<span class="codefrag">menu</span> - the table of contents will be rendered
+ in the menu to the left of the body of the page</li>
+
+<li>
+<span class="codefrag">menu, page</span> - table of contents will be rendered
+ in both the page and the menu positions</li>
+
+</ul>
+
+</li>
+
+</ul>
+</div>
+
+
+<a name="N1020C"></a><a name="linking"></a>
+<h2 class="underlined_10">Linking systems</h2>
+<div class="section">
+<a name="N10212"></a><a name="direct-linking"></a>
+<h3 class="underlined_5">Direct linking</h3>
+<p>
+ In earlier versions of Forrest (and in similar systems), there has
+ been only one URI space: that of the generated site. If <span class="codefrag">index.xml</span> wants to
+ link to <span class="codefrag">todo.xml</span> then <span class="codefrag">index.xml</span> would use
+ </p>
+<pre class="code">
+ <link href="todo.html">to-do list<link>
+ </pre>
+<p>
+ The theoretical problem with this is that the content producer should
+ not know or care how Forrest is going to render the source. A URI
+ should only <em>identify</em> a resource, not specify it's type
+ [<a href="http://marc.theaimsgroup.com/?l=forrest-dev&m=103097808318773&w=2">mail ref</a>] and
+ [<a href="http://www.w3.org/Provider/Style/URI.html">cool URIs</a>]. In fact, as Forrest
+ typically renders to multiple output formats (HTML and PDF), links in
+ one of them (here, the PDF) are likely to break.
+ </p>
+<a name="N10237"></a><a name="indirect-linking"></a>
+<h3 class="underlined_5">Indirect linking</h3>
+<p>
+ Forrest's solution is simple: instead of <link href="todo.html">,
+ write <link href="site:v0.60//todo"> where:
+ </p>
+<dl>
+
+<dt>site</dt>
+
+<dd>is a URI "scheme"; a namespace that restricts
+ the syntax and semantics of the rest of the URI
+ [<a href="http://zvon.org/tmRFC/RFC2396/Output/index.html">rfc2396</a>]. The semantics of "site" are
+ "this identifier locates something in the site's XML sources".</dd>
+
+<dt>todo</dt>
+
+<dd>identifies the content in <span class="codefrag">todo.xml</span> by reference to a
+ "node" of content declared in <span class="codefrag">site.xml</span>
+</dd>
+
+</dl>
+<p>
+ We call this indirect, or <em>semantic</em> linking because instead of
+ linking to a physical representation (todo.html), we've linked to the
+ "idea" of "the todo file". It doesn't matter where it physically lives;
+ that will be sorted out by Forrest.
+ </p>
+<a name="N1025E"></a><a name="resolve-site-uris"></a>
+<h4>Resolving site: URIs</h4>
+<p>
+ So how does "<span class="codefrag">site:todo</span>" get resolved? A full answer
+ is provided in the <a href="#implementation">implementation</a>
+ section. Essentially, the "<span class="codefrag">todo</span>" part has
+ "<span class="codefrag">/site//</span>" prepended, and "<span class="codefrag">/@href</span>" appended, to
+ form the string "<span class="codefrag">/site//todo/@href</span>". This is
+ then used as an XPath expression in <span class="codefrag">site.xml</span> to identify the string
+ replacement, in this case "<span class="codefrag">todo.html</span>"
+ </p>
+<p>
+ Thus by modifying the XPath prefix and suffix, almost any XML
+ format can be accommodated.
+ </p>
+<div class="note">
+<div class="label">Note</div>
+<div class="content">
+ Actually, the XPath is applied to XML generated dynamically from
+ <span class="codefrag">site.xml</span>. The generated XML has each "@href" fully expanded ("absolutized")
+ and dot-dots (..) added as needed ("relativized").
+ </div>
+</div>
+<p>
+ Notice that the "//" allows us any degree of specificity when linking.
+ In the sample <span class="codefrag">site.xml</span> above, both "<span class="codefrag">site:new_content_type</span>" and
+ "<span class="codefrag">site:about/your-project/new_content_type</span>" identify the
+ same node. It is up to you to decide how specific to make links. One
+ nice benefit of link "ambiguity" is that <span class="codefrag">site.xml</span> can be reorganized
+ without breaking links. For example, "new_content_type" currently
+ identifies a node in "your-project". By leaving that fact unspecified
+ in "<span class="codefrag">site:new_content_type</span>" we are free to make
+ "new_content_type" its own XML file, or a node in another file, in
+ another category.
+ </p>
+<a name="N1029C"></a><a name="resolve-ext-uris"></a>
+<h4>ext: URIs: linking to external URLs</h4>
+<p>
+ The "<span class="codefrag">ext:</span>" scheme was created partly to demonstrate the
+ ease with which new schemes can be defined, and partly for practical
+ use. The "<span class="codefrag">ext:</span>" URIs identify nodes in <span class="codefrag">site.xml</span> below the
+ <external-refs> node. By convention, nodes here link to URLs
+ outside the website, and are not listed in the menu generated from
+ the <span class="codefrag">site.xml</span> file.
+ </p>
+<p>Here is a <span class="codefrag">site.xml</span> snippet illustrating "<span class="codefrag">external-refs</span>":</p>
+<pre class="code">
+<site>
+ ...
+ <external-refs>
+ <mail-archive href="http://marc.theaimsgroup.com"/>
+ <xml.apache.org href="http://xml.apache.org/">
+ <commons href="commons/">
+ <resolver href="components/resolver/"/>
+ </commons>
+ </xml.apache.org>
+ ...
+ </external-refs>
+</site></pre>
+<p>
+ As an example, <link href="ext:commons/resolver">
+ generates the link
+ <a href="http://xml.apache.org/commons/components/resolver/">http://xml.apache.org/components/resolver/</a>
+
+</p>
+<p>
+ The general rules of <span class="codefrag">site.xml</span> and "<span class="codefrag">site:</span>" linking apply.
+ Specifically, the "@href" aggregation makes defining large numbers of
+ related URLs easy.
+ </p>
+<a name="N102CF"></a><a name="source-uris"></a>
+<h4>Theory: source URIs</h4>
+<p>
+ The "<span class="codefrag">site:</span>" URIs like "<span class="codefrag">site:todo</span>" are examples of
+ "<em>source</em>" URIs, in contrast to the more usual
+ <span class="codefrag">foo.html</span> style URIs, which we here call
+ "<em>destination</em>" URIs. This introduces an important concept: that
+ the "<em>source</em>" URI space exists and is independent of that of the
+ generated site. Furthermore, URIs (i.e. links) are first-class objects,
+ on par with XML documents, in that just as XML content is transformed,
+ so are the links. Within the source URI space, we can have all sorts of
+ interesting schemes (person: mail: google: java: etc). These will
+ all be translated into plain old "<span class="codefrag">http:</span>" or relative URIs
+ in the destination URI space, just like exotic XML source formats are
+ translated into plain old HTML in the output.
+ </p>
+<a name="N102EE"></a><a name="future-schemes"></a>
+<h4>Future schemes</h4>
+<p>
+ So far, the "<span class="codefrag">site:</span>" and "<span class="codefrag">ext:</span>" schemes are defined.
+ To give you some ideas on other things we'd like to implement (and
+ wouldd welcome help to implement) here are a few possibilities.
+ </p>
+<table class="ForrestTable" cellspacing="1" cellpadding="4">
+
+<tr>
+<th colspan="1" rowspan="1">Scheme</th><th colspan="1" rowspan="1">Example "From"</th><th colspan="1" rowspan="1">Example "To"</th><th colspan="1" rowspan="1">Description</th>
+</tr>
+
+<tr>
+
+<td colspan="1" rowspan="1">java</td>
+ <td colspan="1" rowspan="1">java:org.apache.proj.SomeClass</td>
+ <td colspan="1" rowspan="1"><span class="codefrag">../../apidocs/org/apache/proj/SomeClass.html</span></td>
+ <td colspan="1" rowspan="1">
+ Links to documentation for a Java class (typically generated by
+ <span class="codefrag">javadoc</span>).
+ </td>
+
+</tr>
+
+<tr>
+
+<td colspan="1" rowspan="1">mail</td>
+ <td colspan="1" rowspan="1">mail::<Message-Id></td>
+ <td colspan="1" rowspan="1"><span class="codefrag">http://marc.theaimsgroup.com?t=12345678</span></td>
+ <td colspan="1" rowspan="1">
+ Links to an email, identified by its <span class="codefrag">Message-Id</span>
+ header. Any mail archive website could be used.
+ </td>
+
+</tr>
+
+<tr>
+
+<td colspan="1" rowspan="1">search</td>
+ <td colspan="1" rowspan="1">search:<searchterm></td>
+ <td colspan="1" rowspan="1"><span class="codefrag">http://www.google.com/search?q=searchterm</span></td>
+ <td colspan="1" rowspan="1">Link to set of results from a search engine</td>
+
+</tr>
+
+<tr>
+
+<td colspan="1" rowspan="1">person</td>
+ <td colspan="1" rowspan="1">person:JT, person:JT/blog etc</td>
+ <td colspan="1" rowspan="1"><span class="codefrag">mailto:jefft<at>apache.org</span>,
+ <span class="codefrag">http://www.webweavertech.com/jefft/weblog/</span></td>
+ <td colspan="1" rowspan="1">
+ A "<span class="codefrag">person:</span>" scheme could be used, say, to insert an
+ automatically obfuscated email address, or link to a URI in some
+ way associated with that person.
+ </td>
+
+</tr>
+
+</table>
+<p>
+ There are even more possibilities in specific environments. In an
+ intranet, a "<span class="codefrag">project:XYZ</span>" scheme could identify company
+ project pages. In a project like <a href="http://ant.apache.org/">Apache
+ Ant</a>, each Task could be identified with
+ <span class="codefrag">task:<taskname></span>, e.g. <span class="codefrag">task:pathconvert</span>.
+ </p>
+</div>
+
+<a name="N10391"></a><a name="concept"></a>
+<h2 class="underlined_10">Concept</h2>
+<div class="section">
+<p>
+ The "<span class="codefrag">site:</span>" scheme and associated ideas for <span class="codefrag">site.xml</span> were
+ originally described in <a href="http://marc.theaimsgroup.com/?l=forrest-dev&m=103444028129281&w=2">the 'linkmap' RT
+ email</a> to the forrest-dev list (RT means 'random thought'; a
+ Cocoon invention). Only section 2 has been implemented, and there is
+ still significant work required to implement the full system
+ described. In particular, there is much scope for automating the
+ creation of <span class="codefrag">site.xml</span> (section 4). However, what is currently implemented
+ gains most of the advantages of the system.
+ </p>
+</div>
+
+<a name="N103A8"></a><a name="implementation"></a>
+<h2 class="underlined_10">Implementation</h2>
+<div class="section">
+<p>Full details on the implementation of
+ <a href="../docs_0_60/sitemap-ref.html#linkrewriting_impl">link rewriting</a> and
+ <a href="../docs_0_60/sitemap-ref.html#menu_generation_impl">menu generation</a> are available in
+ the <a href="../docs_0_60/sitemap-ref.html">Sitemap Reference</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-2006 <a href="http://www.apache.org/licenses/">The Apache Software Foundation.</a>
+</div>
+<!--+
+ |end bottomstrip
+ +-->
+</div>
+</body>
+</html>
Propchange: forrest/site/docs_0_60/linking.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/docs_0_60/linking.pdf
URL: http://svn.apache.org/viewvc/forrest/site/docs_0_60/linking.pdf?view=auto&rev=536953
==============================================================================
Binary file - no diff available.
Propchange: forrest/site/docs_0_60/linking.pdf
------------------------------------------------------------------------------
svn:mime-type = application/pdf
Added: forrest/site/docs_0_60/menu-index.html
URL: http://svn.apache.org/viewvc/forrest/site/docs_0_60/menu-index.html?view=auto&rev=536953
==============================================================================
--- forrest/site/docs_0_60/menu-index.html (added)
+++ forrest/site/docs_0_60/menu-index.html Thu May 10 11:06:09 2007
@@ -0,0 +1,206 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<div id="menu">
+<ul>
+<li>
+<h1>0.60</h1>
+<ul>
+
+<li>
+<div class="current">Overview</div>
+</li>
+
+<li>
+<a href="../docs_0_60/faq.html">FAQs</a>
+</li>
+
+<li>
+<a href="../docs_0_60/changes.html">Changes</a>
+</li>
+
+<li>
+<a href="../docs_0_60/todo.html">Todo</a>
+</li>
+
+<li>
+<a href="../docs_0_60/your-project.html">Using Forrest</a>
+</li>
+
+<li>
+<a href="../docs_0_60/upgrading_06.html">Upgrading to 0.6</a>
+</li>
+
+<li>
+<a href="../docs_0_60/validation.html">XML Validation</a>
+</li>
+
+<li>
+<a href="../docs_0_60/linking.html">Menus and Linking</a>
+</li>
+
+<li>
+<a href="../docs_0_60/searching.html">Searching</a>
+</li>
+
+<li>
+<a href="../docs_0_60/skins.html">Default Skins</a>
+</li>
+
+<li>
+<a href="../docs_0_60/skin-package.html">Skin Packages</a>
+</li>
+
+
+<li>
+<a href="../docs_0_60/forrest-contract.html">Our Contract</a>
+</li>
+
+<li>
+<a href="../docs_0_60/compliance.html">Standards Compliance</a>
+</li>
+
+
+<li>
+<h1>How-To</h1>
+<ul>
+
+<li>
+<a href="../docs_0_60/howto/index.html">Overview</a>
+</li>
+
+<li>
+<a href="../docs_0_60/howto/howto-howto.html">Single Page</a>
+</li>
+
+<li>
+<h1>Multi-Page</h1>
+<ul>
+
+<li>
+<a href="../docs_0_60/howto/multi/howto-multi.html">Intro</a>
+</li>
+
+<li>
+<a href="../docs_0_60/howto/multi/step1.html">Step 1</a>
+</li>
+
+<li>
+<a href="../docs_0_60/howto/multi/step2.html">Step 2</a>
+</li>
+
+<li>
+<a href="../docs_0_60/howto/multi/step3.html">Step 3</a>
+</li>
+
+</ul>
+</li>
+
+<li>
+<a href="../docs_0_60/howto/bugzilla-patch/howto-bugzilla-patch.html">With Images</a>
+</li>
+
+<li>
+<a href="../docs_0_60/howto/howto-howto.html">Write a How-to</a>
+</li>
+
+<li>
+<a href="../docs_0_60/howto/howto-asf-mirror.html">Download mirror</a>
+</li>
+
+<li>
+<a href="../docs_0_60/howto/howto-pdf-tab.html">Create tab PDF</a>
+</li>
+
+</ul>
+</li>
+
+
+<li>
+<h1>Advanced Topics</h1>
+<ul>
+
+<li>
+<a href="../docs_0_60/build.html">Building Forrest</a>
+</li>
+
+<li>
+<a href="../docs_0_60/catalog.html">Using DTD Catalogs</a>
+</li>
+
+<li>
+<a href="../docs_0_60/sitemap-ref.html">Sitemap Reference</a>
+</li>
+
+<li>
+<a href="../docs_0_60/project-sitemap.html">Project sitemap</a>
+</li>
+
+<li>
+<a href="../docs_0_60/cap.html">Sourcetype Action</a>
+</li>
+
+</ul>
+</li>
+
+
+<li>
+<h1>Reference docs</h1>
+<ul>
+
+<li>
+<h1>DTD documentation</h1>
+<ul>
+
+<li>
+<a href="../dtdx/dtd-docs.html">Overview</a>
+</li>
+
+<li>
+<a href="../dtdx/document-v20.dtdx.html">document-v20</a>
+</li>
+
+<li>
+<a href="../dtdx/howto-v20.dtdx.html">howto-v20</a>
+</li>
+
+<li>
+<a href="../dtdx/faq-v20.dtdx.html">faq-v20</a>
+</li>
+
+<li>
+<a href="../dtdx/document-v13.dtdx.html">document-v13</a>
+</li>
+
+<li>
+<a href="../dtdx/howto-v13.dtdx.html">howto-v13</a>
+</li>
+
+<li>
+<a href="../dtdx/faq-v13.dtdx.html">faq-v13</a>
+</li>
+
+</ul>
+</li>
+
+<li>
+<h1>Doc samples</h1>
+<ul>
+
+
+<li>
+<a href="../dtdx/document-v13.html">document-v13</a>
+</li>
+
+<li>
+<a href="../dtdx/document-v20.html">document-v20</a>
+</li>
+
+</ul>
+</li>
+
+</ul>
+</li>
+
+</ul>
+</li>
+</ul>
+</div>
Propchange: forrest/site/docs_0_60/menu-index.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/docs_0_60/project-sitemap.html
URL: http://svn.apache.org/viewvc/forrest/site/docs_0_60/project-sitemap.html?view=auto&rev=536953
==============================================================================
--- forrest/site/docs_0_60/project-sitemap.html (added)
+++ forrest/site/docs_0_60/project-sitemap.html Thu May 10 11:06:09 2007
@@ -0,0 +1,379 @@
+<!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 project sitemaps (v0.6)</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');" size="25" name="q" id="query" type="text" value="Search the site with google">
+ <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="unselected" href="../docs_0_80/index.html">0.80-dev (under development)</a><a class="selected" 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">
+
+
+ </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.60</div>
+<div id="menu_selected_1.1" class="selectedmenuitemgroup" style="display: block;">
+<div class="menuitem">
+<a href="../docs_0_60/index.html">Overview</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/faq.html">FAQs</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/changes.html">Changes</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/todo.html">Todo</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/your-project.html">Using Forrest</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/upgrading_06.html">Upgrading to 0.6</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/validation.html">XML Validation</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/linking.html">Menus and Linking</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/searching.html">Searching</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/skins.html">Default Skins</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/skin-package.html">Skin Packages</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/forrest-contract.html">Our Contract</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/compliance.html">Standards Compliance</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.14', '../skin/')" id="menu_1.1.14Title" class="menutitle">How-To</div>
+<div id="menu_1.1.14" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_60/howto/index.html">Overview</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/howto/howto-howto.html">Single Page</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.14.3', '../skin/')" id="menu_1.1.14.3Title" class="menutitle">Multi-Page</div>
+<div id="menu_1.1.14.3" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_60/howto/multi/howto-multi.html">Intro</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/howto/multi/step1.html">Step 1</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/howto/multi/step2.html">Step 2</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/howto/multi/step3.html">Step 3</a>
+</div>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/howto/bugzilla-patch/howto-bugzilla-patch.html">With Images</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/howto/howto-howto.html">Write a How-to</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/howto/howto-asf-mirror.html">Download mirror</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/howto/howto-pdf-tab.html">Create tab PDF</a>
+</div>
+</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 href="../docs_0_60/build.html">Building Forrest</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/catalog.html">Using DTD Catalogs</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/sitemap-ref.html">Sitemap Reference</a>
+</div>
+<div class="menupage">
+<div class="menupagetitle">Project sitemap</div>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/cap.html">Sourcetype Action</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.16', '../skin/')" id="menu_1.1.16Title" class="menutitle">Reference docs</div>
+<div id="menu_1.1.16" class="menuitemgroup">
+<div onclick="SwitchMenu('menu_1.1.16.1', '../skin/')" id="menu_1.1.16.1Title" class="menutitle">DTD documentation</div>
+<div id="menu_1.1.16.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.16.2', '../skin/')" id="menu_1.1.16.2Title" class="menutitle">Doc samples</div>
+<div id="menu_1.1.16.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>
+<div id="credit">
+<hr>
+ This is documentation for past version v0.6
+ (<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://www.asia.apachecon.com/"><img border="0" title="ApacheCon Asia 2006 (14-17 August 2006)" alt="ApacheCon Asia 2006 (14-17 August 2006) - logo" src="../images/apache_con_asia_header.png" style="width: 150px;height: 50px;"></a><a href="http://www.us.apachecon.com/"><img border="0" title="ApacheCon US 2006 (9-13 October 2006)" alt="ApacheCon US 2006 (9-13 October 2006) - logo" src="../images/ASF-us-2006-web_masthead.jpg" style="width: 150px;height: 50px;"></a>
+</div>
+</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 past version v0.6
+ (<a href="http://forrest.apache.org/versions/">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 them synchonised. This will enable hassle-free update to
+ future Forrest versions.</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_60/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_0_60/your-project.html">Using Forrest</a> document
+ and then follow the
+ <a href="../docs_0_60/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-2006 <a href="http://www.apache.org/licenses/">The Apache Software Foundation.</a>
+</div>
+<!--+
+ |end bottomstrip
+ +-->
+</div>
+</body>
+</html>
Propchange: forrest/site/docs_0_60/project-sitemap.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/docs_0_60/project-sitemap.pdf
URL: http://svn.apache.org/viewvc/forrest/site/docs_0_60/project-sitemap.pdf?view=auto&rev=536953
==============================================================================
Binary file - no diff available.
Propchange: forrest/site/docs_0_60/project-sitemap.pdf
------------------------------------------------------------------------------
svn:mime-type = application/pdf
Added: forrest/site/docs_0_60/searching.html
URL: http://svn.apache.org/viewvc/forrest/site/docs_0_60/searching.html?view=auto&rev=536953
==============================================================================
--- forrest/site/docs_0_60/searching.html (added)
+++ forrest/site/docs_0_60/searching.html Thu May 10 11:06:09 2007
@@ -0,0 +1,432 @@
+<!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>Searching Forrest-built documentation (v0.6)</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');" size="25" name="q" id="query" type="text" value="Search the site with google">
+ <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="unselected" href="../docs_0_80/index.html">0.80-dev (under development)</a><a class="selected" 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">
+
+
+ </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.60</div>
+<div id="menu_selected_1.1" class="selectedmenuitemgroup" style="display: block;">
+<div class="menuitem">
+<a href="../docs_0_60/index.html">Overview</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/faq.html">FAQs</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/changes.html">Changes</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/todo.html">Todo</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/your-project.html">Using Forrest</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/upgrading_06.html">Upgrading to 0.6</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/validation.html">XML Validation</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/linking.html">Menus and Linking</a>
+</div>
+<div class="menupage">
+<div class="menupagetitle">Searching</div>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/skins.html">Default Skins</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/skin-package.html">Skin Packages</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/forrest-contract.html">Our Contract</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/compliance.html">Standards Compliance</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.14', '../skin/')" id="menu_1.1.14Title" class="menutitle">How-To</div>
+<div id="menu_1.1.14" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_60/howto/index.html">Overview</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/howto/howto-howto.html">Single Page</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.14.3', '../skin/')" id="menu_1.1.14.3Title" class="menutitle">Multi-Page</div>
+<div id="menu_1.1.14.3" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_60/howto/multi/howto-multi.html">Intro</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/howto/multi/step1.html">Step 1</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/howto/multi/step2.html">Step 2</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/howto/multi/step3.html">Step 3</a>
+</div>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/howto/bugzilla-patch/howto-bugzilla-patch.html">With Images</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/howto/howto-howto.html">Write a How-to</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/howto/howto-asf-mirror.html">Download mirror</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/howto/howto-pdf-tab.html">Create tab PDF</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.15', '../skin/')" id="menu_1.1.15Title" class="menutitle">Advanced Topics</div>
+<div id="menu_1.1.15" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_60/build.html">Building Forrest</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/catalog.html">Using DTD Catalogs</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/sitemap-ref.html">Sitemap Reference</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/project-sitemap.html">Project sitemap</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_60/cap.html">Sourcetype Action</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.16', '../skin/')" id="menu_1.1.16Title" class="menutitle">Reference docs</div>
+<div id="menu_1.1.16" class="menuitemgroup">
+<div onclick="SwitchMenu('menu_1.1.16.1', '../skin/')" id="menu_1.1.16.1Title" class="menutitle">DTD documentation</div>
+<div id="menu_1.1.16.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.16.2', '../skin/')" id="menu_1.1.16.2Title" class="menutitle">Doc samples</div>
+<div id="menu_1.1.16.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>
+<div id="credit">
+<hr>
+ This is documentation for past version v0.6
+ (<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://www.asia.apachecon.com/"><img border="0" title="ApacheCon Asia 2006 (14-17 August 2006)" alt="ApacheCon Asia 2006 (14-17 August 2006) - logo" src="../images/apache_con_asia_header.png" style="width: 150px;height: 50px;"></a><a href="http://www.us.apachecon.com/"><img border="0" title="ApacheCon US 2006 (9-13 October 2006)" alt="ApacheCon US 2006 (9-13 October 2006) - logo" src="../images/ASF-us-2006-web_masthead.jpg" style="width: 150px;height: 50px;"></a>
+</div>
+</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 past version v0.6
+ (<a href="http://forrest.apache.org/versions/">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="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-2006 <a href="http://www.apache.org/licenses/">The Apache Software Foundation.</a>
+</div>
+<!--+
+ |end bottomstrip
+ +-->
+</div>
+</body>
+</html>
Propchange: forrest/site/docs_0_60/searching.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/docs_0_60/searching.pdf
URL: http://svn.apache.org/viewvc/forrest/site/docs_0_60/searching.pdf?view=auto&rev=536953
==============================================================================
Binary file - no diff available.
Propchange: forrest/site/docs_0_60/searching.pdf
------------------------------------------------------------------------------
svn:mime-type = application/pdf