■ WWW更新時刻取得システム "WDB"
■ V2.10 Copyright 1999,2000,2001 GORRY.
■ http://GORRY.hauN.org/wdb/
■ mailto: gorry@hauN.org


================================================================================
■ 1. ファイル構成

説明に"@"がついているものは、WDBが作成／修正するファイルです。
説明に"*"がついているものは、ユーザーが作成／修正するファイルです。

/
+ wdb
|   + sample            WDBメンテナンス用WWWトップページ
|   |   + config.wdb    @* サンプル：巡回先設定ファイル
|   |   + dance.pl      * サンプル：巡回perlスクリプト
|   |   + dance.sh      サンプル：巡回＆アンテナ出力ページ作成
|   |   + disp.shtml    サンプル：WDBメンテナンス用WWWメインページ
|   |   + disp.cgi      サンプル：WDBメンテナンス用WWWメインページ作成
|   |   + head.html     * サンプル：アンテナ出力ページ前半includeファイル
|   |   + tail.html     * サンプル：アンテナ出力ページ後半includeファイル
|   + index.html        WDBメンテナンス用WWWトップページ
|   + mkpasswd.html     パスワード登録フォーム
|   + mkpasswd.cgi      パスワード登録フォーム処理スクリプト
|   + wdb.ph            WDB動作コンフィグレーションファイル
|   + wdb.pl            WDB本体
|   + wdbdisp.pl        WDBメンテナンス本体
|   + wdblib.pl         WDBライブラリ
|   + readme.txt        当ファイル
|   + update.txt        更新記録
|   + myself.hr         @ 自らのリモート情報。内部キャッシュとして使用する
|   + sdb.hr            @ 当方SDBより提供され、取得したリモート情報
|
+ index.html            @ アンテナ出力ページ
+ hina.txt              @ config.wdbにより外部へ提供するリモートアンテナ情報
+ hina.di               @ config.wdbにより外部へ提供するリモートアンテナ情報


================================================================================
■ 2. 概要

WDBは、「WWW更新時刻取得システム」、通称「アンテナ」と呼ばれる
アプリケーションのひとつです。
WWWページは日々更新が行なわれます。どのページがいつ更新されたかを
事前に知ることができれば、WWWアクセスのムダを減らすことができます。

事前に知るための実装のひとつとして、WWWCというクライアントアプリケーションが
あります。これはWWWアクセスロボットのひとつで、指定したターゲットを
自動的に巡回して更新があったかどうかを調べることができます。
ただし、更新を知るためにあらかじめ調査巡回作業を行なっておく必要があり、
ターゲットが増えれば調査巡回にかかる時間が増大するという欠点があります。

この欠点を補う実装として、「朝日奈アンテナ」があります。これはWWWサーバが
動作しているマシン上で定期的に動作させ、結果をHTMLファイルで提供することで、
いつでも最新の調査巡回結果を得ることができます。また、複数の「朝日奈
アンテナ」を協調動作してさせることで、１つの「朝日奈アンテナ］当たりの
負荷を減らすことができるという利点や、WWWサーバサイド提供ということで
「便利なリンク集」として読者間で情報の共有が可能であるという利点があります。

WDBは、「朝日奈アンテナ」を手本にして作られた、別の実装の「アンテナシステム」
です。Windowsシステムでの動作や、WWW経由での設定機能を特長としています。


