<?xml version="1.0" encoding="iso-2022-jp"?>
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.ja.xsl"?>
<!-- English Revision: 1.9 (outdated: 1.9.2.5) -->

<!--
 Copyright 2002-2004 The Apache Software Foundation

 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
 You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
-->

<modulesynopsis metafile="mod_negotiation.xml.meta">

<name>mod_negotiation</name>
<description><a href="../content-negotiation.html">コンテントネゴシエーション</a>
  機能を提供する</description>
<status>Base</status>
<sourcefile>mod_negotiation.c</sourcefile>
<identifier>negotiation_module</identifier>

<summary>
    <p>コンテントネゴシエーション、より正確にはコンテンツの選択機能は、
    複数用意されているドキュメントから、クライアントの能力に一番合った
    ドキュメントを選択する機能です。この実装は二つあります。</p>

    <ul>
      <li>タイプマップ (<code>type-map</code>
      ハンドラで扱われるファイル)。これは variants
      を含んでいるファイルを明示的に指定します。</li>

      <li>MultiViews の探索 (MultiViews <directive
      module="core">Option</directive> で使用するようになります)。
      サーバが暗黙の内にファイル名のパターンマッチを行ない、
      その結果から選択します。</li>
    </ul>
</summary>

<seealso><directive module="mod_mime">DefaultLanguage</directive></seealso>
<seealso><directive module="mod_mime">AddEncoding</directive></seealso>
<seealso><directive module="mod_mime">AddLanguage</directive></seealso>
<seealso><directive module="mod_mime">AddType</directive></seealso>
<seealso><directive module="mod_mime">MultiViewsMatch</directive></seealso>

<section id="typemaps"><title>タイプマップ</title>
    <p>タイプマップは RFC 822 のメールヘッダと同じ書式です。
    ドキュメントの記述が空行で分離されて書かれていて、ハッシュ文字
    ('#') で始まる行はコメントとして扱われます。
    ドキュメントの説明は複数のヘッダレコードから構成されます。
    レコードは、続きの行が空白で始まっていると複数の行にまたがります。
    最初の空白が消去されて、前の行とつなげて 1 行として扱われます。
    ヘッダレコードはキーワード名の後に値が続くという形式で、
    キーワード名は常にコロンで終わります。空白はヘッダ名と値の間、
    値のトークンの間に入れることができます。
    使用可能なヘッダは以下のとおりです:</p>

    <dl>
      <dt>Content-Encoding:</dt>
      <dd>ファイルのエンコーディング。Apache は <directive
      module="mod_mime">AddEncoding</directive> ディレクティブ
      で定義されたエンコーディングだけを認識します。通常 compress
      されたファイルのための <code>x-compress</code> と gzip
      されたファイルのための <code>x-gzip</code> を含みます。
      エンコーディングの比較をするときは、接頭辞 <code>x-</code>
      は無視されます。</dd>


    <dt>Content-Language:</dt>

    <dd>インターネット標準の言語タグ (RFC 1766)
    で定義されている言語の種類。例えば、<code>en</code>
    は英語を表します。</dd>

    <dt>Content-Length:</dt>

    <dd>ファイルの長さ (バイト数)。
    このヘッダがない場合、ファイルの実際の長さが使用されます。</dd>

    <dt>Content-Type:</dt>

    <dd>ドキュメントの MIME
      メディアタイプ、オプショナルなパラメータ付き。パラメータの構文は
      <code>name=value</code>
      で、メディアタイプや他のパラメータとはセミコロンで分離されます。
      共通のパラメータは以下のとおり:

      <dl>
        <dt>level</dt>

        <dd>メディアタイプのバージョンを示す整数。
        <code>text/html</code> では 2 がデフォルトで、その他の場合は
        0 がデフォルトです。</dd>

        <dt>qs</dt>

        <dd>クライアントの能力に関係なく、variant
        を他と比較したときの相対的な「品質」で、0.0 から 1.0
        の範囲の浮動点小数。
        例えば、写真を表現しようとしているときは普通は JPEG
        ファイルの方が ASCII ファイルよりも高い品質になります。
        しかし、リソースが ASCII アートで表現されているときは、ASCII
        ファイルの方が JPEG
        ファイルよりも高い品質になります。このように、qs
        はリソース毎に特有の値を取ります。
        </dd>
      </dl>
      例:

<example>Content-Type: image/jpeg; qs=0.8</example>
      </dd>

      <dt>URI:</dt>

      <dd>(指定のメディアタイプ、コンテントエンコーディングの) variant の
      ファイルの uri.  これは、マップファイルからの相対 URL として
      解釈されます。同じサーバに存在しなければならず、クライアントが
      直接リクエストしたときにアクセスを許可されるものでなければなりません。</dd>

      <dt>Body:</dt>
   
      <dd><p>Apache 2.0 で新設されたこの Body ヘッダを使って、
      リソースの実際の内容をタイプマップファイルに書くことができます。
      このヘッダは本文の内容の区切りとなる文字列で始まる必要があります。
      タイプマップファイルの続く行は、区切り文字列が見つかるまで、
      リソースの本文になります。</p>

      <p>例:</p>
<example>
Body:----xyz----<br />
&lt;html&gt;<br />
&lt;body&gt;<br />
&lt;p&gt;Content of the page.&lt;/p&gt;<br />
&lt;/body&gt;<br />
&lt;/html&gt;<br />
----xyz----
</example>
      </dd>
    </dl>
</section>

