httpd-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From field...@hyperreal.org
Subject cvs commit: apache-1.3/htdocs/manual/mod mod_negotiation.html
Date Sat, 06 Feb 1999 14:00:34 GMT
fielding    99/02/06 06:00:34

  Modified:    .        STATUS
               htdocs/manual content-negotiation.html
               htdocs/manual/mod mod_negotiation.html
  Log:
  Update docs according to new negotiation ordering.  Note that we
  still don't have any documentation of TCN/RVSA effects.
  
  Revision  Changes    Path
  1.613     +4 -5      apache-1.3/STATUS
  
  Index: STATUS
  ===================================================================
  RCS file: /home/cvs/apache-1.3/STATUS,v
  retrieving revision 1.612
  retrieving revision 1.613
  diff -u -r1.612 -r1.613
  --- STATUS	1999/02/06 08:51:22	1.612
  +++ STATUS	1999/02/06 14:00:31	1.613
  @@ -1,5 +1,5 @@
     1.3 STATUS:
  -  Last modified at [$Date: 1999/02/06 08:51:22 $]
  +  Last modified at [$Date: 1999/02/06 14:00:31 $]
   
   Release:
   
  @@ -43,6 +43,9 @@
   
   Documentation that needs writing:
   
  +    * manual/content-negotiation.html lacks any information about the
  +      TCN additions and when the RVSA algorithm is used.
  +
   Available Patches:
   
       * Tony Finch's [PATCH] mod_log_config: support for reliably parsable logs
  @@ -90,10 +93,6 @@
       * Fred's [PATCH: srm.conf and access.conf refer to httpd.conf
           Message-ID: <199901192353.PAA15190@scv4.apple.com>
           Status: 
  -
  -    * Koen Holtman's [PATCH] mod_negotiation some loose ends
  -        Message-ID: <Pine.GSO.3.95a.990125190321.5403B-100000@suncms33.cern.ch>
  -        Status: Roy is looking at it.
   
       * Jun-ichiro itojun Hagino's [PATCH] IPv6 enable patch
         ftp://ftp.kame.net/pub/kame/misc/apache-134-v6-19990118.diff.gz
  
  
  
  1.20      +92 -75    apache-1.3/htdocs/manual/content-negotiation.html
  
  Index: content-negotiation.html
  ===================================================================
  RCS file: /home/cvs/apache-1.3/htdocs/manual/content-negotiation.html,v
  retrieving revision 1.19
  retrieving revision 1.20
  diff -u -r1.19 -r1.20
  --- content-negotiation.html	1998/12/04 17:37:06	1.19
  +++ content-negotiation.html	1999/02/06 14:00:32	1.20
  @@ -70,12 +70,17 @@
   Accept-Language, Accept-Charset and Accept-Encoding request headers.
   <P>
   
  -The terms used in content negotiation are: a <STRONG>resource</STRONG> is an
  -item which can be requested of a server, which might be selected as
  -the result of a content negotiation algorithm. If a resource is
  -available in several formats, these are called <STRONG>representations</STRONG>
  -or <STRONG>variants</STRONG>. The ways in which the variants for a particular
  -resource vary are called the <STRONG>dimensions</STRONG> of negotiation.
  +A <STRONG>resource</STRONG> is a conceptual entity identified by a URI
  +(RFC 2396).  An HTTP server like Apache provides access to
  +<STRONG>representations</STRONG> of the resource(s) within its namespace,
  +with each representation in the form of a sequence of bytes with a
  +defined media type, character set, encoding, etc.  Each resource may be
  +associated with zero, one, or more than one representation
  +at any given time.  If multiple representations are available,
  +the resource is referred to as <STRONG>negotiable</STRONG> and each of its
  +representations is termed a <STRONG>variant</STRONG>. The ways in which the
  +variants for a negotiable resource vary are called the
  +<STRONG>dimensions</STRONG> of negotiation.
   
   <H2>Negotiation in Apache</H2>
   
  @@ -86,9 +91,9 @@
   
   <UL>
     <LI> Using a type map (<EM>i.e.</EM>, a <CODE>*.var</CODE>
file) which
  -       names the files containing the variants explicitly
  -  <LI> Or using a 'MultiViews' search, where the server does an implicit
  -       filename pattern match, and chooses from among the results.
  +       names the files containing the variants explicitly, or
  +  <LI> Using a 'MultiViews' search, where the server does an implicit
  +       filename pattern match and chooses from among the results.
   </UL>
   
   <H3>Using a type-map file</H3>
  @@ -98,25 +103,25 @@
   named <CODE>type-map</CODE> (or, for backwards-compatibility with
   older Apache configurations, the mime type
   <CODE>application/x-type-map</CODE>).  Note that to use this feature,
  -you've got to have a <CODE>SetHandler</CODE> some place which defines a
  +you must have a handler set in the configuration that defines a
   file suffix as <CODE>type-map</CODE>; this is best done with a
  -<PRE>
   
  +<PRE>
     AddHandler type-map var
  -
   </PRE>
  -in <CODE>srm.conf</CODE>.  See comments in the sample config files for
  -details. <P>
   
  +in the server configuration file.  See the comments in the sample config
  +file for more details. <P>
  +
   Type map files have an entry for each available variant; these entries
  -consist of contiguous RFC822-format header lines.  Entries for
  +consist of contiguous HTTP-format header lines.  Entries for
   different variants are separated by blank lines.  Blank lines are
   illegal within an entry.  It is conventional to begin a map file with
   an entry for the combined entity as a whole (although this
   is not required, and if present will be ignored). An example
   map file is:
  -<PRE>
   
  +<PRE>
     URI: foo
   
     URI: foo.en.html
  @@ -124,13 +129,14 @@
     Content-language: en
   
     URI: foo.fr.de.html
  -  Content-type: text/html; charset=iso-8859-2
  +  Content-type: text/html;charset=iso-8859-2
     Content-language: fr, de
   </PRE>
   
   If the variants have different source qualities, that may be indicated
   by the "qs" parameter to the media type, as in this picture (available
   as jpeg, gif, or ASCII-art):
  +
   <PRE>
     URI: foo
   
  @@ -142,14 +148,22 @@
   
     URI: foo.txt
     Content-type: text/plain; qs=0.01
  -
   </PRE>
   <P>
   
  -qs values can vary between 0.000 and 1.000. Note that any variant with
  +qs values can vary in the range 0.000 to 1.000. Note that any variant with
   a qs value of 0.000 will never be chosen. Variants with no 'qs'
  -parameter value are given a qs factor of 1.0.  <P>
  +parameter value are given a qs factor of 1.0. The qs parameter indicates
  +the relative 'quality' of this variant compared to the other available
  +variants, independent of the client's capabilities.  For example, a jpeg
  +file is usually of higher source quality than an ascii file if it is
  +attempting to represent a photograph.  However, if the resource being
  +represented is an original ascii art, then an ascii representation would
  +have a higher source quality than a jpeg representation.  A qs value
  +is therefore specific to a given variant depending on the nature of
  +the resource it represents.
   
  +<P>
   The full list of headers recognized is:
   
   <DL>
  @@ -160,22 +174,24 @@
          the same server (!), and they must refer to files to which the
          client would be granted access if they were to be requested
          directly.
  -  <DT> <CODE>Content-type:</CODE>
  +  <DT> <CODE>Content-Type:</CODE>
     <DD> media type --- charset, level and "qs" parameters may be given.  These
          are often referred to as MIME types; typical media types are
          <CODE>image/gif</CODE>, <CODE>text/plain</CODE>, or
          <CODE>text/html;&nbsp;level=3</CODE>.
  -  <DT> <CODE>Content-language:</CODE>
  +  <DT> <CODE>Content-Language:</CODE>
     <DD> The languages of the variant, specified as an Internet standard
  -       language code (<EM>e.g.</EM>, <CODE>en</CODE> for English,
  +       language tag from RFC 1766 (<EM>e.g.</EM>, <CODE>en</CODE>
for English,
          <CODE>kr</CODE> for Korean, <EM>etc.</EM>).
  -  <DT> <CODE>Content-encoding:</CODE>
  +  <DT> <CODE>Content-Encoding:</CODE>
     <DD> If the file is compressed, or otherwise encoded, rather than
          containing the actual raw data, this says how that was done.
  -       For compressed files (the only case where this generally comes
  -       up), content encoding should be
  -       <CODE>x-compress</CODE>, or <CODE>x-gzip</CODE>, as appropriate.
  -  <DT> <CODE>Content-length:</CODE>
  +       Apache only recognizes encodings that are defined by an
  +       <A HREF="mod/mod_mime.html#addencoding">AddEncoding</A> directive.
  +       This normally includes the encodings <CODE>x-compress</CODE>
  +       for compress'd files, and <CODE>x-gzip</CODE> for gzip'd files.
  +       The <CODE>x-</CODE> prefix is ignored for encoding comparisons.
  +  <DT> <CODE>Content-Length:</CODE>
     <DD> The size of the file.  Clients can ask to receive a given media
          type only if the variant isn't too big; specifying a content
          length in the map allows the server to compare against these
  @@ -185,17 +201,15 @@
   <H3>Multiviews</H3>
   
   <P>
  -This is a per-directory option, meaning it can be set with an
  -<CODE>Options</CODE> directive within a <CODE>&lt;Directory&gt;</CODE>,
  +<CODE>MultiViews</CODE> is a per-directory option, meaning it can be set with
  +an <CODE>Options</CODE> directive within a <CODE>&lt;Directory&gt;</CODE>,
   <CODE>&lt;Location&gt;</CODE> or <CODE>&lt;Files&gt;</CODE>
   section in <CODE>access.conf</CODE>, or (if <CODE>AllowOverride</CODE>
   is properly set) in <CODE>.htaccess</CODE> files.  Note that
   <CODE>Options All</CODE> does not set <CODE>MultiViews</CODE>;
you
  -have to ask for it by name.  (Fixing this is a one-line change to
  -<CODE>http_core.h</CODE>).
  +have to ask for it by name.
   
   <P>
  -
   The effect of <CODE>MultiViews</CODE> is as follows: if the server
   receives a request for <CODE>/some/dir/foo</CODE>, if
   <CODE>/some/dir</CODE> has <CODE>MultiViews</CODE> enabled, and
  @@ -204,23 +218,22 @@
   type map which names all those files, assigning them the same media
   types and content-encodings it would have if the client had asked for
   one of them by name.  It then chooses the best match to the client's
  -requirements, and forwards them along.
  +requirements.
   
   <P>
  -
  -This applies to searches for the file named by the
  +<CODE>MultiViews</CODE> may also apply to searches for the file named by the
   <CODE>DirectoryIndex</CODE> directive, if the server is trying to
  -index a directory; if the configuration files specify
  -<PRE>
  +index a directory. If the configuration files specify
   
  +<PRE>
     DirectoryIndex index
  +</PRE>
   
  -</PRE> then the server will arbitrate between <CODE>index.html</CODE>
  +then the server will arbitrate between <CODE>index.html</CODE>
   and <CODE>index.html3</CODE> if both are present.  If neither are
   present, and <CODE>index.cgi</CODE> is there, the server will run it.
   
   <P>
  -
   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
  @@ -233,7 +246,7 @@
   
   After Apache has obtained a list of the variants for a given resource,
   either from a type-map file or from the filenames in the directory, it
  -applies a algorithm to decide on the 'best' variant to return, if
  +applies an algorithm to decide on the 'best' variant to return, if
   any. To do this it calculates a quality value for each variant in each
   of the dimensions of variance. It is not necessary to know any of the
   details of how negotiation actually takes place in order to use Apache's
  @@ -247,22 +260,28 @@
   <H3>Dimensions of Negotiation</H3>
   
   <TABLE>
  -<TR><TH>Dimension
  +<TR valign="top">
  +<TH>Dimension
   <TH>Notes
  -<TR><TD>Media Type
  -<TD>Browser indicates preferences on Accept: header. Each item
  +<TR valign="top">
  +<TD>Media Type
  +<TD>Browser indicates preferences with the Accept header field. Each item
   can have an associated quality factor. Variant description can also
  -have a quality factor.
  -<TR><TD>Language
  -<TD>Browser indicates preferences on Accept-Language: header. Each
  -item
  -can have a quality factor. Variants can be associated with none, one
  -or more languages.
  -<TR><TD>Encoding
  -<TD>Browser indicates preference with Accept-Encoding: header.
  -<TR><TD>Charset
  -<TD>Browser indicates preference with Accept-Charset: header. Variants
  -can indicate a charset as a parameter of the media type.
  +have a quality factor (the "qs" parameter).
  +<TR valign="top">
  +<TD>Language
  +<TD>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.
  +<TR valign="top">
  +<TD>Encoding
  +<TD>Browser indicates preference with the Accept-Encoding header field.
  +Each item can have a quality factor.
  +<TR valign="top">
  +<TD>Charset
  +<TD>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.
   </TABLE>
   
   <H3>Apache Negotiation Algorithm</H3>
  @@ -270,13 +289,13 @@
   <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:
  +as follows:
   
   <OL>
   <LI>
  -Firstly, for each dimension of the negotiation, the appropriate
  -Accept header is checked and a quality assigned to this each
  -variant. If the Accept header for any dimension means that this
  +First, for each dimension of the negotiation, the appropriate
  +<EM>Accept*</EM> header field is checked and a quality assigned to each
  +variant. If the <EM>Accept*</EM> header for any dimension means that this
   variant is not acceptable, eliminate it. If no variants remain, go
   to step 4.
   
  @@ -284,7 +303,7 @@
   the following tests is applied in order. Any variants not selected at
   each stage are eliminated. After each test, if only one variant
   remains, it is selected as the best match. If more than one variant
  -remains, move onto the next test.
  +remains, move on to the next test.
   
   <OL>
   <LI>Multiply the quality factor from the Accept header with the
  @@ -301,6 +320,11 @@
   <LI>Select the variants with the highest 'level' media parameter
     (used to give the version of text/html media types).
   
  +<LI>Select only variants with acceptable charset media parameters,
  +  as given on the Accept-Charset header line. Charset ISO-8859-1
  +  is acceptable unless explicitly excluded. Variants not associated
  +  with a particular charset are assumed to be in ISO-8859-1.
  +
   <LI>Select the variants with the best encoding. If there are
     variants with an encoding that is acceptable to the user-agent,
     select only these variants. Otherwise if there is a mix of encoded
  @@ -308,16 +332,11 @@
     If either all variants are encoded or all variants are not encoded, 
     select all variants.
   
  -<LI>Select only variants with acceptable charset media parameters,
  -  as given on the Accept-Charset header line. Charset ISO-8859-1
  -  is always acceptable. Variants not associated with a particular
  -  charset are assumed to be in ISO-8859-1.
  -
   <LI>Select the variants with the smallest content length
   
   <LI>Select the first variant of those remaining (this will be either the
  -first listed in the type-map file, or the first read from the directory)
  -and go to stage 3.
  +  first listed in the type-map file, or the first read from the directory)
  +  and go to stage 3.
   
   </OL>
   
  @@ -326,7 +345,7 @@
     dimensions of negotiation (browsers and caches can use this
     information when caching the resource). End.
   
  -<LI>To get here means no variant was selected (because non are acceptable
  +<LI>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
  @@ -508,12 +527,11 @@
   <H2>Note on Caching</H2>
   
   <P>
  -When a cache stores a document, it associates it with the request URL.
  +When a cache stores a representation, 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
  -subject to content negotiation at the server, this would result in
  -only the first requested variant being cached, and subsequent cache
  -hits could return the wrong response. To prevent this,
  +representation. But, if the resource is negotiable at the server,
  +this might result in only the first requested variant being cached and
  +subsequent cache hits might return the wrong response. To prevent this,
   Apache normally marks all responses that are returned after content negotiation
   as non-cacheable by HTTP/1.0 clients. Apache also supports the HTTP/1.1
   protocol features to allow caching of negotiated responses. <P>
  @@ -522,8 +540,7 @@
   browser or a cache), the directive <TT>CacheNegotiatedDocs</TT> can be
   used to allow caching of 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.
  +takes no arguments. It has no effect on requests from HTTP/1.1 clients.
   
   <!--#include virtual="footer.html" -->
   </BODY>
  
  
  
  1.14      +27 -10    apache-1.3/htdocs/manual/mod/mod_negotiation.html
  
  Index: mod_negotiation.html
  ===================================================================
  RCS file: /home/cvs/apache-1.3/htdocs/manual/mod/mod_negotiation.html,v
  retrieving revision 1.13
  retrieving revision 1.14
  diff -u -r1.13 -r1.14
  --- mod_negotiation.html	1998/12/27 02:38:15	1.13
  +++ mod_negotiation.html	1999/02/06 14:00:33	1.14
  @@ -46,26 +46,35 @@
   
   <DL>
   <DT>Content-Encoding:
  -<DD>The encoding of the file. Currently only two encodings are recognized
  -by http; <CODE>x-compress</CODE> for compressed files, and <CODE>x-gzip</CODE>
  -for gzipped files.
  +<DD>The encoding of the file. Apache only recognizes encodings that are
  +defined by an <A HREF="mod_mime.html#addencoding">AddEncoding</A> directive.
  +This normally includes the encodings <CODE>x-compress</CODE> for compress'd
  +files, and <CODE>x-gzip</CODE> for gzip'd files.  The <CODE>x-</CODE>
