Manual of Namazu the full text retrieval search system
Keywords: namazu full text retrieval search engine system

# Manual of Namazu Version 1.3.0.11

Last Modified: 1998-08-31

## NOTICE:

This file is a manual describing how to use Namazu. If you would like to know what is Namazu, see intro.html. Namazu is a free software obeying GPL2. All rights are reserved by Satoru Takabayashi. THE SOFTWARE IS PROVIDED AS IS WITHOUT WARRANTY OF ANY KIND. Use this software at YOUR OWN RISK. I am looking forward to any BUG reports and the idea how to apply Namazu usefully.

Many documents and comments in source code are written in Japanese. I will translate that into English before long. For same reason, contributed softwares written in Japanese will translate into English, maybe.

Namazu home site: http://openlab.ring.gr.jp/namazu/ This is valid until my graduation (March,1999)

## Index

- Index
- Preamble
- Background Information
- System requirements
- Known environments that Namazu works
  - OS
  - C compiler
  - Perl
  - HTTP Server
- How to install
  - From source
    - Extract the Archive
    - Execute configure
- How to use Namazu
  - Making Index
  - Searching
  - Running as CGI
- Query specification

## Preamble

Unfortunately, this manual is now under construction. If I should get email from someone using Namazu from overseas, my motivation would rise :-).

Thanks to Seigo ISHIYAMA for the help of translation.

## Background Information

At the beginning Namazu was made with only intention of Japanese use but now has been developing to handle English (ASCII charset) and other languages defined in ISO-8859-*. I have a desire to distribute Namazu to all over the world but there are many problems on Internationalization. So perhaps using Namazu in non-Japanese environment is currently little inconvinient.

## System requirements

- UNIX
- Win32 (Windows NT/95)
- OS/2
- Http server in your host should supports CGI. (For the use as CGI)
- You need to have a right for using CGI. (For the use as CGI)
- At least, 32MB of memory are needed for the enough performance.

### What you should install / What you shoul have installed in advance

- Perl 5.003 or later [MUST]
- gcc (cc is pearhaps not good) [MUST]
- (for handling Japanese) KAKASI with -w option, or Chasen 1.51 [optional]
- (for handling Japanese) nkf v1.62 [optional]

### About KAKASI/ChaSen

You need KAKASI or ChaSen if you want to deal Japanese (If you don't want, you don't need of course). KAKASI must be patched that -w option is valid. This patch is originally created to Japanize freeWAIS-sf by Hajime BABA. For more information, see freeWAIS-sf japanization information.

## Known environments that Namazu works

Some of them are tested only by earlier version of Namazu. It is not sure that v1.3.0.0 works well under the conditions.

### OS

- Linux 2.0.18, 2.0.30, 2.0.32, 2.0.33
- mklinux DR2.1 update4
- FreeBSD 2.2.1-RELEASE, FreeBSD 2.2.5-RELEASE, FreeBSD 2.2.6-RELEASE
- SunOS 4.1.3-JLE1.1.3_U1, sposk 4.1.4-JL 1, 4.1.4-JLE1.1.4, 5.4
- Japanized Solaris 2.5.1, 2.6
- IRIX 5.3, 6.2
- HP-UX 10.20
- OSF/1 V1.3, V3.2 (on DEC AlphaStation)
- Digital UNIX 4.0B
- DG/UX 5.4R2.10
- BSD/OS 2.1
- EWS-UX/V (Rel4.2) (NEC EWS4800/360)

### C compiler

- gcc 2.5.8, 2.6.3, 2.7.2, 2.7.2.1, 2.7.2.2, 2.7.2.3, 2.8.1

### Perl

- perl 5.003, 5.003 with Japanization Patch 4, 5.004_1, 5.004_03, 5.004_04, 5.005_02

### HTTP Server

- apache 1.1.3, 1.2.0, 1.2.1, 1.2.4, 1.3b3, 1.3b6, 1.2.0
- NCSA HTTPd NCSA/1.5.2
- JavaWebServer 1.0.1
- CERN httpd 3.0A
- Netscape-Commerce/1.1

### Prerequisite to install Namazu on Win32

It is hard to make in Win32. With binary packages of Namazu, you do not have to do that. See Win32 Binary Package.

## How to install

### From source

#### Extract the Archive

