Update xml

php · Oct 11, 2023 · 1b148ed · 1b148ed
1 parent 8a2f288
commit 1b148ed
Show file tree

Hide file tree

Showing 19 changed files with 215 additions and 355 deletions.
diff --git a/language-snippets.ent b/language-snippets.ent
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 71b1e926631d5f5bec9b2e2685553453349ae799 Maintainer: Gregory Status: ready -->
+<!-- EN-Revision: 5a14f904d231d294e2e5b4fb5d2fc4d2fd9eddee Maintainer: Gregory Status: ready -->
 <!-- CREDITS: dallas, mowangjuanzi, Luffy -->
 <!-- 请保持此文件与英文文件中相应的每个 ENTITY 行号一一对应以便于对照，修改与更新！ -->
 
@@ -353,6 +353,16 @@ xmlns="http://docbook.org/ns/docbook"><simpara>此函数自 PHP 8.2.0
 起<emphasis>弃用</emphasis>。强烈建议不要应用此函数。</simpara></warning>'>
 
 
+<!ENTITY warn.deprecated.feature-8-3-0 '<warning
+xmlns="http://docbook.org/ns/docbook"><simpara>本特性已自 PHP 8.3.0
+起<emphasis>废弃</emphasis>。强烈建议不要使用本特性。</simpara></warning>'>
+
+
+<!ENTITY warn.deprecated.function-8-3-0 '<warning
+xmlns="http://docbook.org/ns/docbook"><simpara>此函数自 PHP 8.3.0
+起<emphasis>弃用</emphasis>。强烈建议不要应用此函数。</simpara></warning>'>
+
+
 <!ENTITY removed.php.future '本过时特性<emphasis
 xmlns="http://docbook.org/ns/docbook">将</emphasis>肯定会在未来被<emphasis xmlns="http://docbook.org/ns/docbook">移除</emphasis>。'>
 
@@ -1571,6 +1581,11 @@ It is strongly recommended to avoid timezone abbreviations.
 </books>
 ]]></programlisting>'>
 
+<!-- Dom entities -->
+<!ENTITY dom.parameter.options '<para xmlns="http://docbook.org/ns/docbook">
+  <link linkend="language.operators.bitwise">Bitwise <literal>OR</literal></link>
+  of the <link linkend="libxml.constants">libxml option constants</link>.
+</para>'>
 
 <!-- FileSystem entities -->
 <!ENTITY fs.emits.warning.on.failure '<para xmlns="http://docbook.org/ns/docbook">
@@ -2521,10 +2536,10 @@ PHP 5.1.0 或 PHP 5.0 的特别修补版本，并需启用线程安全。更多
 
 <!-- XML -->
 <!ENTITY libxml.required '<para xmlns="http://docbook.org/ns/docbook">此扩展需要
-<link linkend="book.libxml">libxml</link> PHP 扩展。这表示需要使用
-<option role="configure">--with-libxml</option>，或在 PHP 7.4 之前的版本中使用
+<link linkend="book.libxml">libxml</link> PHP 扩展。这意味着需要传递
+<option role="configure">--with-libxml</option>，或在 PHP 7.4 之前的版本中传递
 <option role="configure">--enable-libxml</option>，
-尽管这将隐式完成因为 libxml 是缺省开启的。
+尽管这将默默完成因为 libxml 是默认开启的。
 </para>'>
 
 
@@ -4243,6 +4258,36 @@ xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
 <emphasis>REMOVED</emphasis> in PECL uopz 5.0.0.</simpara></warning>'>
 
 <!-- XML snippets -->
+<!ENTITY xml.parser.param '<varlistentry xmlns="http://docbook.org/ns/docbook">
+ <term><parameter>parser</parameter></term>
+ <listitem>
+  <para>
+   XML 解析器。
+  </para>
+ </listitem>
+</varlistentry>'>
+
+<!ENTITY xml.handler.description '<para xmlns="http://docbook.org/ns/docbook">
+ 如果传递 &null; 或空字符串，处理程序将重置为其默认状态。
+</para>
+<para xmlns="http://docbook.org/ns/docbook">
+ 如果 <parameter>handler</parameter> 是 <type>callable</type>，设置的 callable 将作为处理程序。
+</para>
+<para xmlns="http://docbook.org/ns/docbook">
+ 如果 <parameter>handler</parameter> 是 <type>string</type>，它可以是 <function>xml_set_object</function>
+ 设置的对象的方法名称。
+</para>'>
+
+
+
+<!ENTITY xml.handler.parser.param '<varlistentry xmlns="http://docbook.org/ns/docbook">
+ <term><parameter>parser</parameter></term>
+ <listitem>
+  <simpara>
+   XML 解析器调用的处理程序。
+  </simpara>
+ </listitem>
+</varlistentry>'>
 
 <!ENTITY xml.changelog.parser-param '<row xmlns="http://docbook.org/ns/docbook">
  <entry>8.0.0</entry>

