Add a separate example section for escaping of characters

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

php/doc-en@33225f7

Author: mumumu

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

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: a453c4ff1cac60f674ca6739695c2990e3150e9f Maintainer: hirokawa Status: ready -->
+<!-- EN-Revision: 33225f7c5759ebd29496e98a55a3e4ba58cb1ac4 Maintainer: hirokawa Status: ready -->
 <!-- CREDITS: shimooka,mumumu -->
 <refentry xml:id="function.parse-ini-file" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
@@ -253,17 +253,71 @@ negative_two = ~1
 ; () はグループ化に使います
 seven = (8|7)&(6|5)
 
-; \ は値のエスケープに使います
-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>文字をエスケープする</title>
+    <para>
+     文字によっては、ダブルクォートで囲まれた文字列の中で特別な意味を持つ場合があり、
+     その場合、バックスラッシュでエスケープしなければなりません。
+     特別な意味を持つのは、文字列の境目の印となるダブルクォート <code>"</code>、
+     および、バックスラッシュ <code>\</code> (この文字の後に特別な文字がひとつ続きます) そのものです。
+    </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>
+     Windows ライクなパスについては例外があります。
+     クォートされた文字列のすぐ後に改行文字が続いた場合、
+     末尾のバックスラッシュはエスケープする必要がないというものです。
+    </para>
+    <programlisting>
+<![CDATA[
+save_path = "C:\Temp\"
+]]>
+    </programlisting>
+    <para>
+     複数行にまたがる値で、改行文字が直後にあるダブルクォート文字をエスケープする必要がある場合、
+     次のようにして値を連結することでそれを実現できます。
+     (ダブルクォートで囲まれた文字列がひとつあり、その直後にもうひとつの文字列が続きます)
+    </para>
+    <programlisting>
+<![CDATA[
+long_text = "Lorem \"ipsum\"""
+ dolor" ; Results in: Lorem "ipsum"\n dolor
+]]>
+    </programlisting>
+    <para>
+     特別な意味を持つ別の文字として、<code>$</code> (ドル記号) があります。
+     これは、開き括弧が続く場合、エスケープしなければいけません:
+    </para>
+    <programlisting>
+<![CDATA[
+code = "\${test}"
+]]>
+    </programlisting>
+    <para>
+     文字のエスケープは、
+     <constant>INI_SCANNER_RAW</constant> モードではサポートされていません。
+     (このモードでは、全ての文字が "そのまま" 処理されます)
+    </para>
+    <para>
+     ini ファイルのパーサーは、標準的なエスケープシーケンス
+     (<code>\n</code>, <code>\t</code>, など) をサポートしていないことに注意して下さい。
+     そのサポートが必要な場合、<function>parse_ini_file</function> の処理結果を
+     <function>stripcslashes</function> で処理するようにして下さい。
+    </para>
+   </example>
+  </para>
  </refsect1>
 
  <refsect1 role="notes">