<section id="multiviews">
    <title>MultiViews</title>

    <p>MultiViews 探索は、Multiviews <directive
    module="core">Options</directive> ディレクティブにより有効になります。
    サーバが <code>/some/dir/foo</code>
    へのリクエストを受け取り、<code>/some/dir/foo</code> が存在
    <em>しない</em>場合、サーバはディレクトリを読んで、
    <code>foo.*</code> にあてはまる全てのファイルを探し、
    事実上それらのファイルをマップするタイプマップを作ります。
    そのとき、メディアタイプとコンテントエンコーディングは、
    そのファイル名を直接指定したときと同じものが割り当てられます。
    それからクライアントの要求に一番合うものを選び、
    そのドキュメントを返します。</p>
</section>

<directivesynopsis>
<name>CacheNegotiatedDocs</name>
<description>コンテントネゴシエーションされたドキュメントをプロキシサーバが
キャッシュできるようにする</description>
<syntax>CacheNegotiatedDocs on|off</syntax>
<default>CacheNegotiatedDocs off</default>
<contextlist><context>server config</context>
<context>virtual host</context>
</contextlist>
<compatibility>バージョン 2.0で構文が変わりました</compatibility>

<usage>
    <p>このディレクティブが設定されていると、コンテントネゴシエーション
    をした結果のドキュメントのキャッシュを許可します。
    これは、プロキシの後ろにいるクライアントが能力に一番合った
    ドキュメントではなく、
    キャッシュをより効果的にするものを得る可能性があるということです。</p>

    <p>このディレクティブは HTTP/1.0 ブラウザからのリクエスト
    のみに適用されます。HTTP/1.1 は、
    交渉されたドキュメントのキャッシュに対してずっとよい制御が可能なので、
    このディレクティブは HTTP/1.1 のリクエストには影響しません。</p>
    <p>2.0 より前のバージョンでは、
    <directive>CacheNegotiatedDocs</directive> は引数を取らず、
    ディレクティブが存在することで on の動作をしていました。</p>
</usage>
</directivesynopsis>

<directivesynopsis>
<name>ForceLanguagePriority</name>
<description>要求に合う単独のドキュメントが見つからなかったときに行なうことを指定
</description>
<syntax>ForceLanguagePriority None|Prefer|Fallback [Prefer|Fallback]</syntax>
<default>ForceLanguagePriority Prefer</default>
<contextlist><context>server config</context>
<context>virtual host</context>
<context>directory</context>
<context>.htaccess</context>
</contextlist>
<override>FileInfo</override>
<compatibility>バージョン 2.0.30 以降で使用可能</compatibility>

<usage>
    <p><directive>ForceLanguagePriority</directive> ディレクティブは
    要求に合うドキュメントを一つだけ返すことができないときに、
    <directive module="mod_negotiation">LanguagePriority</directive>
    ディレクティブを使ってネゴシエーションの結果を返します。</p>

    <p><code>ForceLanguagePriority Prefer</code> は、同等の選択肢が
    いくつかあるときに、HTTP の 300 (MULTIPLE CHOICES) を返す代わりに、
    <code>LanguagePriority</code> を使って一つだけドキュメントを返すように
    します。以下のディレクティブが指定されていて、ユーザの Accept-Language
    ヘッダでは en と de の品質が共に .500 (同じくらい許容) であるときは、
    最初にマッチする variant の en が送られます。</p>

<example>
      LanguagePriority en fr de<br />
      ForceLanguagePriority Prefer
</example>

    <p><code>ForceLanguagePriority Fallback</code> は、HTTP 406
    (NOT ACCEPTABLE) の代わりにドキュメントを送ります。
    以下のディレクティブが指定されていて、ユーザの Accept-Language は
    es 言語のみを許可していて、さらにそのような variant がないときには、
    以下の LanguagePriority のリストの最初の variant が送れれます。</p>

<example>
      LanguagePriority en fr de<br />
      ForceLanguagePriority Fallback
</example>

    <p>Prefer と Fallback の両方のオプションを同時に指定することができます。
    ですから、複数の variant があるときは LanguagePriority の最初の
    variant が送られ、クライアントの許容言語に合う vaiant がないときは
    存在するドキュメントで最初のものが送られる、という様にすることができます。</p>
</usage>
</directivesynopsis>

<directivesynopsis>
<name>LanguagePriority</name>
<description>クライアントが優先度を示さなかったときの言語の variant の優先度を
指定</description>
<syntax>LanguagePriority <em>MIME-lang</em> [<em>MIME-lang</em>] ...</syntax>
<contextlist><context>server config</context>
<context>virtual host</context>
<context>directory</context>
<context>.htaccess</context>
</contextlist>
<override>FileInfo</override>

<usage>
    <p><directive>LanguagePriority</directive> は、MultiViews
    リクエストを扱うときに、クライアントが優先順位を提供していない場合の
    言語の優先順位を設定します。<em>MIME-lang</em>
    のリストが優先度の降順に並びます。
    例:</p>

<example>LanguagePriority en fr de</example>

    <p><code>foo.html</code> がリクエストされ、<code>foo.html.fr</code>
    と <code>foo.html.de</code> が両方存在し、
    ブラウザが言語の優先順位を提供してない場合は
    <code>foo.html.fr</code> が返されます。</p>

    <p>このディレクティブは他の方法で「最善」
    の言語が決定できないときか、<directive
    module="mod_negotiation">ForceLanguagePriority</directive> ディレクティブが
    <code>None</code> 以外のときにのみ効果があることに注意してください。
    HTTP/1.1 リクエストが正しく実装されている場合には、
    このディレクティブは無効になります。</p>
</usage>
</directivesynopsis>

</modulesynopsis>
