doc: cross-reference vs. code

Use a link for uses outside the function documentation and
``pesi.function()`` as the code snippet.

src/vdp_pesi.vcc

@@ -69,7 +69,7 @@ include in a response before the first one. If the logic of ESI
 composition in a standard Varnish deployment does not depend on the
 serial order, then it will work the same way with VDP pesi.
 
-Parallel ESI processing is enabled by invoking ``pesi.activate()`` in
+Parallel ESI processing is enabled by invoking `vmod_pesi.activate`_ in
 ``vcl_deliver {}``::
 
    import pesi;
@@ -84,10 +84,10 @@ Parallel ESI processing is enabled by invoking ``pesi.activate()`` in
 
 Other functions provided by the VDP serve to set configuration
 parameters (or return the VDP version string). If your deployment uses
-the default configuration, then ``pesi.activate()`` in ``vcl_deliver``
+the default configuration, then `vmod_pesi.activate`_ in ``vcl_deliver``
 may be the only modification to VCL that you need.
 
-The invocation of ``pesi.activate()`` can of course be subject to
+The invocation of `vmod_pesi.activate`_ can of course be subject to
 logic in VCL::
 
    sub vcl_deliver {
@@ -97,7 +97,7 @@ logic in VCL::
        }
    }
 
-But see below for restrictions on the use of ``pesi.activate()``.
+But see below for restrictions on the use of `vmod_pesi.activate`_.
 
 All of the computing resources used by the pesi VDP -- threads, storage,
 workspace, locks, and so on -- can be configured, either with Varnish
@@ -111,51 +111,51 @@ $Function VOID activate()
 
 Enable parallel ESI processing for the client response.
 
-``activate()`` MUST be called in ``vcl_deliver {}`` only. If it is
+``pesi.activate()`` MUST be called in ``vcl_deliver {}`` only. If it is
 called in any other VCL subroutine, VCL failure is invoked (see
 `ERRORS`_ below for details).
 
