Version 1.0 alpha2

# How to Search the Documentation

This tool is used to search through the HotJava/Java documentation. To access the tool, select "Search HotJava Documentation..." from the HotJava "Help" menu.

Java documentation is divided into pages and related pages are grouped together into books. For example, the Java language specification is a book that contains a set of pages that describe the language; The Java class documentation (A.P.I.) is made up of a set of pages where each page describes a different class.

Use the tool to locate occurences of specific keywords in the documentation. You submit a query and the tool returns all pages that satisfy the query (see Queries.) For example, the query "hello world" yields a list of all pages that contain the word "hello" or the word "world". The query "hello and world" yields a list of all pages that contain both the word "hello" and the word "world". You can select a page from the resulting list and that page is displayed in HotJava.

You can restrict a search to a particular book or you can search all books. You cannot search through a particular set of books.

### Stoplist

The Search Tool uses a stoplist to shorten search time and reduce the size of the stored indexes. A stoplist is a list of words that are excluded when the documentation is indexed for searching. You can include these words in your query and the tool will not search on them. This allows you to use a more natural language syntax in your query. It is important to note however, that you cannot search on these words (nor should you need to).

The words on the stoplist are as follows:

a, an, and, as at, be, but, by, do, for, from, have, he, in, it, not, of, on, or, she, that, the, there, to, we, which, with, you.

## Queries

A query has the form

        word
        word  op  word
        word  op  word  op  word
        ...

that is, one word, or two words separated by a boolean operator (op), or three words separated by two boolean operators, etc. A boolean operator can be one of and, or, or not.

A word must be longer than a single character and must not contain any punctuation characters except for quote ('). Also, all characters in the query are converted to lowercase before the query is applied.

Here's what the boolean operators mean:

word1
  yields all pages that contain word1.

word1 and word2
  yields all pages that contain both word1 and word2.

word1 or word2
  yields all pages that contain either word1 or word2. The or operator is optional and can be omitted.

word1 not word2
  yields all pages that contain word1 but not word2.

word1 word2
  The or is optional. This is exactly the same as saying word1 or word2.

When a query has more than than one boolean operator, the operators are applied one at a time from left to right. For example, in the query "word1 and word2 or word3 not word4", "word1 and word2" is done first. This yields a set of pages that contain word1 and word2. Next, the set is expanded to also include all pages that contain word3. Finally, the set is reduced by removing all pages that contain word4.

As was mentioned above, a word must be longer than a single character and must not contain any punctuation marks besides quote ('). Here's precisely how a page is broken into words. First, all text between two angle brackets (< text >) and the angle brackets themselves are turned into whitespace (this step is done only on html pages.) Then, all punctuation except for quote (') is turned into whitespace. Next, all characters are made lowercase. Finally, all single letter and duplicate words are removed. The resulting set of words defines the words on that page.

## Results

When you have completed your query select the Search button. The result of the query is displayed in the Search Tool window. It consists of a list of selectable links to pages which satisfy the query,

### Results list

The result of a query is a set of pages. The titles of those pages are displayed in the Results list. You can click on an item in this list and HotJava displays the page. The Results list shows at most 100 page titles. The number of actual pages that satisfy the query appears in the Status bar.

## User Interface Elements

### Query

You type your query in this editable text field. Queries are described in Queries.

### Books to Search

This is a menu of available books that can be searched. If you are interested in searching a particular book, select the book and make the query. The query is only be applied to that book. If you're interested in searching through all books, select "All Books".

### Status bar

The Status bar is the area at the very bottom of the window. In this area, the Search window displays informational messages. For example, when a query is made, the Status bar displays the number of documents which satisfy the query.

### Help

Causes HotJava to display this page.

### Cancel

Closes the search window.