[DOCUMENTATION] add 3 tutorials for Lucene

git-svn-id: http://framework.zend.com/svn/framework/standard/trunk@24115 44c647ce-9c0f-0410-b52a-842ac1e357ba

documentation/manual/ja/tutorials/lucene-index-opening.xml

@@ -5,8 +5,8 @@
     <title>インデックスのオープンと生成</title>
 
     <para>
-        例えばインデックスの新規作成やインデックスへのドキュメント追加、
-        ドキュメント削除、インデックス全体の検索のような、
+        例えばインデックスの新規作成やインデックスへの文書追加、
+        文書削除、インデックス全体の検索のような、
         インデックスの操作は全てインデックス･オブジェクトが必要です。
         オブジェクトは、下記の２つのメソッドのいずれかを用いて入手します。
     </para>

documentation/manual/ja/tutorials/lucene-indexing.xml

@@ -0,0 +1,102 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- Reviewed: no -->
+<!-- EN-Revision: 19807 -->
+<sect1 id="learning.lucene.indexing">
+    <title>索引付け</title>
+
+    <para>
+        索引付けは、既存または新しいインデックスに新しい文書を追加することにより実行されます。
+    </para>
+
+    <programlisting language="php"><![CDATA[
+$index->addDocument($doc);
+]]></programlisting>
+
+    <para>
+        文書オブジェクトを生成する方法は2つあります。
+        その一つは、手動で行なうことです。
+    </para>
+
+    <example id="learning.lucene.indexing.doc-creation">
+        <title>手動の文書構成</title>
+
+        <programlisting language="php"><![CDATA[
+$doc = new Zend_Search_Lucene_Document();
+$doc->addField(Zend_Search_Lucene_Field::Text('url', $docUrl));
+$doc->addField(Zend_Search_Lucene_Field::Text('title', $docTitle));
+$doc->addField(Zend_Search_Lucene_Field::unStored('contents', $docBody));
+$doc->addField(Zend_Search_Lucene_Field::binary('avatar', $avatarData));
+]]></programlisting>
+    </example>
+
+    <para>
+        2つ目の方法は、<acronym>HTML</acronym> または Microsoft Office 2007 ファイルから読み込むことです。
+    </para>
+
+    <example id="learning.lucene.indexing.doc-loading">
+        <title>文書読み込み</title>
+
+        <programlisting language="php"><![CDATA[
+$doc = Zend_Search_Lucene_Document_Html::loadHTML($htmlString);
+$doc = Zend_Search_Lucene_Document_Docx::loadDocxFile($path);
+$doc = Zend_Search_Lucene_Document_Pptx::loadPptFile($path);
+$doc = Zend_Search_Lucene_Document_Xlsx::loadXlsxFile($path);
+]]></programlisting>
+    </example>
+
+    <para>
+        サポートされる形式のいずれかから文書が読み込まれた場合、
+        新しいユーザー定義項目でやはり手動で拡張できます。
+    </para>
+
+    <sect2 id="learning.lucene.indexing.policy">
+        <title>索引付けの方針</title>
+
+        <para>
+            アプリケーション方式設計の中で索引付けの方針を定義しなければなりません。
+        </para>
+
+        <para>
+            オンデマンドでの索引付けの構成を必要とするかもしれません
+            （<acronym>OLTP</acronym>システムのような何か）。
+            そのようなシステムでは、通常ユーザーリクエスト毎に文書を１つ追加します。
+            このように、<emphasis>MaxBufferedDocs</emphasis> オプションは、システムに影響を及ぼしません。
+            一方では、スクリプトの最大実行時間を制限できるので、
+            <emphasis>MaxMergeDocs</emphasis>はとても便利です。
+            <emphasis>MergeFactor</emphasis> は、平均的な索引付け時間
+            （平均的な自動最適化時間によっても影響されます）と、
+            検索のパフォーマンス
+            （インデックス最適化レベルはセグメント数に依存します）
+            との間のバランスを保つ値に設定すべきです。
+        </para>
+
+        <para>
+            主にバッチのインデックス更新を実行しているなら、構成では、
+            利用可能なメモリー量でサポートされる最大値に設定された
+            <emphasis>MaxBufferedDocs</emphasis>オプションを使用すべきです。
+            <emphasis>MaxMergeDocs</emphasis> と <emphasis>MergeFactor</emphasis> は、
+            できる限り自動最適化関係を減らす値に設定されなければなりません。
+            <footnote><para>追加の制限は、
+            並列のオープン操作のために OS によってサポートされるファイル・ハンドラーの最大です。
+            </para></footnote>
+            完全なインデックス最適化は、索引付けの後に利用されなければなりません。
+        </para>
+
+        <example id="learning.lucene.indexing.optimization">
+            <title>インデックスの最適化</title>
+
+            <programlisting language="php"><![CDATA[
+$index->optimize();
+]]></programlisting>
+        </example>
+
+        <para>
+            一部の構成では、
+            <!-- TODO : to be translated -->
+            it's more effective to serialize index updates by organizing
+            update requests into a queue and processing several update requests in a single script execution.
+            これは、インデックスのオープンのオーバーヘッドを減らし、
+            インデックス文書のバッファリングを利用できるようにします。
+        </para>
+    </sect2>
+</sect1>