diff --git a/reference/xml/book.xml b/reference/xml/book.xml
@@ -9,22 +9,20 @@
  <preface xml:id="intro.xml">
   &reftitle.intro;
   <para>
-   XML（可扩展标记语言，eXtensible Markup Language）是一种在互联网上用于结构化文档交互的数据格式。
-   它是互联网协会（W3C）定义的一个标准。与 XML 及其相关技术的信息可访问
+   XML（可扩展标记语言，英文：eXtensible Markup Language）是一种在互联网上用于结构化文档交互的数据格式。
+   它是互联网协会（W3C）定义的标准。与 XML 及其相关技术的信息可访问
    <link xlink:href="&url.xml;">&url.xml;</link>。
   </para>
   <para>
    此 PHP 扩展实现支持 James Clark 使用 PHP 编写的
-   <productname>expat</productname>。
-   此工具包可解析（但不能验证）XML 文档。它支持 PHP 所提供的 3 种<link linkend="xml.encoding">字符编码</link>：
-   <literal>US-ASCII</literal>、<literal>ISO-8859-1</literal> 和 <literal>UTF-8</literal>。不支持 <literal>UTF-16</literal>。
+   <productname>expat</productname>。此工具包可解析（但不能验证）XML 文档。它支持 PHP 所提供的 3
+   种<link linkend="xml.encoding">字符编码</link>：<literal>US-ASCII</literal>、<literal>ISO-8859-1</literal>
+   和 <literal>UTF-8</literal>。不支持 <literal>UTF-16</literal>。
   </para>
   <para>
-   此扩展可
-   <link linkend="function.xml-parser-create">创建 XML 解析器</link>
-   并为不同的 XML 事件定义 <emphasis>处理程序(handler)</emphasis>。
-   每个 XML 解析器还存在少数可以调节的
-   <link linkend="function.xml-parser-set-option">参数</link>。
+   此扩展可<link linkend="function.xml-parser-create">创建 XML 解析器</link>并为不同的 XML
+   事件定义 <emphasis>处理程序</emphasis>。每个 XML 解析器还存在少数可以调节的<link
+   linkend="function.xml-parser-set-option">参数</link>。
   </para>
  </preface>
  <!-- }}} -->

diff --git a/reference/xml/case-folding.xml b/reference/xml/case-folding.xml
@@ -2,10 +2,10 @@
 <!-- $Revision$ -->
 <!-- EN-Revision: af4410a7e15898c3dbe83d6ea38246745ed9c6fb Maintainer: mowangjuanzi Status: ready -->
 <article xml:id="xml.case-folding" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
- <title>Case Folding（大写转换）</title>
+ <title>大写转换</title>
  <para>
-  元素处理函数可取得元素名称转换为 <glossterm>case-folded</glossterm>（大写字母）形式。
-  Case-folding 被定义为“将非大写字母替换为相对应的大写字母的字符串操作”。换句话说，在
+  元素处理函数可取得元素名称转换为 <glossterm>case-folded</glossterm>（大写字母）形式。定义
+  Case-folding 为“将非大写字母替换为相对应的大写字母的字符串操作”。换句话说，在
   XML 中，case-folding 就是转换为大写。
  </para>
  <para>

diff --git a/reference/xml/encoding.xml b/reference/xml/encoding.xml
@@ -17,16 +17,14 @@
   21）的位（bit）, 编码为 1 到 4 个字节。PHP 使用的默认原始编码是 <literal>ISO-8859-1</literal>。
  </para>
  <para>
-  当 PHP 将数据传给 XML 处理函数时，目标编码就完成了。
-  在创建 XML 解析器时，目标编码被设定为与原始编码相同，但可任意修改。
-  目标编码会影响字符数据及标签名，与处理指令目标。
+  当 PHP 将数据传给 XML 处理函数时，目标编码就完成了。在创建 XML
+  解析器时，目标编码被设定为与原始编码相同，但可任意修改。目标编码会影响字符数据及标签名，与处理指令目标。
  </para>
  <para>
   如 XML 解析器遇到原始编码所能表示的范围之外的字符时，会返回一个错误。
  </para>
  <para>
