Documentation overhaul

.gitignore

@@ -33,7 +33,8 @@ Makefile.in
 
 /src/vcc_pesi_debug_if.[ch]
 /src/vcc_pesi_if.[ch]
-/src/vmod_*rst
+/src/vmod_*debug*rst
+/src/vmod_pesi.rst
 /src/VSC_pesi.c
 /src/VSC_pesi.h
 

Makefile.am

@@ -9,10 +9,6 @@ EXTRA_DIST = README.rst LICENSE CONTRIBUTING.rst INSTALL.rst
 
 doc_DATA = README.rst LICENSE CONTRIBUTING.rst INSTALL.rst
 
-README.rst: src/vdp_pesi.vcc
-	$(MAKE) $(AM_MAKEFLAGS) -C src vmod_pesi.man.rst
-	cp src/vmod_pesi.man.rst README.rst
-
 coverage:
 	$(MAKE) $(AM_MAKEFLAGS) -C src coverage
 

src/vdp_pesi.vcc

@@ -62,47 +62,6 @@ SYNOPSIS
 
 .. _varnishstat(1): https://varnish-cache.org/docs/trunk/reference/varnishstat.html
 
-TL;DR: QUICK START
-==================
-
-This documentation is detailed on purpose. It aims to explain well
-how this VMOD works and how optimizations can be tuned.
-
-We welcome all users to read the documentation, but many users will
-neither want to nor need to understand the details. Thus, here is what
-you *really* need to know:
-
-* See `INSTALL.rst <INSTALL.rst>`_ in the source repository for
-  installation instructions.
-
-* To use pESI, add to the top of your VCL::
-
-    import pesi;
-
-  and to your ``sub vcl_deliver {}``, add::
-
-    pesi.activate();
-
-  This should be added *after* any modification of ``resp.do_esi``,
-  ``req.http.Accept-Encoding``, ``req.http.Range`` or
-  ``resp.filters``, if these exist.
-
-  To be safe, ``pesi.activate()`` can be called before any
-  ``return(deliver)`` in ``sub vcl_deliver {}``.
-
-* If you call ``pesi.activate()``, call it unconditionally and on all
-  ESI levels. Read this documentation for details.
-
-It is possible that your current configuration of system resources,
-such as thread pools, workspaces, memory allocation and so forth, will
-suffice after this simple change, and will need no further
-optimization.
-
-But that is by no means ensured, since pESI uses system resources
-differently from standard ESI. Understanding these difference, and how
-to monitor and manage resource usage affected by pESI, is a main focus
-of the detailed discussion that follows.
-
 DESCRIPTION
 ===========
 
@@ -132,11 +91,11 @@ Parallel ESI processing is enabled by invoking |pesi.activate()|_ in
 ``vcl_deliver {}``::
 
    import pesi;
-   
+
    sub vcl_backend_response {
        set beresp.do_esi = true;
    }
-   
+
    sub vcl_deliver {
        pesi.activate();
    }
@@ -809,42 +768,6 @@ at different times, depending on the order of events, and on whether
 or not we use (partial) sequential delivery (for example, when no
 threads are available).
 
-REQUIREMENTS
-============
-
-All versions of the VDP require strict ABI compatibility with Varnish,
-meaning that it must run against the same build version of Varnish as
-the version against which the VDP was built. This means that the
-"commit id" portion of the Varnish version string (the SHA1 hash) must
-be the same at runtime as at build time.
-
-INSTALLATION
-============
-
-See `INSTALL.rst <INSTALL.rst>`_ in the source repository.
-
-ACKNOWLEDGEMENTS
-================
-
-.. _Otto GmbH & Co KG: https://www.otto.de/
-
-Most of the development work of this vmod in 2019 and 2020 has been
-sponsored by `Otto GmbH & Co KG`_.
-
-.. _BoardGameGeek: https://boardgamegeek.com/
-
-The initial release to the public in 2021 has been supported by
-`BoardGameGeek`_.
-
-SUPPORT
-=======
-
-For community support, please use `Gitlab Issues`_.
-
-For commercial support, please contact varnish-support@uplex.de
-
-.. _Gitlab Issues: https://gitlab.com/uplex/varnish/libvdp-pesi/-/issues
-
 SEE ALSO
 ========