reorganize the vcc file and add install & supported version info

README.rst

@@ -6,16 +6,100 @@
 
 .. role:: ref(emphasis)
 
+.. _vmod_etag(3):
+
 =========
-VMOD etag
+vmod_etag
 =========
 
--------------------
-Varnish ETag Module
--------------------
+---------------------
+"Varnish ETag Module"
+---------------------
 
 :Manual section: 3
 
+
+
+
+
+DESCRIPTION
+===========
+
+This vmod adds a `beresp.filter`_ (see aka Varnish Fetch Processor /
+VFP) to generate ETags on the way into the Varnish Cache.
+
+.. _`beresp.filter`: http://varnish-cache.org/docs/trunk/reference/vcl.html#beresp
+
+It is strongly recommended to use this vmod from VCL as shown in the `SYNOPSIS`_
+
+ETag generation is enabled by adding ``etag`` to ``beresp.filters`` as
+shown in the example above.
+
+The ETag format is the string ``"vetag`` followed by 64 hexadecimal
+characters representing a SHA256 hash over the response body and a
+closing quote ``"``. The ``"vetag`` prefix is used to identify
+incompletely generated ETags as explained below.
+
+Usage notes:
+
+* For *streaming*, an ETag can not be generated, because, by design,
+  the response headers are being sent before the backend response is
+  complete.
+
+  The VCL template in the `SYNOPSIS`_ thus contains
+  ``set beresp.do_stream = false`` to disable streaming when the ``etag``
+  filter is activated.
+
+  The ``vcl_deliver`` code from the `SYNOPSIS`_ nevertheless supports
+  streaming by removing any incomplete ETags generated by this vmod.
+
+* By design, ETags generated by this vmod can not be used for backend
+  conditional requests.
+
+  The VCL template in the `SYNOPSIS`_ thus contains code to remove any
+  conditional request headers based on ``vetag`` ETags.
+
+Implementation note:
+
+* Varnish core code does not officially support modifying headers of
+  cache objects after creation, which is exactly what is required
+  here. This vmod thus works by leaving a fixed length placeholder
+  ETag header with the cache object, which later gets overwritten by
+  the VFP. This may or may not work with custom storage engines.
+
+INSTALLING
+==========
+
+This vmod is supported for varnish 6.3 and later.
+
+Building from source
+--------------------
+
+This VMOD is using the standard build procedure.
+
+
+Quick start
+-----------
+
+This sequence should be enough in typical setups:
+
+1. ``./bootstrap``
+2. ``make``
+3. ``make check`` (regression tests)
+4. ``make install`` (may require root: sudo make install)
+
+Alternative configs
+-------------------
+
+If you have installed Varnish to a non-standard directory, call
+``autogen.sh`` and ``configure`` with ``PKG_CONFIG_PATH`` pointing to
+the appropriate path. For example, when varnishd configure was called
+with ``--prefix=$PREFIX``, use::
+
+  PKG_CONFIG_PATH=${PREFIX}/lib/pkgconfig
+  ACLOCAL_PATH=${PREFIX}/share/aclocal
+  export PKG_CONFIG_PATH ACLOCAL_PATH
+
 SYNOPSIS
 ========
 
@@ -66,56 +150,12 @@ SYNOPSIS
             call vetag_deliver;
         }
 
-DESCRIPTION
-===========
-
-This vmod adds a `beresp.filter`_ (see aka Varnish Fetch Processor /
-VFP) to generate ETags on the way into the Varnish Cache.
-
-.. _`beresp.filter`: http://varnish-cache.org/docs/trunk/reference/vcl.html#beresp
-
-It is strongly recommended to use this vmod from VCL as shown in the `SYNOPSIS`_
-
-ETag generation is enabled by adding ``etag`` to ``beresp.filters`` as
-shown in the example above.
-
-The ETag format is the string ``"vetag`` followed by 64 hexadecimal
-characters representing a SHA256 hash over the response body and a
-closing quote ``"``. The ``"vetag`` prefix is used to identify
-incompletely generated ETags as explained below.
-
-Usage notes:
-
-* For *streaming*, an ETag can not be generated, because, by design,
-  the response headers are being sent before the backend response is
-  complete.
-
-  The VCL template in the `SYNOPSIS`_ thus contains
-  ``set beresp.do_stream = false`` to disable streaming when the ``etag``
-  filter is activated.
-
-  The ``vcl_deliver`` code from the `SYNOPSIS`_ nevertheless supports
-  streaming by removing any incomplete ETags generated by this vmod.
-
-* By design, ETags generated by this vmod can not be used for backend
-  conditional requests.
-
-  The VCL template in the `SYNOPSIS`_ thus contains code to remove any
-  conditional request headers based on ``vetag`` ETags.
-
-Implementation note:
-
-* Varnish core code does not officially support modifying headers of
-  cache objects after creation, which is exactly what is required
-  here. This vmod thus works by leaving a fixed length placeholder
-  ETag header with the cache object, which later gets overwritten by
-  the VFP. This may or may not work with custom storage engines.
-
 SEE ALSO
 ========
 * :ref:`vcl(7)`
 * :ref:`varnishd(1)`
 