prefix
  +is ignored for encoding comparisons.
   <DT>Content-Language:
  -<DD>The language of the variant, as an Internet standard language code, such
  -as <CODE>en</CODE>.
  +<DD>The language of the variant, as an Internet standard language tag
  +(RFC 1766).  An example is <CODE>en</CODE>, meaning English.
   <DT>Content-Length:
   <DD>The length of the file, in bytes. If this header is not present, then
   the actual length of the file is used.
   <DT>Content-Type:
   <DD>The MIME media type of the document, with optional parameters.
  -parameters are separated from the media type and from one another by
  -semi-colons. Parameter syntax is name=value; allowed parameters are:
  +Parameters are separated from the media type and from one another by a
  +semi-colon, with a syntax of <CODE>name=value</CODE>. Common parameters
  +include:
   <DL>
   <DT>level
  -<DD>the value is an integer, which specifies the version of the media type.
  +<DD>an integer specifying the version of the media type.
   For <CODE>text/html</CODE> this defaults to 2, otherwise 0.
   <DT>qs
  -<DD>the value is a floating-point number with value between 0. and 1.
  -It indications the 'quality' of this variant.
  +<DD>a floating-point number with a value in the range 0.0 to 1.0,
  +    indicating the relative 'quality' of this variant
  +    compared to the other available variants, independent of the client's
  +    capabilities.  For example, a jpeg file is usually of higher source
  +    quality than an ascii file if it is attempting to represent a
  +    photograph.  However, if the resource being represented is ascii art,
  +    then an ascii file would have a higher source quality than a jpeg file.
  +    All qs values are therefore specific to a given resource.
   </DL>
   Example:
   <BLOCKQUOTE><CODE>Content-Type: image/jpeg; qs=0.8</CODE></BLOCKQUOTE>
  @@ -91,6 +100,14 @@
   <LI><A HREF="#cachenegotiateddocs">CacheNegotiatedDocs</A>
   <LI><A HREF="#languagepriority">LanguagePriority</A>
   </UL>
  +
  +<STRONG>See also</STRONG>:
  +<A HREF="./mod_mime.html#defaultlanguage">DefaultLanguage</A>,
  +<A HREF="./mod_mime.html#addencoding">AddEncoding</A>,
  +<A HREF="./mod_mime.html#addlanguage">AddLanguage</A>,
  +<A HREF="./mod_mime.html#addtype">AddType</A>, and
  +<A HREF="core.html#options">Option</A>.
  +
   <HR>
   
   
  
  
  

Mime
View raw message