documentation/manual/ja/tutorials/lucene-pagination.xml

@@ -7,7 +7,7 @@
     <para>
         <link linkend="learning.lucene.searching.identifiers">上記</link>
         のように、検索結果ヒット・オブジェクトでは、格納された文書項目に対して
-        レイジー・ローディングを使います。格納された項目のどれかがアクセスされると、
+        遅延読み込みを使います。格納された項目のどれかがアクセスされると、
         全ての文書が読み込まれます。
     </para>
 

documentation/manual/ja/tutorials/lucene-queries.xml

@@ -0,0 +1,230 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- Reviewed: no -->
+<!-- EN-Revision: 19807 -->
+<sect1 id="learning.lucene.queries">
+    <title>サポートされるクエリー</title>
+
+    <para>
+        <classname>Zend_Search_Lucene</classname> と Java Lucene は、
+        強力なクエリー言語をサポートします。それにより、個別の語句や
+        条件の範囲を検索できます。ワイルドカードとあいまい検索を使用したり、
+        論理演算子を用いてクエリーを結合するなどして。
+    </para>
+
+    <para>
+        クエリー言語についての詳細は、<link linkend="zend.search.lucene.query-language">
+            Zend_Search_Lucene コンポーネント･ドキュメント</link>をご覧ください。
+    </para>
+
+    <para>
+        下記は、いくつかの一般的なクエリーの種類と方式の例です。
+    </para>
+
+    <example id="learning.lucene.queries.keyword">
+        <title>単一の単語に対する問い合わせ</title>
+
+        <programlisting language="text"><![CDATA[
+hello
+]]></programlisting>
+
+        <para>
+            文書項目全体を通して単語 "hello" を検索します。
+        </para>
+    </example>
+
+    <note>
+        <title>異なる検索項目</title>
+
+        <para>
+            重要事項。Java Lucene は、デフォルトでは "contents" 項目だけを探していきます。
+            しかし、<classname>Zend_Search_Lucene</classname> は、<emphasis>全</emphasis>項目を探していきます。
+            この動作は、<methodname>Zend_Search_Lucene::setDefaultSearchField($fieldName)</methodname>
+            メソッドを使って変更できます。
+        </para>
+    </note>
+
+    <example id="learning.lucene.queries.multiple-words">
+        <title>複数の単語に対する問い合わせ</title>
+
+        <programlisting language="text"><![CDATA[
+hello dolly
+]]></programlisting>
+
+        <para>
+            2つの単語を検索します。両方の単語は任意です。
+            結果の中に少なくとも一つ存在しなければいけません。
+        </para>
+    </example>
+
+    <example id="learning.lucene.queries.required-words">
+        <title>クエリーで必須の単語</title>
+
+        <programlisting language="text"><![CDATA[
++hello dolly
+]]></programlisting>
+
+        <para>
+            2つの単語を検索します。"hello" は必須で、"dolly" は任意です。
+        </para>
+    </example>
+
+    <example id="learning.lucene.queries.prohibited-words">
+        <title>問い合わせられた文書で単語を禁止</title>
+
+        <programlisting language="text"><![CDATA[
++hello -dolly
+]]></programlisting>
+
+        <para>
+            2つの単語を検索します。"hello" は必須で、'dolly' は禁止です。
+            言い換えると、もし文書が "hello" にマッチし、単語
+            "dolly" を含むと、それは一致セットに返されません。
+        </para>
+    </example>
+
+    <example id="learning.lucene.queries.phrases">
+        <title>句に対する問い合わせ</title>
+
+        <programlisting language="text"><![CDATA[
+"hello dolly"
+]]></programlisting>
+
+        <para>
+            句 "hello dolly" を検索します。
+            まさにその文字列が存在する文書のみマッチします。
+        </para>
+    </example>
+
+    <example id="learning.lucene.queries.fields">
+        <title>特定の項目に対する問い合わせ</title>
+
+        <programlisting language="text"><![CDATA[
+title:"The Right Way" AND text:go
+]]></programlisting>
+
+        <para>
+            <property>title</property> 項目内の句 "The Right Way" および
+            <property>text</property> 項目内の単語 "go" を検索します。
+        </para>
+    </example>
+
+    <example id="learning.lucene.queries.fields-and-document">
+        <title>特定の項目ならびに文書全体に対する問合せ</title>
+
+        <programlisting language="text"><![CDATA[
+title:"The Right Way" AND  go
+]]></programlisting>
+
+        <para>
+            <property>title</property> 項目内の句 "The Right Way" および
+            文書の全項目に現れる単語 "go" を検索します。
+        </para>
+    </example>
+
+    <example id="learning.lucene.queries.fields-and-document-alt">
+        <title>特定の項目ならびに文書全体に対する問合せ（別の例）</title>
+
+        <programlisting language="text"><![CDATA[
+title:Do it right
+]]></programlisting>
+
+        <para>
+            <property>title</property> 項目内の単語 "Do" および
+            全項目の単語 "it" および "right" を探していきます。
+            いずれか一つマッチすると、文書がマッチすることになります。
+        </para>
+    </example>
+
+    <example id="learning.lucene.queries.wildcard-question">
+        <title>ワイルドカード "?" を用いた問い合わせ</title>
+
+        <programlisting language="text"><![CDATA[
+te?t
+]]></programlisting>
+
+        <para>
+            パターン "te?t" にマッチする単語を検索します。
+            そのパターンで、"?" は単一文字の全てです。
+        </para>
+    </example>
+
+    <example id="learning.lucene.queries.wildcard-asterisk">
+        <title>ワイルドカード "*" を用いた問い合わせ</title>
+
+        <programlisting language="text"><![CDATA[
+test*
+]]></programlisting>
+
+        <para>
+            パターン "test*" にマッチする単語を検索します。
+            そのパターンで、"*" はゼロ個以上の文字が連続したもの全てです。
+        </para>
+    </example>
+
+    <example id="learning.lucene.queries.range-inclusive">
+        <title>条件を含む範囲に対する問い合わせ</title>
+
+        <programlisting language="text"><![CDATA[
+mod_date:[20020101 TO 20030101]
+]]></programlisting>
+
+        <para>
+            条件の範囲を検索します (含みます)。
+        </para>
+    </example>
+
+    <example id="learning.lucene.queries.range-exclusive">
+        <title>条件を含まない範囲に対する問い合わせ</title>
+
+        <programlisting language="text"><![CDATA[
+title:{Aida to Carmen}
+]]></programlisting>
+
+        <para>
+            条件の範囲を検索します (含みません)。
+        </para>
+    </example>
+
+    <example id="learning.lucene.queries.fuzzy">
+        <title>あいまい検索</title>
+
+        <programlisting language="text"><![CDATA[
+roam~
+]]></programlisting>
+
+        <para>
+            単語 "roam" をあいまい検索します。
+        </para>
+    </example>
+
+    <example id="learning.lucene.queries.boolean">
+        <title>論理検索</title>
+
+        <programlisting language="text"><![CDATA[
+(framework OR library) AND php
+]]></programlisting>
+
+        <para>
+            論理クエリー
+        </para>
+    </example>
+
+    <para>
+        サポートされたクエリーは全て、<classname>Zend_Search_Lucene</classname>
+        の<link linkend="zend.search.lucene.query-api">クエリ構成 API</link>
+        で構成できます。
+        さらに、クエリー解析とクエリー構成を組み合わせるかもしれません。
+    </para>
+
+    <example id="learning.lucene.queries.combining">
+        <title>解析されて構成されたクエリーを組み合わせ</title>
+
+        <programlisting language="php"><![CDATA[
+$userQuery = Zend_Search_Lucene_Search_QueryParser::parse($queryStr);
+
+$query = new Zend_Search_Lucene_Search_Query_Boolean();
+$query->addSubquery($userQuery, true  /* required */);
+$query->addSubquery($constructedQuery, true  /* required */);
+]]></programlisting>
+    </example>
+</sect1>

