<?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://forrest.apache.org/dtd/document-v12.dtd">
<document>
  <header>
    <title>Searching Forrest-built documentation</title>
  </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 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 <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>&lt;search&gt;</code>
	element; it should be near the top of the file. If the element
	does not exist, create it below the
	<code>&lt;skinconfig&gt;</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. 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>
    </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 the '<code>forrest
	  site</code>' command.</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>&lt;search&gt;</code> element. If the element does not
	exist, insert it right underneath the
	<code>&lt;skinconfig&gt;</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>&lt;search&gt;</code> element.</p>
    </section>
  </body>
</document>