-  如 PHP 遇到在被解析的 XML 文档中不能用所指定的目标编码表示的字符时，
-  这个问题字符会被“降级”。通常来说，就是那些字符会被替换成问号（?）。
+  如 PHP 遇到在被解析的 XML 文档中不能用所指定的目标编码表示的字符时，这个问题字符会被“降级”。通常来说，就是那些字符会被替换成问号（?）。
  </para>
 </article>
 

diff --git a/reference/xml/eventhandlers.xml b/reference/xml/eventhandlers.xml
@@ -18,35 +18,31 @@
      <row>
       <entry><function>xml_set_element_handler</function></entry>
       <entry>
-       当 XML 解析器遇到开始或结束标签时，会触发元素事件。
-       开始标签和结束标签有不同的处理程序。
+       当 XML 解析器遇到开始或结束标签时，会触发元素事件。开始标签和结束标签有不同的处理程序。
       </entry>
      </row>
      <row>
       <entry>
        <function>xml_set_character_data_handler</function>
       </entry>
       <entry>
-       字符数据范指 XML 文档中所有非标记的内容，包括标签之间的空格。
-       注意，XML 解析器不会添加或删除任何空格，由应用程序(你)来判断空格是否有意义。
+       字符数据范指 XML 文档中所有非标记的内容，包括标签之间的空格。注意，XML
+       解析器不会添加或删除任何空格，由应用程序(你)来判断空格是否有意义。
       </entry>
      </row>
      <row>
       <entry>
        <function>xml_set_processing_instruction_handler</function>
       </entry>
       <entry>
-       PHP 程序员必须熟练掌握处理指令(PI)。&lt;?php ?&gt;是处理指令，
-       其中<replaceable>php</replaceable>被称为“处理指令对象”。
-       除所有以“XML”开头的处理指令对象是系统保留的外，
-       其他的处理函数均是由应用程序指定的。
+       PHP 程序员必须熟练掌握处理指令（PI）。&lt;?php ?&gt;是处理指令，其中 <replaceable>php</replaceable>
+       被称为“处理指令对象”。除所有以“XML”开头的处理指令对象是系统保留的外，其他的处理函数均是由应用程序指定的。
       </entry>
      </row>
      <row>
       <entry><function>xml_set_default_handler</function></entry>
       <entry>
-       不执行其他处理函数，则会执行缺省的处理函数。
-       在缺省的处理函数中可取得如 XML 和文档类型声明等信息。
+       不执行其他处理函数，则会执行默认的处理函数。在默认的处理函数中可取得如 XML 和文档类型声明等信息。
       </entry>
      </row>
      <row>
@@ -88,7 +84,7 @@
        <function>xml_set_end_namespace_decl_handler</function>
       </entry>
       <entry>
-       在命名空间声明的结束处调用此处理程序。请注意，此事件不是由 <emphasis>not</emphasis> 触发的。
+       在命名空间声明的结束处调用此处理程序。请注意，此事件<emphasis>不是</emphasis>由 libXML 触发的。
       </entry>
      </row>
     </tbody>

diff --git a/reference/xml/examples.xml b/reference/xml/examples.xml
@@ -59,9 +59,9 @@ xml_parser_free($xml_parser);
    <example>
     <title>将 XML 映射为 HTML</title>
     <para>
