complete and fix the ban syntax documentation

doc/sphinx/reference/vcl.rst

@@ -388,21 +388,58 @@ Functions
 
 The following built-in functions are available:
 
-ban(expression)
-  Invalidates all objects in cache that match the expression with the
+.. _vcl(7)_ban:
+
+ban(STRING)
+~~~~~~~~~~~
+
+  Invalidates all objects in cache that match the given expression with the
   ban mechanism.
 
+  The format of `STRING` is::
+
+	<field> <operator> <arg> [&& <field> <oper> <arg> ...]
+
+  * `<field>`:
+
+    * ``req.url``: The request url
+    * ``req.http.*``: Any request header
+    * ``obj.status``: The cache object status
+    * ``obj.http.*``: Any cache object header
+
+  * `<operator>`:
+
+    * ``==``: `<field>` and `<arg>` are equal strings (case sensitive)
+    * ``!=``: `<field>` and `<arg>` are unequal strings (case sensitive)
+    * ``~``: `<field>` matches the regular expression `<arg>`
+    * ``!~``:`<field>` does not match the regular expression `<arg>`
+
+  * `<arg>`: Either a literal string or a regular expression. Note
+    that `<arg>` does not use any of the string delimiters like ``"``
+    or ``{"..."}`` used elsewhere in varnish. To match against strings
+    containing whitespace, regular expressions containing ``\s`` can
+    be used.
+
+  Expressions can be chained using the `and` operator ``&&``. For `or`
+  semantics, use several bans.
+
 hash_data(input)
+~~~~~~~~~~~~~~~~
+
   Adds an input to the hash input. In the built-in VCL hash_data()
   is called on the host and URL of the *request*. Available in vcl_hash.
 
 synthetic(STRING)
+~~~~~~~~~~~~~~~~~
+
   Prepare a synthetic response body containing the STRING. Available in
   vcl_synth and vcl_backend_error.
 
 .. list above comes from struct action_table[] in vcc_action.c.
 
 regsub(str, regex, sub)
+~~~~~~~~~~~~~~~~~~~~~~~
+
   Returns a copy of str with the first occurrence of the regular
   expression regex replaced with sub. Within sub, \\0 (which can
   also be spelled \\&) is replaced with the entire matched string,
@@ -410,6 +447,7 @@ regsub(str, regex, sub)
   matched string.
 
 regsuball(str, regex, sub)
+~~~~~~~~~~~~~~~~~~~~~~~~~~
   As regsub() but this replaces all occurrences.
 
 .. regsub* is in vcc_expr.c

doc/sphinx/users-guide/purging.rst

@@ -71,11 +71,14 @@ prevent new content from entering the cache or being served.
 
 Support for bans is built into Varnish and available in the CLI
 interface. To ban every png object belonging on example.com, issue
-the following command::
+the following command from the shell::
 
-  ban req.http.host == "example.com" && req.url ~ "\\.png$"
+  varnishadm ban req.http.host == example.com '&&' req.url '~' '\\.png$'
 
-Quite powerful, really.
+See :ref:`vcl(7)_ban` for details on the syntax of ban expressions. In
+particular, note that in the example given above, the quotes are
+required for execution from the shell and escaping the backslash is in
+the regular expression is required by the varnish cli interface.
 
 Bans are checked when we hit an object in the cache, but before we
 deliver it. *An object is only checked against newer bans*.

include/tbl/cli_cmds.h

@@ -44,7 +44,7 @@ CLI_CMD(BAN,
 	"ban",
 	"ban <field> <operator> <arg> [&& <field> <oper> <arg> ...]",
 	"Mark obsolete all objects where all the conditions match.",
-	"",
+	"See :ref:`vcl(7)_ban` for details",
 	3, -1
 )