Try to split out small chunks of man vcl into separate bitsize files for reuse in users guide

doc/sphinx/include/vcl-backends.rst

+Backend declarations
+--------------------
+
+A backend declaration creates and initializes a named backend object:
+::
+
+  backend www {
+    .host = "www.example.com";
+    .port = "http";
+  }
+
+The backend object can later be used to select a backend at request time:
+::
+
+  if (req.http.host ~ "(?i)^(www.)?example.com$") {
+    set req.backend = www;
+  }
+
+To avoid overloading backend servers, .max_connections can be set to
+limit the maximum number of concurrent backend connections.
+
+The timeout parameters can be overridden in the backend declaration.
+The timeout parameters are .connect_timeout for the time to wait for a
+backend connection, .first_byte_timeout for the time to wait for the
+first byte from the backend and .between_bytes_timeout for time to
+wait between each received byte.
+
+These can be set in the declaration like this:
+::
+
+  backend www {
+    .host = "www.example.com";
+    .port = "http";
+    .connect_timeout = 1s;
+    .first_byte_timeout = 5s;
+    .between_bytes_timeout = 2s;
+  }
+
+To mark a backend as unhealthy after number of items have been added
+to its saintmode list ``.saintmode_threshold`` can be set to the maximum
+list size. Setting a value of 0 disables saint mode checking entirely
+for that backend.  The value in the backend declaration overrides the
+parameter.
+

doc/sphinx/include/vcl-syntax.rst

+VCL SYNTAX
+==========
+
+The VCL syntax is very simple, and deliberately similar to C and Perl.
+Blocks are delimited by curly braces, statements end with semicolons,
+and comments may be written as in C, C++ or Perl according to your own
+preferences.
+
+In addition to the C-like assignment (=), comparison (==, !=) and
+boolean (!, && and \|\|) operators, VCL supports both regular
+expression and ACL matching using the ~ and the !~ operators.
+
+Basic strings are enclosed in " ... ", and may not contain newlines.
+
+Long strings are enclosed in {" ... "}. They may contain any
+character including ", newline and other control characters except
+for the NUL (0x00) character.
+
+Unlike C and Perl, the backslash (\) character has no special meaning
+in strings in VCL, so it can be freely used in regular expressions
+without doubling.
+
+Strings are concatenated using the '+' operator. 
+
+Assignments are introduced with the *set* keyword.  There are no
+user-defined variables; values can only be assigned to variables
+attached to backend, request or document objects.  Most of these are
+typed, and the values assigned to them must have a compatible unit
+suffix.
+
+You can use the *set* keyword to arbitrary HTTP headers. You can
+remove headers with the *remove* or *unset* keywords, which are
+synonym.
+
+You can use the *rollback* keyword to revert any changes to req at
+any time.
+
+The *synthetic* keyword is used to produce a synthetic response
+body in vcl_error. It takes a single string as argument.
+
+You can force a crash of the client process with the *panic* keyword.
+*panic* takes a string as argument.
+
+The ``return(action)`` keyword terminates the subroutine. *action* can be,
+depending on context one of
+
+* deliver
+* error
+* fetch
+* hash
+* hit_for_pass
+* lookup
+* ok
+* pass
+* pipe
+* restart
+
+Please see the list of subroutines to see what return actions are
+available where.
+
+VCL has if tests, but no loops.
+
+The contents of another VCL file may be inserted at any point in the
+code by using the *include* keyword followed by the name of the other
+file as a quoted string.

doc/sphinx/reference/vcl.rst

@@ -27,117 +27,11 @@ When a new configuration is loaded, the varnishd management process
 translates the VCL code to C and compiles it to a shared object which
 is then dynamically linked into the server process.
 
-SYNTAX
-======
+.. include:: ../include/vcl-syntax.rst
 
-The VCL syntax is very simple, and deliberately similar to C and Perl.
-Blocks are delimited by curly braces, statements end with semicolons,
-and comments may be written as in C, C++ or Perl according to your own
-preferences.
+.. include:: ../include/vcl-backends.rst
 
-In addition to the C-like assignment (=), comparison (==, !=) and
-boolean (!, && and \|\|) operators, VCL supports both regular
-expression and ACL matching using the ~ and the !~ operators.
-
-Basic strings are enclosed in " ... ", and may not contain newlines.
-
-Long strings are enclosed in {" ... "}. They may contain any
-character including ", newline and other control characters except
-for the NUL (0x00) character.
-
-Unlike C and Perl, the backslash (\) character has no special meaning
-in strings in VCL, so it can be freely used in regular expressions
-without doubling.
-
-Strings are concatenated using the '+' operator. 
-
-Assignments are introduced with the *set* keyword.  There are no
-user-defined variables; values can only be assigned to variables
-attached to backend, request or document objects.  Most of these are
-typed, and the values assigned to them must have a compatible unit
-suffix.
-
-You can use the *set* keyword to arbitrary HTTP headers. You can
-remove headers with the *remove* or *unset* keywords, which are
-synonym.
-
-You can use the *rollback* keyword to revert any changes to req at
-any time.
-
-The *synthetic* keyword is used to produce a synthetic response
-body in vcl_error. It takes a single string as argument.
-
-You can force a crash of the client process with the *panic* keyword.
-*panic* takes a string as argument.
-
-The ``return(action)`` keyword terminates the subroutine. *action* can be,
-depending on context one of
-
-* deliver
-* error
-* fetch
-* hash
-* hit_for_pass
-* lookup
-* ok
-* pass
-* pipe
-* restart
-
-Please see the list of subroutines to see what return actions are
-available where.
-
-VCL has if tests, but no loops.
-
-The contents of another VCL file may be inserted at any point in the
-code by using the *include* keyword followed by the name of the other
-file as a quoted string.
-
-Backend declarations
---------------------
-
-A backend declaration creates and initializes a named backend object:
-::
-
-  backend www {
-    .host = "www.example.com";
-    .port = "http";
-  }
-
-The backend object can later be used to select a backend at request time:
-::
-
-  if (req.http.host ~ "(?i)^(www.)?example.com$") {
-    set req.backend = www;
-  }
-
-To avoid overloading backend servers, .max_connections can be set to
-limit the maximum number of concurrent backend connections.
-
-The timeout parameters can be overridden in the backend declaration.
-The timeout parameters are .connect_timeout for the time to wait for a
-backend connection, .first_byte_timeout for the time to wait for the
-first byte from the backend and .between_bytes_timeout for time to
-wait between each received byte.
-
-These can be set in the declaration like this:
-::
-
-  backend www {
-    .host = "www.example.com";
-    .port = "http";
-    .connect_timeout = 1s;
-    .first_byte_timeout = 5s;
-    .between_bytes_timeout = 2s;
-  }
-
-To mark a backend as unhealthy after number of items have been added
-to its saintmode list ``.saintmode_threshold`` can be set to the maximum
-list size. Setting a value of 0 disables saint mode checking entirely
-for that backend.  The value in the backend declaration overrides the
-parameter.
-
-.. _reference-vcl-director:
+.. _ref-vcl-director:
 
 Directors
 ---------