Doc fixes and polish.

README.rst

@@ -61,9 +61,9 @@ SYNOPSIS
 DESCRIPTION
 ===========
 
-Varnish Fetch Processor (VFP) to support the brotli compresion
-algorithm for responses fetched from backends. This VFP integrates
-Varnish with the `Google brotli library`_.
+VFP brotli is a Varnish Fetch Processor to support the brotli
+compression algorithm for responses fetched from backends. The VFP
+integrates Varnish with the `Google brotli library`_.
 
 The Brotli Compressed Data Format is specified in `RFC 7932`_. Details
 of the compression algorithm are beyond the scope of this manual; see
@@ -71,15 +71,15 @@ the RFC and library documentation for more information.
 
 A VFP is technically similar to a Varnish Module (VMOD). In
 particular, it must be installed against Varnish in the same way a
-VMOD is installed, and like a VMOD, a VCL source must instruct Varnish
-to load the VFP using the ``import`` statement. But unlike a VMOD, a
-VFP's primary purpose is not to extend the VCL language; instead, a
-VFP creates filters for backend fetches that can be named as strings
-in the space-separated list assigned to the VCL variable
+VMOD is installed; and as with a VMOD, a VCL source must instruct
+Varnish to load the VFP using the ``import`` statement. But unlike a
+VMOD, a VFP's primary purpose is not to extend the VCL language;
+instead, a VFP creates filters for backend fetches that can be named
+as strings in the space-separated list assigned to the VCL variable
 ``beresp.filters`` (see ``vcl(7)``).
 
 VFP brotli always creates two filters named ``"br"`` and ``"unbr"``,
-for compression and decompression, respectively, with default
+for compression and decompression respectively, with default
 parameters for the compression algorithm::
 
   import brotli;
@@ -114,11 +114,10 @@ the incoming backend response body. The resulting response body is
 passed to the client, and if the response is cached, then the body is
 stored in the cache as it results from the filtering.
 
-To use non-default values for the compression algorithm, create an
+To use non-default settings for the compression algorithm, create an
 ``encoder`` or ``decoder`` object as specified below. The string
 passed in the ``name`` parameter of the object constructor can be used
-in a ``beresp.filters`` list, as with ``"br"`` and
-``"unbr"``::
+in a ``beresp.filters`` list, as with ``"br"`` and ``"unbr"``::
 
   import brotli;
   
@@ -181,12 +180,12 @@ support:
   response header is removed.
 
 * Any ``Content-Length`` response header fetched from the backend is
-  removed -- Varnish may set a new ``Content-Length`` header in a
+  removed -- Varnish may add a new ``Content-Length`` header in a
   client response, set to the changed size of the response body. When
   streaming is enabled, Varnish sends the client response for a fetch
   with chunked encoding (and hence with no ``Content-Length`` header).
 
-* If the backend response has an ``ETag`` header, then the ``Etag``
+* If the backend response has an ``ETag`` header, then the ``ETag``
   value is "weakened" (prefixed with ``W/``), for weak validation
   according to `RFC 7232`_ section 2.1. This is because the response
   after de-/compression is not byte-identical with the fetched
@@ -240,7 +239,7 @@ The parameters are:
 * ``quality`` (default 11): sets a compression level, where 0
   represents the fastest execution, and 11 represents the highest
   compression rate (smallest compressed result). ``quality`` MUST be
-  >= 0 and <= 11.
+  in the range 0 to 11, inclusive.
 
 * ``large_win`` (default ``false``): if ``true``, use Large Window
   Brotli, which may yield better results for response bodies larger
@@ -248,10 +247,10 @@ The parameters are:
   algorithm; under certain circumstances, it may be necessary to use
   the Large Window setting for both compression and decompression.
 
-* ``lgwin`` (default 22): set the window size for the LZ77 algorithm.
-  The window size is (2 ^ ``lgwin`` - 16), and larger window sizes may
-  result in better compression rates. ``lgwin`` MUST be >= 10 and <=
-  24.
+* ``lgwin`` (default 22): set the size of the LZ77 sliding window used
+  by the brotli algorithm.  The window size is (2 ^ ``lgwin`` - 16),
+  and larger window sizes may result in better compression rates.
+  ``lgwin`` MUST be in the range 10 to 24, inclusive.
 
 * ``mode`` (default ``GENERIC``): provide a hint about the expected
   contents of the response body; the compression may benefit from
