From e07570b4630b756bd7a33729f8ad803f89029e12 Mon Sep 17 00:00:00 2001
From: Nikita Popov <nikic@php.net>
Date: Fri, 27 Jan 2012 20:42:48 +0000
Subject: [PATCH] Minor improvements to htmlspecialchars() and htmlentities()
 docs

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@322868 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/strings/functions/htmlentities.xml  | 35 +++++++++----------
 .../strings/functions/htmlspecialchars.xml    | 20 ++++-------
 2 files changed, 22 insertions(+), 33 deletions(-)

diff --git a/reference/strings/functions/htmlentities.xml b/reference/strings/functions/htmlentities.xml
index 13d4e190b1..dce3679c41 100644
--- a/reference/strings/functions/htmlentities.xml
+++ b/reference/strings/functions/htmlentities.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.htmlentities">
+<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.htmlentities" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>htmlentities</refname>
   <refpurpose>Convert all applicable characters to HTML entities</refpurpose>
@@ -21,7 +21,7 @@
    have HTML character entity equivalents are translated into these entities.
   </para>
   <para>
-   If you're wanting to decode instead (the reverse) you can use
+   If you want to decode instead (the reverse) you can use
    <function>html_entity_decode</function>.
   </para>
  </refsect1>
@@ -71,8 +71,8 @@
            <entry><constant>ENT_IGNORE</constant></entry>
            <entry>
             Silently discard invalid code unit sequences instead of returning
-            an empty string. This is provided for backwards compatibility;
-            avoid using it as it may have security implications.
+            an empty string. Using this flag is discouraged as it
+            <link xlink:href="&url.delete.nonchars;">may have security implications</link>.
            </entry>
           </row>
           <row>
@@ -123,14 +123,12 @@
      <term><parameter>charset</parameter></term>
      <listitem>
       <para>
-       Like <function>htmlspecialchars</function>,
-       <function>htmlentities</function> takes an optional third argument
-       <parameter>charset</parameter> which defines character set used in
-       conversion.
-       If omitted, the default value for this argument is ISO-8859-1 in
-       versions of PHP prior to 5.4.0, and UTF-8 from PHP 5.4.0 onwards.
-       Although this argument is technically optional, you are highly
-       encouraged to specify the correct value for your code.
+       Like <function>htmlspecialchars</function>, it takes an optional
+       third argument <parameter>charset</parameter> which defines character
+       set used in conversion.
+       Presently, the ISO-8859-1 character set is used as the default.
+       However, this default is very likely to change in future versions of
+       PHP; the programmer is highly encouraged to specify a value.
       </para>
       &reference.strings.charsets;
      </listitem>
@@ -153,6 +151,12 @@
   <para>
    Returns the encoded string.
   </para>
+  <para>
+   If the input <parameter>string</parameter> contains an invalid code unit
+   sequence within the given <parameter>charset</parameter> an empty string
+   will be returned, unless either the <constant>ENT_IGNORE</constant> or
+   <constant>ENT_SUBSTITUTE</constant> flags are set.
+  </para>
  </refsect1>
 
  <refsect1 role="changelog">
@@ -167,13 +171,6 @@
       </row>
      </thead>
      <tbody>
-      <row>
-       <entry>5.4.0</entry>
-       <entry>
-        The default value for the <parameter>charset</parameter> parameter was
-        changed to UTF-8.
-       </entry>
-      </row>
       <row>
        <entry>5.4.0</entry>
        <entry>
diff --git a/reference/strings/functions/htmlspecialchars.xml b/reference/strings/functions/htmlspecialchars.xml
index b06098cda8..199c1560eb 100644
--- a/reference/strings/functions/htmlspecialchars.xml
+++ b/reference/strings/functions/htmlspecialchars.xml
@@ -108,8 +108,8 @@
            <entry><constant>ENT_IGNORE</constant></entry>
            <entry>
             Silently discard invalid code unit sequences instead of returning
-            an empty string. This is provided for backwards compatibility;
-            avoid using it as it may have security implications.
+            an empty string. Using this flag is discouraged as it
+            <link xlink:href="&url.delete.nonchars;">may have security implications</link>.
            </entry>
           </row>
           <row>
@@ -161,8 +161,7 @@
      <listitem>
       <para>
        Defines character set used in conversion.
-       If omitted, the default value for this argument is ISO-8859-1 in
-       versions of PHP prior to 5.4.0, and UTF-8 from PHP 5.4.0 onwards.
+       The default character set is ISO-8859-1.
       </para>
       <para>
        For the purposes of this function, the charsets
@@ -197,9 +196,9 @@
   </para>
   <para>
    If the input <parameter>string</parameter> contains an invalid code unit
-   sequence within the given <parameter>charset</parameter> and the
-   <constant>ENT_IGNORE</constant> flag is not set, then
-   <function>htmlspecialchars</function> will return an empty string.
+   sequence within the given <parameter>charset</parameter> an empty string
+   will be returned, unless either the <constant>ENT_IGNORE</constant> or
+   <constant>ENT_SUBSTITUTE</constant> flags are set.
   </para>
  </refsect1>
 
@@ -215,13 +214,6 @@
       </row>
      </thead>
      <tbody>
-      <row>
-       <entry>5.4.0</entry>
-       <entry>
-        The default value for the <parameter>charset</parameter> parameter was
-        changed to UTF-8.
-       </entry>
-      </row>
       <row>
        <entry>5.4.0</entry>
        <entry>