[master] 54df9be Add strings to syntax doc

[Per Buer]

commit 54df9be7fadb293ddf259a0714750baa43728e76
Author: Per Buer <perbu at varnish-software.com>
Date:   Tue Feb 19 17:24:32 2013 +0100

    Add strings to syntax doc

diff --git a/doc/sphinx/users-guide/vcl-syntax.rst b/doc/sphinx/users-guide/vcl-syntax.rst
index c49ef91..95cb6c6 100644
--- a/doc/sphinx/users-guide/vcl-syntax.rst
+++ b/doc/sphinx/users-guide/vcl-syntax.rst
@@ -13,11 +13,37 @@ Note that VCL doesn't contain any loops or jump statements.
 Strings
 ~~~~~~~
 
+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. If you really want NUL characters in a string there
+is a VMOD that makes it possible to create such strings.
 
 
 Access control lists (ACLs)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+An ACL declaration creates and initializes a named access control list
+which can later be used to match client addresses::
+
+       acl local {
+         "localhost";         // myself
+         "192.0.2.0"/24;      // and everyone on the local network
+         ! "192.0.2.23";      // except for the dialin router
+       }
+
+If an ACL entry specifies a host name which Varnish is unable to
+resolve, it will match any address it is compared to.  Consequently,
+if it is preceded by a negation mark, it will reject any address it is
+compared to, which may not be what you intended.  If the entry is
+enclosed in parentheses, however, it will simply be ignored.
+
+To match an IP address against an ACL, simply use the match operator::
+
+       if (client.ip ~ local) {
+         return (pipe);
+       }
 
 Operators
 ~~~~~~~~~
@@ -43,3 +69,23 @@ down for, uhm, examples.
 ||
  Logical *or*
 
+
+Subroutines
+~~~~~~~~~~~
+
+A subroutine is used to group code for legibility or reusability:
+::
+  
+  sub pipe_if_local {
+    if (client.ip ~ local) {
+      return (pipe);
+    }
+  }
+
+Subroutines in VCL do not take arguments, nor do they return values.
+
+To call a subroutine, use the call keyword followed by the subroutine's name:
+
+call pipe_if_local;
+
+Varnish has quite a few built in subroutines that are called for each transaction as it flows through Varnish. See :ref:`vcl-built-in-subs`.