documentation/manual/ja/tutorials/lucene-searching.xml

@@ -0,0 +1,99 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- Reviewed: no -->
+<!-- EN-Revision: 19807 -->
+<sect1 id="learning.lucene.searching">
+    <title>検索</title>
+
+    <para>
+        検索は、<methodname>find()</methodname> メソッドを使って実行されます。
+    </para>
+
+    <example id="learning.lucene.searching.search-example">
+        <title>インデックスを検索</title>
+
+        <programlisting language="php"><![CDATA[
+$hits = $index->find($query);
+
+foreach ($hits as $hit) {
+    printf("%d %f %s\n", $hit->id, $hit->score, $hit->title);
+}
+]]></programlisting>
+    </example>
+
+    <para>
+        この例は、2つの特別な検索ヒット・プロパティ、
+        <property>id</property> および <property>score</property> の使用法を示します。
+    </para>
+
+    <para>
+        <property>id</property> は、Lucene インデックス内で使用される内部的な文書識別番号です。
+        それは、インデックスから文書を削除することを含む、様々な操作のために使われるでしょう。
+    </para>
+
+    <example id="learning.lucene.searching.delete-example">
+        <title>索引付けされた文書を削除</title>
+
+        <programlisting language="php"><![CDATA[
+$index->delete($id);
+]]></programlisting>
+    </example>
+
+    <para>
+        あるいは、インデックスによって文書を取得します。
+    </para>
+
+    <example id="learning.lucene.searching.retrieve-example">
+        <title>索引付けされた文書を取得</title>
+
+        <programlisting language="php"><![CDATA[
+$doc = $index->getDocument($id);
+]]></programlisting>
+    </example>
+
+    <note id="learning.lucene.searching.identifiers">
+        <title>内部的な文書識別番号</title>
+
+        <para>
+            重要事項！内部的な文書識別番号は、インデックスの最適化または自動最適化処理によって変わるかもしれません。
+            しかし、（自動最適化処理に含まれるであろう） <methodname>addDocument()</methodname>
+            や、<methodname>optimize()</methodname> メソッドが呼び出されない限り、
+            単一のスクリプト実行中には決して変わりません。
+        </para>
+    </note>
+
+    <para>
+        <property>score</property>項目は、ヒット・スコアです。
+        検索結果は、デフォルトで得点によって順序づけられます。（最高の結果は、最初に戻されます）
+    </para>
+
+    <para>
+        特定の項目値によって結果セットを順序づけることもできます。この可能性について詳しくは、
+        <link linkend="zend.search.lucene.searching.sorting">
+        <classname>Zend_Search_Lucene</classname> ドキュメント</link>をご覧ください。
+    </para>
+
+    <para>
+        その例は、格納された項目にアクセスする能力も示します。
+        （例えば、<command>$hit->title</command>）
+        <property>id</property> または <property>score</property>
+        以外のいずれかのヒット・プロパティーに初めてアクセスすると、
+        文書の保管された項目が読み込まれ、対応する項目値が返されます。
+    </para>
+
+    <para>
+        これは、それら自身の <property>id</property> または <property>score</property>
+        項目を持つ文書にあいまいさを引き起こします。
+        その結果、保管された文書内でそれらの項目名を使うことはお勧めしません。
+        とはいっても、それらは <methodname>getDocument()</methodname> メソッドを通じて、
+        今まで通りアクセスできます。
+    </para>
+
+    <example id="learning.lucene.searching.id-score-fields">
+        <title>オリジナル文書の "id" および "score" 項目にアクセス</title>
+
+        <programlisting language="php"><![CDATA[
+$id    = $hit->getDocument()->id;
+$score = $hit->getDocument()->score;
+]]></programlisting>
+    </example>
+</sect1>