From d12bfddd25e16fa69d40d31e48702b422cb07524 Mon Sep 17 00:00:00 2001 From: Joshua Slive Date: Wed, 29 May 2002 03:42:32 +0000 Subject: [PATCH] Update the content negotiation docs to incorporate some of the new stuff in 2.0. This could use review! git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@95335 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/content-negotiation.html | 157 +++++++++--------------- docs/manual/content-negotiation.html.en | 157 +++++++++--------------- docs/manual/mod/mod_negotiation.xml | 36 +++++- 3 files changed, 152 insertions(+), 198 deletions(-) diff --git a/docs/manual/content-negotiation.html b/docs/manual/content-negotiation.html index b5af8bf892..8403cb2733 100644 --- a/docs/manual/content-negotiation.html +++ b/docs/manual/content-negotiation.html @@ -15,12 +15,12 @@

Content Negotiation

-

Apache's support for content negotiation has been updated to - meet the HTTP/1.1 specification. It can choose the best +

Apache's supports content negotiation as described in + the HTTP/1.1 specification. It can choose the best representation of a resource based on the browser-supplied preferences for media type, languages, character set and - encoding. It is also implements a couple of features to give - more intelligent handling of requests from browsers which send + encoding. It also implements a couple of features to give + more intelligent handling of requests from browsers that send incomplete negotiation information.

Content negotiation is provided by the - Apache 1.2 supports 'server driven' content negotiation, as + Apache supports 'server driven' content negotiation, as defined in the HTTP/1.1 specification. It fully supports the Accept, Accept-Language, Accept-Charset and Accept-Encoding - request headers. Apache 1.3.4 also supports 'transparent' + request headers. Apache also supports 'transparent' content negotiation, which is an experimental negotiation protocol defined in RFC 2295 and RFC 2296. It does not offer support for 'feature negotiation' as defined in these RFCs. @@ -164,63 +164,10 @@ variant depending on the nature of the resource it represents.

-

The full list of headers recognized is:

+

The full list of headers recognized is available in the mod_negotation + documentation.

-
-
URI:
- -
uri of the file containing the variant (of the given - media type, encoded with the given content encoding). These - are interpreted as URLs relative to the map file; they must - be on the same server (!), and they must refer to files to - which the client would be granted access if they were to be - requested directly.
- -
Content-Type:
- -
media type --- charset, level and "qs" parameters may be - given. These are often referred to as MIME types; typical - media types are image/gif, - text/plain, or - text/html; level=3.
- -
Content-Language:
- -
The languages of the variant, specified as an Internet - standard language tag from RFC 1766 (e.g., - en for English, kr for Korean, - etc.).
- -
Content-Encoding:
- -
If the file is compressed, or otherwise encoded, rather - than containing the actual raw data, this says how that was - done. Apache only recognizes encodings that are defined by an - AddEncoding - directive. This normally includes the encodings - x-compress for compress'd files, and - x-gzip for gzip'd files. The x- - prefix is ignored for encoding comparisons.
- -
Content-Length:
- -
The size of the file in bytes. Specifying content lengths - in the type-map allows the server to compare file sizes - without checking the actual files.
- -
Description:
- -
A human-readable textual description of the variant. If - Apache cannot find any appropriate variant to return, it will - return an error response which lists all available variants - instead. Such a variant list will include the human-readable - variant descriptions.
-
- Using a type map file is preferred over MultiViews - because it requires less CPU time, and less file access, to - parse a file explicitly listing the various resource variants, - than to have to look at every matching file, and parse its file - extensions.

Multiviews

@@ -255,13 +202,14 @@ are present, and index.cgi is there, the server will run it. -

If one of the files found when reading the directive is a - CGI script, it's not obvious what should happen. The code gives - that case special treatment --- if the request was a POST, or a - GET with QUERY_ARGS or PATH_INFO, the script is given an - extremely high quality rating, and generally invoked; otherwise - it is given an extremely low quality rating, which generally - causes one of the other views (if any) to be retrieved.

+

If one of the files found when reading the directory does not + have an extension recognized by mod_mime to designate + its Charset, Content-Type, Language, or Encoding, then the result + depends on the setting of the MultiViewsMatch + directive. This directive determines whether handlers, filters, + and other file types can participate in MultiViews + negotiation.

The Negotiation Methods

After Apache has obtained a list of the variants for a given @@ -476,33 +424,42 @@ not applied, so requests from browsers which send the correct information to start with work as expected.

-

Variants with no Language

+

Language Negotiation Exceptions

+ +

