man: Document built-in subs in a reference manual

Instead of documenting built-in subroutines in the user guide, a new
vcl-step(7) manual is added. It is structured with a vcl-step.rst file
that includes a vcl_step.rst file containing the actual list of steps.

This is similar to how the vcl-var(7) manual is constructed to later
make it authoritative.

doc/sphinx/conf.py.in

@@ -64,7 +64,7 @@ release = '@VERSION@'
 
 # List of directories, relative to source directory, that shouldn't be searched
 # for source files.
-exclude_patterns = ['build','include/*.rst','reference/vcl_var.rst']
+exclude_patterns = ['build','include/*.rst','reference/vcl_*.rst']
 
 # The reST default role (used for this markup: `text`) to use for all documents.
 #default_role = None

doc/sphinx/reference/index.rst

@@ -19,6 +19,7 @@ The VCL language
 
 	VCL - The Varnish Configuration Language <vcl>
 	VCL Variables <vcl-var>
+	VCL Steps <vcl-step>
 	VCL backend configuration <vcl-backend>
 	VCL backend health probe <vcl-probe>
 	states.rst

doc/sphinx/reference/states.rst

@@ -18,7 +18,7 @@ state machines. Whenever a state is entered, a C function is called,
 which in turn calls the appropriate Varnish core code functions to
 process the request or response at this stage. For most states, core
 code also calls into a state-specific function compiled from VCL, a
-VCL subroutine (see :ref:`vcl-built-in-subs` ).
+VCL subroutine (see :ref:`vcl_steps`).
 
 As a general guideline, core code aims to prepare objects accessible
 from VCL with good defaults for the most common cases before calling

doc/sphinx/reference/vcl-step.rst

+..
+	Copyright (c) 2013-2021 Varnish Software AS
+	SPDX-License-Identifier: BSD-2-Clause
+	See LICENSE file for full text of license
+
+
+.. role:: ref(emphasis)
+
+.. _vcl-steps(7):
+
+=========
+VCL-steps
+=========
+
+--------------------
+Built-in subroutines
+--------------------
+
+:Manual section: 7
+
+
+DESCRIPTION
+===========
+
+Various built-in subroutines are called during processing of client
+and backend requests as well as upon ``vcl.load`` and ``vcl.discard``.
+
+See :ref:`reference-states` for a detailed graphical overview of the
+states and how they relate to core code functions and VCL subroutines.
+
+Built-in subroutines always terminate with a ``return (<action>)``,
+where ``<action>`` determines how processing continues in the request
+processing state machine.
+
+The behaviour of actions is identical or at least similar across
+subroutines, so differences are only documented where relevant.
+
+Common actions are documented in
+:ref:`user-guide-vcl_actions`. Actions specific to only one or some
+subroutines are documented herein.
+
+A default behavior is provided for all :ref:`reference-states` in the
+:ref:`vcl-built-in-code` code.
+
+
+.. include:: vcl_step.rst
+
+
+
+SEE ALSO
+========
+
+* :ref:`varnishd(1)`
+* :ref:`vcl(7)`
+
+COPYRIGHT
+=========
+
+This document is licensed under the same license as Varnish
+itself. See LICENSE for details.
+
+* Copyright (c) 2006 Verdens Gang AS
+* Copyright (c) 2006-2021 Varnish Software AS

doc/sphinx/reference/vcl.rst

@@ -445,6 +445,7 @@ SEE ALSO
 * :ref:`varnishd(1)`
 * :ref:`vcl-backend(7)`
 * :ref:`vcl-probe(7)`
+* :ref:`vcl-steps(7)`
 * :ref:`vcl-var(7)`
 * :ref:`vmod_directors(3)`
 * :ref:`vmod_std(3)`

doc/sphinx/users-guide/vcl-actions.rst

@@ -14,7 +14,7 @@ processing in varnish continues as shown in :ref:`reference-states`.
 
 Common actions are documented here, while additional actions specific
 to only one or some subroutines are documented in
-:ref:`vcl-built-in-subs` as well as which action can be used from
+:ref:`vcl-steps(7)` as well as which action can be used from
 which built in subroutine.
 
 common actions for the client and backend side

doc/sphinx/users-guide/vcl-built-in-code.rst

@@ -4,7 +4,7 @@ Built-in VCL
 ============
 
 Whenever a VCL program is loaded, the built-in VCL is appended to it. The
-:ref:`vcl-built-in-subs` have a special property, they can appear multiple
+vcl built-in subs (:ref:`vcl_steps`) have a special property, they can appear multiple
 times and the result is concatenation of all built-in subroutines.
 
 For example, let's take the following snippet::

doc/sphinx/users-guide/vcl-syntax.rst

@@ -99,7 +99,7 @@ Built in subroutines
 
 Varnish has quite a few built-in subroutines that are called for each
 transaction as it flows through Varnish. These built-in subroutines are
-all named ``vcl_*`` and are explained in :ref:`vcl-built-in-subs`.
+all named ``vcl_*`` and are explained in :ref:`vcl_steps`.
 
 Processing in built-in subroutines ends with ``return (<action>)``
 (see :ref:`user-guide-vcl_actions`).
@@ -130,7 +130,7 @@ values.
 
 ``return (<action>)`` (see :ref:`user-guide-vcl_actions`) as shown in
 the example above returns all the way from the top level built in
-subroutine (see :ref:`vcl-built-in-subs`) which, possibly through
+subroutine (see :ref:`vcl_steps`) which, possibly through
 multiple steps, lead to the call of the custom subroutine.
 
 ``return`` without an action resumes execution after the ``call``

doc/sphinx/users-guide/vcl.rst

@@ -40,7 +40,6 @@ code commented out in the file `builtin.vcl` that ships with Varnish Cache.
    :maxdepth: 1
 
    vcl-syntax
-   vcl-built-in-subs
    vcl-built-in-code
    vcl-variables
    vcl-actions

man/Makefile.am

@@ -7,6 +7,7 @@ dist_man_MANS = \
 	vcl-backend.7 \
 	vcl-probe.7 \
 	vcl-var.7 \
+	vcl-step.7 \
 	vsl.7 \
 	vsl-query.7 \
 	varnishadm.1 \
@@ -60,6 +61,10 @@ vcl-probe.7: $(top_builddir)/doc/sphinx/reference/vcl-probe.rst
 vcl-var.7: $(top_builddir)/doc/sphinx/reference/vcl-var.rst
 	$(BUILD_MAN) $(top_builddir)/doc/sphinx/reference/vcl-var.rst $@
 
+vcl-step.7: $(top_builddir)/doc/sphinx/reference/vcl-step.rst \
+	$(top_builddir)/doc/sphinx/reference/vcl_step.rst
+	$(BUILD_MAN) $(top_builddir)/doc/sphinx/reference/vcl-step.rst $@
+
 vsl.7: $(top_builddir)/doc/sphinx/reference/vsl.rst \
 	$(top_builddir)/doc/sphinx/include/vsl-tags.rst
 	$(BUILD_MAN) $(top_builddir)/doc/sphinx/reference/vsl.rst $@