Add a separate example section for escaping of characters

See also merged PR php/php-src#7420 (php/php-src@d3a6054)

Closes GH-898.

Author: dryabov

reference/filesystem/functions/parse-ini-file.xml

@@ -227,7 +227,7 @@ echo '(loaded) magic_quotes_gpc = ' . yesno(get_cfg_var('magic_quotes_gpc')) . P
   </para>
   <para>
    <example>
-    <title>value interpolation</title>
+    <title>Value Interpolation</title>
     <para>
      In addition to evaluating constants, certain characters have special meaning in an ini value.
      Additionally, environment variables and previously defined values may be read using
@@ -250,17 +250,66 @@ negative_two = ~1
 ; () is used for grouping
 seven = (8|7)&(6|5)
 
-; \ is used to escape a value.
-newline_is = "\\n" ; results in the string "\n", not a newline character.
-with quotes = "She said \"Exactly my point\"." ; Results in a string with quote marks in it.
-
 path = ${PATH}
 also_five = ${five}
 
 ]]>
     </programlisting>
    </example>
   </para>
+  <para>
+   <example>
+    <title>Escaping Characters</title>
+    <para>
+     Some characters have special meaning in double-quoted strings and must be escaped by the backslash prefix.
+     First of all, these are the double quote <code>"</code> as the boundary marker, and the backslash <code>\</code> itself
+     (if followed by one of the special characters):
+    </para>
+    <programlisting>
+<![CDATA[
+quoted = "She said \"Exactly my point\"." ; Results in a string with quote marks in it.
+hint = "Use \\\" to escape double quote" ; Results in: Use \" to escape double quote
+]]>
+    </programlisting>
+    <para>
+     There is an exception made for Windows-like paths: it's possible to not escape trailing backslash
+     if the quoted string is directly followed by a linebreak:
+    </para>
+    <programlisting>
+<![CDATA[
+save_path = "C:\Temp\"
+]]>
+    </programlisting>
+    <para>
+     If one does need to escape double quote followed by linebreak in a multiline value,
+     it's possible to use value concatenation in the following way
+     (there is one double-quoted string directly followed by another one):
+    </para>
+    <programlisting>
+<![CDATA[
+long_text = "Lorem \"ipsum\"""
+ dolor" ; Results in: Lorem "ipsum"\n dolor
+]]>
+    </programlisting>
+    <para>
+     Another character with special meaning is <code>$</code> (the dollar sign).
+     It must be escaped if followed by the open curly brace:
+    </para>
+    <programlisting>
+<![CDATA[
+code = "\${test}"
+]]>
+    </programlisting>
+    <para>
+     Escaping characters is not supported in the <constant>INI_SCANNER_RAW</constant> mode
+     (in this mode all characters are processed "as is").
+    </para>
+    <para>
+     Note that the ini parser doesn't support standard escape sequences (<code>\n</code>, <code>\t</code>, etc.).
+     If necessary, post-process the result of <function>parse_ini_file</function> with <function>stripcslashes</function> function.
+    </para>
+   </example>
+  </para>
  </refsect1>
 
  <refsect1 role="notes">