forrest-svn mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cross...@apache.org
Subject svn commit: r193078 [9/65] - 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_70/ docs_0_70/howto/ docs_0_70/howto/cvs-ssh/ docs_0...
Date Thu, 23 Jun 2005 05:36:34 GMT
Added: forrest/site/docs_0_60/linking.html
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_60/linking.html?rev=193078&view=auto
==============================================================================
--- forrest/site/docs_0_60/linking.html (added)
+++ forrest/site/docs_0_60/linking.html Wed Jun 22 22:36:19 2005
@@ -0,0 +1,887 @@
+<!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">
+<div class="breadtrail">
+<a href="http://www.apache.org/">apache</a> &gt; <a href="http://forrest.apache.org/">forrest</a><script src="../skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script>
+</div>
+<div class="header">
+<div class="grouplogo">
+<a href="http://www.apache.org/"><img class="logoImage" alt="Apache" src="../images/apache-forrest.png" title="The Apache Software Foundation"></a>
+</div>
+<div class="projectlogo">
+<a href="http://forrest.apache.org/"><img class="logoImage" alt="Forrest" src="../images/project-logo.gif" title="Apache Forrest"></a>
+</div>
+<div class="searchbox">
+<form action="http://www.google.com/search" method="get" class="roundtopsmall">
+<input value="forrest.apache.org" name="sitesearch" type="hidden"><input onFocus="getBlank (this, 'Search the site with google');" size="25" name="q" id="query" type="text" value="Search the site with google">&nbsp; 
+                    <input attr="value" name="Search" value="Search" type="submit">
+</form>
+</div>
+<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>
+<a class="base-not-selected" href="../versions/index.html">Versioned Docs</a>
+</li>
+<li>
+<a class="base-not-selected" href="../pluginDocs/index.html">Plugins</a>
+</li>
+<li>
+<a class="base-not-selected" href="../tools/index.html">Tools</a>
+</li>
+</ul>
+</div>
+</div>
+<div id="main">
+<div id="publishedStrip">
+<div id="level2tabs"></div>
+<script type="text/javascript"><!--
+document.write("<text>Last Published:</text> " + document.lastModified);
+//  --></script>
+</div>
+<div class="breadtrail">
+             
+             &nbsp;
+           </div>
+<div id="menu">
+<div onclick="SwitchMenu('menu_selected_1.1', '../skin/')" id="menu_selected_1.1Title" class="menutitle" style="background-image: url('../skin/images/chapter_open.gif');">0.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="/versions/index.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>
+<div id="credit2">
+<a href="http://apachecon.com/"><img border="0" title="ApacheCon Europe 2005" alt="ApacheCon Europe 2005 - logo" src="http://apache.org/images/ac2005eu_135x50.gif" style="width: 135px;height: 50px;"></a>
+</div>
+</div>
+<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">
+<text>Font size:</text> 
+	          &nbsp;<input value="Reset" class="resetfont" title="Reset text" onclick="ndeSetTextSize('reset'); return false;" type="button">      
+	          &nbsp;<input value="-a" class="smallerfont" title="Shrink text" onclick="ndeSetTextSize('decr'); return false;" type="button">
+	          &nbsp;<input value="+a" class="biggerfont" title="Enlarge text" onclick="ndeSetTextSize('incr'); return false;" type="button">
+</div>
+<h1>Menus and Linking</h1>
+<div id="motd-area">
+        This is documentation for past version v0.6
+       (<a href="/versions/index.html">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 &lt;link href="site:v0.60//changes"&gt; 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">
+&lt;?xml version="1.0"?&gt;
+&lt;site label="Forrest" href="" tab="home"
+  xmlns="http://apache.org/forrest/linkmap/1.0"&gt;
+
+  &lt;about label="About"&gt;
+    &lt;index label="Index" href="index.html"/&gt;
+    &lt;license label="License" href="license.html"/&gt;
+    &lt;your-project label="Using Forrest" href="your-project.html"&gt;
+      &lt;new_content_type href="#adding_new_content_type"/&gt;
+    &lt;/your-project&gt;
+    &lt;linking label="Linking" href="linking.html"/&gt;
+    &lt;changes label="Changes" href="changes.html"/&gt;
+    &lt;todo label="Todo" href="todo.html"/&gt;
+    &lt;live-sites label="Live sites" href="live-sites.html"/&gt;
+  &lt;/about&gt;
+
+  &lt;community label="Community" href="community/" tab="community"&gt;
+    &lt;index label="About" href="index.html"/&gt;
+    &lt;howto-samples label="How-To Samples" href="howto/" tab="howto"&gt;
+      &lt;overview label="Overview" href="index.html"/&gt;
+      &lt;single-page label="Single Page" href="v10/howto-v10.html"/&gt;
+      &lt;multi-page label="Multi-Page" href="multi/"&gt;
+        &lt;intro label="Intro" href="howto-multi.html"/&gt;
+        &lt;step1 label="Step 1" href="step1.html"/&gt;
+        &lt;step2 label="Step 2" href="step2.html"/&gt;
+      &lt;/multi-page&gt;
+    &lt;/howto-samples&gt;
+  &lt;/community&gt;
+
+  &lt;references label="References"&gt;
+    &lt;gump label="Apache Gump" href="http://gump.apache.org/"/&gt;
+    &lt;cocoon label="Apache Cocoon" href="http://cocoon.apache.org/"/&gt;
+  &lt;/references&gt;
+
+  &lt;external-refs&gt;
+    &lt;mail-archive href="http://marc.theaimsgroup.com"/&gt;
+    &lt;xml.apache.org href="http://xml.apache.org/"&gt;
+      &lt;commons href="commons/"&gt;
+        &lt;resolver href="components/resolver/"/&gt;
+      &lt;/commons&gt;
+      &lt;fop href="fop/"/&gt;
+      &lt;batik href="batik/"/&gt;
+    &lt;/xml.apache.org&gt;
+
+    &lt;mail&gt;
+      &lt;semantic-linking href="http://marc.theaimsgroup.com/?l=forrest-dev
+        &amp;amp;m=103097808318773&amp;amp;w=2"/&gt;
+    &lt;/mail&gt;
+    &lt;cool-uris href="www.w3.org/Provider/Style/URI.html"/&gt;
+    &lt;uri-rfc href="http://zvon.org/tmRFC/RFC2396/Output/index.html"/&gt;
+
+  &lt;/external-refs&gt;
+&lt;/site&gt;
+        </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">
+&lt;tabs ...&gt;
+    &lt;tab id="home" label="Home" dir=""/&gt;
+    &lt;tab id="community" label="Community" dir="community" indexfile="mailLists.html"/&gt;
+    &lt;tab id="howto" label="How-Tos" dir="community/howto"/&gt;
+&lt;/tabs&gt;
+      </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">&nbsp;&nbsp;&nbsp;
+        <img alt="Community menu generated from site.xml" src="images/menu2.png">&nbsp;&nbsp;&nbsp;
+        <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">
+&lt;tab id="apache" label="XML Apache" href="http://xml.apache.org/"/&gt;
+        </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">
+&lt;site label="Forrest" href="" <strong>tab="home"</strong>
+  xmlns="http://apache.org/forrest/linkmap/1.0"&gt;
+
+  &lt;about label="About"&gt;
+    &lt;index label="Index" href="index.html"/&gt;
+    &lt;license label="License" href="license.html"/&gt;
+    &lt;your-project label="Using Forrest" href="your-project.html"&gt;
+      &lt;new_content_type href="#adding_new_content_type"/&gt;
+    &lt;/your-project&gt;
+    &lt;linking label="Linking" href="linking.html"/&gt;
+    ....
+  &lt;/about&gt;
+
+  &lt;community label="Community" href="community/" <strong>tab="community"</strong>&gt;
+    &lt;index label="About" href="index.html"/&gt;
+    &lt;howto-samples label="How-To Samples" href="howto/" <strong>tab="howto"</strong>&gt;
+      &lt;overview label="Overview" href="index.html"/&gt;
+      &lt;single-page label="Single Page" href="v10/howto-v10.html"/&gt;
+      &lt;multi label="Multi-Page" href="multi/"&gt;
+        &lt;intro label="Intro" href="howto-multi.html"/&gt;
+        &lt;step1 label="Step 1" href="step1.html"/&gt;
+      ...</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>&lt;about&gt;</strong> section has an implicit
+          <span class="codefrag">tab="home" </span>attribute.</p>
+<div class="frame 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>&lt;linking&gt;</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">&nbsp;&nbsp;&nbsp;
+            <img alt="community/ directory menu" src="images/dir-menu2.png">&nbsp;&nbsp;&nbsp;
+            <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">&lt;foo label="Foo" href="index.html"/&gt;</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">
+&lt;toc level="2" location="page"/&gt;
+      </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">
+          &lt;link href="todo.html"&gt;to-do list&lt;link&gt;
+        </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 &lt;link href="todo.html"&gt;,
+          write &lt;link href="site:v0.60//todo"&gt; 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="frame 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
+            &lt;external-refs&gt; 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">
+&lt;site&gt;
+  ...
+  &lt;external-refs&gt;
+    &lt;mail-archive href="http://marc.theaimsgroup.com"/&gt;
+    &lt;xml.apache.org href="http://xml.apache.org/"&gt;
+      &lt;commons href="commons/"&gt;
+        &lt;resolver href="components/resolver/"/&gt;
+      &lt;/commons&gt;
+    &lt;/xml.apache.org&gt;
+    ...
+  &lt;/external-refs&gt;
+&lt;/site&gt;</pre>
+<p>
+            As an example, &lt;link href="ext:commons/resolver"&gt;
+            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::&lt;Message-Id&gt;</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:&lt;searchterm&gt;</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&lt;at&gt;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:&lt;taskname&gt;</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>
+<div class="clearboth">&nbsp;</div>
+</div>
+<div id="footer">
+<div class="lastmodified">
+<script type="text/javascript"><!--
+document.write("<text>Last Published:</text> " + document.lastModified);
+//  --></script>
+</div>
+<div class="copyright">
+        Copyright &copy;
+         2002-2005 <a href="http://www.apache.org/licenses/">The Apache Software Foundation.</a>
+</div>
+</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/viewcvs/forrest/site/docs_0_60/linking.pdf?rev=193078&view=auto
==============================================================================
Binary file - no diff available.

Propchange: forrest/site/docs_0_60/linking.pdf
------------------------------------------------------------------------------
    svn:mime-type = application/pdf

Added: forrest/site/docs_0_60/project-sitemap.html
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_60/project-sitemap.html?rev=193078&view=auto
==============================================================================
--- forrest/site/docs_0_60/project-sitemap.html (added)
+++ forrest/site/docs_0_60/project-sitemap.html Wed Jun 22 22:36:19 2005
@@ -0,0 +1,315 @@
+<!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">
+<div class="breadtrail">
+<a href="http://www.apache.org/">apache</a> &gt; <a href="http://forrest.apache.org/">forrest</a><script src="../skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script>
+</div>
+<div class="header">
+<div class="grouplogo">
+<a href="http://www.apache.org/"><img class="logoImage" alt="Apache" src="../images/apache-forrest.png" title="The Apache Software Foundation"></a>
+</div>
+<div class="projectlogo">
+<a href="http://forrest.apache.org/"><img class="logoImage" alt="Forrest" src="../images/project-logo.gif" title="Apache Forrest"></a>
+</div>
+<div class="searchbox">
+<form action="http://www.google.com/search" method="get" class="roundtopsmall">
+<input value="forrest.apache.org" name="sitesearch" type="hidden"><input onFocus="getBlank (this, 'Search the site with google');" size="25" name="q" id="query" type="text" value="Search the site with google">&nbsp; 
+                    <input attr="value" name="Search" value="Search" type="submit">
+</form>
+</div>
+<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>
+<a class="base-not-selected" href="../versions/index.html">Versioned Docs</a>
+</li>
+<li>
+<a class="base-not-selected" href="../pluginDocs/index.html">Plugins</a>
+</li>
+<li>
+<a class="base-not-selected" href="../tools/index.html">Tools</a>
+</li>
+</ul>
+</div>
+</div>
+<div id="main">
+<div id="publishedStrip">
+<div id="level2tabs"></div>
+<script type="text/javascript"><!--
+document.write("<text>Last Published:</text> " + document.lastModified);
+//  --></script>
+</div>
+<div class="breadtrail">
+             
+             &nbsp;
+           </div>
+<div id="menu">
+<div onclick="SwitchMenu('menu_selected_1.1', '../skin/')" id="menu_selected_1.1Title" class="menutitle" style="background-image: url('../skin/images/chapter_open.gif');">0.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="/versions/index.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>
+<div id="credit2">
+<a href="http://apachecon.com/"><img border="0" title="ApacheCon Europe 2005" alt="ApacheCon Europe 2005 - logo" src="http://apache.org/images/ac2005eu_135x50.gif" style="width: 135px;height: 50px;"></a>
+</div>
+</div>
+<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">
+<text>Font size:</text> 
+	          &nbsp;<input value="Reset" class="resetfont" title="Reset text" onclick="ndeSetTextSize('reset'); return false;" type="button">      
+	          &nbsp;<input value="-a" class="smallerfont" title="Shrink text" onclick="ndeSetTextSize('decr'); return false;" type="button">
+	          &nbsp;<input value="+a" class="biggerfont" title="Enlarge text" onclick="ndeSetTextSize('incr'); return false;" type="button">
+</div>
+<h1>Using project sitemaps</h1>
+<div id="motd-area">
+        This is documentation for past version v0.6
+       (<a href="/versions/index.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 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_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>
+<div class="clearboth">&nbsp;</div>
+</div>
+<div id="footer">
+<div class="lastmodified">
+<script type="text/javascript"><!--
+document.write("<text>Last Published:</text> " + document.lastModified);
+//  --></script>
+</div>
+<div class="copyright">
+        Copyright &copy;
+         2002-2005 <a href="http://www.apache.org/licenses/">The Apache Software Foundation.</a>
+</div>
+</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/viewcvs/forrest/site/docs_0_60/project-sitemap.pdf?rev=193078&view=auto
==============================================================================
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/viewcvs/forrest/site/docs_0_60/searching.html?rev=193078&view=auto
==============================================================================
--- forrest/site/docs_0_60/searching.html (added)
+++ forrest/site/docs_0_60/searching.html Wed Jun 22 22:36:19 2005
@@ -0,0 +1,368 @@
+<!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">
+<div class="breadtrail">
+<a href="http://www.apache.org/">apache</a> &gt; <a href="http://forrest.apache.org/">forrest</a><script src="../skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script>
+</div>
+<div class="header">
+<div class="grouplogo">
+<a href="http://www.apache.org/"><img class="logoImage" alt="Apache" src="../images/apache-forrest.png" title="The Apache Software Foundation"></a>
+</div>
+<div class="projectlogo">
+<a href="http://forrest.apache.org/"><img class="logoImage" alt="Forrest" src="../images/project-logo.gif" title="Apache Forrest"></a>
+</div>
+<div class="searchbox">
+<form action="http://www.google.com/search" method="get" class="roundtopsmall">
+<input value="forrest.apache.org" name="sitesearch" type="hidden"><input onFocus="getBlank (this, 'Search the site with google');" size="25" name="q" id="query" type="text" value="Search the site with google">&nbsp; 
+                    <input attr="value" name="Search" value="Search" type="submit">
+</form>
+</div>
+<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>
+<a class="base-not-selected" href="../versions/index.html">Versioned Docs</a>
+</li>
+<li>
+<a class="base-not-selected" href="../pluginDocs/index.html">Plugins</a>
+</li>
+<li>
+<a class="base-not-selected" href="../tools/index.html">Tools</a>
+</li>
+</ul>
+</div>
+</div>
+<div id="main">
+<div id="publishedStrip">
+<div id="level2tabs"></div>
+<script type="text/javascript"><!--
+document.write("<text>Last Published:</text> " + document.lastModified);
+//  --></script>
+</div>
+<div class="breadtrail">
+             
+             &nbsp;
+           </div>
+<div id="menu">
+<div onclick="SwitchMenu('menu_selected_1.1', '../skin/')" id="menu_selected_1.1Title" class="menutitle" style="background-image: url('../skin/images/chapter_open.gif');">0.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="/versions/index.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>
+<div id="credit2">
+<a href="http://apachecon.com/"><img border="0" title="ApacheCon Europe 2005" alt="ApacheCon Europe 2005 - logo" src="http://apache.org/images/ac2005eu_135x50.gif" style="width: 135px;height: 50px;"></a>
+</div>
+</div>
+<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">
+<text>Font size:</text> 
+	          &nbsp;<input value="Reset" class="resetfont" title="Reset text" onclick="ndeSetTextSize('reset'); return false;" type="button">      
+	          &nbsp;<input value="-a" class="smallerfont" title="Shrink text" onclick="ndeSetTextSize('decr'); return false;" type="button">
+	          &nbsp;<input value="+a" class="biggerfont" title="Enlarge text" onclick="ndeSetTextSize('incr'); return false;" type="button">
+</div>
+<h1>Searching Forrest-built documentation</h1>
+<div id="motd-area">
+        This is documentation for past version v0.6
+       (<a href="/versions/index.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">&lt;search&gt;</span>
+	element; it should be near the top of the file. If the element
+	does not exist, create it below the
+	<span class="codefrag">&lt;skinconfig&gt;</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">&lt;search name="MyProject"
+	domain="myproject.com"/&gt;</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">&lt;search&gt;</span> element. If the element does not
+	exist, insert it right underneath the
+	<span class="codefrag">&lt;skinconfig&gt;</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">&lt;search name="MyProject" domain="myproject.com"
+	provider="lucene"/&gt;</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">&lt;search&gt;</span> element.</p>
+</div>
+  
+</div>
+<div class="clearboth">&nbsp;</div>
+</div>
+<div id="footer">
+<div class="lastmodified">
+<script type="text/javascript"><!--
+document.write("<text>Last Published:</text> " + document.lastModified);
+//  --></script>
+</div>
+<div class="copyright">
+        Copyright &copy;
+         2002-2005 <a href="http://www.apache.org/licenses/">The Apache Software Foundation.</a>
+</div>
+</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/viewcvs/forrest/site/docs_0_60/searching.pdf?rev=193078&view=auto
==============================================================================
Binary file - no diff available.

Propchange: forrest/site/docs_0_60/searching.pdf
------------------------------------------------------------------------------
    svn:mime-type = application/pdf



Mime
View raw message