[4.1] 055551d Reorganize the syntax description in varnish-cli(7)

[Dridi Boukelmoune]

commit 055551d091f83a9ecc65f18dfc3cea40497304e6
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.
    
    Conflicts:
    	doc/sphinx/reference/varnish-cli.rst

diff --git a/doc/sphinx/reference/varnish-cli.rst b/doc/sphinx/reference/varnish-cli.rst
index 7dcc9a4..3e785d4 100644
--- a/doc/sphinx/reference/varnish-cli.rst
+++ b/doc/sphinx/reference/varnish-cli.rst
@@ -50,30 +50,49 @@ that service. Please see :ref:`varnishd(1)` for details.
 Syntax
 ------
 
-Commands are usually terminated with a newline. Long command can be
-entered using sh style *here documents*. The format of here-documents
-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*.
+*word* can be any continuous string chosen to make sure it doesn't appear
+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
 --------