[master] 160b2e0 Split the examples into sep files

[Per Buer]

commit 160b2e08c9f993454b667782587176abf0f04ecd
Author: Per Buer <perbu at varnish-software.com>
Date:   Tue Feb 19 17:24:00 2013 +0100

    Split the examples into sep files

diff --git a/doc/sphinx/users-guide/vcl-example1-manipulating-headers.rst b/doc/sphinx/users-guide/vcl-example1-manipulating-headers.rst
new file mode 100644
index 0000000..35dcb1e
--- /dev/null
+++ b/doc/sphinx/users-guide/vcl-example1-manipulating-headers.rst
@@ -0,0 +1,21 @@
+
+
+
+Manipulating request headers in VCL
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Lets say we want to remove the cookie for all objects in the /images
+directory of our web server::
+
+  sub vcl_recv {
+    if (req.url ~ "^/images") {
+      unset req.http.cookie;
+    }
+  }
+
+Now, when the request is handled to the backend server there will be
+no cookie header. The interesting line is the one with the
+if-statement. It matches the URL, taken from the request object, and
+matches it against the regular expression. Note the match operator. If
+it matches the Cookie: header of the request is unset (deleted). 
+
diff --git a/doc/sphinx/users-guide/vcl-example2-manipulating-responses.rst b/doc/sphinx/users-guide/vcl-example2-manipulating-responses.rst
new file mode 100644
index 0000000..7362789
--- /dev/null
+++ b/doc/sphinx/users-guide/vcl-example2-manipulating-responses.rst
@@ -0,0 +1,19 @@
+
+
+Altering the backend response
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Here we override the TTL of a object comming from the backend if it
+matches certain criteria::
+
+  sub vcl_fetch {
+     if (req.url ~ "\.(png|gif|jpg)$") {
+       unset beresp.http.set-cookie;
+       set beresp.ttl = 1h;
+    }
+  }
+
+.. XXX ref hit-for-pass
+
+We also remove any Set-Cookie headers in order to avoid a hit-for-pass
+object to be created.
diff --git a/doc/sphinx/users-guide/vcl-example3-acls.rst b/doc/sphinx/users-guide/vcl-example3-acls.rst
new file mode 100644
index 0000000..3d0226a
--- /dev/null
+++ b/doc/sphinx/users-guide/vcl-example3-acls.rst
@@ -0,0 +1,34 @@
+
+ACLs
+~~~~
+
+You create a named access control list with the *acl* keyword. You can match
+the IP address of the client against an ACL with the match operator.::
+
+  # Who is allowed to purge....
+  acl local {
+      "localhost";
+      "192.168.1.0"/24; /* and everyone on the local network */
+      ! "192.168.1.23"; /* except for the dialin router */
+  }
+  
+  sub vcl_recv {
+    if (req.method == "PURGE") {
+      if (client.ip ~ local) {
+         return(lookup);
+      }
+    } 
+  }
+  
+  sub vcl_hit {
+     if (req.method == "PURGE") {
+       set obj.ttl = 0s;
+       error 200 "Purged.";
+      }
+  }
+
+  sub vcl_miss {
+    if (req.method == "PURGE") {
+      error 404 "Not in cache.";
+    }
+  }
diff --git a/doc/sphinx/users-guide/vcl-examples.rst b/doc/sphinx/users-guide/vcl-examples.rst
index ea78b9b..fdd892a 100644
--- a/doc/sphinx/users-guide/vcl-examples.rst
+++ b/doc/sphinx/users-guide/vcl-examples.rst
@@ -1,65 +1,14 @@
-Example 1 - manipulating headers
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Lets say we want to remove the cookie for all objects in the /images
-directory of our web server::
+VCL Examples
+------------
 
-  sub vcl_recv {
-    if (req.url ~ "^/images") {
-      unset req.http.cookie;
-    }
-  }
+These are a short collection of examples that showcase some of the
+capabilites of the VCL language.
 
-Now, when the request is handled to the backend server there will be
-no cookie header. The interesting line is the one with the
-if-statement. It matches the URL, taken from the request object, and
-matches it against the regular expression. Note the match operator. If
-it matches the Cookie: header of the request is unset (deleted). 
+.. toctree::
 
-Example 2 - manipulating beresp
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+  vcl-example1-manipulating-headers
+  vcl-example2-manipulating-responses
+  vcl-example3-acls
 
-Here we override the TTL of a object comming from the backend if it
-matches certain criteria::
-
-  sub vcl_fetch {
-     if (req.url ~ "\.(png|gif|jpg)$") {
-       unset beresp.http.set-cookie;
-       set beresp.ttl = 1h;
-    }
-  }
-
-Example 3 - ACLs
-~~~~~~~~~~~~~~~~
-
-You create a named access control list with the *acl* keyword. You can match
-the IP address of the client against an ACL with the match operator.::
-
-  # Who is allowed to purge....
-  acl local {
-      "localhost";
-      "192.168.1.0"/24; /* and everyone on the local network */
-      ! "192.168.1.23"; /* except for the dialin router */
-  }
-  
-  sub vcl_recv {
-    if (req.method == "PURGE") {
-      if (client.ip ~ local) {
-         return(lookup);
-      }
-    } 
-  }
-  
-  sub vcl_hit {
-     if (req.method == "PURGE") {
-       set obj.ttl = 0s;
-       error 200 "Purged.";
-      }
-  }
-
-  sub vcl_miss {
-    if (req.method == "PURGE") {
-      error 404 "Not in cache.";
-    }
-  }