You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@forrest.apache.org by ch...@apache.org on 2004/06/04 10:04:51 UTC
svn commit: rev 20816 - forrest/trunk/src/documentation/content/xdocs
Author: cheche
Date: Fri Jun 4 01:04:50 2004
New Revision: 20816
Added:
forrest/trunk/src/documentation/content/xdocs/searching.xml
Log:
Added documentation about the search funcionality.
Added: forrest/trunk/src/documentation/content/xdocs/searching.xml
==============================================================================
--- (empty file)
+++ forrest/trunk/src/documentation/content/xdocs/searching.xml Fri Jun 4 01:04:50 2004
@@ -0,0 +1,128 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright 2002-2004 The Apache Software Foundation
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://apache.org/forrest/dtd/document-v12.dtd">
+<document>
+ <header>
+ <title>Searching Forrest-built documentation</title>
+ <authors>
+ <person name="Florian G. Haas" email="f.g.haas@gmx.net"/>
+ </authors>
+ </header>
+ <body>
+ <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>
+ <section>
+ <title>Google SiteSearch</title>
+ <p>Forrest provides a simple interface to the Google search
+ engine. It invokes Google Advanced Search limiting the search
+ scope to the domain of your choosing. 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 <code>forrest site</code>).</p>
+ <p>To use Google SiteSearch in your Forrest application, open
+ your <code>skinconf.xml</code> file. By default this file is
+ in the <code>src/documentation</code> subdirectory of your
+ Forrest repository root. Find the <code><search></code>
+ element; it should be near the top of the file. If the element
+ does not exist, create it below the
+ <code><skinconfig></code> opening tag. If there is any
+ attribute named <code>provider</code>, remove it. The element
+ should look similar to this:</p>
+ <source><![CDATA[<search name="MyProject"
+ domain="myproject.com"/>]]></source>
+ <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. The search is fast,
+ however, 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>
+ </section>
+ <section>
+ <title>Lucene search</title>
+ <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 <code>forrest
+ site</code>.</p>
+ <p>In order to enable Lucene-based full-text search in your
+ Forrest application, you must first edit your
+ <code>skinconf.xml</code> file. Locate the
+ <code><search></code> element. If the element does not
+ exist, insert it right underneath the
+ <code><skinconfig></code> opening tag. Add an attribute
+ named <code>provider</code> with a value of
+ <code>lucene</code>, so that the element looks similar to
+ this:</p>
+ <source><![CDATA[<search name="MyProject" domain="myproject.com"
+ provider="lucene"/>]]></source>
+ <p>Next, create and run your Forrest webapp. This may mean
+ simply invoking <code>forrest run</code>, or building and
+ bundling a servlet webapp (with <code>forrest webapp</code>),
+ and then deploying it to your servlet container.</p>
+ <p>You can now build a Lucene search index by pointing your web
+ browser at
+ <code>http://localhost:8888/lucene-update.html</code>. This
+ generates the search index and provides some information about
+ the index generation process.</p>
+ <note>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
+ <code>forrest run</code>.</note>
+ <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>
+ </section>
+ <section>
+ <title>Disabling full-text search</title>
+ <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
+ <code>skinconf.xml</code> file and remove (or comment out) the
+ entire <code><search></code> element.</p>
+ </section>
+ </body>
+</document>