granicus.if.org Git - apache/blob - docs/manual/mod/mod_negotiation.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
   3 <?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?>
   4 <modulesynopsis>
   5
   6 <name>mod_negotiation</name>
   7 <description>Provides for <a
   8     href="../content-negotiation.html">content negotiation</a></description>
   9 <status>Base</status>
  10 <sourcefile>mod_negotiation.c</sourcefile>
  11 <identifier>negotiation_module</identifier>
  12
  13 <summary>
  14     <p>Content negotiation, or more accurately content selection, is
  15     the selection of the document that best matches the clients
  16     capabilities, from one of several available documents. There
  17     are two implementations of this.</p>
  18
  19     <ul>
  20       <li>A type map (a file with the handler
  21       <code>type-map</code>) which explicitly lists the files
  22       containing the variants.</li>
  23
  24       <li>A MultiViews search (enabled by the MultiViews <directive
  25       module="core">Options</directive>, where the server does an
  26       implicit filename pattern match, and choose from amongst the
  27       results.</li>
  28     </ul>
  29 </summary>
  30
  31 <seealso><directive module="mod_mime">DefaultLangauge</directive></seealso>
  32 <seealso><directive module="mod_mime">AddEncoding</directive></seealso>
  33 <seealso><directive module="mod_mime">AddLanguage</directive></seealso>
  34 <seealso><directive module="mod_mime">AddType</directive></seealso>
  35
  36 <section><title>Type maps</title>
  37     <p>A type map has the same format as RFC822 mail headers. It
  38     contains document descriptions separated by blank lines, with
  39     lines beginning with a hash character ('#') treated as
  40     comments. A document description consists of several header
  41     records; records may be continued on multiple lines if the
  42     continuation lines start with spaces. The leading space will be
  43     deleted and the lines concatenated. A header record consists of
  44     a keyword name, which always ends in a colon, followed by a
  45     value. Whitespace is allowed between the header name and value,
  46     and between the tokens of value. The headers allowed are: </p>
  47
  48     <dl>
  49       <dt>Content-Encoding:</dt>
  50
  51       <dd>The encoding of the file. Apache only recognizes
  52       encodings that are defined by an <directive
  53       module="mod_mime">AddEncoding</directive> directive.
  54       This normally includes the encodings <code>x-compress</code>
  55       for compress'd files, and <code>x-gzip</code> for gzip'd
  56       files. The <code>x-</code> prefix is ignored for encoding
  57       comparisons.</dd>
  58
  59       <dt>Content-Language:</dt>
  60
  61       <dd>The language of the variant, as an Internet standard
  62       language tag (RFC 1766). An example is <code>en</code>,
  63       meaning English.</dd>
  64
  65       <dt>Content-Length:</dt>
  66
  67       <dd>The length of the file, in bytes. If this header is not
  68       present, then the actual length of the file is used.</dd>
  69
  70       <dt>Content-Type:</dt>
  71
  72       <dd>
  73         The MIME media type of the document, with optional
  74         parameters. Parameters are separated from the media type
  75         and from one another by a semi-colon, with a syntax of
  76         <code>name=value</code>. Common parameters include:
  77
  78         <dl>
  79           <dt>level</dt>
  80
  81           <dd>an integer specifying the version of the media type.
  82           For <code>text/html</code> this defaults to 2, otherwise
  83           0.</dd>
  84
  85           <dt>qs</dt>
  86
  87           <dd>a floating-point number with a value in the range 0.0
  88           to 1.0, indicating the relative 'quality' of this variant
  89           compared to the other available variants, independent of
  90           the client's capabilities. For example, a jpeg file is
  91           usually of higher source quality than an ascii file if it
  92           is attempting to represent a photograph. However, if the
  93           resource being represented is ascii art, then an ascii
  94           file would have a higher source quality than a jpeg file.
  95           All qs values are therefore specific to a given
  96           resource.</dd>
  97         </dl>
  98         Example:
  99
 100         <blockquote>
 101           <code>Content-Type: image/jpeg; qs=0.8</code>
 102         </blockquote>
 103       </dd>
 104
 105       <dt>URI:</dt>
 106
 107       <dd>The path to the file containing this variant, relative to
 108       the map file.</dd>
 109     </dl>
 110 </section>
 111
 112 <section><title>MultiViews</title>
 113
 114     <p>A MultiViews search is enabled by the MultiViews <directive
 115     module="core">Options</directive>. If the server receives a
 116     request for <code>/some/dir/foo</code> and
 117     <code>/some/dir/foo</code> does <em>not</em> exist, then the
 118     server reads the directory looking for all files named
 119     <code>foo.*</code>, and effectively fakes up a type map which
 120     names all those files, assigning them the same media types and
 121     content-encodings it would have if the client had asked for one
 122     of them by name. It then chooses the best match to the client's
 123     requirements, and returns that document.</p>
 124 </section>
 125
 126 <directivesynopsis>
 127 <name>CacheNegotiatedDocs</name>
 128 <description>Allows content-negotiated documents to be
 129 cached by proxy servers</description>
 130 <syntax>CacheNegotiatedDocs on|off</syntax>
 131 <default>CacheNegotiatedDocs off</default>
 132 <contextlist><context>server config</context></contextlist>
 133 <compatibility>The syntax changed in version 2.0.</compatibility>
 134
 135 <usage>
 136     <p>If set, this directive allows content-negotiated documents
 137     to be cached by proxy servers. This could mean that clients
 138     behind those proxys could retrieve versions of the documents
 139     that are not the best match for their abilities, but it will
 140     make caching more efficient.</p>
 141
 142     <p>This directive only applies to requests which come from
 143     HTTP/1.0 browsers. HTTP/1.1 provides much better control over
 144     the caching of negotiated documents, and this directive has no
 145     effect in responses to HTTP/1.1 requests.</p>
 146
 147     <p>Prior to version 2.0,
 148     <directive>CacheNegotiatedDocs</directive> did not take an
 149     argument; it was turned on by the presence of the directive by
 150     itself.</p>
 151 </usage>
 152 </directivesynopsis>
 153
 154 <directivesynopsis>
 155 <name>ForceLangaugePriority</name>
 156 <description>Action to take if a single acceptable document is not
 157 found</description>
 158 <syntax>ForceLanguagePriority None|Prefer|Fallback [Prefer|Fallback]</syntax>
 159 <default>ForceLangaugePriority None</default>
 160 <contextlist><context>server config</context>
 161 <context>virtual host</context>
 162 <context>directory</context>
 163 <context>.htaccess</context>
 164 </contextlist>
 165 <override>FileInfo</override>
 166 <compatibility>Available in version 2.0.30 and later</compatibility>
 167
 168 <usage>
 169     <p>The <directive>ForceLanguagePriority</directive> directive uses
 170     the given <directive
 171     module="mod_negotiation">LanguagePriority</directive> to satisfy
 172     negotation where the server could otherwise not return a single
 173     matching document.</p>
 174
 175     <p><code>ForceLanguagePriority Prefer</code> uses
 176     <code>LanguagePriority</code> to serve a one valid result, rather
 177     than returning an HTTP result 300 (MULTIPLE CHOICES) when there
 178     are several equally valid choices.  If the directives below were
 179     given, and the user's Accept-Language header assigned en and de
 180     each as quality .500 (equally acceptable) then then first matching
 181     variant, en, will be served.</p>
 182
 183 <example>
 184       LanguagePriority en fr de<br />
 185       ForceLanguagePriority Prefer
 186 </example>
 187
 188     <p><code>ForceLanguagePriority Fallback</code> uses
 189     <code>LanguagePriority</code> to serve a valid result, rather than
 190     returning an HTTP result 406 (NOT ACCEPTABLE).  If the directives
 191     below were given, and the user's Accept-Language only permitted an
 192     es langauge response, but such a variant isn't found, then the
 193     first variant from the LanguagePriority list below will be
 194     served.</p>
 195
 196 <example>
 197       LanguagePriority en fr de<br />
 198       ForceLanguagePriority Fallback
 199 </example>
 200
 201     <p>Both options, Prefer and Fallback, may be specified, so either the
 202     first matching variant from LanguagePriority will be served if more
 203     that one variant is acceptable, or first available document will be
 204     served if none of the variants matched the client's acceptable list of
 205     languages.</p>
 206 </usage>
 207 </directivesynopsis>
 208
 209 <directivesynopsis>
 210 <name>LanguagePriority</name>
 211 <description>The precendence of language variants for cases where
 212 the client does not express a preference</description>
 213 <syntax>LanguagePriority <em>MIME-lang</em> [<em>MIME-lang</em>] ...</syntax>
 214 <contextlist><context>server config</context>
 215 <context>virtual host</context>
 216 <context>directory</context>
 217 <context>.htaccess</context>
 218 </contextlist>
 219 <override>FileInfo</override>
 220
 221 <usage>
 222     <p>The <directive>LanguagePriority</directive> sets the precedence
 223     of language variants for the case where the client does not
 224     express a preference, when handling a MultiViews request. The list
 225     of <em>MIME-lang</em> are in order of decreasing preference.
 226     Example:</p>
 227
 228 <example>LanguagePriority en fr de</example>
 229
 230     <p>For a request for <code>foo.html</code>, where
 231     <code>foo.html.fr</code> and <code>foo.html.de</code> both
 232     existed, but the browser did not express a language preference,
 233     then <code>foo.html.fr</code> would be returned.</p>
 234
 235     <p>Note that this directive only has an effect if a 'best'
 236     language cannot be determined by any other means or the <directive
 237     module="mod_negotiation">ForceLanguagePriority</directive> directive
 238     is not <code>None</code>. Correctly implemented HTTP/1.1 requests
 239     will mean this directive has no effect.</p>
 240 </usage>
 241 </directivesynopsis>
 242
 243 </modulesynopsis>