[prev in list] [next in list] [prev in thread] [next in thread] 

List:       php-doc-cvs
Subject:    [DOC-CVS] =?utf-8?q?svn:_/phpdoc/en/trunk/reference/strings/functions/_html-entity-decode.xml_htmlsp
From:       Gustavo_André_dos_Santos_Lopes <cataphract () php ! net>
Date:       2012-06-21 13:17:23
Message-ID: svn-cataphract-1340284643-326281-1640099501 () svn ! php ! net
[Download RAW message or body]

cataphract                               Thu, 21 Jun 2012 13:17:23 +0000

Revision: http://svn.php.net/viewvc?view=revision&revision=326281

Log:
- Improve htmlspecialchars() and html_entity_decode() docs.

Changed paths:
    U   phpdoc/en/trunk/reference/strings/functions/html-entity-decode.xml
    U   phpdoc/en/trunk/reference/strings/functions/htmlspecialchars.xml

Modified: phpdoc/en/trunk/reference/strings/functions/html-entity-decode.xml
===================================================================
--- phpdoc/en/trunk/reference/strings/functions/html-entity-decode.xml	2012-06-21 \
                12:51:37 UTC (rev 326280)
+++ phpdoc/en/trunk/reference/strings/functions/html-entity-decode.xml	2012-06-21 \
13:17:23 UTC (rev 326281) @@ -19,6 +19,14 @@
    <function>htmlentities</function> in that it converts all HTML entities
    in the <parameter>string</parameter> to their applicable characters.
   </para>
+  <para>
+   More precisely, this function decodes all the entities (including all numeric
+   entities) that a) are necessarily valid for the chosen document type — i.e.,
+   for XML, this function does not decode named entities that might be defined
+   in some DTD — and b) whose character or characters are in the coded character
+   set associated with the chosen encoding and are permitted in the chosen
+   document type. All other entities are left as is.
+  </para>
  </refsect1>

  <refsect1 role="parameters">

Modified: phpdoc/en/trunk/reference/strings/functions/htmlspecialchars.xml
===================================================================
--- phpdoc/en/trunk/reference/strings/functions/htmlspecialchars.xml	2012-06-21 \
                12:51:37 UTC (rev 326280)
+++ phpdoc/en/trunk/reference/strings/functions/htmlspecialchars.xml	2012-06-21 \
13:17:23 UTC (rev 326281) @@ -19,22 +19,20 @@
    Certain characters have special significance in HTML, and should
    be represented by HTML entities if they are to preserve their
    meanings. This function returns a string with these
-   conversions made. If you require all HTML
-   character entities to be translated, use
-   <function>htmlentities</function> instead.
+   conversions made. If you require all input substrings that have associated
+   named entities to be translated, use <function>htmlentities</function>
+   instead.
   </para>
   <para>
-   Calling <function>htmlspecialchars</function> is sufficient if the encoding
-   supports all characters in the input string (such us UTF-8 but also
-   ISO-8859-1 on ISO-8859-1 only input).
-   <function>htmlentities</function> needs to be called only if the output
-   encoding doesn't support all characters in the input string.
+   If the input string passed to this function and the final document share the
+   same character set, this function is sufficient to prepare input for
+   inclusion in most contexts of an HTML document. If, however, the input can
+   represent characters that are not coded in the final document character set
+   and you wish to retain those characters (as numeric or named entities),
+   both this function and <function>htmlentities</function> (which only encodes
+   substrings that have named entity equivalents) may be insufficient.
+   You may have to use <function>mb_encode_numericentity</function> instead.
   </para>
-  <simpara>
-   This function is useful in preventing user-supplied text from
-   containing HTML markup, such as in a message board or guest book
-   application.
-  </simpara>
   <para>
    The translations performed are:
    <itemizedlist>
@@ -51,8 +49,8 @@
     </listitem>
     <listitem>
      <simpara>
-      &quot;&#039;&quot; (single quote) becomes '&amp;#039;' only when
-      <constant>ENT_QUOTES</constant> is set.
+      &quot;&#039;&quot; (single quote) becomes '&amp;#039;' (or &amp;apos;)
+      only when <constant>ENT_QUOTES</constant> is set.
      </simpara>
     </listitem>
     <listitem>



-- 
PHP Documentation Commits Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php

[prev in list] [next in list] [prev in thread] [next in thread]