+
 COPYRIGHT
 =========
 

src/vmod_etag.vcc

@@ -26,6 +26,84 @@
 $Module etag 3 "Varnish ETag Module"
 $Synopsis manual
 
+DESCRIPTION
+===========
+
+This vmod adds a `beresp.filter`_ (see aka Varnish Fetch Processor /
+VFP) to generate ETags on the way into the Varnish Cache.
+
+.. _`beresp.filter`: http://varnish-cache.org/docs/trunk/reference/vcl.html#beresp
+
+It is strongly recommended to use this vmod from VCL as shown in the `SYNOPSIS`_
+
+ETag generation is enabled by adding ``etag`` to ``beresp.filters`` as
+shown in the example above.
+
+The ETag format is the string ``"vetag`` followed by 64 hexadecimal
+characters representing a SHA256 hash over the response body and a
+closing quote ``"``. The ``"vetag`` prefix is used to identify
+incompletely generated ETags as explained below.
+
+Usage notes:
+
+* For *streaming*, an ETag can not be generated, because, by design,
+  the response headers are being sent before the backend response is
+  complete.
+
+  The VCL template in the `SYNOPSIS`_ thus contains
+  ``set beresp.do_stream = false`` to disable streaming when the ``etag``
+  filter is activated.
+
+  The ``vcl_deliver`` code from the `SYNOPSIS`_ nevertheless supports
+  streaming by removing any incomplete ETags generated by this vmod.
+
+* By design, ETags generated by this vmod can not be used for backend
+  conditional requests.
+
+  The VCL template in the `SYNOPSIS`_ thus contains code to remove any
+  conditional request headers based on ``vetag`` ETags.
+
+Implementation note:
+
+* Varnish core code does not officially support modifying headers of
+  cache objects after creation, which is exactly what is required
+  here. This vmod thus works by leaving a fixed length placeholder
+  ETag header with the cache object, which later gets overwritten by
+  the VFP. This may or may not work with custom storage engines.
+
+INSTALLING
+==========
+
+This vmod is supported for varnish 6.3 and later.
+
+Building from source
+--------------------
+
+This VMOD is using the standard build procedure.
+
+
+Quick start
+-----------
+
+This sequence should be enough in typical setups:
+
+1. ``./bootstrap``
+2. ``make``
+3. ``make check`` (regression tests)
+4. ``make install`` (may require root: sudo make install)
+
+Alternative configs
+-------------------
+
+If you have installed Varnish to a non-standard directory, call
+``autogen.sh`` and ``configure`` with ``PKG_CONFIG_PATH`` pointing to
+the appropriate path. For example, when varnishd configure was called
+with ``--prefix=$PREFIX``, use::
+
+  PKG_CONFIG_PATH=${PREFIX}/lib/pkgconfig
+  ACLOCAL_PATH=${PREFIX}/share/aclocal
+  export PKG_CONFIG_PATH ACLOCAL_PATH
+
 SYNOPSIS
 ========
 
@@ -76,51 +154,6 @@ SYNOPSIS
             call vetag_deliver;
         }
 
-DESCRIPTION
-===========
-
-This vmod adds a `beresp.filter`_ (see aka Varnish Fetch Processor /
-VFP) to generate ETags on the way into the Varnish Cache.
-
-.. _`beresp.filter`: http://varnish-cache.org/docs/trunk/reference/vcl.html#beresp
-
-It is strongly recommended to use this vmod from VCL as shown in the `SYNOPSIS`_
-
-ETag generation is enabled by adding ``etag`` to ``beresp.filters`` as
-shown in the example above.
-
-The ETag format is the string ``"vetag`` followed by 64 hexadecimal
-characters representing a SHA256 hash over the response body and a
-closing quote ``"``. The ``"vetag`` prefix is used to identify
-incompletely generated ETags as explained below.
-
-Usage notes:
-
-* For *streaming*, an ETag can not be generated, because, by design,
-  the response headers are being sent before the backend response is
-  complete.
-
-  The VCL template in the `SYNOPSIS`_ thus contains
-  ``set beresp.do_stream = false`` to disable streaming when the ``etag``
-  filter is activated.
-
-  The ``vcl_deliver`` code from the `SYNOPSIS`_ nevertheless supports
-  streaming by removing any incomplete ETags generated by this vmod.
-
-* By design, ETags generated by this vmod can not be used for backend
-  conditional requests.
-
-  The VCL template in the `SYNOPSIS`_ thus contains code to remove any
-  conditional request headers based on ``vetag`` ETags.
-
-Implementation note:
-
-* Varnish core code does not officially support modifying headers of
-  cache objects after creation, which is exactly what is required
-  here. This vmod thus works by leaving a fixed length placeholder
-  ETag header with the cache object, which later gets overwritten by
-  the VFP. This may or may not work with custom storage engines.
-
 SEE ALSO
 ========
 * :ref:`vcl(7)`