At first, extract the Archive. with GNU tar:

`tar xzvf` namazu-xxx.tar.gz

If not:

`gunzip -c` namazu-xxx.tar.gz`| tar xvf -`
`zcat` namazu-xxx.tar.gz`| tar xvf -`

#### Execute configure

Then create Makefile.

            % ./configure --without-japanese # be careful!
    	% make
    	% su                          # switch the user to root, if needed.
    	% make install

It is enough for most cases. In case of trouble, I might be help of you if you report the detail of your environment and error message.

## How to use Namazu

### Making Index

Namazu should make the index like a dictionary in advance of searching. a command ``mknmz`' do this task. Basic way is like this:

`% mknmz` /target/directory

You must specify the /target/directory which contains files you want to index. If /target/directory has subdirectories, ``mknmz`' recursively traverse them and do indexing.

After this processing is finished, ``mknmz`' makes files named ' NMZ.*' as index in current directory.

### Searching

A command ``namazu`' is a search engine. Basic usage is like this:

`% namazu` "query" /index/directory ...

`query' can be specified with flexible conditions supported by ``namazu`'. See the section "Query specification" for details.

`/index/directory' that contains index (NMZ.*) what you want to search is must be specified at least one. You can enumrate directories to search multiple indices at once.

### Running as CGI

At first, You can copy ``namazu.cgi`' to the direcotry allowed to run CGI. ``namazu.cgi`' search the index placed in `INDEXDIR` defined in Makefile as default index.

And you should edit `NMZ.(head|foot|msg|body).en` (``.en`` means English message) which contains messages of search result pages.

Then you can edit `namazu.conf` (usually in `/usr/local/namazu/lib` defined as `LIBDIR` in Makefile) or `.namazurc` placed at the same directory as `namazu.cgi` to adjust URL in the result page. Normally, `mknmz` makes index which point to local files like `/home/foo/public_html/baz.html`, so the result page of CGI is must be substituted.

For example:

`REPLACE /home/foo/public_html/ http://www.hoge.jp/%7Efoo/`

It means to replace `/home/foo/public_html/` with `http://www.hoge.jp/%7Efoo/`. They are MUST be separated with TAB characters.

If ``namazu.cgi`' works successfully, you are lucky :-)!

## Query specification

This search system is case insensitive. You can use asterisk character at the end of the word to do forward match search, for instance: "foo*"

Separating keywords by spaces is automatically assumed to be AND-search that is to find only documents containing all of the specified keywords.

You can search the word containing symbols like "TCP/IP". However, this processing isn't perfect, so you can describe "TCP IP" instead of "TCP/IP", but it may cause noisy results.

This search system has boolean operators '&', '!', '|'. In place of symbols, the word "and", "or", "not", are accepted. Each operator must be separated by space.

For exapmle (both expressions is same meaning):

- `( sed | awk ) ! perl & regexp`
- `( sed or awk ) not perl and regexp`

This sample finds the files which contain "sed" or "awk", and no "perl", but include "regexp".

You can use nested parenthesises expression for advanced search.

By surronding words with double quotation mark '"' or curly brace '{' '}', Namazu would recognize it as phrase but it is not perfect precision, so it cause wrong hit occasionally.

For exapmle (both expressions is same meaning):

- `"SIMPLE MAIL TRANSFER PROTOCOL"`
- `{SIMPLE MAIL TRANSFER PROTOCOL}`

Also, Namazu can do "regular expression search", "middle or backward match search" but it's little slow.

For exapmle:

- `*net` (backward match)
- `*foo*` (middle match)
- `/(foo|bar)[a-z]+/` (regular expression)
- `"rain dance"` (phrase)

You can do 'field specified search' as well if indices are prepared.

- `+date:/Aug 1998/` (something dated on 'Aug 1998')
- `+from:foo@bar.jp` (article by foo@bar.jp)
- `+subject:"internet message"` (search a string for Subject:)
- `+subject:"(mule|xemacs|emacs)"` (search a string for Subject: with regex)
- `+message-id:<199801240555.OAA18737@foo.bar.jp>` (Message-Id)
- `+title:amarok` (title of document)
- `+author:foo@bar.jp` (author of document)
- `+url:http://foo.bar.jp/` (URL of document)

Happy searching!

Namazu homepage