[master] 59b4902 Rewrite Vary. Use A-L instead of A-E. A-E is handled by varnish anyway and this is confusing

[Per Buer]

commit 59b490254d4edc7d87a7c09d24ad7a2ac3a9e6f4
Author: Per Buer <perbu at varnish-software.com>
Date:   Thu Jun 6 10:10:09 2013 +0200

    Rewrite Vary. Use A-L instead of A-E.
    A-E is handled by varnish anyway and this is confusing

diff --git a/doc/sphinx/users-guide/vary.rst b/doc/sphinx/users-guide/vary.rst
index 31c3bde..a171992 100644
--- a/doc/sphinx/users-guide/vary.rst
+++ b/doc/sphinx/users-guide/vary.rst
@@ -3,39 +3,43 @@
 HTTP Vary
 ---------
 
+_HTTP Vary is not a trivial concept. It is by far the most
+misunderstood HTTP header._
+
 The Vary header is sent by the web server to indicate what makes a
 HTTP object Vary. This makes a lot of sense with headers like
-Accept-Encoding. When a server issues a "Vary: Accept-Encoding" it
-tells Varnish that its needs to cache a separate version for every
-different Accept-Encoding that is coming from the clients. So, if a
-clients only accepts gzip encoding Varnish won't serve the version of
-the page encoded with the deflate encoding.
-
-The problem is that the Accept-Encoding field contains a lot of
-different encodings. If one browser sends::
-
-  Accept-Encoding: gzip,deflate
-
-And another one sends::
-
-  Accept-Encoding: deflate,gzip
-
-Varnish will keep two variants of the page requested due to the
-different Accept-Encoding headers. Normalizing the accept-encoding
-header will sure that you have as few variants as possible. The
-following VCL code will normalize the Accept-Encoding headers::
-
-    if (req.http.Accept-Encoding) {
-        if (req.url ~ "\.(jpg|png|gif|gz|tgz|bz2|tbz|mp3|ogg)$") {
-            # No point in compressing these
-            remove req.http.Accept-Encoding;
-        } elsif (req.http.Accept-Encoding ~ "gzip") {
-            set req.http.Accept-Encoding = "gzip";
-        } elsif (req.http.Accept-Encoding ~ "deflate") {
-            set req.http.Accept-Encoding = "deflate";
+Accept-Language. When a server issues a "Vary: Accept-Accept" it tells
+Varnish that its needs to cache a separate version for every different
+Accept-Language that is coming from the clients. 
+
+So, if a client says it accepts the languages "en-us, en-uk" Varnish
+will serve a different version to a client that says it accepts the
+languages "da, de".
+
+Please note that the headers that Vary refer to need to match
+_exactly_ for there to be a match. So Varnish will keep two copies of
+a page if one of them was created for "en-us, en-uk" and the other for
+"en-us,en-uk". 
+
+To achieve a high hitrate whilst using Vary is there therefor crucial
+to normalize the headers the backends varies on. Remember, just a
+differce in case can force different cache entries.
+
+
+The following VCL code will normalize the Accept-Language headers, to
+one of either "en","de" or "fr"::
+
+    if (req.http.Accept-Language) {
+        if (req.http.Accept-Language ~ "en") {
+            set req.http.Accept-Language = "en";
+        } elsif (req.http.Accept-Language ~ "de") {
+            set req.http.Accept-Language = "de";
+        } elsif (req.http.Accept-Language ~ "fr") {
+            set req.http.Accept-Language = "fr";
         } else {
-            # unknown algorithm
-            remove req.http.Accept-Encoding;
+            # unknown language. Remove the accept-language header and 
+	    # use the backend default.
+            remove req.http.Accept-Language
         }
     }