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

Added: forrest/site/docs_0_100/linking.html
URL: http://svn.apache.org/viewvc/forrest/site/docs_0_100/linking.html?rev=1068306&view=auto
==============================================================================
--- forrest/site/docs_0_100/linking.html (added)
+++ forrest/site/docs_0_100/linking.html Tue Feb 8 09:44:46 2011
@@ -0,0 +1,1128 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<meta content="Apache Forrest" name="Generator">
+<meta name="Forrest-version" content="0.10-dev">
+<meta name="Forrest-skin-name" content="pelt">
+<title>Menus and Linking (v0.10-dev)</title>
+<link type="text/css" href="../skin/basic.css" rel="stylesheet">
+<link media="screen" type="text/css" href="../skin/screen.css" rel="stylesheet">
+<link media="print" type="text/css" href="../skin/print.css" rel="stylesheet">
+<link type="text/css" href="../skin/profile.css" rel="stylesheet">
+<script src="../skin/getBlank.js" language="javascript" type="text/javascript"></script><script src="../skin/getMenu.js" language="javascript" type="text/javascript"></script><script src="../skin/fontsize.js" language="javascript" type="text/javascript"></script>
+<link rel="shortcut icon" href="../favicon.ico">
+</head>
+<body onload="init()">
+<script type="text/javascript">ndeSetTextSize();</script>
+<div id="top">
+
+<div class="breadtrail">
+<a href="http://www.apache.org/">Apache Software Foundation</a> > <a href="http://forrest.apache.org/">Apache Forrest</a><script src="../skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script>
+</div>
+
+<div class="header">
+
+<div class="grouplogo">
+<a href="http://www.apache.org/"><img class="logoImage" alt="Apache" src="../images/apache-forrest.png" title="The Apache Software Foundation"></a>
+</div>
+
+
+<div class="projectlogo">
+<a href="http://forrest.apache.org/"><img class="logoImage" alt="Forrest" src="../images/project-logo.gif" title="Apache Forrest"></a>
+</div>
+
+
+<div class="searchbox">
+<form action="http://www.google.com/search" method="get" class="roundtopsmall">
+<input value="forrest.apache.org" name="sitesearch" type="hidden"><input onFocus="getBlank (this, 'Search the site with google');" size="25" name="q" id="query" type="text" value="Search the site with google"> 
+ <input name="Search" value="Search" type="submit">
+</form>
+</div>
+
+
+<ul id="tabs">
+<li>
+<a class="unselected" href="../index.html">Welcome</a>
+</li>
+<li>
+<a class="unselected" href="../contrib.html">Developers</a>
+</li>
+<li class="current">
+<a class="selected" href="../versions/index.html">Versioned Docs</a>
+</li>
+<li>
+<a class="unselected" href="../pluginDocs/index.html">Plugins</a>
+</li>
+<li>
+<a class="unselected" href="../tools/index.html">Tools</a>
+</li>
+</ul>
+
+</div>
+</div>
+<div id="main">
+<div id="publishedStrip">
+
+<div id="level2tabs">
+<a class="unselected" href="../docs_0_90/index.html">0.90 (current)</a><a class="selected" href="../docs_0_100/index.html">0.100-dev (under development)</a><a class="unselected" href="../docs_0_80/index.html">0.80 (past)</a>
+</div>
+
+<script type="text/javascript"></script>
+</div>
+
+<div class="breadtrail">
+
+  
+ </div>
+
+
+<div id="menu">
+<div onclick="SwitchMenu('menu_selected_1.1', '../skin/')" id="menu_selected_1.1Title" class="menutitle" style="background-image: url('../skin/images/chapter_open.gif');">0.100-dev</div>
+<div id="menu_selected_1.1" class="selectedmenuitemgroup" style="display: block;">
+<div class="menuitem">
+<a href="../docs_0_100/index.html">Overview</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/your-project.html">Using Forrest</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3', '../skin/')" id="menu_1.1.3Title" class="menutitle">How-To</div>
+<div id="menu_1.1.3" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_100/howto/index.html">Overview</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3.2', '../skin/')" id="menu_1.1.3.2Title" class="menutitle">Install Forrest</div>
+<div id="menu_1.1.3.2" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_100/build.html" title="Build and install the current unreleased version">Building Forrest from Source</a>
+</div>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/upgrading_010.html">Upgrading to 0.10-dev</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3.4', '../skin/')" id="menu_1.1.3.4Title" class="menutitle">Customize Forrest</div>
+<div id="menu_1.1.3.4" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_100/sitemap-explain.html">Sitemaps explained</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/howto/howto-custom-html-source.html">Custom html source</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/project-sitemap.html">Project sitemap</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/howto/howto-editcss.html">Edit CSS (WYSIWYG)</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/howto/howto-pdf-tab.html" title="Generate one pdf-document for all pages of a tab">Create tab PDF</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/howto/howto-corner-images.html">CSS corner SVG</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3.5', '../skin/')" id="menu_1.1.3.5Title" class="menutitle">Integrate Forrest with tools</div>
+<div id="menu_1.1.3.5" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_100/howto/howto-forrest-from-maven.html">Maven Integration</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/catalog.html">Using DTD Catalogs</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3.6', '../skin/')" id="menu_1.1.3.6Title" class="menutitle">Extend Forrest</div>
+<div id="menu_1.1.3.6" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_100/howto/howto-buildPlugin.html">Build a Plugin</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/skin-package.html">Package new Skins</a>
+</div>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/howto/howto-asf-mirror.html">Download mirror</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3.8', '../skin/')" id="menu_1.1.3.8Title" class="menutitle">Adding Documentation</div>
+<div id="menu_1.1.3.8" class="menuitemgroup">
+<div class="menuitem">
+<a href="../howto-howto.html" title="Instructions for writing a new howto-document">Write a How-to</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3.8.2', '../skin/')" id="menu_1.1.3.8.2Title" class="menutitle">Multipage HowTo</div>
+<div id="menu_1.1.3.8.2" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_100/howto/multi/howto-multi.html">Introduction</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/howto/multi/step1.html">Step 1</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/howto/multi/step2.html">Step 2</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/howto/multi/step3.html">Step 3</a>
+</div>
+</div>
+</div>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/faq.html">FAQs</a>
+</div>
+<div onclick="SwitchMenu('menu_selected_1.1.5', '../skin/')" id="menu_selected_1.1.5Title" class="menutitle" style="background-image: url('../skin/images/chapter_open.gif');">Background</div>
+<div id="menu_selected_1.1.5" class="selectedmenuitemgroup" style="display: block;">
+<div class="menupage">
+<div class="menupagetitle">Menus and Linking</div>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/searching.html">Search Options in Forrest</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/locationmap.html">Locationmap</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/properties.html">Properties system</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/sitemap-ref.html">Sitemap Reference</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/skins.html" title="About default skins, their naming and features">Skins</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/status-themes.html">Dispatcher versus Skins</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/cap.html">Sourcetype Action</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/validation.html">XML validation and entity resolution</a>
+</div>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/changes.html">Changes</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/glossary.html">Glossary</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.8', '../skin/')" id="menu_1.1.8Title" class="menutitle">Reference docs</div>
+<div id="menu_1.1.8" class="menuitemgroup">
+<div onclick="SwitchMenu('menu_1.1.8.1', '../skin/')" id="menu_1.1.8.1Title" class="menutitle">DTD documentation</div>
+<div id="menu_1.1.8.1" class="menuitemgroup">
+<div class="menuitem">
+<a href="../dtdx/dtd-docs.html">Overview</a>
+</div>
+<div class="menuitem">
+<a href="../dtdx/document-v20.dtdx.html">document-v20</a>
+</div>
+<div class="menuitem">
+<a href="../dtdx/howto-v20.dtdx.html">howto-v20</a>
+</div>
+<div class="menuitem">
+<a href="../dtdx/faq-v20.dtdx.html">faq-v20</a>
+</div>
+<div class="menuitem">
+<a href="../dtdx/document-v13.dtdx.html">document-v13</a>
+</div>
+<div class="menuitem">
+<a href="../dtdx/howto-v13.dtdx.html">howto-v13</a>
+</div>
+<div class="menuitem">
+<a href="../dtdx/faq-v13.dtdx.html">faq-v13</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.8.2', '../skin/')" id="menu_1.1.8.2Title" class="menutitle">Doc samples</div>
+<div id="menu_1.1.8.2" class="menuitemgroup">
+<div class="menuitem">
+<a href="../dtdx/document-v13.html">document-v13</a>
+</div>
+<div class="menuitem">
+<a href="../dtdx/document-v20.html">document-v20</a>
+</div>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.9', '../skin/')" id="menu_1.1.9Title" class="menutitle">Older Docs</div>
+<div id="menu_1.1.9" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_100/primer.html">Forrest Primer</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/libre-intro.html">Libre</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/dreams.html">Dream list</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/howto/cvs-ssh/howto-cvs-ssh.html">CVS over SSH</a>
+</div>
+</div>
+</div>
+<div id="credit">
+<hr>
+ This is documentation for development version v0.10-dev
+ (<a href="http://forrest.apache.org/versions/">More</a>)</div>
+<div id="roundbottom">
+<img style="display: none" class="corner" height="15" width="15" alt="" src="../skin/images/rc-b-l-15-1body-2menu-3menu.png"></div>
+
+<div id="credit2">
+<a href="http://www.apache.org/events/current-event.html"><img border="0" title="ApacheCon" alt="ApacheCon - logo" src="http://www.apache.org/events/current-event-125x125.png" style="width: 125px;height: 125px;"></a>
+</div>
+</div>
+
+
+<div id="content">
+<div class="trail">Font size:
+  <input value="Reset" class="resetfont" title="Reset text" onclick="ndeSetTextSize('reset'); return false;" type="button">
+  <input value="-a" class="smallerfont" title="Shrink text" onclick="ndeSetTextSize('decr'); return false;" type="button">
+  <input value="+a" class="biggerfont" title="Enlarge text" onclick="ndeSetTextSize('incr'); return false;" type="button">
+</div>
+<h1>Menus and Linking</h1>
+<div id="front-matter">
+<div id="motd-area">
+ This is documentation for development version v0.10-dev
+ (<a href="http://forrest.apache.org/versions/">More</a>)</div>
+<div id="minitoc-area">
+<ul class="minitoc">
+<li>
+<a href="#intro">Introduction</a>
+</li>
+<li>
+<a href="#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>
+<li>
+<a href="#tab-site">Configuring the interaction between tabs.xml and site.xml</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>
+</div>
+
+<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>
+<p>
+ While reading this document, bear in mind that the Cocoon
+ <a href="../docs_0_100/sitemap-ref.html">Sitemap</a> is handling the processing.
+ The sitemaps are resolving the site: URIs and then matching them to
+ determine how to process each. In general, you can use the power of the
+ Cocoon Sitemap to handle certain difficult linking and menu situations
+ (for example see this <a href="../docs_0_100/faq.html#tab-index">FAQ</a>).
+ </p>
+</div>
+
+<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="#indirect-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: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> ...
+ </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>
+<p>
+ See another <a href="../docs_0_100/faq.html#site-xml">explained example</a>.
+ Also remember to look at the comprehensive example with Forrest's own
+ documentation.
+ </p>
+</div>
+
+<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="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="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="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="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="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="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". However the interaction of <span class="codefrag">tabs.xml</span> and <span class="codefrag">site.xml</span> while powerful, can
+ be complex to establish.
+ </p>
+<a name="tab-site"></a>
+<h3 class="underlined_5">Configuring the interaction between tabs.xml and site.xml</h3>
+<p>
+ This is a collection of tips to assist with getting your menus and
+ tabs to properly display.
+ </p>
+<ul>
+
+<li>
+ See the various notes above, not repeated in this list of tips.
+ </li>
+
+<li>
+ View your site's
+ <a href="../abs-menulinks">abs-menulinks</a> pipeline in a
+ browser. This is part of the internal Cocoon machinery, but like
+ other sitemap resources, it is useful to view them to assist with
+ debugging.
+ </li>
+
+<li>
+ The Forrest website also accompanies your software release
+ in the <span class="codefrag">site-author</span> directory, so
+ inspect its <span class="codefrag">tabs.xml</span> and <span class="codefrag">site.xml</span> to see how it is done. Also see the
+ 'forrest seed site' example. It is not as complex as the Forrest website.
+ </li>
+
+<li>
+ When you are fiddling with your attributes, change one thing at a time
+ and document what you have changed.</li>
+
+<li>
+ The value of the tab @id attribute cannot begin with a digit.
+ Likewise, element names in <span class="codefrag">tabs.xml</span> and <span class="codefrag">site.xml</span> cannot begin with a digit.
+ </li>
+
+<li>
+ Add label attributes to <span class="codefrag">site.xml</span> elements to make the menus show.
+ With nested elements in <span class="codefrag">site.xml</span> if the outer element does not have a label
+ attribute then the inner elements will not be displayed.
+ </li>
+
+<li>
+ To cause tabs and menu items to be highlighted, there need to be
+ corresponding elements in <span class="codefrag">site.xml</span> that have href attributes which match
+ the relevant path.
+ See
+ <a href="http://www.mail-archive.com/user%40forrest.apache.org/msg01750.html">email explanation</a>.
+ </li>
+
+<li>
+ When the tab points to a directory, then to make the tab highlighted
+ when selected, you need an element which matches index.html within the
+ group of elements that define the menus for this tab in the <span class="codefrag">site.xml</span>
+ file. That element can be without a label attribute, so that it doesn't
+ display as a menu item. However doing that causes that tab's menus
+ to be collapsed.
+ </li>
+
+<li>
+ Q: The tab link in my site assumes that 'index.html'
+ is present in the linked-to directory. How do I fix this?
+ A: In <span class="codefrag">tabs.xml</span> use @href instead of @dir attribute and omit the trailing '/'.
+ Which file to serve is then a concern of the sitemap.
+ See more at the <a href="../docs_0_100/faq.html#tab-index">FAQ</a>.
+ </li>
+
+</ul>
+</div>
+
+<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="linking"></a>
+<h2 class="underlined_10">Linking systems</h2>
+<div class="section">
+<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">
+ <a href="todo.html">to-do list<a>
+ </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="indirect-linking"></a>
+<h3 class="underlined_5">Indirect linking</h3>
+<p>
+ Forrest's solution is simple: instead of <a href="todo.html">,
+ write <a href="site: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="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="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, <a href="ext:commons/resolver"> generates the
+ link
+ <a href="http://xml.apache.org/commons/components/resolver/">http://xml.apache.org/commons/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="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="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.Some</td>
+ <td colspan="1" rowspan="1"><span class="codefrag">../../apidocs/org/apache/proj/Some.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.info?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.example.org/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="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="implementation"></a>
+<h2 class="underlined_10">Implementation</h2>
+<div class="section">
+<p>
+ Full details on the implementation of
+ <a href="../docs_0_100/sitemap-ref.html#linkrewriting_impl">link rewriting</a> and
+ <a href="../docs_0_100/sitemap-ref.html#menu_generation_impl">menu generation</a> are
+ available in the <a href="../docs_0_100/sitemap-ref.html">Sitemap Reference</a>
+
+</p>
+</div>
+
+</div>
+
+<div class="clearboth"> </div>
+</div>
+<div id="footer">
+
+<div class="lastmodified">
+<script type="text/javascript"></script>
+</div>
+<div class="copyright">
+ Copyright ©
+ 2002-2011 <a href="http://www.apache.org/licenses/">The Apache Software Foundation. Licensed under Apache License 2.0</a>
+<br>
+ Apache Forrest, Forrest, Apache, the Apache feather logo, and the Apache Forrest
+ logos are trademarks of The Apache Software Foundation.
+ </div>
+
+</div>
+</body>
+</html>

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

