From: Jason S. Lingohr Date: Fri, 19 Sep 2003 10:41:09 +0000 (+0000) Subject: Corrections/fixes & transformation update. X-Git-Tag: pre_ajp_proxy~1152 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=1694ed909d339128068f4938a53eaf2c14e9ad90;p=apache Corrections/fixes & transformation update. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@101292 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/content-negotiation.html.en b/docs/manual/content-negotiation.html.en index edc03c0bec..455f4a3954 100644 --- a/docs/manual/content-negotiation.html.en +++ b/docs/manual/content-negotiation.html.en @@ -277,8 +277,8 @@ Negotiation Media Type - Browser indicates preferences with the Accept header - field. Each item can have an associated quality factor. + Browser indicates preferences with the Accept + header field. Each item can have an associated quality factor. Variant description can also have a quality factor (the "qs" parameter). @@ -286,26 +286,27 @@ Negotiation Language - Browser indicates preferences with the Accept-Language - header field. Each item can have a quality factor. Variants - can be associated with none, one or more than one - language. + Browser indicates preferences with the + Accept-Language header field. Each item can + have a quality factor. Variants can be associated with none, + one or more than one language. Encoding - Browser indicates preference with the Accept-Encoding - header field. Each item can have a quality factor. + Browser indicates preference with the + Accept-Encoding header field. Each item can have + a quality factor. Charset - Browser indicates preference with the Accept-Charset - header field. Each item can have a quality factor. Variants - can indicate a charset as a parameter of the media - type. + Browser indicates preference with the + Accept-Charset header field. Each item can have a + quality factor. Variants can indicate a charset as a parameter + of the media type. @@ -332,30 +333,30 @@ Negotiation move on to the next test.
    -
  1. Multiply the quality factor from the Accept header - with the quality-of-source factor for this variant's - media type, and select the variants with the highest - value.
    2. +
  2. Multiply the quality factor from the Accept + header with the quality-of-source factor for this variants + media type, and select the variants with the highest + value.
  3. Select the variants with the highest language quality factor.
  4. Select the variants with the best language match, using either the order of languages in the - Accept-Language header (if present), or else the order of - languages in the LanguagePriority directive - (if present).
    5. + Accept-Language header (if present), or else + the order of languages in the LanguagePriority + directive (if present).
  5. Select the variants with the highest 'level' media parameter (used to give the version of text/html media types).
  6. Select variants with the best charset media - parameters, as given on the Accept-Charset header line. - Charset ISO-8859-1 is acceptable unless explicitly - excluded. Variants with a text/* media type - but not explicitly associated with a particular charset - are assumed to be in ISO-8859-1.
    7. + parameters, as given on the Accept-Charset + header line. Charset ISO-8859-1 is acceptable unless + explicitly excluded. Variants with a text/* + media type but not explicitly associated with a particular + charset are assumed to be in ISO-8859-1.
  7. Select those variants which have associated charset media parameters that are not ISO-8859-1. If @@ -382,17 +383,17 @@ Negotiation
  8. The algorithm has now selected one 'best' variant, so - return it as the response. The HTTP response header Vary is - set to indicate the dimensions of negotiation (browsers and - caches can use this information when caching the resource). - End.
    9. + return it as the response. The HTTP response header + Vary is set to indicate the dimensions of + negotiation (browsers and caches can use this information when + caching the resource). End.
  9. To get here means no variant was selected (because none are acceptable to the browser). Return a 406 status (meaning "No acceptable representation") with a response body consisting of an HTML document listing the available - variants. Also set the HTTP Vary header to indicate the - dimensions of variance.
    10. + variants. Also set the HTTP Vary header to + indicate the dimensions of variance.
top
@@ -405,16 +406,16 @@ Negotiation negotiation algorithm above. This is to get a better result from the algorithm for browsers which do not send full or accurate information. Some of the most popular browsers send - Accept header information which would otherwise result in the - selection of the wrong variant in many cases. If a browser - sends full and correct information these fiddles will not be - applied.

+ Accept header information which would otherwise + result in the selection of the wrong variant in many cases. If a + browser sends full and correct information these fiddles will not + 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 +

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:

Accept: image/*, */*

@@ -439,14 +440,14 @@ Negotiation low preference of 0.01, so other types will only be returned if no variant matches an explicitly listed type.

-

