[4.0] 52083bf update gzip docs

[Lasse Karstensen]

commit 52083bf48324854d46f3ff596c23707fa55902cd
Author: Nils Goroll <nils.goroll at uplex.de>
Date:   Thu Aug 28 11:06:06 2014 +0200

    update gzip docs

diff --git a/doc/sphinx/users-guide/compression.rst b/doc/sphinx/users-guide/compression.rst
index bff1ebb..e7cfda2 100644
--- a/doc/sphinx/users-guide/compression.rst
+++ b/doc/sphinx/users-guide/compression.rst
@@ -9,24 +9,47 @@ encoding. *Before* 3.0, Varnish would never compress objects.
 In Varnish 4.0 compression defaults to "on", meaning that it tries to
 be smart and do the sensible thing.
 
-.. XXX:Heavy refactoring to Varnish 4 above. benc
-
 If you don't want Varnish tampering with the encoding you can disable
-compression all together by setting the parameter 'http_gzip_support' to
+compression all together by setting the parameter `http_gzip_support` to
 false. Please see man :ref:`ref-varnishd` for details.
 
 
 Default behaviour
 ~~~~~~~~~~~~~~~~~
 
-The default behaviour for Varnish is to check if the client supports our
-compression scheme (gzip) and if it does it will override the
-'Accept-Encoding' header and set it to "gzip".
+The default behaviour is active when the `http_gzip_support` parameter
+is set to "on" and neither `beresp.do_gzip` nor `beresp.do_gunzip` are
+used in VCL.
+
+Unless returning from `vcl_recv` with `pipe` or `pass`, varnish sets
+`req.http.Accept-Encoding` to "gzip". It removes the header otherwise.
+
+Unless the request is a `pass`, Varnish will set
+`bereq.http.Accept-Encoding` to "gzip" before `vcl_backend_fetch`
+runs, so the header can be changed in VCL.
+
+If the server responds with gzip'ed content it will be stored in
+memory in its compressed form and `Accept-Encoding` will be added to
+the `Vary` header.
+
+To clients supporting gzip, compressed content is delivered
+unmodified.
+
+For clients not supporting gzip, compressed content gets decompressed
+on the fly while delivering. The `Content-Encoding` response header
+gets removed and any `Etag` gets weakened (by prepending "W/").
 
-When Varnish then issues a backend request the 'Accept-Encoding' will
-then only consist of "gzip". If the server responds with gzip'ed
-content it will be stored in memory in its compressed form. If the
-backend sends content in clear text it will be stored in clear text.
+For Vary Lookups, `Accept-Encoding` is ignored.
+
+Turning off gzip support
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+When the `http_gzip_support` parameter is set to "off", Varnish does
+not do any of the header alterations documented above and handles
+`Vary: Accept-Encoding` like it would for any other `Vary` value.
+
+Compressing content if backends don't
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 You can make Varnish compress content before storing it in cache in
 `vcl_backend_response` by setting 'do_gzip' to true, like this::
@@ -37,15 +60,41 @@ You can make Varnish compress content before storing it in cache in
         }
   }
 
-Please make sure that you don't try to compress content that is
-uncompressable, like jpgs, gifs and mp3. You'll only waste CPU
-cycles. You can also uncompress objects before storing it in memory by
-setting 'do_gunzip' to true but that will usually not be the most sensible thing to do.
+With `do_gzip` Varnish will make the following alterations to the
+headers of the resulting object which cannot be modified in a backend
+VCL (but in `vcl_deliver`):
+
+* set `obj.http.Content-Encoding` to "gzip"
+* add "Accept-Encoding" to `obj.http.Content-Encoding`, unless already
+  present
+* weaken any `Etag` (by prepending "W/")
+
 Generally, Varnish doesn't use much CPU so it might make more sense to
 have Varnish spend CPU cycles compressing content than doing it in
 your web- or application servers, which are more likely to be
 CPU-bound.
 
+Please make sure that you don't try to compress content that is
+uncompressable, like jpgs, gifs and mp3. You'll only waste CPU cycles.
+
+Uncompressing content before entering the cache
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can also uncompress objects before storing it in memory by setting
+`do_gunzip` to true. One use case for this feature is to work around
+badly configured backends uselessly compressing already compressed
+content like JPG images (but fixing the misbehaving backend is always
+the better option).
+
+With `do_gzip` Varnish will make the following alterations to the
+headers of the resulting object which cannot be modified in a backend
+VCL (but in `vcl_deliver`):
+
+* remove `obj.http.Content-Encoding` to "gzip"
+* remove any "Accept-Encoding" from `obj.http.Content-Encoding`
+  (XXX review when closing #940)
+* weaken any `Etag` (by prepending "W/")
+
 GZIP and ESI
 ~~~~~~~~~~~~
 
@@ -54,20 +103,6 @@ and GZIP work together really well. Varnish will magically decompress
 the content to do the ESI-processing, then recompress it for efficient
 storage and delivery. 
 
-
-Clients that don't support gzip
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If the client does not support gzip the 'Accept-Encoding' header is left
-alone then we'll end up serving whatever we get from the backend
-server. Remember that the backend might tell Varnish to *Vary* on the
-'Accept-Encoding'.
-
-If the client does not support gzip but we've already got a compressed
-version of the page in memory Varnish will automatically decompress
-the page while delivering it.
-
-
 A random outburst
 ~~~~~~~~~~~~~~~~~