Added: forrest/site/docs_0_100/locationmap.html
URL: http://svn.apache.org/viewvc/forrest/site/docs_0_100/locationmap.html?rev=1068306&view=auto
==============================================================================
--- forrest/site/docs_0_100/locationmap.html (added)
+++ forrest/site/docs_0_100/locationmap.html Tue Feb 8 09:44:46 2011
@@ -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.10-dev">
+<meta name="Forrest-skin-name" content="pelt">
+<title>Locationmaps (v0.10-dev)</title>
+<link type="text/css" href="../skin/basic.css" rel="stylesheet">
+<link media="screen" type="text/css" href="../skin/screen.css" rel="stylesheet">
+<link media="print" type="text/css" href="../skin/print.css" rel="stylesheet">
+<link type="text/css" href="../skin/profile.css" rel="stylesheet">
+<script src="../skin/getBlank.js" language="javascript" type="text/javascript"></script><script src="../skin/getMenu.js" language="javascript" type="text/javascript"></script><script src="../skin/fontsize.js" language="javascript" type="text/javascript"></script>
+<link rel="shortcut icon" href="../favicon.ico">
+</head>
+<body onload="init()">
+<script type="text/javascript">ndeSetTextSize();</script>
+<div id="top">
+
+<div class="breadtrail">
+<a href="http://www.apache.org/">Apache Software Foundation</a> > <a href="http://forrest.apache.org/">Apache Forrest</a><script src="../skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script>
+</div>
+
+<div class="header">
+
+<div class="grouplogo">
+<a href="http://www.apache.org/"><img class="logoImage" alt="Apache" src="../images/apache-forrest.png" title="The Apache Software Foundation"></a>
+</div>
+
+
+<div class="projectlogo">
+<a href="http://forrest.apache.org/"><img class="logoImage" alt="Forrest" src="../images/project-logo.gif" title="Apache Forrest"></a>
+</div>
+
+
+<div class="searchbox">
+<form action="http://www.google.com/search" method="get" class="roundtopsmall">
+<input value="forrest.apache.org" name="sitesearch" type="hidden"><input onFocus="getBlank (this, 'Search the site with google');" size="25" name="q" id="query" type="text" value="Search the site with google"> 
+ <input name="Search" value="Search" type="submit">
+</form>
+</div>
+
+
+<ul id="tabs">
+<li>
+<a class="unselected" href="../index.html">Welcome</a>
+</li>
+<li>
+<a class="unselected" href="../contrib.html">Developers</a>
+</li>
+<li class="current">
+<a class="selected" href="../versions/index.html">Versioned Docs</a>
+</li>
+<li>
+<a class="unselected" href="../pluginDocs/index.html">Plugins</a>
+</li>
+<li>
+<a class="unselected" href="../tools/index.html">Tools</a>
+</li>
+</ul>
+
+</div>
+</div>
+<div id="main">
+<div id="publishedStrip">
+
+<div id="level2tabs">
+<a class="unselected" href="../docs_0_90/index.html">0.90 (current)</a><a class="selected" href="../docs_0_100/index.html">0.100-dev (under development)</a><a class="unselected" href="../docs_0_80/index.html">0.80 (past)</a>
+</div>
+
+<script type="text/javascript"></script>
+</div>
+
+<div class="breadtrail">
+
+  
+ </div>
+
+
+<div id="menu">
+<div onclick="SwitchMenu('menu_selected_1.1', '../skin/')" id="menu_selected_1.1Title" class="menutitle" style="background-image: url('../skin/images/chapter_open.gif');">0.100-dev</div>
+<div id="menu_selected_1.1" class="selectedmenuitemgroup" style="display: block;">
+<div class="menuitem">
+<a href="../docs_0_100/index.html">Overview</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/your-project.html">Using Forrest</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3', '../skin/')" id="menu_1.1.3Title" class="menutitle">How-To</div>
+<div id="menu_1.1.3" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_100/howto/index.html">Overview</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3.2', '../skin/')" id="menu_1.1.3.2Title" class="menutitle">Install Forrest</div>
+<div id="menu_1.1.3.2" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_100/build.html" title="Build and install the current unreleased version">Building Forrest from Source</a>
+</div>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/upgrading_010.html">Upgrading to 0.10-dev</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3.4', '../skin/')" id="menu_1.1.3.4Title" class="menutitle">Customize Forrest</div>
+<div id="menu_1.1.3.4" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_100/sitemap-explain.html">Sitemaps explained</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/howto/howto-custom-html-source.html">Custom html source</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/project-sitemap.html">Project sitemap</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/howto/howto-editcss.html">Edit CSS (WYSIWYG)</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/howto/howto-pdf-tab.html" title="Generate one pdf-document for all pages of a tab">Create tab PDF</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/howto/howto-corner-images.html">CSS corner SVG</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3.5', '../skin/')" id="menu_1.1.3.5Title" class="menutitle">Integrate Forrest with tools</div>
+<div id="menu_1.1.3.5" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_100/howto/howto-forrest-from-maven.html">Maven Integration</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/catalog.html">Using DTD Catalogs</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3.6', '../skin/')" id="menu_1.1.3.6Title" class="menutitle">Extend Forrest</div>
+<div id="menu_1.1.3.6" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_100/howto/howto-buildPlugin.html">Build a Plugin</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/skin-package.html">Package new Skins</a>
+</div>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/howto/howto-asf-mirror.html">Download mirror</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3.8', '../skin/')" id="menu_1.1.3.8Title" class="menutitle">Adding Documentation</div>
+<div id="menu_1.1.3.8" class="menuitemgroup">
+<div class="menuitem">
+<a href="../howto-howto.html" title="Instructions for writing a new howto-document">Write a How-to</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.3.8.2', '../skin/')" id="menu_1.1.3.8.2Title" class="menutitle">Multipage HowTo</div>
+<div id="menu_1.1.3.8.2" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_100/howto/multi/howto-multi.html">Introduction</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/howto/multi/step1.html">Step 1</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/howto/multi/step2.html">Step 2</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/howto/multi/step3.html">Step 3</a>
+</div>
+</div>
+</div>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/faq.html">FAQs</a>
+</div>
+<div onclick="SwitchMenu('menu_selected_1.1.5', '../skin/')" id="menu_selected_1.1.5Title" class="menutitle" style="background-image: url('../skin/images/chapter_open.gif');">Background</div>
+<div id="menu_selected_1.1.5" class="selectedmenuitemgroup" style="display: block;">
+<div class="menuitem">
+<a href="../docs_0_100/linking.html">Menus and Linking</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/searching.html">Search Options in Forrest</a>
+</div>
+<div class="menupage">
+<div class="menupagetitle">Locationmap</div>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/properties.html">Properties system</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/sitemap-ref.html">Sitemap Reference</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/skins.html" title="About default skins, their naming and features">Skins</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/status-themes.html">Dispatcher versus Skins</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/cap.html">Sourcetype Action</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/validation.html">XML validation and entity resolution</a>
+</div>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/changes.html">Changes</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/glossary.html">Glossary</a>
+</div>
+<div onclick="SwitchMenu('menu_1.1.8', '../skin/')" id="menu_1.1.8Title" class="menutitle">Reference docs</div>
+<div id="menu_1.1.8" class="menuitemgroup">
+<div onclick="SwitchMenu('menu_1.1.8.1', '../skin/')" id="menu_1.1.8.1Title" class="menutitle">DTD documentation</div>
+<div id="menu_1.1.8.1" class="menuitemgroup">
+<div class="menuitem">
+<a href="../dtdx/dtd-docs.html">Overview</a>
+</div>
+<div class="menuitem">
+<a href="../dtdx/document-v20.dtdx.html">document-v20</a>
+</div>
+<div class="menuitem">
+<a href="../dtdx/howto-v20.dtdx.html">howto-v20</a>
+</div>
+<div class="menuitem">
+<a href="../dtdx/faq-v20.dtdx.html">faq-v20</a>
+</div>
+<div class="menuitem">
+<a href="../dtdx/document-v13.dtdx.html">document-v13</a>
+</div>
+<div class="menuitem">
+<a href="../dtdx/howto-v13.dtdx.html">howto-v13</a>
+</div>
+<div class="menuitem">
+<a href="../dtdx/faq-v13.dtdx.html">faq-v13</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.8.2', '../skin/')" id="menu_1.1.8.2Title" class="menutitle">Doc samples</div>
+<div id="menu_1.1.8.2" class="menuitemgroup">
+<div class="menuitem">
+<a href="../dtdx/document-v13.html">document-v13</a>
+</div>
+<div class="menuitem">
+<a href="../dtdx/document-v20.html">document-v20</a>
+</div>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.9', '../skin/')" id="menu_1.1.9Title" class="menutitle">Older Docs</div>
+<div id="menu_1.1.9" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_100/primer.html">Forrest Primer</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/libre-intro.html">Libre</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/dreams.html">Dream list</a>
+</div>
+<div class="menuitem">
+<a href="../docs_0_100/howto/cvs-ssh/howto-cvs-ssh.html">CVS over SSH</a>
+</div>
+</div>
+</div>
+<div id="credit">
+<hr>
+ This is documentation for development version v0.10-dev
+ (<a href="http://forrest.apache.org/versions/">More</a>)</div>
+<div id="roundbottom">
+<img style="display: none" class="corner" height="15" width="15" alt="" src="../skin/images/rc-b-l-15-1body-2menu-3menu.png"></div>
+
+<div id="credit2">
+<a href="http://www.apache.org/events/current-event.html"><img border="0" title="ApacheCon" alt="ApacheCon - logo" src="http://www.apache.org/events/current-event-125x125.png" style="width: 125px;height: 125px;"></a>
+</div>
+</div>
+
+
+<div id="content">
+<div class="trail">Font size:
+  <input value="Reset" class="resetfont" title="Reset text" onclick="ndeSetTextSize('reset'); return false;" type="button">
+  <input value="-a" class="smallerfont" title="Shrink text" onclick="ndeSetTextSize('decr'); return false;" type="button">
+  <input value="+a" class="biggerfont" title="Enlarge text" onclick="ndeSetTextSize('incr'); return false;" type="button">
+</div>
+<h1>Locationmaps</h1>
+<div id="front-matter">
+<div id="motd-area">
+ This is documentation for development version v0.10-dev
+ (<a href="http://forrest.apache.org/versions/">More</a>)</div>
+<div id="minitoc-area">
+<ul class="minitoc">
+<li>
+<a href="#overview">About Locationmaps</a>
+</li>
+<li>
+<a href="#namingConvention">Naming Convention</a>
+</li>
+<li>
+<a href="#process">Explanation of Locationmap processing</a>
+</li>
+<li>
+<a href="#selector">Multiple Location Selectors</a>
+</li>
+<li>
+<a href="#examples">Other Locationmap examples</a>
+<ul class="minitoc">
+<li>
+<a href="#source-via-http">Retrieving an XDoc via HTTP</a>
+</li>
+<li>
+<a href="#source-from-remote-cms">Retrieving HTML from a CMS</a>
+</li>
+<li>
+<a href="#enhancePDFOutput">Enhanced PDF-output plugin</a>
+</li>
+<li>
+<a href="#sourceResolving">Source Resolving</a>
+</li>
+<li>
+<a href="#linkrewriting">Link Rewriting</a>
+</li>
+<li>
+<a href="#debugging">Debugging Locationmaps</a>
+</li>
+</ul>
+</li>
+</ul>
+</div>
+</div>
+
+<a name="overview"></a>
+<h2 class="underlined_10">About Locationmaps</h2>
+<div class="section">
+<p>
+ A locationmap defines a mapping from requests to location strings.
+ </p>
+<p>
+ It was conceived to:
+ </p>
+<ul>
+
+<li>Provide a more powerful means for semantic linking.</li>
+
+<li>Enable Forrest with a standard configuration override mechanism.</li>
+
+<li>Decouple the conceptual source space used by Cocoon from
+ the concrete source space, so that a change in the concrete sources
+ does not impact on the sitemap.</li>
+
+</ul>
+<p>
+ In other words, the locationmap enables content to be retrieved from a
+ location that is defined in a locationmap file (located at
+ <span class="codefrag">PROJECT_HOME/src/documentation/content/locationmap.xml</span>
+ file. The advantage of this is that the URL seen by the user need bear
+ no relation to the location of the source document, thus Forrest can
+ separate the client URL space from the source document URL space. Thus,
+ using the locationmap it is possible to pull together documents from
+ many different locations into a single uniform site.
+ </p>
+<p>
+ In addition, since the user URL space is now not connected to the source
+ URL space it is possible to move source documents without breaking any
+ existing user links.
+ </p>
+<p>
+ The syntax of a locationmap resembles that of the sitemap, in that it
+ also makes use of Matchers and Selectors to traverse a tree of nodes
+ towards a leaf. In the case of the locationmap however the leaf does not
+ identify a pipeline, but instead identifies a location string.
+ </p>
+<p>
+ Apache Forrest looks in the standard location for the source file first
+ (by default <span class="codefrag">PROJECT_HOME/src/documentation/content/...</span>), if
+ a file is found in this location then the locationmap is not consulted.
+ However, if one is not found then the locationmap is used to resolve the
+ source file. The locationmap is resolved via the core sitemap, this
+ means that you can generate it dynamically if you so wish. Simply add a
+ match that looks something like this to your projects sitemap:
+ </p>
+<pre class="code">
+
+ <map:match pattern="locationmap-project.xml">
+ <map:generate src="..."/>
+ <map:transform src="..."/>
+ <map:serialize type="xml"/>
+ </map:match>
+
+ </pre>
+</div>
+
+<a name="namingConvention"></a>
+<h2 class="underlined_10">Naming Convention</h2>
+<div class="section">
+<p>
+ For those that are familiar with name resolution servers or the Handles
+ Service, it might be easier to think of the locationmap as a name
+ resolution module or sort of a handle resolution module that it accepts
+ "names" or whatever you desire to call these "hints" and returns the
+ location.
+ </p>
+<p>
+ The thought is that by using hints that look a little like a file name
+ it disguises what locationmaps are really doing for us. By using
+ URN-style names, we are truly disassociating the name/hint from the
+ physical location.
+ </p>
+<p>
+ For example, here is a locationmap entry based purely on filename:
+ </p>
+<pre class="code">
+
+<map:transform src="{lm:html-to-document.xsl}"/>
+
+ </pre>
+<p>
+ and here is that same entry using a "name" style. One implies a certain
+ physical location, whereas the one below is truly a name that needs to
+ be resolved to a physical location.
+ </p>
+<pre class="code">
+
+<map:transform src="{lm:transform.html.document}"/>
+
+ </pre>
+<p>
+ Locationmaps are also used by plugins, and your project can also have
+ its own locationmap.
+ </p>
+<p>
+ Where the resource is provided by a plugin rather than Forrest itself,
+ this is prefixed with the last part of the plugin name. For example:
+ </p>
+<pre class="code">
+
+<map:transform src="{lm:projectInfo.transform.changes.document}"/>
+
+ </pre>
+<p>
+ The above match means look in the projectInfo plugin for a transformer
+ stylesheet with filename changes-to-document.xsl
+ </p>
+<p>
+ The naming convention is essentially one of:
+ </p>
+<pre class="code">
+[PLUGIN_NAME.]resource-type(dot)from-format(dot)to-format
+ </pre>
+<p>
+ or
+ </p>
+<pre class="code">
+[PLUGIN_NAME.]resource-type(dot)type(dot)name
+ </pre>
+<p>
+ Examples of these:
+ </p>
+<pre class="code">
+transform.xthml2.html
+graphic.png.project-logo
+projectInfo.transform.changes.rss
+ </pre>
+</div>
+
+<a name="process"></a>
+<h2 class="underlined_10">Explanation of Locationmap processing</h2>
+<div class="section">
+<p>
+ Some specific examples will explain. Please follow the relevant source
+ files.
+ </p>
+<p>
+ The document <a href="../docs_0_100/howto/../sitemap-explain.html">Cocoon sitemaps
+ explained</a> (better understand that document before trying to
+ understand locationmaps) has two specific transformers which use
+ locationmap references. The first one is: <span class="codefrag">
+<map:transform src="{lm:transform.linkmap.document}"/>
+ </span>
+
+</p>
+<p>
+ The Locationmap component first consults the primary locationmap
+ <span class="codefrag">$FORREST_HOME/main/webapp/locationmap.xml</span> file. This first
+ mounts any project locationmap if available, then the locationmaps from
+ plugins, then the rest of the core locationmaps in the
+ <span class="codefrag">$FORREST_HOME/main/webapp/</span> directory. As with sitemaps, the
+ first match wins. So matches in your project locationmap have
+ precedence, then plugins, then core.
+ </p>
+<p>
+ So let us get back to our specific example,
+ "<span class="codefrag">lm:transform.linkmap.document</span>". The "lm:" part means use
+ the locationmap protocol. There is no specific match for this in your
+ project locationmap, nor in any of the plugin locationmaps, so this
+ falls through to the core locationmaps. However, you will not find any
+ specific match for this in the core locationmaps, so what is happening?
+ </p>
+<p>
+ See the last match in
+ <span class="codefrag">$FORREST_HOME/main/webapp/locationmap-transforms.xml</span> file.
+ This a catchall matcher for any reference starting with
+ "<span class="codefrag">transform.</span>"
+ </p>
+<pre class="code">
+
+ <match pattern="transform.*.*">
+ <select>
+ ...
+ ...
+ <location src="{forrest:forrest.stylesheets}/{1}-to-{2}.xsl"/>
+ </select>
+ </match>
+ </pre>
+<p>
+ As you know from your understanding of Cocoon sitemaps, the first
+ asterisk yields "linkmap" and the second asterisk yields "document". So,
+ ignoring the other possible locations in this group which look in the
+ various skins stylesheet directories (see locationmap-transforms.xml
+ source), it will finally resolve to that last possible location to look
+ for a stylesheet called <span class="codefrag">linkmap-to-document.xsl</span> in the core
+ stylesheets directory
+ <span class="codefrag">$FORREST_HOME/main/webapp/resources/stylesheets/</span>
+
+</p>
+<p>
+ That explains the magic of the locationmap naming convention.
+ </p>
+</div>
+
+<a name="selector"></a>
+<h2 class="underlined_10">Multiple Location Selectors</h2>
+<div class="section">
+<p>
+ You can define multiple possible locations for a file in the locationmap
+ with the following code:
+ </p>
+<pre class="code">
+
+<match pattern="tabs.xml">
+ <select type="exists">
+ <location src="{properties:content.xdocs}tabs1.xml"/>
+ <location src="{properties:content.xdocs}tabs2.xml"/>
+ </select>
+</match>
+
+ </pre>
+<p>
+ Each location will be tested in turn, if the file exists then it will be
+ returned as a match, otherwise testing will continue.
+ </p>
+</div>
+
+<a name="examples"></a>
+<h2 class="underlined_10">Other Locationmap examples</h2>
+<div class="section">
+<a name="source-via-http"></a>
+<h3 class="underlined_5">Retrieving an XDoc via HTTP</h3>
+<p>
+ Normally files are generated from
+ <span class="codefrag">{properties:content.xdocs}</span>. Using the Locationmap it is
+ possible to make these files come from elsewhere. This is useful if
+ you want to pull files from different directory structures, or even
+ remote repositories. For example, the following location match will
+ match any request for a document below "remote." and will retrieve the
+ source file from the Apache Forrest SVN repository (directly from the
+ ASF's SVN webserver). This is an ideal way to ensure that your
+ published docs are always up-to-date.
+ </p>
+<pre class="code">
+ <match pattern="project.remote.**.xml">
+ <location src="http://svn.apache.org/repos/asf/forrest/trunk/site-author/content/xdocs/{1}.xml" />
+ </match>
+ </pre>
+<p>
+ Note that because this is a wildcard matcher you can request any page
+ from the svn server simply by requesting
+ <span class="codefrag">/remote.PATH/TO/FILE/FILENAME.html</span>. In addition, we can
+ request any other output format available via Forrest plugins.
+ </p>
+<p>
+ When including resources from remote repositories one has to be
+ careful about things like <span class="codefrag">site</span> and <span class="codefrag">ext</span>
+ linking. If the targets are not defined in the local
+ <span class="codefrag">site.xml</span> file then these links will be broken.
+ </p>
+<div class="warning">
+<div class="label">Warning</div>
+<div class="content">
+ Because of the above limitation many of the links in the page
+ generated from the above example are broken.
+ </div>
+</div>
+<a name="source-from-remote-cms"></a>
+<h3 class="underlined_5">Retrieving HTML from a CMS</h3>
+<p>
+ Using the locationmap you can use Forrest to retrieve data from a
+ Content Management System (CMS), wither local or remote. As an example
+ we will consider Apache Lenya.
+ </p>
+<p>
+
+<a href="http://lenya.apache.org">Apache Lenya</a> is a Java
+ Open-Source Content Management System based on open standards such as
+ XML and XSLT and the Apache Software Stack, in particular the XML
+ publishing framework Apache Cocoon.
+ </p>
+<p>
+ The following locationmap matcher will instruct Forrest to retrieve
+ content from
+ <span class="codefrag">http://lenya.zones.apache.org:8888/default/live/*.html?raw=true</span>,
+ whenever a local URL of <span class="codefrag">lenya/**</span> is encountered.
+ </p>
+<pre class="code">
+ <match pattern="lenya/**.xml">
+ <location src="http://lenya.zones.apache.org:8888/default/live/{1}.html?raw=true" />
+ </match>
+ </pre>
+<p>
+ However, since the source returned by this match is HTML and not XDoc
+ we must convert this to our internal XDoc format before we can use it.
+ We do this by adding the match below to our project's
+ <span class="codefrag">sitemap.xmap</span> file.
+ </p>
+<pre class="code">
+<map:match pattern="lenya/**.xml">
+ <map:generate type="html" src="{lm:{0}}" />
+ <map:transform src="{forrest:forrest.stylesheets}/html-to-document.xsl" />
+ <map:serialize type="xml"/>
+</map:match>
+ </pre>
+<p>
+ Since this snippet uses the HTML generator you must also ensure that
+ your sitemap has the HTML generator component defined. That is, your
+ sitemap must also include:
+ </p>
+<pre class="code">
+<map:components>
+ <map:generators default="file">
+ <map:generator name="html"
+ src="org.apache.cocoon.generation.HTMLGenerator">
+ <jtidy-config>WEB-INF/jtidy.properties</jtidy-config>
+ </map:generator>
+ </map:generators>
+</map:components>
+ </pre>
+<p>
+ Since the HTML generator uses JTidy we need to make available a JTidy
+ configuration file. This is placed in
+ <span class="codefrag">PROJECT_HOME/src/documentation/WEB-INF/jtidy.properties</span>
+ (the location can be changed in the above sitemap snippet). A sample
+ config file is given below:
+ </p>
+<pre class="code">
+indent=yes
+indent-spaces=8
+wrap=72
+markup=no
+output-xml=no
+input-xml=no
+show-warnings=yes
+numeric-entities=yes
+quote-marks=yes
+quote-nbsp=yes
+quote-ampersand=yes
+break-before-br=yes
+uppercase-tags=no
+uppercase-attributes=no
+char-encoding=latin1
+ </pre>
+<div class="note">
+<div class="label">Note</div>
+<div class="content">
+ This requirement to add items to your project sitemap will be removed
+ in a future version either by Lenya outputting XDoc, or by Forrest
+ switching to using XHTML as its internal format, or through the
+ development of a plugin for Lenya that will include the necessary
+ processing (whichever comes first).
+ </div>
+</div>
+<div class="warning">
+<div class="label">Warning</div>
+<div class="content">
+ This demo is an example only, it does not fully work at this time. For
+ example, absolute URLs in the source document need to be rewritten to
+ ensure that they are matched by the locationmap.
+ </div>
+</div>
+<a name="enhancePDFOutput"></a>
+<h3 class="underlined_5">Enhanced PDF-output plugin</h3>
+<p>In order to change PDF rendered output, e.g. for your own skin
+ it is necessary to enhance/change the
+ plugin 'org.apache.forrest.plugin.output.pdf'. However, by default the plugin
+ takes its own locationmap pointing to the file 'document-to-fo.xsl' of the
+ plugin.
+ </p>
+<pre class="code">
+<match pattern="pdf.transform.*.*">
+ <select>
+ <location src="resources/stylesheets/{1}-to-{2}.xsl"/>
+ <location
+ src="{forrest:forrest.plugins}/org.apache.forrest.plugin.output.pdf/resources/stylesheets/{1}-to-{2}.xsl"/>
+ </select>
+</match>
+ </pre>
+<p>To override this choice you can add this to your locationmap:
+ </p>
+<pre class="code">
+<match pattern="pdf.transform.*.*">
+ <location src="{properties:skins-dir}/yourskin/xslt/fo/{1}-to-{2}.xsl"/>
+</match>
+ </pre>
+<p>Next, you can write your own 'document-to-fo.xsl' in the place specified above.
+ For example, you like to have a special paragraph that looks different to
+ default paragraphs by setting the font to 'oblique' and align it right:
+ </p>
+<pre class="code">
+<?xml version="1.0"?>
+
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ xmlns:fo="http://www.w3.org/1999/XSL/Format"
+ version="1.0">
+
+<xsl:include href="lm://globalpdf.transform.document.fo" />
+
+ <xsl:template match="p[@class='special']">
+ <fo:block
+ font-size="10pt"
+ text-align="right"
+ font-style="oblique">
+ <xsl:apply-templates/>
+ </fo:block>
+ </xsl:template>
+
+</xsl:stylesheet>
+ </pre>
+<p>
+ You may notice that this file contains only your definition and
+ a reference to "lm://globalpdf.transform.document.fo" which needs
+ to be resolved again in your locationmap with an entry that points to the
+ plugins 'document-to-fo.xsl'-file where all the other definitions are made:
+ </p>
+<pre class="code">
+<match pattern="globalpdf.transform.*.*">
+ <location
+ src="{forrest:forrest.plugins}/org.apache.forrest.plugin.output.pdf/resources/stylesheets/{1}-to-{2}.xsl"/>
+</match>
+ </pre>
+<a name="sourceResolving"></a>
+<h3 class="underlined_5">Source Resolving</h3>
+<p>
+ As well as being able to use the locationmap as a parameter in the
+ sitemap, it is also possible to use it as a pseudo-protocol within
+ resources processed by Forrest. For example, you can use it to import
+ an XSL provided by one plugin within another plugin:
+ </p>
+<pre class="code">
+
+ <xsl:import src="lm://OOo.transform.write.xdoc"/>
+
+ </pre>
+<a name="linkrewriting"></a>
+<h3 class="underlined_5">Link Rewriting</h3>
+<p>
+ The locationmap can be used to rewrite URLs when the page is
+ generated. For example, when the locationmap has:
+ </p>
+<pre class="code">
+ <match pattern="rewriteDemo/**">
+ <location src="http://www.domain.org/{1}.xml" />
+ </match>
+ </pre>
+<p>
+ With the above match in the locationmap, a link which has
+ <span class="codefrag">href="lm:rewriteDemo/index"</span> will be rewritten to an
+ off-site address at <span class="codefrag">domain.org</span>
+
+</p>
+<a name="debugging"></a>
+<h3 class="underlined_5">Debugging Locationmaps</h3>
+<p>
+ Debugging the locationmap can be difficult because Cocoons error
+ messages no longer provide meaningful data. We hope to improve this
+ over time, in the meantime we recommend that you increase the log
+ level of the locationmap logger. To do this edit the following line in
+ $FORREST_HOME/main/webapp/WEB-INF/logkit.conf:
+ </p>
+<pre class="code">
+<category name="modules.mapper.lm" log-level="INFO">
+ </pre>
+<p>
+ For example, you could change the log level to "DEBUG".
+ </p>
+<p>
+ Output from this logger can be found in
+ $PROJECT_HOME/build/webapp/WEB-INF/logs/locationmap.log
+ </p>
+<p>If you are interested in your local locationmap
+ (<span class="codefrag">PROJECT_HOME/src/documentation/content/locationmap.xml</span>)
+ the following lines at the top of the log-file indicate that the file
+ was read with success:
+ </p>
+<pre class="code">
+...
+DEBUG (2009-02-26) 14:11.30:322 [core.modules.mapper.lm] (/):
+ loading location map at cocoon://locationmap.xml
+...
+DEBUG (2009-02-26) 14:11.30:385 [core.modules.mapper.lm] (/):
+ loading mounted location map at cocoon://locationmap-project.xml
+...
+ </pre>
+<p>If you find any Java-Exception below these lines, you should deactivate
+ your changes and locate the wrong piece of code, otherwise your locationmap
+ will be ignored.
+ </p>
+<p>In addition it is sometimes useful to increase the log level for the
+ sitemap too, since it may give hints on the locationmaps searched
+ in $FORREST_HOME and $PROJECT_HOME. Thus, changing the following line
+ in the same file from "ERROR" to "DEBUG" results in detailed output in
+ $PROJECT_HOME/build/webapp/WEB-INF/logs/sitemap.log:
+ </p>
+<pre class="code">
+<category name="sitemap" log-level="ERROR">
+ </pre>
+<p>
+ You should not run production systems with this logger set higher than
+ "INFO" and "ERROR" as each request can generate large amounts of log information.
+ </p>
+</div>
+
+</div>
+
+<div class="clearboth"> </div>
+</div>
+<div id="footer">
+
+<div class="lastmodified">
+<script type="text/javascript"></script>
+</div>
+<div class="copyright">
+ Copyright ©
+ 2002-2011 <a href="http://www.apache.org/licenses/">The Apache Software Foundation. Licensed under Apache License 2.0</a>
+<br>
+ Apache Forrest, Forrest, Apache, the Apache feather logo, and the Apache Forrest
+ logos are trademarks of The Apache Software Foundation.
+ </div>
+
+</div>
+</body>
+</html>

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

Added: forrest/site/docs_0_100/menu-index.html
URL: http://svn.apache.org/viewvc/forrest/site/docs_0_100/menu-index.html?rev=1068306&view=auto
==============================================================================
--- forrest/site/docs_0_100/menu-index.html (added)
+++ forrest/site/docs_0_100/menu-index.html Tue Feb 8 09:44:46 2011
@@ -0,0 +1,288 @@
+<!DOCTYPE div PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<div id="menu">
+<ul>
+<li>
+<h1>0.100-dev</h1>
+<ul>
+
+<li>
+<div class="current">Overview</div>
+</li>
+
+
+
+
+
+
+
+<li>
+<a href="../docs_0_100/your-project.html">Using Forrest</a>
+</li>
+
+<li>
+<h1>How-To</h1>
+<ul>
+
+<li>
+<a href="../docs_0_100/howto/index.html">Overview</a>
+</li>
+
+<li>
+<h1>Install Forrest</h1>
+<ul>
+
+<li>
+<a href="../docs_0_100/build.html" title="Build and install the current unreleased version">Building Forrest from Source</a>
+</li>
+
+</ul>
+</li>
+
+<li>
+<a href="../docs_0_100/upgrading_010.html">Upgrading to 0.10-dev</a>
+</li>
+
+<li>
+<h1>Customize Forrest</h1>
+<ul>
+
+<li>
+<a href="../docs_0_100/sitemap-explain.html">Sitemaps explained</a>
+</li>
+
+<li>
+<a href="../docs_0_100/howto/howto-custom-html-source.html">Custom html source</a>
+</li>
+
+<li>
+<a href="../docs_0_100/project-sitemap.html">Project sitemap</a>
+</li>
+
+<li>
+<a href="../docs_0_100/howto/howto-editcss.html">Edit CSS (WYSIWYG)</a>
+</li>
+
+<li>
+<a href="../docs_0_100/howto/howto-pdf-tab.html" title="Generate one pdf-document for all pages of a tab">Create tab PDF</a>
+</li>
+
+<li>
+<a href="../docs_0_100/howto/howto-corner-images.html">CSS corner SVG</a>
+</li>
+
+</ul>
+</li>
+
+<li>
+<h1>Integrate Forrest with tools</h1>
+<ul>
+
+<li>
+<a href="../docs_0_100/howto/howto-forrest-from-maven.html">Maven Integration</a>
+</li>
+
+<li>
+<a href="../docs_0_100/catalog.html">Using DTD Catalogs</a>
+</li>
+
+</ul>
+</li>
+
+<li>
+<h1>Extend Forrest</h1>
+<ul>
+
+<li>
+<a href="../docs_0_100/howto/howto-buildPlugin.html">Build a Plugin</a>
+</li>
+
+<li>
+<a href="../docs_0_100/skin-package.html">Package new Skins</a>
+</li>
+
+</ul>
+</li>
+
+<li>
+<a href="../docs_0_100/howto/howto-asf-mirror.html">Download mirror</a>
+</li>
+
+<li>
+<h1>Adding Documentation</h1>
+<ul>
+
+<li>
+<a href="../howto-howto.html" title="Instructions for writing a new howto-document">Write a How-to</a>
+</li>
+
+<li>
+<h1>Multipage HowTo</h1>
+<ul>
+
+<li>
+<a href="../docs_0_100/howto/multi/howto-multi.html">Introduction</a>
+</li>
+
+<li>
+<a href="../docs_0_100/howto/multi/step1.html">Step 1</a>
+</li>
+
+<li>
+<a href="../docs_0_100/howto/multi/step2.html">Step 2</a>
+</li>
+
+<li>
+<a href="../docs_0_100/howto/multi/step3.html">Step 3</a>
+</li>
+
+</ul>
+</li>
+
+</ul>
+</li>
+
+</ul>
+</li>
+
+<li>
+<a href="../docs_0_100/faq.html">FAQs</a>
+</li>
+
+<li>
+<h1>Background</h1>
+<ul>
+
+<li>
+<a href="../docs_0_100/linking.html">Menus and Linking</a>
+</li>
+
+<li>
+<a href="../docs_0_100/searching.html">Search Options in Forrest</a>
+</li>
+
+<li>
+<a href="../docs_0_100/locationmap.html">Locationmap</a>
+</li>
+
+<li>
+<a href="../docs_0_100/properties.html">Properties system</a>
+</li>
+
+<li>
+<a href="../docs_0_100/sitemap-ref.html">Sitemap Reference</a>
+</li>
+
+<li>
+<a href="../docs_0_100/skins.html" title="About default skins, their naming and features">Skins</a>
+</li>
+
+<li>
+<a href="../docs_0_100/status-themes.html">Dispatcher versus Skins</a>
+</li>
+
+<li>
+<a href="../docs_0_100/cap.html">Sourcetype Action</a>
+</li>
+
+<li>
+<a href="../docs_0_100/validation.html">XML validation and entity resolution</a>
+</li>
+
+</ul>
+</li>
+
+<li>
+<a href="../docs_0_100/changes.html">Changes</a>
+</li>
+
+
+<li>
+<a href="../docs_0_100/glossary.html">Glossary</a>
+</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>
+
+
+<li>
+<h1>Older Docs</h1>
+<ul>
+
+<li>
+<a href="../docs_0_100/primer.html">Forrest Primer</a>
+</li>
+
+<li>
+<a href="../docs_0_100/libre-intro.html">Libre</a>
+</li>
+
+<li>
+<a href="../docs_0_100/dreams.html">Dream list</a>
+</li>
+
+<li>
+<a href="../docs_0_100/howto/cvs-ssh/howto-cvs-ssh.html">CVS over SSH</a>
+</li>
+
+</ul>
+</li>
+
+</ul>
+</li>
+</ul>
+</div>

Propchange: forrest/site/docs_0_100/menu-index.html
------------------------------------------------------------------------------
svn:eol-style = native