================================================================================
■ 3. ローカルでの使用方法

  0. このシステムの実行にはnkf・perlとjcode.plが必要です。sample.wdb
     の設定は手書きでも行なえますが、WWWサーバーをインストールすれば
     WWWブラウザによる管理が可能になります。この場合は3.をお読みください。
  1. 適当なディレクトリ(以後wdbroot）に展開します。wdb-?.??ディレクトリ
    （以後wdb）が作られ、以下に展開が行なわれます。
  2. wdbroot/wdb/sample/にある設定ファイル群をwdbroot/wdbにコピーします。
  3. 「■ 7. 設定項目」を読み、設定を行なってください。
  4. wdbroot/wdbディレクトリ上で以下のように実行します。
     > dance.bat （Windows）
     > ./dance.sh （UNIX系）
  5. 指定された各WWWページにWDBがアクセスを行ない、得られた情報から
     wdbroot/にindex.htmlとhina.diファイルが作成されます。
  6. wdbroot/index.htmlをブラウザで閲覧します。


================================================================================
■ 4. HTTPサーバにインストールしての使用方法

  0. このシステムの実行にはnkf・perlとCGI・SSIが使用可能なHTTPサーバ、
     およびjcode.plが必要です。作者はFreeBSDにperl5,apacheを入れて
     使用しています。
  1. 適当なディレクトリ(以後wdbroot）に展開します。wdb-?.??ディレクトリ
     （以後wdb）が作られ、以下に展開が行なわれます。
  2. wdbroot/wdb/sample/にある設定ファイル群をwdbroot/wdbにコピーします。
  3. 「■ 7. 設定項目」を読み、設定を行なってください。
  4. wdbroot, wdbroot/wdbのpermissionにo+wを与えてください。
  5. wdbroot/wdb/*.wdbのpermissionにo+wを与えてください。
  6. wdbroot/wdb/に何らかのアクセス制御をかけたほうがよろしいかと思います。
  7. HTTPサーバへ接続し、wdbroot/wdb/mkpasswd.htmlを開いてください。
  8. パスワード登録画面になりますので、パスワードを登録してください。
     なお、パスワードの再登録はupdate.passを削除して再度登録します。
  9. HTTPサーバへ接続し、wdbroot/wdb/を開いてください。
 10. 開いたformで情報を取得するWWWページや、すでに情報収集された結果ページ
     （リモート情報）のURIを与え、"記録"を選んで"OK"を押します。
 11. wdbroot/wdb/config.wdbが更新されます。
 12. この状態でwdbroot/wdb/dance.shを実行することで、wdbroot/index.htmlと
     wdbroot/hina.diが作成されます。
 13. cronでwdbroot/wdb/dance.shを実行するよう設定することで、
     指定時間ごとにWWWページの巡回を行ない、情報を自動取得してWWWで提供する
     「アンテナシステム」として動作するようになります。


================================================================================
■ 5. WDBファイル

wdbroot/wdb/*.wdbは、ユーザーが巡回先を設定するファイルです。
sample_disp.shtmlのブラウズによりブラウザからの更新を行なうことが
前提になっていますが、ここではWDBファイルのフォーマットについての
解説を行ないます。

--------------------------------------------------------------------------------
■ 5.1. リモート情報定義部

REMOTE:         sdb
URI:            http://na01.shonan.ne.jp/~gorry/hina/
TITLE:          SDB
AUTHOR:         GORRY
VIRTUAL:        http://na01.shonan.ne.jp/~gorry/hina/hina.di
MARK:           s
SAVEAS:         sdb.hr

「リモート情報定義部」は、他のWWW更新時刻調査システム（アンテナ）の
出力結果を「自らが取得するデータの代わり」に使用するための定義を
行なう部分です。この外部アンテナを「リモートアンテナ」と呼びます。
「REMOTE」行で定義開始、空行で終了となります。

  ・REMOTE [name]
    リモートアンテナの定義部を開始し、登録コード名を[name]とします。
  ・URI [uri]
    リモートアンテナのURIを[uri]とします。
  ・TITLE [title]
    リモートアンテナの名称を[title]とします。
  ・AUTHOR [author]
    リモートアンテナの管理者名を[author]とします。
  ・VIRTUAL [uri]
    データ取得に使用するデータのURIを[uri]とします。
    省略可能で、省略した場合は「URI」で定義されたところから取得します。
  ・MARK [mark]
    アンテナ出力ページで、このリモートアンテナを示す文字列を[mark]と
    します。"%m"がこの文字列に置換されます。
  ・SAVEAS [savefile]
    getしたデータを[savefile]というファイル名で保存します。
    データgetに失敗した場合はこのファイル名で定義されたファイルを
    読み込むため、get先ホストがダウンしていてもしばらくは情報を持ち続ける
    ことができます。

リモートアンテナとして使用できる情報ファイルフォーマットは、以下があります。

  ・hina.txt （朝日奈アンテナ・WDB）
  ・hina.di （朝日奈アンテナ・WDB）
  ・hina.di.gz （朝日奈アンテナ・WDB）

両方を提供しているアンテナからは、hina.diを取得するようにしてください。
hina.di.gzは、gzipで圧縮されているhina.diファイルです。

内部キャッシュとして、必ず自分自身が提供しているhina.diファイルを最初に
定義してください。自らの提供情報と外部の提供情報をすりあわせることで、
もっとも効率のいい情報分析が可能になります。

--------------------------------------------------------------------------------
■ 5.2. ターゲット定義部

PAGE:           gorry
URI:            http://na01.shonan.ne.jp/~gorry/diary/digestdiary.html
TITLE:          なびろぐ
AUTHOR:         GORRY
VIRTUAL:        http://na01.shonan.ne.jp/~gorry/diary/digestdiary.antenna
METHOD:         HEAD
COMMENT:        
KEY:            

「ターゲット定義部」は、更新時刻調査先（ターゲット）の定義を行なう部分です。
「PAGE」行で定義開始、空行で終了となります。

  ・PAGE [name]
    定義部を開始し、登録コード名を[page]とします。
  ・URI [uri]
    ターゲットへのリンク先となるURIを[uri]とします。
  ・TITLE [title]
    ターゲットとなるWWWページの名称を[title]とします。
  ・AUTHOR [author]
    ターゲットとなるWWWページの著者名を[author]とします。
  ・VIRTUAL [uri]
    データ取得に使用するURIを[uri]とします。
    省略可能で、省略した場合は「URI」で定義されたところから取得します。
  ・METHOD [method]
    更新時刻の調査方法を[method]に設定します。

      ●GET
        GETリクエストでコンテンツをgetします。
        ただし、「リモートアンテナから抽出された情報に十分新しいものが
        存在している」場合にはそれを利用し、HTTPアクセスを行ないません。
      ●HEAD
        HEADリクエストでコンテンツをgetします。
        WWWサーバやコンテンツの設定が適切である場合、HEAD指定することで
        GETよりも少ない負荷で必要な情報を得ることが可能になります。
        ただし、「リモートアンテナから抽出された情報に十分新しいものが
        存在している」場合にはそれを利用し、HTTPアクセスを行ないません。
      ●REMOTE
        調査のためのHTTPアクセスを行ないません。
        リモート情報から抽出されたもののみで調査を行ないます。
      ●GET2
        GETと同じですが、リモート情報は無視します。
        つまり必ずHTTPアクセスを行ないます。
      ●HEAD2
        HEADと同じですが、リモート情報は無視します。
        つまり必ずHTTPアクセスを行ないます。

  ・COMMENT [comment]
    ターゲットについて、何か追記したいことがあればここに書くことで
    アンテナ出力ページへの出力結果に反映することができます。
  ・KEY [key]
    「時刻を示す文字列」を抽出するための検索キーを[key]とします。
    WDBは、HTTPアクセスで得られたテキストファイルに対して[key]で検索をかけ、
    ヒットした行に対して「時刻を示す文字列」があるかどうかを調べます。
    省略可能で、省略した場合は"Last"という検索キーを使用します。これにより
    HTTPヘッダの"Last-modified"行を抽出することが望まれています。
    [key]には、正規表現を使用します。また".*"という文字列を含ませることで
    抽出した行から不要な部分を切り捨てることができます。
      "Last.*"    "Last"より左側を切り捨てる
      ".*Last"    "Last"より右側を切り捨てる
      "Last"      切り捨てない


================================================================================
■ 6. 時刻文字列について

WDBは、時刻文字列として以下のものを認識します。

  (1)  YYYY/MM/DD hh:mm:ss Zone
  (2)  Day Month Year hh:mm:ss Zone
  (3)  Day Month hh:mm:ss Zone Year
  (4)  Month Day hh:mm:ss Zone Year
  (5)  YYYY/MM/DD hh:mm AM/PM
  (6)  YYYY/MM/DD AM/PM hh:mm
  (7)  YYYY/MM/DD hh:mm
  (8)  YYYY/MM/DD
  (9)  MM/DD hh:mm AM/PM
  (10) MM/DD AM/PM hh:mm
  (11) MM/DD AM/PM hh:
  (12) MM/DD hh:
  (13) MM/DD

Zone（JSTなどのタイムゾーン名）はなくても構いません。ない場合は、
wdb.phで設定されているデフォルトのもの（配布時はJST）として処理します。

"/"は"-"や"."などの文字でも構いません。

(5)以降の場合、ss（秒）は0であるものとして扱います。

(13)の場合、hh:mm:ss（時:分:秒）は0であるものとして扱います。
ただし、２度目以降は「文字列から認識した時刻」でなく、「前回と異なる
結果を認識した時刻」を更新時刻として持つようになります。

Year（年）が２桁以下の数値である場合、「80以上であれば1900年代、未満なら
2000年代」として扱います。


================================================================================
■ 7. 設定項目

この配布パッケージでは、とりあえず最少の設定で動作させるための
「wdbroot/wdb/sample/*」というファイル群を持っています。
これらのファイルをコピーして変更すれば、独自の巡回環境が作成できます。

WDBを動作させるには、以下の設定が必要です。

--------------------------------------------------------------------------------
■ 7.1. dance.pl

  巡回を行なうperlスクリプトです。これを実行することで巡回を行ない、
  結果を標準出力へ出力します。通常はsample_dance.shやsample_dance.batから
  このスクリプトを起動し、完全なHTMLファイルになるようにします。

  > $WDBFILE = "config.wdb";

    WDBに入力する巡回設定ファイルを記述します。

  > $PROXY    = "your-server:8080";

    WDBのHTTPアクセスにPROXYを使用する場合、そのサーバ名とポート番号を
    "your-server:8080"のように記述します。PROXYを使用しない場合は
    コメント化して無効にします。

  > $ANTENNA_URI  = "http://www.example.com/~your-home/your-antenna/";

    当アンテナのURLを記述します。 

  > $HINA_HTML_FORMAT = 
  > "<li>%s%l (%m:%g) <a href=\"%h\"><B>%t</B> by %n %C</a>\n"

    hina.htmlへの出力フォーマットを記述します。
    以下は置換内容です。

      %s 動作結果を示す文字列。<!-- -->で括られる。
      %h 朝日奈クエリ入りのURL。
         朝日奈クエリとは、URLの末尾に付く"?08181509"のような
         文字列のことで、以下の効果を持つ。
         ・URLから更新時刻を認識できる（上例では08/18 15:09）。
         ・URLがuniqueになるため、一部ブラウザではリンク色から未読・既読を
           判別できるようになる。
         ・URLがuniqueになるため、PROXYのCACHEを事実上無効にできる。
      %t 日記名。
      %n 著者名。
      %l 更新時刻。YYYY/MM/DD hh:mmに固定。
      %m 取得方法。G(get)・H(head)、あるいはリモートアンテナ名となる。
      %g 取得所要時間。
      %c 著者識別名。<!-- -->で括られる。
      %C コメント。
      %H 朝日奈クエリを含まないURL。
      %E 動作結果を示す文字。
         "N" 404 NOT FOUND
         "T" タイムアウト
         "R" リモート先に情報がない
         "D" 時刻情報が検知できない
         "C" TCP接続エラー
         "E" その他エラー

  > $SORT = !0;

    出力結果を更新時刻順に並べ替えるなら!0を、変えないなら0を指定します。

--------------------------------------------------------------------------------
■ 7.2. dance.sh

  dance.plを起動して巡回を行なったあと、その結果を
  wdbroot/index.htmlに出力するシェルスクリプトです。単独で起動しても
  かまいませんが、通常はwebサーバ上でcronでこれを起動させるように
  設定します。

  > DIR="/home/your-home/public_html/your-antenna/wdb"

    実行時にカレントにするディレクトリを設定します。

  > PERL="/usr/local/bin/perl"
  > NKF="/usr/local/bin/nkf"

    PERL・NKFのパスを設定します。

--------------------------------------------------------------------------------
■ 7.3. dance.bat

  dance.plを起動して巡回を行なったあと、その結果を
  wdbroot/index.htmlに出力するWindows用バッチファイルです。
  Windows上ではかなりの方が単独で起動すると思いますが、もちろん
  atコマンドなどでタイマ登録する方法もあるでしょう。

  このファイルには特に設定項目はありません。
  ただし、perl・nkfにpathが通る環境で起動してください。

--------------------------------------------------------------------------------
■ 7.4. disp.cgi

  disp.shtmlから起動され、巡回設定画面を表示するperlスクリプトです。

  > $WDBFILE = "config.wdb";

    WDBに入力する巡回設定ファイルを記述します。

  > $MAILTO = "";

    巡回設定ファイルを更新したときに、そのコピーをこれで指定するアドレスに
    メールで転送することができます。

--------------------------------------------------------------------------------
■ 7.5. disp.shtml

  disp.cgiをSSI経由でCGI起動して、巡回設定画面を表示する
  HTMLファイルです。

  このファイルには特に設定項目はありません。
  ただし、perl・nkfにpathが通る環境で起動してください。

--------------------------------------------------------------------------------
■ 7.6. head.html

  dance.sh・dance.batにより巡回結果ファイルに前置され、
  アンテナ出力HTMLファイルとなるHTMLファイルです。

  内容の制限はとくにありませんが、初期設定では巡回結果ファイルが
  <LI>によるリスト要素として出力されるため、<UL>などのリストフィールドを
  開始した状態でファイルが終了するようにしておく必要があります。

--------------------------------------------------------------------------------
■ 7.7. tail.html

  headと同様ですが、巡回結果ファイルに後置されます。

  内容の制限はとくにありませんが、初期設定では巡回結果ファイルが
  <LI>によるリスト要素として出力されるため、<UL>などのリストフィールドを
  閉じるタグから始まる必要があります。


================================================================================
■ 8. hina.diについて

WDBは、「hina-di」に準拠したリモートアンテナファイル
「hina.di」を作成することができます。これは、外部への提供は
もちろんのこと、自らの前回動作結果としても使用することができます。

自らの前回動作結果を取り込むようにすると、各種障害により更新時刻が
取得できなくなったときに、前回の動作結果を今回の動作結果として
引き継ぐことができるようになります。

WDBは、「hina-2.2beta」でサポートされているすべてのフィールドを
入出力することができます。

・HINA-Version:
対応しているhina-diのバージョンを示します。
WDBでは、"hina-2.2beta"を出力します。

・URL:
ターゲットのリンク先URIです。

・Date:
hina.diのファイル生成を始めた時刻です。

・Title:
ターゲットのタイトル名です。
「朝日奈アンテナ」ではコンテンツの<TITLE></TITLE>を解析して
値を生成します。WDBでも同様に解析します。
このフィールドを出力するには、コンテンツをGETリクエストで得るか、
リモートアンテナからこの情報を得なければなりません。

・Author-Name:
著者名です。
「朝日奈アンテナ」ではコンテンツの<META NAME="Author">タグを
解析して値を生成します。WDBでも同様に解析します。
このフィールドを出力するには、コンテンツをGETリクエストで得るか、
リモートアンテナからこの情報を得なければなりません。

・Keyword:
コンテンツに含まれる情報を簡潔に抜き出したものです。
WDBでは、自分自身では生成を行ないません。

・Last-Modified:
コンテンツの更新時刻です。
GMTのUNIX TIMEフォーマットで記述されます。

・Server:
HTTPサーバを稼働させているサーバ名です。

・Authorized:
hina.diを生成したシステム名です。

・Authorized-url:
hina.diを生成したシステムのURLです。

・Method:
コンテンツへのアクセス記録です。

・Expire:
情報を無効化する時刻です。これ以降は、情報が新しくない可能性があります。

・Last-Modified-Detected:
コンテンツの更新を検知した時刻です。
GMTのUNIX TIMEフォーマットで記述されます。

・Image-Width:, Image-Height:
コンテンツが画像である場合に、画像の幅と高さを値とします。

・X-LM-Is-FMD:
コンテンツからは更新時刻が取得できないことを"1"で示します。
この場合、アンテナ出力HTMLファイルにはLast-Modified:でなく
X-First-Modified-Detected:の時刻を出力することを暗に要求します。

・X-WDB-Title:
巡回定義ファイルで定義された「WWWページの名称」を値とします。

・X-WDB-Author-Name:
巡回定義ファイルで定義された「WWWページの著者名」を値とします。

・X-First-Modified-Detected
Last-Modified:が現在の値であることを最初に検知した時刻です。


================================================================================
■ 8. WDB MAINTENANCE DISPLAYの使用方法

WDB MAINTENANCE DISPLAYは、ブラウザでwdbroot/wdb/を開くと表示されます。

まず最初に"SAMPLE"を選ぶ画面となります。ここでは"SAMPLE"を
選んでください。
# これは複数のアンテナを１つのフォームでメンテ可能にするための
# クッションです。sample*.*を他の名前でコピーして適切な設定を
# 行なうことで、１つのエンジンで複数のアンテナを稼動させることが
# 可能になります。

この画面は上から順に２つのフィールドに分かれています。

 1. ターゲットフィールド
    ターゲットの表示と入力を行ないます。

 2. リモートアンテナフィールド
    リモートアンテナの表示と入力を行ないます。

ターゲットフィールドには、以下のボックスがあります。

 [取得先登録]    登録済みのターゲットがリストされます。
 [右の一覧から呼び出し]
                 リストから選択されたターゲットの情報を入力フィールドへ
                 呼び出します。
 [登録コード名]  ターゲットを識別する名前を入力します。
                 名前は、ファイル名として使用できる文字のみが使用できます。
 [OK]            メンテナンス作業を実行します。
 [RESET]         ターゲット情報の内容をリセットします。
 [呼び出し/記録/削除]
                 呼び出しの場合、[登録コード名]で指定したターゲットを
                 呼び出します。
                 記録の場合、入力されたターゲット情報を[登録コード名]で
                 記録します。
                 削除の場合、[登録コード名]で指定したターゲットの情報を
                 削除します。
 [PASS]          パスワードを入力します。
 [Help]          readme.txtを表示します。
 [URI]           ターゲットのリンク先URIです。
 [タイトル]      ターゲットの名称です。
 [著者]          ターゲットの著者名です。
 [コメント]      ターゲットに対するコメントです。
 [更新時刻取得用URI]
                 ターゲットから情報を取得するためのURIです。
                 指定がなければ、[URI]と同一になります。
 [取得方法]      更新時刻の調査方法です。
 [キーワード]    「時刻を示す文字列」を抽出するための検索キーです。


================================================================================
■ 9. 湘南日記放送局(SDB)について

WDBを使用して作者が構築しているサイトとして、湘南日記放送局(SDB)が
あります。
http://gorry.hauN.org/hina/
http://na01.fortune.ad.jp/~gorry/hina/ （ミラー）


================================================================================
■ 10. 使用許諾

WDBはフリーソフトウェアです。

・各ソースファイルに含まれる著作権表記を削除しないこと。
・発行するHTTPリクエストのUser-Agent:フィールドから"WDB"の文字を
  削除しないこと。

以上の項目を遵守する限り、使用・再配布・改造を認めます。

WDBを使用することにより発生したすべてのトラブルにおいて、作者で
あるGORRYは責任を負いません。とくに、HTTPサーバ上に設置しての使
用は、バグや予想外の事態によりサーバやネットワークシステムに大き
なダメージを与える可能性があります。使用者の責任と厳重な監視のも
とでご使用ください。


================================================================================
[EOF]