[master] 4af8328 Reorganize the syntax description in varnish-cli(7)

[Dridi Boukelmoune]

commit 4af8328933cf63c54ba5c1766a049ff9a6b0d40d
Author: Dridi Boukelmoune <dridi.boukelmoune at gmail.com>
Date:   Tue Nov 8 15:21:57 2016 +0100

    Reorganize the syntax description in varnish-cli(7)
    
    Ramp up from simple tokens to here documents.

diff --git a/doc/sphinx/reference/varnish-cli.rst b/doc/sphinx/reference/varnish-cli.rst
index fda59c9..c0c911a 100644
--- a/doc/sphinx/reference/varnish-cli.rst
+++ b/doc/sphinx/reference/varnish-cli.rst
@@ -51,30 +51,49 @@ that service. Please see :ref:`varnishd(1)` for details.
 Syntax
 ------
 
-Commands are usually terminated with a newline. Long command can be
-entered using shell-style *here document* (here-document or heredoc).
-The format of here document is::
+The Varnish CLI is similar to another command line interface, the Bourne
+Shell. Commands are usually terminated with a newline, and they may take
+arguments. The command and its arguments are *tokenized* before parsing,
+and as such arguments containing must must be enclosed in double quotes.
+
+It means that command parsing of
+
+::
+
+   help banner
+
+is equivalent to
+
+::
+
+   "help" banner
+
+because the double quotes only indicate the boundaries of the ``help``
+token.
+
+Within double quotes you can escape characters with \\ (backslash). The \\n,
+\\r, and \\t get translated to newlines, carriage returns, an tabs.  Double
+quotes and backslashes themselves can be escaped with \\" and \\\\
+respectively.
+
+To enter characters in octals use the \\nnn syntax. Hexadecimals can
+be entered with the \\xnn syntax.
+
+Commands may not end with a newline when a shell-style *here document*
+(here-document or heredoc) is used. The format of a here document is::
 
    << word
 	here document
    word
 
 *word* can be any continuous string chosen to make sure it doesn't appear
-naturally in the following *here document*. Often EOF or END is used.
+naturally in the following *here document*. Traditionally EOF or END is
+used.
 
 When using the here document style of input there are no restrictions
 on length. When using newline-terminated commands maximum length is
 limited by the varnishd parameter *cli_buffer*.
 
-When commands are newline terminated they get *tokenized* before
-parsing so if you have significant spaces enclose your strings in
-double quotes. Within the quotes you can escape characters with
-\\. The \n, \r and \t get translated to newlines, carriage returns and
-tabs. Double quotes themselves can be escaped with a backslash.
-
-To enter characters in octals use the \\nnn syntax. Hexadecimals can
-be entered with the \\xnn syntax.
-
 Commands
 --------