[master] a057cfa Try to split out small chunks of man vcl into separate bitsize files for reuse in users guide
Per Buer
perbu at varnish-cache.org
Sun Sep 9 10:29:41 CEST 2012
commit a057cfa7ce0a4199add3118fe2c8ed440753bb17
Author: Per Buer <per.buer at gmail.com>
Date: Sun Sep 9 10:29:40 2012 +0200
Try to split out small chunks of man vcl into separate bitsize files for reuse in users guide
diff --git a/doc/sphinx/include/vcl-backends.rst b/doc/sphinx/include/vcl-backends.rst
new file mode 100644
index 0000000..0290bf7
--- /dev/null
+++ b/doc/sphinx/include/vcl-backends.rst
@@ -0,0 +1,44 @@
+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.
+
diff --git a/doc/sphinx/include/vcl-syntax.rst b/doc/sphinx/include/vcl-syntax.rst
new file mode 100644
index 0000000..441aa06
--- /dev/null
+++ b/doc/sphinx/include/vcl-syntax.rst
@@ -0,0 +1,65 @@
+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.
diff --git a/doc/sphinx/reference/vcl.rst b/doc/sphinx/reference/vcl.rst
index 8d6ed9c..772e696 100644
--- a/doc/sphinx/reference/vcl.rst
+++ b/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
---------
More information about the varnish-commit
mailing list