When a client requests a page on your server, but the server + cannot find a single page that matches the Accept-language sent by + the browser, the server will return either a "No Acceptable + Variant" or "Multiple Choices" response to the client. To avoid + these error messages, it is possible to configure Apache to ignore + the Accept-language in these cases and provide a document that + does not explictly match the client's request. The ForceLanguagePriority + directive can be used to override one or both of these error + messages and subsitute the servers judgement in the form of the LanguagePriority + directive.

+ +

The ForceLanguagePriority directive also causes + Apache to attempt to match language-subsets against their parent + language when no other match can be obtained. For example, if a + client requests documents with the language en-GB for + British English, the server is not normally allowed by the + HTTP/1.1 standard to return a document that is marked as simply + en. (Note that it is almost surely a configuration + error to include en-GB and not en in the + Accept-Language header, since it is very unlikely that a reader + understands British English, but doesn't understand English in + general. Unfortunately, many current clients have default + configurations that resemble this.) With the + ForceLanguagePriority header, the server can be + configured to ignore the subset specification and match + en-GB against en documents. But note + that if the client requests "en-GB; qs=0.9, fr; qs=0.8", and the + server has documents designated "en" and "fr", then the "fr" + document will be returned regardless of the + ForceLanguagePriority directive. This is necessary + to maintain compliance with the HTTP/1.1 specification.

-

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.

- -

The reason for setting this language quality factor for - variant with no language to a very low value is to allow for a - default variant which can be supplied if none of the other - variants match the browser's language preferences. For example, - consider the situation with three variants:

- - - -

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.

Extensions to Transparent Content Negotiation

Apache extends the transparent content negotiation protocol @@ -644,8 +601,16 @@ responses which were subject to negotiation. This directive can be given in the server config or virtual host, and takes no arguments. It has no effect on requests from HTTP/1.1 clients. + +

More Information

+ +

For more information about content negotiation, see Alan + J. Flavell's Language + Negotiation Notes. But note that this document may not be + updated to include changes in Apache 2.0.

+ -

diff --git a/docs/manual/content-negotiation.html.en b/docs/manual/content-negotiation.html.en index b5af8bf892..8403cb2733 100644 --- a/docs/manual/content-negotiation.html.en +++ b/docs/manual/content-negotiation.html.en @@ -15,12 +15,12 @@

Content Negotiation

-

Apache's support for content negotiation has been updated to - meet the HTTP/1.1 specification. It can choose the best +

Apache's supports content negotiation as described in + the HTTP/1.1 specification. It can choose the best representation of a resource based on the browser-supplied preferences for media type, languages, character set and - encoding. It is also implements a couple of features to give - more intelligent handling of requests from browsers which send + encoding. It also implements a couple of features to give + more intelligent handling of requests from browsers that send incomplete negotiation information.

Content negotiation is provided by the - Apache 1.2 supports 'server driven' content negotiation, as + Apache supports 'server driven' content negotiation, as defined in the HTTP/1.1 specification. It fully supports the Accept, Accept-Language, Accept-Charset and Accept-Encoding - request headers. Apache 1.3.4 also supports 'transparent' + request headers. Apache also supports 'transparent' content negotiation, which is an experimental negotiation protocol defined in RFC 2295 and RFC 2296. It does not offer support for 'feature negotiation' as defined in these RFCs. @@ -164,63 +164,10 @@ variant depending on the nature of the resource it represents.

-

The full list of headers recognized is:

+

The full list of headers recognized is available in the mod_negotation + documentation.

-
-
URI:
- -
uri of the file containing the variant (of the given - media type, encoded with the given content encoding). These - are interpreted as URLs relative to the map file; they must - be on the same server (!), and they must refer to files to - which the client would be granted access if they were to be - requested directly.
- -
Content-Type:
- -
media type --- charset, level and "qs" parameters may be - given. These are often referred to as MIME types; typical - media types are image/gif, - text/plain, or - text/html; level=3.
- -
Content-Language:
- -
The languages of the variant, specified as an Internet - standard language tag from RFC 1766 (e.g., - en for English, kr for Korean, - etc.).
- -
Content-Encoding:
- -
If the file is compressed, or otherwise encoded, rather - than containing the actual raw data, this says how that was - done. Apache only recognizes encodings that are defined by an - AddEncoding - directive. This normally includes the encodings - x-compress for compress'd files, and - x-gzip for gzip'd files. The x- - prefix is ignored for encoding comparisons.
- -
Content-Length:
- -
The size of the file in bytes. Specifying content lengths - in the type-map allows the server to compare file sizes - without checking the actual files.
- -
Description:
- -
A human-readable textual description of the variant. If - Apache cannot find any appropriate variant to return, it will - return an error response which lists all available variants - instead. Such a variant list will include the human-readable - variant descriptions.
-
- Using a type map file is preferred over MultiViews - because it requires less CPU time, and less file access, to - parse a file explicitly listing the various resource variants, - than to have to look at every matching file, and parse its file - extensions.

Multiviews

@@ -255,13 +202,14 @@ are present, and index.cgi is there, the server will run it. -

If one of the files found when reading the directive is a - CGI script, it's not obvious what should happen. The code gives - that case special treatment --- if the request was a POST, or a - GET with QUERY_ARGS or PATH_INFO, the script is given an - extremely high quality rating, and generally invoked; otherwise - it is given an extremely low quality rating, which generally - causes one of the other views (if any) to be retrieved.

+

If one of the files found when reading the directory does not + have an extension recognized by mod_mime to designate + its Charset, Content-Type, Language, or Encoding, then the result + depends on the setting of the MultiViewsMatch + directive. This directive determines whether handlers, filters, + and other file types can participate in MultiViews + negotiation.

The Negotiation Methods

After Apache has obtained a list of the variants for a given @@ -476,33 +424,42 @@ not applied, so requests from browsers which send the correct information to start with work as expected.

-

Variants with no Language

+

Language Negotiation Exceptions

+ +

When a client requests a page on your server, but the server + cannot find a single page that matches the Accept-language sent by + the browser, the server will return either a "No Acceptable + Variant" or "Multiple Choices" response to the client. To avoid + these error messages, it is possible to configure Apache to ignore + the Accept-language in these cases and provide a document that + does not explictly match the client's request. The ForceLanguagePriority + directive can be used to override one or both of these error + messages and subsitute the servers judgement in the form of the LanguagePriority + directive.

+ +

The ForceLanguagePriority directive also causes + Apache to attempt to match language-subsets against their parent + language when no other match can be obtained. For example, if a + client requests documents with the language en-GB for + British English, the server is not normally allowed by the + HTTP/1.1 standard to return a document that is marked as simply + en. (Note that it is almost surely a configuration + error to include en-GB and not en in the + Accept-Language header, since it is very unlikely that a reader + understands British English, but doesn't understand English in + general. Unfortunately, many current clients have default + configurations that resemble this.) With the + ForceLanguagePriority header, the server can be + configured to ignore the subset specification and match + en-GB against en documents. But note + that if the client requests "en-GB; qs=0.9, fr; qs=0.8", and the + server has documents designated "en" and "fr", then the "fr" + document will be returned regardless of the + ForceLanguagePriority directive. This is necessary + to maintain compliance with the HTTP/1.1 specification.

-

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.

- -

The reason for setting this language quality factor for - variant with no language to a very low value is to allow for a - default variant which can be supplied if none of the other - variants match the browser's language preferences. For example, - consider the situation with three variants:

- - - -

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.

Extensions to Transparent Content Negotiation

Apache extends the transparent content negotiation protocol @@ -644,8 +601,16 @@ responses which were subject to negotiation. This directive can be given in the server config or virtual host, and takes no arguments. It has no effect on requests from HTTP/1.1 clients. + +

More Information

+ +

For more information about content negotiation, see Alan + J. Flavell's Language + Negotiation Notes. But note that this document may not be + updated to include changes in Apache 2.0.

+ -

diff --git a/docs/manual/mod/mod_negotiation.xml b/docs/manual/mod/mod_negotiation.xml index 84712edf08..a30ea4f0fa 100644 --- a/docs/manual/mod/mod_negotiation.xml +++ b/docs/manual/mod/mod_negotiation.xml @@ -32,8 +32,9 @@ AddEncoding AddLanguage AddType +MultiViewsMatch -
Type maps +
Type maps

A type map has the same format as RFC822 mail headers. It contains document descriptions separated by blank lines, with lines beginning with a hash character ('#') treated as @@ -97,15 +98,38 @@ Example: -

- Content-Type: image/jpeg; qs=0.8 -
+Content-Type: image/jpeg; qs=0.8
URI:
-
The path to the file containing this variant, relative to - the map file.
+
uri of the file containing the variant (of the given + media type, encoded with the given content encoding). These + are interpreted as URLs relative to the map file; they must + be on the same server (!), and they must refer to files to + which the client would be granted access if they were to be + requested directly.
+ +
Body:
+ +

New in Apache 2.0, the actual content of the resource may + be included in the type-map file using the Body header. This + header must contain a string that designates a delimiter for + the body content. Then all following lines in the type map + file will be considered part of the resource body until the + delimiter string is found.

+ +

Example:

+ +Body:----xyz----
+<html>
+<body>
+<p>Content of the page.</p>
+</body>
+</html>
+----xyz---- + +
-- 2.50.1