[5105] Updated examples and User's Guide to match double escapes.

doc/examples/kea4/multiple-options.json

@@ -47,11 +47,13 @@
          },
          {
              // String options that have a comma in their values need to have
-             // it escaped (i.e. each comma is predeced by a backslash). That's
+             // it escaped (i.e. each comma is predeced by two backslashes). That's
              // because commas are reserved for separating fields in compound
-             // options.
+             // options. At the same time, we need to be conformant with JSON spec,
+             // that does not allow "\,". Therefore the slightly uncommon double
+             // backslashes natation is needed.
              "name": "boot-file-name",
-             "data": "EST5EDT4\,M3.2.0/02:00\,M11.1.0/02:00"
+             "data": "EST5EDT4\\,M3.2.0/02:00\\,M11.1.0/02:00"
          }
        ]
     } 

doc/examples/kea6/multiple-options.json

@@ -52,9 +52,11 @@
         },
         {
             // String options that have a comma in their values need to have
-            // it escaped (i.e. each comma is predeced by a backslash). That's
+            // it escaped (i.e. each comma is predeced by two backslashes). That's
             // because commas are reserved for separating fields in compound
-            // options.
+            // options. At the same time, we need to be conformant with JSON spec,
+            // that does not allow "\,". Therefore the slightly uncommon double
+            // backslashes natation is needed.
             "name": "new-posix-timezone",
             "data": "EST5EDT4\,M3.2.0/02:00\,M11.1.0/02:00"
         }

doc/guide/dhcp4-srv.xml

@@ -1018,8 +1018,9 @@ temporarily override a list of interface names and listen on all interfaces.
       </para>
 
       <para>When the data field is a string, and that string contains the comma
-      (,; U+002C) character, the comma must be escaped with a reverse solidus
-      character (\; U+005C). For example, the string
+      (,; U+002C) character, the comma must be escaped with a double reverse solidus
+      character (\; U+005C). This double escape is required, because a
+      single escape (\,) would make the JSON invalid. For example, the string
       &quot;foo,bar&quot; would be represented as:
       <screen>
 "Dhcp4": {
@@ -1030,7 +1031,7 @@ temporarily override a list of interface names and listen on all interfaces.
                     <userinput>"option-data": [
                         {
                             "name": "boot-file-name",
-                            "data": "foo\,bar"
+                            "data": "foo\\,bar"
                         }
                     ]</userinput>
                 },

doc/guide/dhcp6-srv.xml

@@ -1050,9 +1050,12 @@ temporarily override a list of interface names and listen on all interfaces.
       which was not assigned by IANA) are listed in
       <xref linkend="dhcp6-exp-options-list"/>.
     </para>
-    <para>When the data field is a string, and that string contains the comma
-    (,; U+002C) character, the comma must be escaped with a reverse solidus
-    character (\; U+005C). For example, the string &quot;EST5EDT4,M3.2.0/02:00,M11.1.0/02:00&quot; would be
+    <para>When the data field is a string, and that string contains
+    the comma (,; U+002C) character, the comma must be escaped with a
+    reverse solidus character (\; U+005C). This double escape is
+    required, because a single escape (\,) would make the JSON
+    invalid. For example, the string
+    &quot;EST5EDT4,M3.2.0/02:00,M11.1.0/02:00&quot; would be
     represented as:
 <screen>
 "Dhcp6": {