If the Accept: header contains no q factors at all, - Apache sets the q value of "*/*", if present, to 0.01 to - emulate the desired behavior. It also sets the q value of - wildcards of the format "type/*" to 0.02 (so these are - preferred over matches against "*/*". If any media type on the - Accept: header contains a q factor, these special values are - not applied, so requests from browsers which send the - explicit information to start with work as expected.

+

If the Accept: header contains no q + factors at all, Apache sets the q value of "*/*", if present, to + 0.01 to emulate the desired behavior. It also sets the q value of + wildcards of the format "type/*" to 0.02 (so these are preferred + over matches against "*/*". If any media type on the + Accept: header contains a q factor, these special + values are not applied, so requests from browsers which + send the explicit information to start with work as expected.

Language Negotiation Exceptions

@@ -456,14 +457,16 @@ Negotiation negotiation fails to find a match.

When a client requests a page on your server, but the server - cannot find a single page that matches the Accept-language sent by + 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 explicitly match the client's request. The ForceLanguagePriority + the Accept-language in these cases and provide a + document that does not explicitly match the client's request. The + ForceLanguagePriority directive can be used to override one or both of these error - messages and substitute the servers judgement in the form of the + messages and substitute the servers judgement in the form of the LanguagePriority directive.

@@ -474,11 +477,11 @@ Negotiation standard to match that against 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.) However, if no other language - match is possible and the server is about to return a "No + 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.) However, if no other + language match is possible and the server is about to return a "No Acceptable Variants" error or fallback to the LanguagePriority, the server will ignore the subset specification and match en-GB against en documents. Implicitly, Apache will add @@ -490,7 +493,7 @@ Negotiation specification and to work effectively with properly configured clients.

-

In order to support advanced techniques (such as Cookies or +

In order to support advanced techniques (such as cookies or special URL-paths) to determine the user's preferred language, since Apache 2.0.47 mod_negotiation recognizes the environment variable @@ -514,9 +517,9 @@ variant lists to label variants which are available with a specific content-encoding only. The implementation of the RVSA/1.0 algorithm (RFC 2296) is extended to recognize encoded variants in the list, and to use them as candidate variants whenever their encodings are -acceptable according to the Accept-Encoding request header. The -RVSA/1.0 implementation does not round computed quality factors to 5 -decimal places before choosing the best variant.

+acceptable according to the Accept-Encoding request +header. The RVSA/1.0 implementation does not round computed quality +factors to 5 decimal places before choosing the best variant.

top

Note on hyperlinks and naming conventions

diff --git a/docs/manual/content-negotiation.xml b/docs/manual/content-negotiation.xml index b9b15e4986..098bc0c7a5 100644 --- a/docs/manual/content-negotiation.xml +++ b/docs/manual/content-negotiation.xml @@ -255,8 +255,8 @@ Media Type - Browser indicates preferences with the Accept header - field. Each item can have an associated quality factor. + Browser indicates preferences with the Accept + header field. Each item can have an associated quality factor. Variant description can also have a quality factor (the "qs" parameter). @@ -264,26 +264,27 @@ Language - Browser indicates preferences with the Accept-Language - header field. Each item can have a quality factor. Variants - can be associated with none, one or more than one - language. + Browser indicates preferences with the + Accept-Language header field. Each item can + have a quality factor. Variants can be associated with none, + one or more than one language. Encoding - Browser indicates preference with the Accept-Encoding - header field. Each item can have a quality factor. + Browser indicates preference with the + Accept-Encoding header field. Each item can have + a quality factor. Charset - Browser indicates preference with the Accept-Charset - header field. Each item can have a quality factor. Variants - can indicate a charset as a parameter of the media - type. + Browser indicates preference with the + Accept-Charset header field. Each item can have a + quality factor. Variants can indicate a charset as a parameter + of the media type. @@ -310,30 +311,30 @@ move on to the next test.
    -
  1. Multiply the quality factor from the Accept header - with the quality-of-source factor for this variant's - media type, and select the variants with the highest - value.
    2. +
  2. Multiply the quality factor from the Accept + header with the quality-of-source factor for this variants + media type, and select the variants with the highest + value.
  3. Select the variants with the highest language quality factor.
  4. Select the variants with the best language match, using either the order of languages in the - Accept-Language header (if present), or else the order of - languages in the LanguagePriority directive - (if present).
    5. + Accept-Language header (if present), or else + the order of languages in the LanguagePriority + directive (if present).
  5. Select the variants with the highest 'level' media parameter (used to give the version of text/html media types).
  6. Select variants with the best charset media - parameters, as given on the Accept-Charset header line. - Charset ISO-8859-1 is acceptable unless explicitly - excluded. Variants with a text/* media type - but not explicitly associated with a particular charset - are assumed to be in ISO-8859-1.
    7. + parameters, as given on the Accept-Charset + header line. Charset ISO-8859-1 is acceptable unless + explicitly excluded. Variants with a text/* + media type but not explicitly associated with a particular + charset are assumed to be in ISO-8859-1.
  7. Select those variants which have associated charset media parameters that are not ISO-8859-1. If @@ -360,17 +361,17 @@
  8. The algorithm has now selected one 'best' variant, so - return it as the response. The HTTP response header Vary is - set to indicate the dimensions of negotiation (browsers and - caches can use this information when caching the resource). - End.
    9. + return it as the response. The HTTP response header + Vary is set to indicate the dimensions of + negotiation (browsers and caches can use this information when + caching the resource). End.
  9. To get here means no variant was selected (because none are acceptable to the browser). Return a 406 status (meaning "No acceptable representation") with a response body consisting of an HTML document listing the available - variants. Also set the HTTP Vary header to indicate the - dimensions of variance.
    10. + variants. Also set the HTTP Vary header to + indicate the dimensions of variance.
@@ -383,16 +384,16 @@ negotiation algorithm above. This is to get a better result from the algorithm for browsers which do not send full or accurate information. Some of the most popular browsers send - Accept header information which would otherwise result in the - selection of the wrong variant in many cases. If a browser - sends full and correct information these fiddles will not be - applied.

+ Accept header information which would otherwise + result in the selection of the wrong variant in many cases. If a + browser sends full and correct information these fiddles will not + 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 +

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:

Accept: image/*, */* @@ -417,14 +418,14 @@ low preference of 0.01, so other types will only be returned if no variant matches an explicitly listed type.

-

If the Accept: header contains no q factors at all, - Apache sets the q value of "*/*", if present, to 0.01 to - emulate the desired behavior. It also sets the q value of - wildcards of the format "type/*" to 0.02 (so these are - preferred over matches against "*/*". If any media type on the - Accept: header contains a q factor, these special values are - not applied, so requests from browsers which send the - explicit information to start with work as expected.

+

If the Accept: header contains no q + factors at all, Apache sets the q value of "*/*", if present, to + 0.01 to emulate the desired behavior. It also sets the q value of + wildcards of the format "type/*" to 0.02 (so these are preferred + over matches against "*/*". If any media type on the + Accept: header contains a q factor, these special + values are not applied, so requests from browsers which + send the explicit information to start with work as expected.

Language Negotiation Exceptions @@ -434,15 +435,17 @@ negotiation fails to find a match.

When a client requests a page on your server, but the server - cannot find a single page that matches the Accept-language sent by + 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 explicitly match the client's request. The Accept-language in these cases and provide a + document that does not explicitly match the client's request. The + ForceLanguagePriority directive can be used to override one or both of these error - messages and substitute the servers judgement in the form of the + messages and substitute the servers judgement in the form of the LanguagePriority directive.

@@ -453,11 +456,11 @@ standard to match that against 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.) However, if no other language - match is possible and the server is about to return a "No + 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.) However, if no other + language match is possible and the server is about to return a "No Acceptable Variants" error or fallback to the LanguagePriority, the server will ignore the subset specification and match en-GB @@ -470,7 +473,7 @@ specification and to work effectively with properly configured clients.

-

In order to support advanced techniques (such as Cookies or +

In order to support advanced techniques (such as cookies or special URL-paths) to determine the user's preferred language, since Apache 2.0.47 mod_negotiation recognizes the environment variable @@ -494,9 +497,9 @@ variant lists to label variants which are available with a specific content-encoding only. The implementation of the RVSA/1.0 algorithm (RFC 2296) is extended to recognize encoded variants in the list, and to use them as candidate variants whenever their encodings are -acceptable according to the Accept-Encoding request header. The -RVSA/1.0 implementation does not round computed quality factors to 5 -decimal places before choosing the best variant.

+acceptable according to the Accept-Encoding request +header. The RVSA/1.0 implementation does not round computed quality +factors to 5 decimal places before choosing the best variant.

Note on hyperlinks and naming conventions