Modified the examples for mb_convert_kana, mb_detect_encoding, mb_encode_numericentity (#4510)

Author: SakiTakamachi

reference/mbstring/functions/mb-convert-kana.xml

@@ -200,23 +200,28 @@
 
  <refsect1 role="examples">
   &reftitle.examples;
-  <para>
-   <example>
-    <title><function>mb_convert_kana</function> example</title>
-    <programlisting role="php">
+  <example>
+   <title><function>mb_convert_kana</function> example</title>
+   <programlisting role="php">
 <![CDATA[
 <?php
-/* Convert all "kana" to "zen-kaku" "kata-kana" */
-$str = mb_convert_kana($str, "KVC");
+/* Convert all "han-kaku" "kata-kana" to "zen-kaku" "hira-gana" */
+echo mb_convert_kana('ﾔﾏﾀﾞ ﾊﾅｺ', "HV") . "\n";
 
 /* Convert "han-kaku" "kata-kana" to "zen-kaku" "kata-kana" 
    and "zen-kaku" alphanumeric to "han-kaku" */
-$str = mb_convert_kana($str, "KVa");
+echo mb_convert_kana('ｺｳｻﾞﾊﾞﾝｺﾞｳ ０１２３４５６', "KVa") . "\n";
 ?>
 ]]>
-    </programlisting>
-   </example>
-  </para>
+   </programlisting>
+   &example.outputs;
+   <screen>
+<![CDATA[
+やまだ はなこ
+コウザバンゴウ 0123456
+]]>
+   </screen>
+  </example>
  </refsect1>
 
 </refentry>

reference/mbstring/functions/mb-detect-encoding.xml

@@ -29,6 +29,17 @@
    bytes form a valid string. If the input string contains such a sequence, that
    encoding will be rejected, and the next encoding checked.
   </para>
+
+  <warning>
+   <title>The result is not accurate</title>
+   <para>
+    The name of this function is misleading, it performs "guessing" rather than "detection".
+   </para>
+   <para>
+    The guesses are far from accurate, and therefore you cannot use this function to accurately
+    detect the correct character encoding.
+   </para>
+  </warning>
  </refsect1>
 
  <refsect1 role="parameters">
@@ -121,25 +132,37 @@
     <programlisting role="php">
 <![CDATA[
 <?php
+
+$str = "\x95\xB6\x8E\x9A\x83\x52\x81\x5B\x83\x68";
+
 // Detect character encoding with current detect_order
-echo mb_detect_encoding($str);
+var_dump(mb_detect_encoding($str));
 
 // "auto" is expanded according to mbstring.language
-echo mb_detect_encoding($str, "auto");
+var_dump(mb_detect_encoding($str, "auto"));
 
 // Specify "encodings" parameter by list separated by comma
-echo mb_detect_encoding($str, "JIS, eucjp-win, sjis-win");
+var_dump(mb_detect_encoding($str, "JIS, eucjp-win, sjis-win"));
 
 // Use array to specify "encodings" parameter
 $encodings = [
   "ASCII",
   "JIS",
   "EUC-JP"
 ];
-echo mb_detect_encoding($str, $encodings);
+var_dump(mb_detect_encoding($str, $encodings));
 ?>
 ]]>
     </programlisting>
+    &example.outputs;
+    <screen>
+<![CDATA[
+string(5) "ASCII"
+string(5) "ASCII"
+string(8) "SJIS-win"
+string(5) "ASCII"
+]]>
+    </screen>
    </example>
   </para>
   <para>

reference/mbstring/functions/mb-encode-numericentity.xml

@@ -130,27 +130,29 @@ $convmap = array (
     <programlisting role="php">
 <![CDATA[
 <?php
-/* Convert Left side of ISO-8859-1 to HTML numeric character reference */
-$convmap = array(0x80, 0xff, 0, 0xff);
-$str = mb_encode_numericentity($str, $convmap, "ISO-8859-1");
 
-/* Convert user defined SJIS-win code in block 95-104 to numeric
-   string reference */
-$convmap = array(
-       0xe000, 0xe03e, 0x1040, 0xffff,
-       0xe03f, 0xe0bb, 0x1041, 0xffff,
-       0xe0bc, 0xe0fa, 0x1084, 0xffff,
-       0xe0fb, 0xe177, 0x1085, 0xffff,
-       0xe178, 0xe1b6, 0x10c8, 0xffff,
-       0xe1b7, 0xe233, 0x10c9, 0xffff,
-       0xe234, 0xe272, 0x110c, 0xffff,
-       0xe273, 0xe2ef, 0x110d, 0xffff,
-       0xe2f0, 0xe32e, 0x1150, 0xffff,
-       0xe32f, 0xe3ab, 0x1151, 0xffff );
-$str = mb_encode_numericentity($str, $convmap, "sjis-win");
+$str = "aAæÆあア𩸽";
+
+/* Convert all UTF8 characters up to 4 bytes to HTML numeric character reference */
+$convmap = [0, 0x1FFFFF, 0, 0x10FFFF];
+var_dump(mb_encode_numericentity($str, $convmap, "utf8"));
+
+/* Converts only 2-byte and 4-byte UTF8 characters to HTML numeric character reference */
+$convmap = [
+    0x80, 0x7FF, 0, 0x10FFFF,
+    0x10000, 0x1FFFFF, 0, 0x10FFFF,
+];
+var_dump(mb_encode_numericentity($str, $convmap, "utf8"));
 ?>
 ]]>
     </programlisting>
+   &example.outputs;
+   <screen>
+<![CDATA[
+string(46) "&#97;&#65;&#230;&#198;&#12354;&#12450;&#40509;"
+string(28) "aA&#230;&#198;あア&#40509;"
+]]>
+   </screen>
    </example>
   </para>
  </refsect1>