[5.2] 80435af Documentation

[PÃ¥l Hermunn Johansen]

commit 80435af9bcab570f5163ec32f1bddae1cba9b93f
Author: Dridi Boukelmoune <dridi.boukelmoune at gmail.com>
Date:   Wed Sep 13 17:40:27 2017 +0200

    Documentation

diff --git a/doc/sphinx/whats-new/upgrading-5.2.rst b/doc/sphinx/whats-new/upgrading-5.2.rst
index 56c925b..00abba5 100644
--- a/doc/sphinx/whats-new/upgrading-5.2.rst
+++ b/doc/sphinx/whats-new/upgrading-5.2.rst
@@ -40,10 +40,37 @@ XXX: headline changes ...
 
 *XXX: the most important changes or additions first*
 
-Stricter checking of VCL symbol names
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Consistent symbol names
+~~~~~~~~~~~~~~~~~~~~~~~
+
+VCL symbols originate from various parts of Varnish: there are built-in
+variables, subroutines, functions, and the free-form headers. Symbols
+may live in a namespace denoted by the ``'.'`` (dot) character as in
+``req.http.Cache-Control``. When you create a VCL label, a new symbol
+becomes available, named after the label. Storage backends always have
+a name, even if you don't specify one, and they can also be accessed in
+VCL: for example ``storage.Transient``.
+
+Because headers and VCL names could contain dashes, while subroutines or
+VMOD objects couldn't, this created an inconsistency. All symbols follow
+the same rules now and must follow the same (case-insensitive) pattern:
+``[a-z][a-z0-9_-]*``.
+
+You can now write code like::
+
+  sub my-sub {
+      new my-obj = my_vmod.my_constuctor(storage.my-store);
+  }
+
+  sub vcl_init {
+      call my-sub;
+  }
+
+As you may notice in the example above, it is not possible yet to have
+dashes in a vmod symbol.
 
-*XXX: TBD by DB*
+Long storage backend names used to be truncated due to a limitation in
+the VSC subsystem, this is no longer the case.
 
 ``req.hash`` and ``bereq.hash``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -127,6 +154,10 @@ Other changes
     ``vcl_path`` parameter if a relative file name is used, see
     :ref:`varnishd(1)` and :ref:`ref_param_vcl_path`.
 
+  * The ``-a`` option can now take a name, otherwise a default one
+    is selected to name the listen address. It may become accessible
+    in VCL in the future.
+
 * ``varnishstat(1)``:
 
   * In curses mode, the top two lines showing uptimes for the
@@ -160,6 +191,11 @@ Other changes
 
     See :ref:`vsl(7)`.
 
+  * The ``SessOpen`` log record displays the name of the listen address
+    instead of the endpoint in its 3rd field.
+
+    See :ref:`vsl(7)`.
+
 * ``varnishtest(1)`` and ``vtc(7)``:
 
   * *XXX: changes in test scripting or test code, for example due to VMOD vtc?*