@@ -275,7 +274,7 @@ Example::
   sub vcl_init {
 	# Create a compression filter with a 1MiB buffer, optimized
 	# for WOFF.
-	new br_woff = brotli.encoder("br_woff", buffer=1m, mode=WOFF);
+	new br_woff = brotli.encoder("br_woff", buffer=1m, mode=FONT);
   }
 
   sub vcl_backend_response {
@@ -330,7 +329,7 @@ As with the ``encoder`` object, the default values for the parameters
 correspond to the defaults used in the standard ``"unbr"``
 decompression filter.
 
-Also as with ``"encoder``, the ``name`` MAY NOT be ``"br"`` or
+Also as with ``encoder``, the ``name`` MAY NOT be ``"br"`` or
 ``"unbr"``, or the same as any of Varnish's standard filters. It
 SHOULD NOT be the same as a name used by another third-party VFP.
 

src/vfp_brotli.vcc

@@ -63,9 +63,9 @@ SYNOPSIS
 DESCRIPTION
 ===========
 
-Varnish Fetch Processor (VFP) to support the brotli compresion
-algorithm for responses fetched from backends. This VFP integrates
-Varnish with the `Google brotli library`_.
+VFP brotli is a Varnish Fetch Processor to support the brotli
+compression algorithm for responses fetched from backends. The VFP
+integrates Varnish with the `Google brotli library`_.
 
 The Brotli Compressed Data Format is specified in `RFC 7932`_. Details
 of the compression algorithm are beyond the scope of this manual; see
@@ -73,15 +73,15 @@ the RFC and library documentation for more information.
 
 A VFP is technically similar to a Varnish Module (VMOD). In
 particular, it must be installed against Varnish in the same way a
-VMOD is installed, and like a VMOD, a VCL source must instruct Varnish
-to load the VFP using the ``import`` statement. But unlike a VMOD, a
-VFP's primary purpose is not to extend the VCL language; instead, a
-VFP creates filters for backend fetches that can be named as strings
-in the space-separated list assigned to the VCL variable
+VMOD is installed; and as with a VMOD, a VCL source must instruct
+Varnish to load the VFP using the ``import`` statement. But unlike a
+VMOD, a VFP's primary purpose is not to extend the VCL language;
+instead, a VFP creates filters for backend fetches that can be named
+as strings in the space-separated list assigned to the VCL variable
 ``beresp.filters`` (see ``vcl(7)``).
 
 VFP brotli always creates two filters named ``"br"`` and ``"unbr"``,
-for compression and decompression, respectively, with default
+for compression and decompression respectively, with default
 parameters for the compression algorithm::
 
   import brotli;
@@ -116,11 +116,10 @@ the incoming backend response body. The resulting response body is
 passed to the client, and if the response is cached, then the body is
 stored in the cache as it results from the filtering.
 
-To use non-default values for the compression algorithm, create an
+To use non-default settings for the compression algorithm, create an
 ``encoder`` or ``decoder`` object as specified below. The string
 passed in the ``name`` parameter of the object constructor can be used
-in a ``beresp.filters`` list, as with ``"br"`` and
-``"unbr"``::
+in a ``beresp.filters`` list, as with ``"br"`` and ``"unbr"``::
 
   import brotli;
   
@@ -183,12 +182,12 @@ support:
   response header is removed.
 
 * Any ``Content-Length`` response header fetched from the backend is
-  removed -- Varnish may set a new ``Content-Length`` header in a
+  removed -- Varnish may add a new ``Content-Length`` header in a
   client response, set to the changed size of the response body. When
   streaming is enabled, Varnish sends the client response for a fetch
   with chunked encoding (and hence with no ``Content-Length`` header).
 
-* If the backend response has an ``ETag`` header, then the ``Etag``
+* If the backend response has an ``ETag`` header, then the ``ETag``
   value is "weakened" (prefixed with ``W/``), for weak validation
   according to `RFC 7232`_ section 2.1. This is because the response
   after de-/compression is not byte-identical with the fetched
@@ -230,7 +229,7 @@ The parameters are:
 * ``quality`` (default 11): sets a compression level, where 0
   represents the fastest execution, and 11 represents the highest
   compression rate (smallest compressed result). ``quality`` MUST be
-  >= 0 and <= 11.
+  in the range 0 to 11, inclusive.
 
 * ``large_win`` (default ``false``): if ``true``, use Large Window
   Brotli, which may yield better results for response bodies larger
@@ -238,10 +237,10 @@ The parameters are:
   algorithm; under certain circumstances, it may be necessary to use
   the Large Window setting for both compression and decompression.
 
-* ``lgwin`` (default 22): set the window size for the LZ77 algorithm.
-  The window size is (2 ^ ``lgwin`` - 16), and larger window sizes may
-  result in better compression rates. ``lgwin`` MUST be >= 10 and <=
-  24.
+* ``lgwin`` (default 22): set the size of the LZ77 sliding window used
+  by the brotli algorithm.  The window size is (2 ^ ``lgwin`` - 16),
+  and larger window sizes may result in better compression rates.
+  ``lgwin`` MUST be in the range 10 to 24, inclusive.
 
 * ``mode`` (default ``GENERIC``): provide a hint about the expected
   contents of the response body; the compression may benefit from
@@ -265,7 +264,7 @@ Example::
   sub vcl_init {
 	# Create a compression filter with a 1MiB buffer, optimized
 	# for WOFF.
-	new br_woff = brotli.encoder("br_woff", buffer=1m, mode=WOFF);
+	new br_woff = brotli.encoder("br_woff", buffer=1m, mode=FONT);
   }
 
   sub vcl_backend_response {
@@ -306,7 +305,7 @@ As with the ``encoder`` object, the default values for the parameters
 correspond to the defaults used in the standard ``"unbr"``
 decompression filter.
 
-Also as with ``"encoder``, the ``name`` MAY NOT be ``"br"`` or
+Also as with ``encoder``, the ``name`` MAY NOT be ``"br"`` or
 ``"unbr"``, or the same as any of Varnish's standard filters. It
 SHOULD NOT be the same as a name used by another third-party VFP.