From: dgaudet Date: Sat, 20 Dec 1997 20:42:29 +0000 (+0000) Subject: Lars says: X-Git-Tag: APACHE_1_3b5~38 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=7f9ce50323d5933e04fd3ee413573c0607e8841d;p=thirdparty%2Fapache%2Fhttpd.git 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 git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@79735 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/content-negotiation.html b/docs/manual/content-negotiation.html index dee5e6f30a9..c6b096a688a 100644 --- a/docs/manual/content-negotiation.html +++ b/docs/manual/content-negotiation.html @@ -15,6 +15,7 @@

Content Negotiation

+

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 @@ which is compiled in by default.

About Content Negotiation

+

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 @@ French representations, the browser would send Accept-Language: fr +

Note that this preference will only be applied when there is a choice of representations and they vary by language.

@@ -76,6 +79,7 @@ resource vary are called the dimensions of negotiation.

Negotiation in Apache

+

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 @@ ways:

Using a type-map file

+

A type map is a document which is associated with the handler named type-map (or, for backwards-compatibility with older Apache configurations, the mime type @@ -179,6 +184,7 @@ The full list of headers recognized is:

Multiviews

+

This is a per-directory option, meaning it can be set with an Options directive within a <Directory>, <Location> or <Files> @@ -261,10 +267,10 @@ can indicate a charset as a parameter of the media type.

Apache Negotiation Algorithm

+

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: -

  1. @@ -323,8 +329,10 @@ and go to stage 3. dimensions of variance.
+

Fiddling with Quality Values

+

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 @@ be applied.

Media Types and Wildcards

+

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 @@ which send the correct information to start with work as expected.

Variants with no Language

+

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.

@@ -396,14 +406,103 @@ For example, consider the situation with three variants:

  • foo.html, no language +

    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. +

    Note on hyperlinks and naming conventions

    + +

    +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 mod_mime documentation for details). +

    +A typical file has a mime-type extension (e.g. html), +maybe an encoding extension (e.g. gz and of course a +language extension (e.g. en) when we have different +language variants of this file. + +

    +Examples: +

    + +

    +Here some more examples of filenames together with valid and invalid hyperlinks: +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FilenameValid hyperlinkInvalid hyperlink
    foo.html.enfoo
    + foo.html    		-
    foo.en.htmlfoofoo.html
    foo.html.en.gzfoo
    + foo.html    		foo.gz
    + foo.html.gz
    foo.en.html.gzfoofoo.html
    + foo.html.gz
    + foo.gz
    foo.gz.html.enfoo
    + foo.gz
    + foo.gz.html    		foo.html
    foo.html.gz.enfoo
    + foo.html
    + foo.html.gz    		foo.gz
    + +

    +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. foo). +The advantage is that you can hide the actual type of a +document rsp. file and can change it later, e.g. from html +to shtml or cgi without changing any +hyperlink references. + +

    +If you want to continue to use a mime-type in your hyperlinks (e.g. +foo.html) 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. foo.html.en). + +

    Note on Caching

    +

    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 diff --git a/docs/manual/content-negotiation.html.en b/docs/manual/content-negotiation.html.en index dee5e6f30a9..c6b096a688a 100644 --- a/docs/manual/content-negotiation.html.en +++ b/docs/manual/content-negotiation.html.en @@ -15,6 +15,7 @@

    Content Negotiation

    +

    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 @@ which is compiled in by default.

    About Content Negotiation

    +

    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 @@ French representations, the browser would send Accept-Language: fr +

    Note that this preference will only be applied when there is a choice of representations and they vary by language.

    @@ -76,6 +79,7 @@ resource vary are called the dimensions of negotiation.

    Negotiation in Apache

    +

    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 @@ ways:

    Using a type-map file

    +

    A type map is a document which is associated with the handler named type-map (or, for backwards-compatibility with older Apache configurations, the mime type @@ -179,6 +184,7 @@ The full list of headers recognized is:

    Multiviews

    +

    This is a per-directory option, meaning it can be set with an Options directive within a <Directory>, <Location> or <Files> @@ -261,10 +267,10 @@ can indicate a charset as a parameter of the media type.

    Apache Negotiation Algorithm

    +

    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: -

    1. @@ -323,8 +329,10 @@ and go to stage 3. dimensions of variance.
    +

    Fiddling with Quality Values

    +

    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 @@ be applied.

    Media Types and Wildcards

    +

    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 @@ which send the correct information to start with work as expected.

    Variants with no Language

    +

    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.

    @@ -396,14 +406,103 @@ For example, consider the situation with three variants:

  • foo.html, no language +

    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. +

    Note on hyperlinks and naming conventions

    + +

    +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 mod_mime documentation for details). +

    +A typical file has a mime-type extension (e.g. html), +maybe an encoding extension (e.g. gz and of course a +language extension (e.g. en) when we have different +language variants of this file. + +

    +Examples: +

    + +

    +Here some more examples of filenames together with valid and invalid hyperlinks: +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FilenameValid hyperlinkInvalid hyperlink
    foo.html.enfoo
    + foo.html    		-
    foo.en.htmlfoofoo.html
    foo.html.en.gzfoo
    + foo.html    		foo.gz
    + foo.html.gz
    foo.en.html.gzfoofoo.html
    + foo.html.gz
    + foo.gz
    foo.gz.html.enfoo
    + foo.gz
    + foo.gz.html    		foo.html
    foo.html.gz.enfoo
    + foo.html
    + foo.html.gz    		foo.gz
    + +

    +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. foo). +The advantage is that you can hide the actual type of a +document rsp. file and can change it later, e.g. from html +to shtml or cgi without changing any +hyperlink references. + +

    +If you want to continue to use a mime-type in your hyperlinks (e.g. +foo.html) 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. foo.html.en). + +

    Note on Caching

    +

    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