-If ``activate()`` is called on *any* ESI level (any depth of include
+If ``pesi.activate()`` is called on *any* ESI level (any depth of include
 nesting), then it MUST be called on *all* levels of the response. If
-``activate()`` is invoked at some ESI levels but not others, then the
+``pesi.activate()`` is invoked at some ESI levels but not others, then the
 results are undefined, and will very likely lead to a Varnish panic.
 
-It is also safe, for instance, to call ``activate()`` only if a
+It is also safe, for instance, to call ``pesi.activate()`` only if a
 request header is present, as in the example shown above; since the
 same request headers are set for every ESI subrequest, the result is
 the same at every ESI level. But that should *not* be done if you have
 logic that unsets the header at some ESI levels but not at
-others. Under no circumstances should the invocation of ``activate()``
+others. Under no circumstances should the invocation of ``pesi.activate()``
 depend on the value of ``req.esi_level``, or of ``req.url`` (since
 URLs are different at different ESI levels).
 
-See the documentation of ``set()`` below for a way to choose serial
+See `vmod_pesi.set`_ below for a way to choose serial
 ESI processing for all of the includes in the response at the current
-ESI level. Even then, ``activate()`` must be called in ``vcl_deliver
-{}`` in addition to ``set()``.
+ESI level. Even then, ``pesi.activate()`` must be called in ``vcl_deliver
+{}`` in addition to ``pesi.set()``.
 
 As with standard Varnish, ESI processing can be selectively disabled
 for a client response, by setting ``resp.do_esi`` to ``false`` in VCL
 since version 4.1, or setting ``req.esi`` to ``false`` in VCL 4.0 (see
 `vcl(7)`_). The requirement remains: if ESI processing is enabled and
-``activate()`` is called at any ESI level, then both must happen at
+``pesi.activate()`` is called at any ESI level, then both must happen at
 all levels.
 
-``activate()`` has the effect of setting the VCL string variable
+``pesi.activate()`` has the effect of setting the VCL string variable
 ``resp.filters``, which is a whitespace-separated list of the names of
 delivery processors to be applied to the client response (see
 `vcl(7)`_). It configures the correct list of filters for the current
 response, analogous to the default filter settings in Varnish when
 sequential ESI is in use. These include the ``gunzip`` VDP for
 uncompressed responses, and ``range`` for responses to range
-requests. ``activate()`` checks the conditions for which the VDPs are
+requests. ``pesi.activate()`` checks the conditions for which the VDPs are
 required, and arranges them in the correct order.
 
 It is possible to manually set or change ``resp.filters`` to enable
-parallel ESI, instead of calling ``activate()``, but that is only
+parallel ESI, instead of calling ``pesi.activate()``, but that is only
 advised to experts. If you do so, use the string ``pesi`` for this
 VDP, and do *not* include ``esi``, for Varnish's standard ESI VDP, in
-the same list with ``pesi``. As with the ``activate()`` call -- if
+the same list with ``pesi``. As with the ``pesi.activate()`` call -- if
 ``pesi`` appears in ``resp.filters`` for a response at *any* ESI
 level, it MUST be in ``resp.filters`` at *all* ESI levels.
 
@@ -197,7 +197,7 @@ identified by the ENUM ``parameter``. Currently the parameters can
 only be set with a boolean value in ``bool`` (but future versions of
 this function may allow for setting other data types).
 
-``set()`` MUST be called in ``vcl_deliver {}`` only; otherwise VCL
+``pesi.set()`` MUST be called in ``vcl_deliver {}`` only; otherwise VCL
 failure is invoked (see `ERRORS`_).
 
 The parameters that can be set are currently ``serial`` and ``thread``:
@@ -288,9 +288,9 @@ since the number of pre-allocated nodes is constant. So any adjustment
 to Varnish's ``workspace_client`` parameter that may be necessary due
 to the pre-allocation will be valid for all requests.
 
-``workspace_prealloc()`` configures the pre-allocation. The default
+``pesi.workspace_prealloc()`` configures the pre-allocation. The default
 values of its parameters are defaults used by the VDP; that is, the
-configuration if ``workspace_prealloc()`` is never called.
+configuration if ``pesi.workspace_prealloc()`` is never called.
 
 The ``min_free`` parameter sets the minimum amount of space that the
 pre-allocation will always leave free in client workspace; if the
@@ -310,13 +310,13 @@ invoked (see `ERRORS`_). If ``max_nodes`` is set to 0, then no nodes
 are pre-allocated; they are all taken from the memory pool described
 below.
 
-When ``workspace_prealloc()`` is called, its configuration becomes
+When ``pesi.workspace_prealloc()`` is called, its configuration becomes
 effective immediately for all new requests processed by the VDP. The
 configuration remains valid for all instances of VCL, for as long as
 the VDP remains loaded; that is, until the last instance of VCL using
 the VDP is discarded.
 
-``workspace_prealloc()`` can be called in ``vcl_init`` to set the
+``pesi.workspace_prealloc()`` can be called in ``vcl_init`` to set the
 configuration at VCL load time.  But you can also write VCL that calls
 the function when a request is received by Varnish, for example using
 a special URL for system administrators. This is similar to using the
@@ -324,7 +324,7 @@ a special URL for system administrators. This is similar to using the
 parameter at runtime. Such a request should be protected, for example
 with an ACL and/or Basic Authentication, so that it can be invoked
 only by admins. Remember that as soon as such a request is processed
-and ``workspace_prealloc()`` is executed, the changed configuration is
+and ``pesi.workspace_prealloc()`` is executed, the changed configuration is
 globally valid.
 
 Examples::
@@ -401,11 +401,11 @@ allocation requests, even if ``max`` is execeeded when nodes are
 returned to the pool. But the pool size will then be reduced to
 ``max``, without waiting for ``max_age`` to expire.
 
-As with ``workspace_prealloc()``: when ``pool()`` is called, the
+As with `vmod_pesi.workspace_prealloc`_: when ``pesi.pool()`` is called, the
 changed configuration immediately becomes valid (although it may take
 some time for the memory pool to adjust to the new values). It remains
-vaild for as long as the VDP is still loaded, unless ``pool()`` is
-called again. ``pool()`` may be called in ``vcl_init`` to set a
+vaild for as long as the VDP is still loaded, unless ``pesi.pool()`` is
+called again. ``pesi.pool()`` may be called in ``vcl_init`` to set a
 configuration at VCL load time, but may also be called elsewhere in
 VCL, for example to enable changing configurations at runtime using a
 special "admin" request.
@@ -509,7 +509,7 @@ processed at any one time.
 
 The VDP runs ESI subrequests (for each ``<esi:include>`` directive at
 every ESI level) in separate threads, unless instructed not to do so
-due to the use of either ``set(serial, true)`` or ``set(thread,
+due to the use of either ``pesi.set(serial, true)`` or ``pesi.set(thread,
 false)``, as documented above. The threads are requested from the
 thread pools managed by Varnish. This means that in most cases, for
 well-configured thread pools, the overhead of starting new threads is
@@ -519,18 +519,18 @@ that is immediately ready for use.
 The VDP uses client workspace at the top-level request (ESI level 0)
 for fixed-sized internal metadata. It also uses client workspace to
 pre-allocate a constant number of nodes in variable-sized structures,
-as described in the documentation of ``workspace_prealloc()`` above.
-Together these make for a fixed-sized demand on client workspace, when
-``activate()`` is invoked. The size of the space needed from workspace
-varies on different systems, and depends on any
-``workspace_prealloc()`` you may have set, but broadly speaking, it can
+as described in `vmod_pesi.workspace_prealloc`_ above.  Together these
+make for a fixed-sized demand on client workspace, when
+`vmod_pesi.activate`_ is invoked. The size of the space needed from
+workspace varies on different systems, and depends on
+`vmod_pesi.workspace_prealloc`_ setting, but broadly speaking, it can
 expected to be less than 10 KiB.
 
-As described in the documentation for ``pool()`` above, the VDP uses a
-memory pool for nodes in its internal reconstruction of the ESI tree,
-if more are needed than are pre-allocated in workspace. The same
-mechanism is employed as Varnish's memory pools, so the same
-considerations apply to the configuration and monitoring of the pool.
+As described for `vmod_pesi.pool`_, the VDP uses a memory pool for
+nodes in its internal reconstruction of the ESI tree, if more are
+needed than are pre-allocated in workspace. The same mechanism is
+employed as Varnish's memory pools, so the same considerations apply
+to the configuration and monitoring of the pool.
 
 For each top-level ESI request using the VDP, two locks are employed;
 one to synchronize access to common data structures, and another to