How to use Freya
■ 索引の作成 (索引づけ, インデクシング)
索引は findex(1)を使って作成します。しかし，findexが入力として受け付け
るのはFDIFファイルのみです。各種の文書ファイルをこのFDIFファイルに統一
してから，findexを起動することになります。FDIFファイルはXML文書のよう
なものです(*1)。
text2fdif
プレインテキストをFDIF形式に変換します。
html2fdif
HTMLをFDIF形式に変換します。
mail2fdif
RFC822に従ったメールをFDIF形式に変換します。
(*1) FDIFは一見するとXMLの適性形式に準拠しているように見えます。が，
findexは任意のXML文書を受け付けるわけではありません。また，FDIF形式は
XMLに準拠していない部分があります(Unicode採用していないなど)。さらに現
在のfindex(1)の実装は実験的なものであり，タグはすべて行頭から始まる必
要があるなど(^_^;，極めて制限の大きいものとなっています。そのため，今
後，FDIF形式を別のフォーマットに変更する可能性があります。わざわざ，
XML風にしているのは今後を考えてのことではあるのですが。
○ mail2fdif を使う場合
mail2fdif はファイル名を並べたリストを受けとり，それらのファイルをFDIF
形式に変換して出力します。また，同時に.dscファイルも作成します。
処理対象のメールは，1メールにつき1ファイルになっている必要があります。
また，ヘッダ部分と本体部分が空行で句切られていなくてはなりません。
% mkdir ~/Indices
% cd ~/Mail
% find hoge-ml -type f -print > ~/Indices/hoge.list
% mail2fdif -v -o ~/Indices/hoge -f ~/Indices/hoge.list
% cd ~/Indices
% findex -d /usr/local/lib/freya/dict/icot.dic -o hoge hoge.fdif
○ html2fdif を使う場合
html2fdifはlibwww-perl-5を使用するので，あらかじめインストールしておい
てください。
html2fdif はファイル名とそのファイルに対応するURLを並べたリストを受け
とり，それらのファイルをFDIF形式に変換して出力します。また，同時に.dsc
ファイルも作成します。
まず，各行にファイル名(html2fdifを実行するディレクトリからの相対パスあ
るいは絶対パス)と検索結果の表示に使用するURLをスペース句切りで並べたファ
イルを用意します。
% cd /usr/local/etc/httpd
% mkdir freya
% find htdocs -name '*.html' -print | sed -e 's/\(.*\)/\1 \1/;s/ htdocs/ http:\/\/www.graco.c.u-tokyo.ac.jp/' > freya/web.list
このリストを -f オプションで指定することで，変換が実行されます。-o オ
プションには生成するファイルの名前を指定します。たとえば，-o hoge とし
た場合，hoge.dsc と hoge.fdif が出力されます。省略すると -o default が
仮定されます。
% html2fdif -v -o freya/web -f freya/web.list
FDIF形式のテキストが出力されたら，それをfindex(1)で処理することで索引
を作ることができます。
-o オプションで出力する索引の名前を指定します。-o hoge とすると，
hoge.lex, hoge.idx, hoge.map を出力します。省略すると "default" が指定
されたものとみなされます。
デフォルトの形態素辞書以外を使うときは -d オプションで指定します。
% cd freya
% findex -d /usr/local/lib/freya/dict/icot.dic -o web web.fdif
索引作成時にはテンポラリファイルが作られます。索引名の末尾に '_' がつ
いたファイルがそうです。これらのファイルは実行時に消さないように注意し
てください。
■ ファイル構成
Freyaを使うことで作成されるファイルは以下のようになります。一セットの
索引につき，4つのファイルがfsearch(1), fsearch.cgi(1)によって使用され
ることになります。
拡張子 概要 検索時に必要? 作成するプログラム
hoge.fdif FDIF形式テキスト 不要 html2fdifなど
hoge.dsc 検索結果表示用要約ファイル 要 html2fdifなど
hoge.lex 索引ファイル(見出し語) 要 findex/fmerge
hoge.idx 索引ファイル(本体) 要 findex/fmerge
hoge.map 出現位置座標変換用ファイル 要 findex/fmerge
icot.dic 形態素辞書 不要 mkicotdic,fmkmorphdic
これらをすべてを合わせると(文書の内容によって変動しますが)，元のテキス
トの70%くらいの容量を占めることになります。ある程度のオーバーヘッドが
あるため，大量のファイルを処理するほど，格納効率はよくなります。
■ コマンドラインからの検索
fsearch(1)を使うことでコマンドラインから検索できます。検索時には
hoge.dsc, hoge.map, hoge.idx, hoge.lex という4種類のファイルが必要です。
Usage: fsearch [-s mail|html] [-f n] [-t n] -i index key [key ..]
fsearchのオプションは以下の通りです。
-i index
索引ファイルの名前を指定します。.dsc, .map, .idx, .lexの
前につく名前を使います。省略すると "default" が仮定されます。
-s style
検索結果の表示スタイルを選択します。
mail2fdif を使ってメールを索引づけ場合は -s mail を，
html2fdif を使ってHTMLを索引づけした場合は -s html を指定します。
適切なstyleを選ばないと時刻表示等がおかしくなります。
-f n
検索結果をn番目から表示します。n は 1 以上です。
-t n
検索結果をn番目まで表示します。n は 1 以上です。
■ CGIを使った検索
○ CGIの準備
まず，CGI用ディレクトリを用意してください。cgi-binを直接使うのではなく，
専用のディレクトリを作ったほうがよいでしょう。たとえば，
cgi-bin/fsearch/などを作ります。そこにmakeした cgi-bin/fsearch.cgi と
パッケージに含まれている cgi-bin/head.html, cgi-bin/foot.html,
cgi-bin/error.htmlをコピーします。
% cd /usr/local/etc/httpd
% mkdir cgi-bin/fsearch
% cp /usr/local/lib/freya/cgi-bin/fsearch.cgi cgi-bin/fsearch
% cp /usr/local/lib/freya/cgi-bin/{head,foot,error}.html cgi-bin/fsearch
また，検索時に必要な索引ファイルを同じディレクトリコピーします。
% cp freya/web.{dsc,map,idx,lex} cgi-bin/fsearch
CGIを使うためのインターフェースとして，
パラメータ from, n, index は次のような意味になります。
from 検索結果をn番目から表示する。通常は0にします。
n 検索結果の表示数。最大で200です。
index 索引の名前。タグを省略すると"default"したことになります。
index等を適切に指定したら，fsearch.html をWWWブラウザで閲覧し，検索を
実行してみます。うまく動いたでしょうか? 動かない場合は httpd のエラー
ログを見るなどして，対応してみてください。
注: fsearch.cgi以外のファイル(索引ファイルやfoot.html)にアクセスした場
合にエラーになることを確かめてください。必要ないファイルが外部から見え
てしまうとセキュリティホールになりかねません。
○ CGIのカスタマイズ
fsearch.cgiによる検索が正しく動作したら，検索結果表示画面のカスタマイ
ズを行ないます。さきほど cgi-bin/fsearch/ にコピーした，head.html,
foot.html, error.htmlを編集してデザイン等を好みに合わせて変更してくだ
さい。メールアドレスをWWWサーバー管理者のアドレスにするなどしてくださ
い(your@mail.host.domになっている部分)。
head.html
検索に成功した場合に検索結果の前に表示されるHTML
foot.html
検索に成功した場合に検索結果の後ろに表示されるHTML
error.html
検索に失敗した場合に表示されるHTML
各HTMLには以下の変数(キーワード)を書くことができます。
$title
タイトル。検索に成功した場合は「Result: 検索式 (#xx-#yy)」，
何も見つからなかった場合は「見つかりませんでした」
エラーになった場合はエラーの内容を表す文字列に置き換えられます
$errormsg
エラーが発生した場合にエラーの説明文に置き換えられます。
error.htmlにだけ書けばいいでしょう。
$query
検索式に置き換えられます。利用者が入力した検索式そのものでは
なく，実際の検索に使用された検索式になっています。
(大文字・小文字の起き換えなど)
$index
検索に使用した索引ファイル名に置き換わります。
$result
検索結果数に置き換えられます。エラーの場合は0です。
注: 現在のところ，同じ行に同じ変数は複数書けません。たとえば，
「$query ($result件)
検索結果は $result でした。」
とは書くことはできません。よって，
「$query ($result件)
検索結果は $result でした。」
というように，二行にわけてください。このバグは将来の版で修正される
予定です。
複数の索引ファイルがあるときに選択して検索したい場合は，たとえば以下の
ようにすればよいでしょう。
------------------------------------------------------------
Copyright (c) 1997 HARADA Masanori. All rights reserved.
$Id: MANUAL.ja,v 0.9 1997-12-29 14:25:28+09 harada Exp $