add encoding directive to declare documentation

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@268981 c90b9560-bf6c-de11-be94-00142212c4b1

language/control-structures.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.170 $ -->
+<!-- $Revision: 1.171 $ -->
  <chapter xml:id="language.control-structures" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
   <title>Control Structures</title>
 
@@ -1171,12 +1171,20 @@ declare (directive)
     The <literal>directive</literal> section allows the
     behavior of the <literal>declare</literal> block to
     be set.
-    Currently only one directive is recognized: the
-    <literal>ticks</literal> directive. (See below for more
+    Currently only two directives are recognized: the
+    <literal>ticks</literal> directive (See below for more
     information on the
     <link linkend="control-structures.declare.ticks">ticks</link>
-    directive)
+    directive) and the <literal>encoding</literal> directive (See below for more
+    information on the
+    <link linkend="control-structures.declare.encoding">encoding</link>
+    directive).
    </para>
+   <note>
+    <simpara>
+     The encoding directive was added in PHP 5.3.0
+    </simpara>
+   </note>
    <para>
     The <literal>statement</literal> part of the
     <literal>declare</literal> block will be executed - how
@@ -1287,6 +1295,39 @@ print_r(profile(TRUE));
     <function>unregister_tick_function</function>.
    </simpara>
    </sect2>
+   <sect2 xml:id="control-structures.declare.encoding">
+    <title>Encoding</title>
+   <para>
+    <example>
+     <title>Declaring an encoding for the script.</title>
+     <para>
+      A script's encoding can be specified per-script using the encoding directive.
+      <programlisting role="php">
+<![CDATA[
+<?php
+declare(encoding='ISO-8859-1');
+// code here
+?>
+]]>
+      </programlisting>
+     </example>
+    </para>
+
+    <caution>
+     <simpara>
+      When combined with namespaces, the only legal syntax for declare
+      is <literal>declare(encoding='...');</literal> where <literal>...</literal>
+      is the encoding value.  <literal>declare(encoding='...') {}</literal>
+      will result in a parse error when combined with namespaces.
+     </simpara>
+    </caution>
+    <para>
+     The encoding declare value is ignored in PHP 5.3 unless php is compiled with
+     <literal>--enable-zend-multibyte</literal>.  In PHP 6.0, the <literal>encoding</literal>
+     directive will be used to inform the scanner what encoding the file is created in.  Legal
+     values are encoding names such as <literal>UTF-8</literal>.
+    </para>
+   </sect2>
   </sect1>
 
   <sect1 xml:id="function.return">