dgaudet 97/12/20 12:42:29
Modified: htdocs/manual content-negotiation.html Log: Lars says: some people are confused if they see the different naming conventions for language negotiated documents (e.g. foo.html.en vs. foo.en.html) and how a hyperlink to such a document should look like. There's a PR about it (#1559) and I've seen several questions on usenet about it. I tried to clarify this issue in an extra paragraph in the content-negotiation.html document (see attachment). PR: 1559 Submitted by: Lars Eilebrecht Reviewed by: Dean Gaudet Revision Changes Path 1.12 +100 -1 apachen/htdocs/manual/content-negotiation.html Index: content-negotiation.html =================================================================== RCS file: /export/home/cvs/apachen/htdocs/manual/content-negotiation.html,v retrieving revision 1.11 retrieving revision 1.12 diff -u -r1.11 -r1.12 --- content-negotiation.html 1997/07/06 17:18:52 1.11 +++ content-negotiation.html 1997/12/20 20:42:29 1.12 @@ -15,6 +15,7 @@ <!--#include virtual="header.html" --> <h1 ALIGN="CENTER">Content Negotiation</h1> +<p> Apache's support for content negotiation has been updated to meet the HTTP/1.1 specification. It can choose the best representation of a resource based on the browser-supplied preferences for media type, @@ -30,6 +31,7 @@ <h2>About Content Negotiation</h2> +<p> A resource may be available in several different representations. For example, it might be available in different languages or different media types, or a combination. One way of selecting the most @@ -46,6 +48,7 @@ Accept-Language: fr </pre> +<p> Note that this preference will only be applied when there is a choice of representations and they vary by language. <p> @@ -76,6 +79,7 @@ <h2>Negotiation in Apache</h2> +<p> In order to negotiate a resource, the server needs to be given information about each of the variants. This is done in one of two ways: @@ -89,6 +93,7 @@ <h3>Using a type-map file</h3> +<p> A type map is a document which is associated with the handler named <code>type-map</code> (or, for backwards-compatibility with older Apache configurations, the mime type @@ -179,6 +184,7 @@ <h3>Multiviews</h3> +<p> This is a per-directory option, meaning it can be set with an <code>Options</code> directive within a <code><Directory></code>, <code><Location></code> or <code><Files></code> @@ -261,10 +267,10 @@ <h3>Apache Negotiation Algorithm</h3> +<p> Apache uses an algorithm to select the 'best' variant (if any) to return to the browser. This algorithm is not configurable. It operates like this: -<p> <ol> <li> @@ -323,8 +329,10 @@ dimensions of variance. </ol> + <h2><a name="better">Fiddling with Quality Values</a></h2> +<p> Apache sometimes changes the quality values from what would be expected by a strict interpretation of the algorithm above. This is to get a better result from the algorithm for browsers which do not send @@ -337,6 +345,7 @@ <h3>Media Types and Wildcards</h3> +<p> The Accept: request header indicates preferences for media types. It can also include 'wildcard' media types, such as "image/*" or "*/*" where the * matches any string. So a request including: @@ -379,6 +388,7 @@ <h3>Variants with no Language</h3> +<p> If some of the variants for a particular resource have a language attribute, and some do not, those variants with no language are given a very low language quality factor of 0.001.<p> @@ -396,14 +406,103 @@ <li>foo.html, no language </ul> +<p> The meaning of a variant with no language is that it is always acceptable to the browser. If the request Accept-Language header includes either en or fr (or both) one of foo.en.html or foo.fr.html will be returned. If the browser does not list either en or fr as acceptable, foo.html will be returned instead. +<h2>Note on hyperlinks and naming conventions</h2> + +<p> +If you are using language negotiation you can choose between +different naming conventions, because files can have more than one +extension, and the order of the extensions is normally irrelevant +(see <a href="mod/mod_mime.html">mod_mime</a> documentation for details). +<p> +A typical file has a mime-type extension (e.g. <samp>html</samp>), +maybe an encoding extension (e.g. <samp>gz</samp> and of course a +language extension (e.g. <samp>en</samp>) when we have different +language variants of this file. + +<p> +Examples: +<ul> +<li>foo.en.html +<li>foo.html.en +<li>foo.en.html.gz +</ul> + +<p> +Here some more examples of filenames together with valid and invalid hyperlinks: +</p> + +<table border=1 cellpadding=8 cellspacing=0> +<tr> + <th>Filename</th> + <th>Valid hyperlink</th> + <th>Invalid hyperlink</th> +</tr> +<tr> + <td><em>foo.html.en</em></td> + <td>foo<br> + foo.html</td> + <td>-</td> +</tr> +<tr> + <td><em>foo.en.html</em></td> + <td>foo</td> + <td>foo.html</td> +</tr> +<tr> + <td><em>foo.html.en.gz</em></td> + <td>foo<br> + foo.html</td> + <td>foo.gz<br> + foo.html.gz</td> +</tr> +<tr> + <td><em>foo.en.html.gz</em></td> + <td>foo</td> + <td>foo.html<br> + foo.html.gz<br> + foo.gz</td> +</tr> +<tr> + <td><em>foo.gz.html.en</em></td> + <td>foo<br> + foo.gz<br> + foo.gz.html</td> + <td>foo.html</td> +</tr> +<tr> + <td><em>foo.html.gz.en</em></td> + <td>foo<br> + foo.html<br> + foo.html.gz</td> + <td>foo.gz</td> +</tr> +</table> + +<p> +Looking at the table above you will notice that it is always possible to +use the name without any extensions in an hyperlink (e.g. <samp>foo</samp>). +The advantage is that you can hide the actual type of a +document rsp. file and can change it later, e.g. from <samp>html</samp> +to <samp>shtml</samp> or <samp>cgi</samp> without changing any +hyperlink references. + +<p> +If you want to continue to use a mime-type in your hyperlinks (e.g. +<samp>foo.html</samp>) the language extension (including an encoding extension +if there is one) must be on the right hand side of the mime-type extension +(e.g. <samp>foo.html.en</samp>). + + <h2>Note on Caching</h2> +<p> When a cache stores a document, it associates it with the request URL. The next time that URL is requested, the cache can use the stored document, provided it is still within date. But if the resource is