-     此示例直接地将 XML 标签映射为 HTML 标签。
-     在“map_array”中未找到的元素将被忽略。
-     当然，此示例只针对特定的 XML 文档类型起作用。
+     此示例直接地将 XML 标签映射为 HTML
+     标签。在“map_array”中未找到的元素将被忽略。当然，此示例只针对特定的
+     XML 文档类型起作用。
     </para>
     <programlisting role="php">
 <![CDATA[
@@ -121,12 +121,11 @@ xml_parser_free($xml_parser);
  <section xml:id="example.xml-external-entity">
   <title>XML 外部实体示例</title>
   <para>
-   此示例用于加亮 XML 代码。举例说明如何使用外部实体引用来包含和解析其他文档，
-   及处理指令是如何被处理的，及判断处理指令所包含代码是否“可信任”的一种方法
+   此示例用于加亮 XML 代码。举例说明如何使用外部实体引用来包含和解析其他文档，及处理指令是如何被处理的，及判断处理指令所包含代码是否“可信任”的一种方法
   </para>
   <para>
-   用于此示例的 XML 文档位于此示例的下方(<filename>xmltest.xml</filename> 和
-   <filename>xmltest2.xml</filename>)。
+   用于此示例的 XML 文档位于此示例的下方（<filename>xmltest.xml</filename> 和
+   <filename>xmltest2.xml</filename>）。
   </para>
   <para>
    <example>
@@ -299,7 +298,7 @@ xml_parser_free($xml_parser);
    </example>
   </para>
   <para>
-   此文件包含在 <filename>xmltest.xml</filename> 中:
+   此文件包含在 <filename>xmltest.xml</filename> 中：
    <example>
     <title>xmltest2.xml</title>
     <programlisting role="xml">

diff --git a/reference/xml/functions/xml-parser-get-option.xml b/reference/xml/functions/xml-parser-get-option.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 98b449545887ecfda8ae8c9fa5ace0cac8e49fdd Maintainer: class007 Status: ready -->
+<!-- EN-Revision: 9fb00a4cf8563ea56d53cb1f72e2856b68899646 Maintainer: class007 Status: ready -->
 <!-- CREDITS: mowangjuanzi -->
 <refentry xml:id="function.xml-parser-get-option" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
@@ -11,7 +11,7 @@
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
-   <type class="union"><type>string</type><type>int</type></type><methodname>xml_parser_get_option</methodname>
+   <type class="union"><type>string</type><type>int</type><type>bool</type></type><methodname>xml_parser_get_option</methodname>
    <methodparam><type>XMLParser</type><parameter>parser</parameter></methodparam>
    <methodparam><type>int</type><parameter>option</parameter></methodparam>
   </methodsynopsis>
@@ -48,7 +48,7 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   如果 <parameter>parser</parameter> 没有指向有效的解析器，该函数将返回 &false;。否则将返回指定选项的值。
+   返回选项的值。
   </para>
  </refsect1>
 
@@ -74,6 +74,12 @@
      </row>
     </thead>
     <tbody>
+     <row>
+      <entry>8.3.0</entry>
+      <entry>
+       此函数为 bool 选项返回 bool 值。
+      </entry>
+     </row>
      &xml.changelog.parser-param;
      <row>
       <entry>8.0.0</entry>

diff --git a/reference/xml/functions/xml-parser-set-option.xml b/reference/xml/functions/xml-parser-set-option.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 98b449545887ecfda8ae8c9fa5ace0cac8e49fdd Maintainer: class007 Status: ready -->
+<!-- EN-Revision: 9fb00a4cf8563ea56d53cb1f72e2856b68899646 Maintainer: class007 Status: ready -->
 <!-- CREDITS: mowangjuanzi -->
 <refentry xml:id="function.xml-parser-set-option" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
@@ -14,7 +14,7 @@
    <type>bool</type><methodname>xml_parser_set_option</methodname>
    <methodparam><type>XMLParser</type><parameter>parser</parameter></methodparam>
    <methodparam><type>int</type><parameter>option</parameter></methodparam>
-   <methodparam><type class="union"><type>string</type><type>int</type></type><parameter>value</parameter></methodparam>
+   <methodparam><type class="union"><type>string</type><type>int</type><type>bool</type></type><parameter>value</parameter></methodparam>
   </methodsynopsis>
   <para>
    在 XML 解析器中设置选项。
@@ -54,9 +54,9 @@
          <tbody>
           <row>
            <entry><constant>XML_OPTION_CASE_FOLDING</constant></entry>
-           <entry>integer</entry>
+           <entry>bool</entry>
            <entry>
-            控制是否为此 XML 解析器启用<link linkend="xml.case-folding">大小写折叠</link>。默认启用。
+            控制是否为此 XML 解析器启用<link linkend="xml.case-folding">大写转换</link>。默认启用。
            </entry>
           </row>
           <row>
@@ -68,7 +68,7 @@
           </row>
           <row>
            <entry><constant>XML_OPTION_SKIP_WHITE</constant></entry>
-           <entry>integer</entry> 
+           <entry>bool</entry> 
            <entry>
             是否略过由空白字符组成的值。
            </entry>
@@ -102,8 +102,7 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   如果 <parameter>parser</parameter> 没有指向有效的解析器或者 option 无法设置，该函数将返回
-   &false;。否则设置选项并返回 &true;。
+   成功时返回 &true;，失败时返回 &false;。
   </para>
  </refsect1>
 
@@ -129,6 +128,13 @@
      </row>
     </thead>
     <tbody>
+     <row>
+      <entry>8.3.0</entry>
+      <entry>
+       <parameter>value</parameter> 参数现在也接受 bool。选项 <constant>XML_OPTION_CASE_FOLDING</constant> 和
+       <constant>XML_OPTION_SKIP_WHITE</constant> 现在是 bool 选项。
+      </entry>
+     </row>
      &xml.changelog.parser-param;
      <row>
       <entry>8.0.0</entry>