You are viewing a plain text version of this content. The canonical link for it is here.
Posted to site-svn@forrest.apache.org by cr...@apache.org on 2011/02/08 10:44:48 UTC
svn commit: r1068306 [17/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_70/
Added: forrest/site/docs_0_100/searching.html
URL: http://svn.apache.org/viewvc/forrest/site/docs_0_100/searching.html?rev=1068306&view=auto
==============================================================================
--- forrest/site/docs_0_100/searching.html (added)
+++ forrest/site/docs_0_100/searching.html Tue Feb 8 09:44:46 2011
@@ -0,0 +1,501 @@
+<!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>Searching Forrest-built documentation (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">
+<!--+
+ |breadtrail
+ +-->
+<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>
+<!--+
+ |header
+ +-->
+<div class="header">
+<!--+
+ |start group logo
+ +-->
+<div class="grouplogo">
+<a href="http://www.apache.org/"><img class="logoImage" alt="Apache" src="../images/apache-forrest.png" title="The Apache Software Foundation"></a>
+</div>
+<!--+
+ |end group logo
+ +-->
+<!--+
+ |start Project Logo
+ +-->
+<div class="projectlogo">
+<a href="http://forrest.apache.org/"><img class="logoImage" alt="Forrest" src="../images/project-logo.gif" title="Apache Forrest"></a>
+</div>
+<!--+
+ |end Project Logo
+ +-->
+<!--+
+ |start Search
+ +-->
+<div class="searchbox">
+<form action="http://www.google.com/search" method="get" class="roundtopsmall">
+<input value="forrest.apache.org" name="sitesearch" type="hidden"><input onFocus="getBlank (this, 'Search the site with google');" size="25" name="q" id="query" type="text" value="Search the site with google">
+ <input name="Search" value="Search" type="submit">
+</form>
+</div>
+<!--+
+ |end search
+ +-->
+<!--+
+ |start Tabs
+ +-->
+<ul id="tabs">
+<li>
+<a class="unselected" href="../index.html">Welcome</a>
+</li>
+<li>
+<a class="unselected" href="../contrib.html">Developers</a>
+</li>
+<li class="current">
+<a class="selected" href="../versions/index.html">Versioned Docs</a>
+</li>
+<li>
+<a class="unselected" href="../pluginDocs/index.html">Plugins</a>
+</li>
+<li>
+<a class="unselected" href="../tools/index.html">Tools</a>
+</li>
+</ul>
+<!--+
+ |end Tabs
+ +-->
+</div>
+</div>
+<div id="main">
+<div id="publishedStrip">
+<!--+
+ |start Subtabs
+ +-->
+<div id="level2tabs">
+<a class="unselected" href="../docs_0_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>
+<!--+
+ |end Endtabs
+ +-->
+<script type="text/javascript"><!--
+document.write("Last Published: " + document.lastModified);
+// --></script>
+</div>
+<!--+
+ |breadtrail
+ +-->
+<div class="breadtrail">
+
+
+ </div>
+<!--+
+ |start Menu, mainarea
+ +-->
+<!--+
+ |start Menu
+ +-->
+<div id="menu">
+<div onclick="SwitchMenu('menu_selected_1.1', '../skin/')" id="menu_selected_1.1Title" class="menutitle" style="background-image: url('../skin/images/chapter_open.gif');">0.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="menupage">
+<div class="menupagetitle">Search Options in Forrest</div>
+</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>
+<!--+
+ |alternative credits
+ +-->
+<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>
+<!--+
+ |end Menu
+ +-->
+<!--+
+ |start content
+ +-->
+<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>Searching Forrest-built documentation</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="#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>
+</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="Google+SiteSearch"></a>
+<h2 class="underlined_10">Google SiteSearch</h2>
+<div class="section">
+<p>
+ Forrest provides a simple interface to the Google search engine. It
+ invokes Google Advanced Search and limits the search scope to the domain
+ of your choice. Since the actual search functionality is implemented on
+ Google's end, you do not need any additional capability on your Forrest
+ server (which may well be a simple static web server serving content
+ generated with <span class="codefrag">forrest site</span>).
+ </p>
+<p>
+ To use Google SiteSearch in your Forrest application, open your
+ <span class="codefrag">skinconf.xml</span> file. By default this file is in the
+ <span class="codefrag">src/documentation</span> subdirectory of your Forrest repository
+ root. Find the <span class="codefrag"><search></span> element; it should be near
+ the top of the file. If the element does not exist, create it below the
+ <span class="codefrag"><skinconfig></span> opening tag. If there is any attribute
+ named <span class="codefrag">provider</span>, remove it. The element should look similar
+ to this:
+ </p>
+<pre class="code">
+<search name="MyProject"
+ domain="myproject.com"/>
+ </pre>
+<p>
+ Then, build your Forrest documentation and open it using your favorite
+ web browser. You are now invited to peruse the search box (most skins
+ render this in the top-right corner). Google's search results will be
+ displayed in a new browser window.
+ </p>
+<p>
+ Needless to say, for this to work your content must be accessible to
+ Google's indexing robot. It can't be stored on a server which is only
+ locally accessible, or which requires authentication. In addition, the
+ content index is created and updated at a time of Google's choosing.
+ However, the search is fast and search precision is usually excellent.
+ So if your Forrest content is placed on a busy, popular public web
+ server, Google search is probably the best choice.
+ </p>
+</div>
+
+<a name="Lucene+search"></a>
+<h2 class="underlined_10">Lucene search</h2>
+<div class="section">
+<p>
+ Lucene is a high-performance, full-text search engine built entirely in
+ Java. To use Lucene-based search with your Forrest documentation, you
+ will need to run Forrest in a Java servlet environment (such as Tomcat
+ or Jetty). Lucene-based searching will not work in a static site
+ generated with the '<span class="codefrag">forrest site</span>' command.
+ </p>
+<p>
+ In order to enable Lucene-based full-text search in your Forrest
+ application, you must first edit your <span class="codefrag">skinconf.xml</span> file.
+ Locate the <span class="codefrag"><search></span> element. If the element does not
+ exist, insert it right underneath the <span class="codefrag"><skinconfig></span>
+ opening tag. Add an attribute named <span class="codefrag">provider</span> with a value
+ of <span class="codefrag">lucene</span>, so that the element looks similar to this:
+ </p>
+<pre class="code">
+<search name="MyProject" domain="myproject.com"
+ provider="lucene"/>
+ </pre>
+<p>
+ Next, create and run your Forrest webapp. This may mean simply invoking
+ <span class="codefrag">forrest run</span>, or building and bundling a servlet webapp
+ (with <span class="codefrag">forrest webapp</span>), and then deploying it to your
+ servlet container.
+ </p>
+<p>
+ You can now build a Lucene search index by pointing your web browser at
+ <span class="codefrag">http://localhost:8888/lucene-update.html</span>. This generates
+ the search index and provides some information about the index
+ generation process.
+ </p>
+<div class="note">
+<div class="label">Note</div>
+<div class="content">
+ You may have to substitute a different hostname, port, or path,
+ depending on your configuration. The path mentioned here reflects
+ Forrest's default settings when invoked as <span class="codefrag">forrest run</span>.
+ </div>
+</div>
+<p>
+ Now you can utilize the full-text search box, located in the top-right
+ corner of the rendered Forrest pages. Search results will be displayed
+ in the same browser window and will look remarkably similar to the rest
+ of your Forrest documents.
+ </p>
+<p>
+ Unlike with Google SiteSearch, the indexing information retrieved by
+ Lucene is stored on your own server, access to which you may limit to
+ users in your own organization. Likewise, you may update or recreate the
+ Lucene index at any time and at your own discretion. So if you aren't
+ making your Forrest-built documentation publicly available, and you're
+ able to run Forrest on a Java-enabled web server, Lucene search is
+ probably right for you.
+ </p>
+</div>
+
+<a name="Disabling+full-text+search"></a>
+<h2 class="underlined_10">Disabling full-text search</h2>
+<div class="section">
+<p>
+ If you are convinced your users don't need any full-text search
+ capability whatsoever, you may disallow displaying the search box
+ entirely. You may also wish to do so if you're keeping Forrest-built
+ content on a restricted server (meaning you can't use Google), while at
+ the same time not having any usable servlet-capable web server at your
+ disposal (meaning you can't use Lucene, either).
+ </p>
+<p>
+ To disable full-text search completely, open the
+ <span class="codefrag">skinconf.xml</span> file and remove (or comment out) the entire
+ <span class="codefrag"><search></span> element.
+ </p>
+</div>
+
+</div>
+<!--+
+ |end content
+ +-->
+<div class="clearboth"> </div>
+</div>
+<div id="footer">
+<!--+
+ |start bottomstrip
+ +-->
+<div class="lastmodified">
+<script type="text/javascript"><!--
+document.write("Last Published: " + document.lastModified);
+// --></script>
+</div>
+<div class="copyright">
+ Copyright ©
+ 2002-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>
+<!--+
+ |end bottomstrip
+ +-->
+</div>
+</body>
+</html>
Propchange: forrest/site/docs_0_100/searching.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: forrest/site/docs_0_100/sitemap-explain.html
URL: http://svn.apache.org/viewvc/forrest/site/docs_0_100/sitemap-explain.html?rev=1068306&view=auto
==============================================================================
--- forrest/site/docs_0_100/sitemap-explain.html (added)
+++ forrest/site/docs_0_100/sitemap-explain.html Tue Feb 8 09:44:46 2011
@@ -0,0 +1,538 @@
+<!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>Cocoon sitemap explained (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">
+<!--+
+ |breadtrail
+ +-->
+<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>
+<!--+
+ |header
+ +-->
+<div class="header">
+<!--+
+ |start group logo
+ +-->
+<div class="grouplogo">
+<a href="http://www.apache.org/"><img class="logoImage" alt="Apache" src="../images/apache-forrest.png" title="The Apache Software Foundation"></a>
+</div>
+<!--+
+ |end group logo
+ +-->
+<!--+
+ |start Project Logo
+ +-->
+<div class="projectlogo">
+<a href="http://forrest.apache.org/"><img class="logoImage" alt="Forrest" src="../images/project-logo.gif" title="Apache Forrest"></a>
+</div>
+<!--+
+ |end Project Logo
+ +-->
+<!--+
+ |start Search
+ +-->
+<div class="searchbox">
+<form action="http://www.google.com/search" method="get" class="roundtopsmall">
+<input value="forrest.apache.org" name="sitesearch" type="hidden"><input onFocus="getBlank (this, 'Search the site with google');" size="25" name="q" id="query" type="text" value="Search the site with google">
+ <input name="Search" value="Search" type="submit">
+</form>
+</div>
+<!--+
+ |end search
+ +-->
+<!--+
+ |start Tabs
+ +-->
+<ul id="tabs">
+<li>
+<a class="unselected" href="../index.html">Welcome</a>
+</li>
+<li>
+<a class="unselected" href="../contrib.html">Developers</a>
+</li>
+<li class="current">
+<a class="selected" href="../versions/index.html">Versioned Docs</a>
+</li>
+<li>
+<a class="unselected" href="../pluginDocs/index.html">Plugins</a>
+</li>
+<li>
+<a class="unselected" href="../tools/index.html">Tools</a>
+</li>
+</ul>
+<!--+
+ |end Tabs
+ +-->
+</div>
+</div>
+<div id="main">
+<div id="publishedStrip">
+<!--+
+ |start Subtabs
+ +-->
+<div id="level2tabs">
+<a class="unselected" href="../docs_0_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>
+<!--+
+ |end Endtabs
+ +-->
+<script type="text/javascript"><!--
+document.write("Last Published: " + document.lastModified);
+// --></script>
+</div>
+<!--+
+ |breadtrail
+ +-->
+<div class="breadtrail">
+
+
+ </div>
+<!--+
+ |start Menu, mainarea
+ +-->
+<!--+
+ |start Menu
+ +-->
+<div id="menu">
+<div onclick="SwitchMenu('menu_selected_1.1', '../skin/')" id="menu_selected_1.1Title" class="menutitle" style="background-image: url('../skin/images/chapter_open.gif');">0.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_selected_1.1.3', '../skin/')" id="menu_selected_1.1.3Title" class="menutitle" style="background-image: url('../skin/images/chapter_open.gif');">How-To</div>
+<div id="menu_selected_1.1.3" class="selectedmenuitemgroup" style="display: block;">
+<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_selected_1.1.3.4', '../skin/')" id="menu_selected_1.1.3.4Title" class="menutitle" style="background-image: url('../skin/images/chapter_open.gif');">Customize Forrest</div>
+<div id="menu_selected_1.1.3.4" class="selectedmenuitemgroup" style="display: block;">
+<div class="menupage">
+<div class="menupagetitle">Sitemaps explained</div>
+</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_1.1.5', '../skin/')" id="menu_1.1.5Title" class="menutitle">Background</div>
+<div id="menu_1.1.5" class="menuitemgroup">
+<div class="menuitem">
+<a href="../docs_0_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="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>
+<!--+
+ |alternative credits
+ +-->
+<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>
+<!--+
+ |end Menu
+ +-->
+<!--+
+ |start content
+ +-->
+<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>Cocoon sitemap explained</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>
+
+<p>
+ This document is intended to be a concise explanation of the Apache Cocoon
+ <a href="../docs_0_100/sitemap-ref.html">Sitemap</a> and its use in Apache Forrest. This
+ is a worked example showing the automatically generated Table of Contents.
+ Please follow the various sitemaps as we explain.
+ </p>
+
+<pre class="code">
+cd $FORREST_HOME/site-author
+forrest run
+</pre>
+
+<p>
+ In a separate browser window, open
+ <a href="../linkmap.html"><span class="codefrag">localhost:8888/linkmap.html</span></a> to see
+ the generated Table of Contents. This has been transformed from the
+ site.xml navigation configuration to show the layout of the whole site as
+ a ToC.
+ </p>
+
+<p>
+ Cocoon consults the sitemaps to find out how to process the
+ <span class="codefrag">linkmap.html</span> request.
+ </p>
+
+<p>
+ The main sitemap is <span class="codefrag">$FORREST_HOME/main/webapp/sitemap.xmap</span>
+ and if the match is not found there then other sitemaps are consulted. The
+ first match wins. Various sitemaps are responsible for different types of
+ processing and there are also sitemaps in the many plugins.
+ </p>
+
+<p>
+ So let us see how <span class="codefrag">linkmap.html</span> is handled.
+ </p>
+
+<p>
+ Open <span class="codefrag">$FORREST_HOME/main/webapp/sitemap.xmap</span> in another
+ window. Search for "linkmap" to find the following snippet:
+ </p>
+
+<pre class="code">
+<map:match pattern="linkmap.*">
+ <map:mount uri-prefix="" src="linkmap.xmap" check-reload="yes" />
+</map:match>
+ </pre>
+
+<p>
+ Cocoon has passed through the other potential matches earlier in the
+ sitemap and now does further handling via the <span class="codefrag">linkmap.xmap</span>
+ sitemap.
+ </p>
+
+<p>
+ Before going any further, it is necessary to understand the "**" and "*"
+ pattern matching and replacements. See the email thread: "Re: explain
+ sitemap matches and pass parameters to transformers"
+ <a href="http://issues.apache.org/jira/browse/FOR-874">FOR-874</a>.
+ </p>
+
+<p>
+ Okay we will skip some explanation of processing. At this stage we are
+ only concerned with generating the internal xml. Later steps of processing
+ will transform that into the final html output and adorn it with
+ navigation menus and headers, etc. This is your main aim for most of your
+ sitemap work for input formats: handle the incoming requests, and
+ transform into the standard internal xml format. Then Forrest
+ automatically does the rest.
+ </p>
+
+<p>
+ In another browser window, open <span class="codefrag">localhost:8888/linkmap.xml</span> to
+ see the internal xml format.
+ </p>
+
+<p>
+ Open <span class="codefrag">$FORREST_HOME/main/webapp/linkmap.xmap</span> sitemap. Move to
+ the "map:pipeline" section.
+ </p>
+
+<p>
+ A digression: The first match is not triggered because our request is for
+ <span class="codefrag">linkmap.xml</span> and this match handles
+ <span class="codefrag">linkmap.source.xml</span> to essentially re-direct it to
+ <span class="codefrag">linkmap.xml</span> instead. That is what the cocoon:// means:
+ generate it via a different request within this sitemap. Try
+ <span class="codefrag">localhost:8888/linkmap.source.xml</span> to see the exact same
+ internal xml format.
+ </p>
+
+<p>
+ The second match exactly meets our pattern <span class="codefrag">linkmap.xml</span>
+
+</p>
+
+<pre class="code">
+<map:match pattern="linkmap.xml">
+ <map:generate src="cocoon://abs-linkmap" />
+ <map:transform src="{lm:transform.linkmap.document}"/>
+ <map:serialize type="xml" />
+</map:match>
+ </pre>
+
+<p>
+ As with all pipelines, it starts with a generator to commence the xml
+ stream, then transforms it with a single transformer (there could be
+ multiple sequential transformers) and finally the serializer component.
+ Here it is:
+ </p>
+
+<p>
+ The generator is not simply reading an xml file. It produces the xml via a
+ different part of this sitemap. Let us explain that later and assume for
+ now that it produces the xml from your site.xml file.
+ </p>
+
+<p>
+ Move on to the transformer. It transforms the xml obtained from the
+ site.xml into the internal document xml format using an XSLT stylesheet.
+ The locationmap reference defines the source for that stylesheet:
+ "lm:transform.linkmap.document" is evaluated by the Locationmap to be the
+ <span class="codefrag">main/webapp/resources/stylesheets/linkmap-to-document.xsl</span>
+ stylesheet. See the <a href="../docs_0_100/locationmap.html">Locationmap</a>
+ documentation for explanation.
+ </p>
+
+<p>
+ Now let us get back to that new request for "abs-linkmap". This is used a
+ number of times within this sitemap, hence it is its own pipeline. As
+ usual it starts with a generator, then a transformer, then a serializer.
+ </p>
+
+<p>
+ Again the generator is sent to some other part of the sitemap hierarchy,
+ because this request is needed by many other parts of the system beyond
+ just this linkmap handling. You see that it is not matched within this
+ linkmap.xmap sitemap. Go to the main sitemap.xmap and search for
+ "site.navigation.links.xml" where you find the match that handles this by
+ looking for various Locationmap definitions to find and transform the
+ site.xml file.
+ </p>
+
+<p>
+ Don't get lost, come back to the linkmap.xmap sitemap.
+ </p>
+
+<p>
+ Following this generator, the transformer turns the links into absolute
+ references. This is then serialized as xml to finish this "abs-linkmap"
+ match which is the end of the generator in our main match.
+ </p>
+
+<p>
+ A developer's trick will help to understand what is happening. Edit the
+ linkmap.xmap to comment-out the transformer ...
+ </p>
+
+<pre class="code">
+
+ <map:match pattern="linkmap.xml">
+ <map:generate src="cocoon://abs-linkmap" />
+<!--
+ <map:transform src="{lm:transform.linkmap.document}"/>
+-->
+ <map:serialize type="xml" />
+ </map:match>
+
+ </pre>
+
+<p>
+ Browser <span class="codefrag">localhost:8888/linkmap.xml</span> to see the result of the
+ "abs-linkmap" generation before it is transformed into the internal
+ document xml.
+ </p>
+
+<p>
+ So now you understand some of the power of sitemaps.
+ </p>
+
+<p>
+ A basic understanding of Cocoon's pipelines and their components will help
+ you to realise the true power. You should know about matchers, generators,
+ transformers and serializers and have a rough idea how they work together
+ in a pipeline. A good place to start learning about Cocoon is
+ <a href="http://cocoon.apache.org/2.1/userdocs/concepts/">Understanding
+ Apache Cocoon</a>. The Forrest <a href="../docs_0_100/sitemap-ref.html">Sitemap
+ Reference</a> will also be helpful.
+ </p>
+
+</div>
+<!--+
+ |end content
+ +-->
+<div class="clearboth"> </div>
+</div>
+<div id="footer">
+<!--+
+ |start bottomstrip
+ +-->
+<div class="lastmodified">
+<script type="text/javascript"><!--
+document.write("Last Published: " + document.lastModified);
+// --></script>
+</div>
+<div class="copyright">
+ Copyright ©
+ 2002-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>
+<!--+
+ |end bottomstrip
+ +-->
+</div>
+</body>
+</html>
Propchange: forrest/site/docs_0_100/sitemap-explain.html
------------------------------------------------------------------------------
svn:eol-style = native