com doc/zh: sync to en: Tell people about the possibility to doc-en source code from git: appendices/about.xml

[email protected] (Bole Chen) Tue, 02 Feb 2021 03:17:15 +0000
Newsgroups php.doc.zh
Message-ID <[email protected]>
Commit:    9279b397d4a2548c5e9f9dc50c174845bed8d7d2
Author:    Bole Chen <[email protected]>         Tue, 2 Feb 2021 11:17:15 +0800
Parents:   59f52eca9daa7bf7371abb93b0b108a0e3ec1746
Branches:  master

Link:       http://git.php.net/?p=doc/zh.git;a=commitdiff;h=9279b397d4a2548c5e9f9dc50c174845bed8d7d2

Log:
sync to en: Tell people about the possibility to doc-en source code from git

Changed paths:
  M  appendices/about.xml
diff_9279b397d4a2548c5e9f9dc50c174845bed8d7d2.txt (text/plain, 12.7 KB)
diff --git a/appendices/about.xml b/appendices/about.xml
index 406e7f0e..e5a41023 100644
--- a/appendices/about.xml
+++ b/appendices/about.xml
@@ -1,7 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 904f11cd5ca4d358f5e9bf5985980929fd7caa0f Maintainer: Gregory Status: ready -->
-<!-- Reviewed: no Maintainer: avenger -->
+<!-- EN-Revision: 2c2251ec924e1a5d30f08914bba231a4ed9c1923 Maintainer: Gregory Status: ready -->
 <!-- CREDITS: dallas -->
 <appendix xml:id="about" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>关于本手册</title>
@@ -88,149 +87,131 @@
  </sect1>
 
  <sect1 xml:id="about.prototypes">
-  <title>如何阅读函数的定义(函数原型)</title>
-  <para>
-   文档中的每个函数都只是快速参考,学会如何阅读和理解文档将使得
-   PHP 的使用更加简单。和依赖赖于复制/粘贴范例比起来,用户一定更希望知道如何阅读函数的定义(函数原型):
-  </para>
-  <note>
-   <title>
-    先决条件,对<link linkend="language.types">变量类型</link>的基本理解
-   </title>
+   <title>如何阅读函数的定义(函数原型)</title>
    <para>
-    尽管 PHP 是一种松散类型语言,但<link
-    linkend="language.types">变量类型</link>有重要的意义,需要理解它的基本知识。
+    文档中的每个函数都只是快速参考,学会如何阅读和理解文档将使得
+    PHP 的使用更加简单。和依赖赖于复制/粘贴范例比起来,用户一定更希望知道如何阅读函数的定义(函数原型):
    </para>
-  </note>
-  <para>
-   函数定义告诉我们函数<link
-   linkend="functions.returning-values">返回</link>什么类型的值,让我们用函数
-   <function>strlen</function> 的定义作为第一个范例:
-  </para>
-  <para>
-  <screen role="html">
+   <note>
+    <title>
+     先决条件,对<link linkend="language.types">变量类型</link>的基本理解
+    </title>
+    <para>
+     尽管 PHP 是一种松散类型语言,但<link
+     linkend="language.types">变量类型</link>有重要的意义,需要理解它的基本知识。
+    </para>
+   </note>
+   <para>
+    函数定义告诉我们函数<link
+    linkend="functions.returning-values">返回</link>什么类型的值,让我们用函数
+    <function>strlen</function> 的定义作为第一个范例:
+   </para>
+   <para>
+    <screen role="html">
 <![CDATA[
 strlen
 
-(PHP 4, PHP 5)
-strlen -- 获取字符串长度
+(PHP 4, PHP 5, PHP 7)
+strlen -- Get string length
 
 说明
 strlen ( string $string ) : int
 
 返回给定的字符串 string 的长度。
 ]]>
-   </screen>
-  </para>
-  <para>
-   <table>
-    <title>对函数定义的解释</title>
-    <tgroup cols="2">
-     <thead>
-      <row>
-       <entry>组成部分</entry>
-       <entry>说明</entry>
-      </row>
-     </thead>
-     <tbody>
-      <row>
-       <entry>
-        strlen
-       </entry>
-       <entry>
-        函数名称。
-       </entry>
-      </row>
-      <row>
-       <entry>
-        (PHP 4, PHP 5)
-       </entry>
-       <entry>
-        strlen() 在 PHP 4 和 PHP 5 的所有版本中都存在。
-       </entry>
-      </row>
-      <row>
-       <entry>
-        ( string str )
-       </entry>
-       <entry>
-        第一个(本例中是唯一的)参数,在该函数中名为 <parameter>string</parameter>,且类型为 <type>string</type>。
-       </entry>
-      </row>
-      <row>
-       <entry>
-        int
-       </entry>
-       <entry>
-        该函数返回的值的类型,这里为整型 <type>integer</type>(即以数字来衡量的字符串的长度)。
-       </entry>
-      </row>
-     </tbody>
-    </tgroup>
-   </table>
-  </para>
-  <para>
-   可以将以上函数的定义写成一般形式:
-  </para>
-  <para>
-   <screen>
+     </screen>
+    </para>
+    <para>
+     <table>
+      <title>对函数定义的解释</title>
+      <tgroup cols="2">
+       <thead>
+        <row>
+         <entry>组成部分</entry>
+         <entry>说明</entry>
+        </row>
+       </thead>
+       <tbody>
+        <row>
+         <entry>
+          strlen
+         </entry>
+         <entry>
+          函数名称。
+         </entry>
+        </row>
+        <row>
+         <entry>
+          (PHP 4, PHP 5, PHP 7)
+         </entry>
+         <entry>
+          strlen() 在 PHP 4, PHP 5 和 PHP 7 的所有版本中都存在。
+         </entry>
+        </row>
+        <row>
+         <entry>
+          ( string $string )
+         </entry>
+         <entry>
+          第一个(本例中是唯一的)参数,在该函数中名为 <parameter>string</parameter>,且类型为 <type>string</type>。
+         </entry>
+        </row>
+        <row>
+         <entry>
+          int
+         </entry>
+         <entry>
+          该函数返回的值的类型,这里为整型 <type>int</type>(即以数字来衡量的字符串的长度)。
+         </entry>
+        </row>
+       </tbody>
+      </tgroup>
+     </table>
+    </para>
+    <para>
+     可以将以上函数的定义写成一般形式:
+    </para>
+    <para>
+     <screen>
 <![CDATA[
           函数名          ( 参数类型           参数名 )        返回类型
       function name    ( parameter type   parameter name ) : returned type
 ]]>
-   </screen>
-  </para>
-  <para>
+     </screen>
+    </para>
+    <para>
    很多函数都有多个变量,例如 <function>in_array</function>。其函数原型如下:
-  </para>
-  <para>
-   <screen>
+    </para>
+    <para>
+     <screen>
 <![CDATA[
-      in_array ( mixed $needle, array $haystack [, bool $strict = FALSE ] ) : bool
+      in_array ( mixed $needle, array $haystack , bool $strict = false ) : bool
 ]]>
-   </screen>
-  </para>
-  
-  
-  
-  
-  
-  
-  
-  
-  
-  
-  
-  
-  
-  
-  
-  
-  
-  
-  <para>
-   这是什么意思?<function>in_array</function>
-   返回一个“<link linkend="language.types.boolean">布尔</link>”值,成功(如果在参数
-   <parameter>haystack</parameter> 中能找到参数
-   <parameter>needle</parameter>)则返回 &true;,
-   &return.falseforfailure;(如果在参数 <parameter>haystack</parameter> 中找不到参数
-   <parameter>needle</parameter>)。第一个参数被命名为
-   <parameter>needle</parameter> 且其<link
-   linkend="language.types">类型</link>不定,因此我们将其称为“<emphasis>混和</emphasis>”类型。该混和类型的
-   <parameter>needle</parameter> 参数(我们要找的对象)可以是一个标量的值(字符串、整数、或者<link
-   linkend="language.types.float">浮点数</link>),或者一个<link
-   linkend="language.types.array">数组</link>。<parameter>haystack</parameter>(我们寻找的范围)是第二个参数。第三个<emphasis>可选</emphasis>参数被命名为
-   <parameter>strict</parameter>。所有的可选参数都用
-   <emphasis>[</emphasis> 方括号 <emphasis>]</emphasis> 括起来。手册表明
-   <parameter>strict</parameter> 参数默认值为布尔值
-   &false;。需要了解函数工作的细节,请参阅手册中和该函数相关的页面。
-  </para>
-    <para> 
-     函数参数前的 &amp; 符号使参数以 <link linkend="language.references.pass">引用</link> 方式传递,如下所见: 
+     </screen>
     </para>
     <para>
-     <screen> 
-<![CDATA[ 
+     这是什么意思?<function>in_array</function>
+     返回一个“<link linkend="language.types.boolean">布尔</link>”值,成功(如果在参数
+     <parameter>haystack</parameter> 中能找到参数
+     <parameter>needle</parameter>)则返回 &true;,
+     &return.falseforfailure;(如果在参数 <parameter>haystack</parameter> 中找不到参数
+     <parameter>needle</parameter>)。第一个参数被命名为
+     <parameter>needle</parameter> 且其<link
+     linkend="language.types">类型</link>不定,因此我们将其称为“<emphasis>混和</emphasis>”类型。该混和类型的
+     <parameter>needle</parameter> 参数(我们要找的对象)可以是一个标量的值(字符串、整数、或者<link
+     linkend="language.types.float">浮点数</link>),或者一个<link
+     linkend="language.types.array">数组</link>。<parameter>haystack</parameter>(我们寻找的范围)是第二个参数。第三个<emphasis>可选</emphasis>参数被命名为
+     <parameter>strict</parameter>。所有的可选参数都用
+     <emphasis>[</emphasis> 方括号 <emphasis>]</emphasis> 括起来。手册表明
+     <parameter>strict</parameter> 参数默认值为布尔值
+     &false;。需要了解函数工作的细节,请参阅手册中和该函数相关的页面。
+    </para>
+    <para>
+     函数参数前的 &amp; 符号使参数以 <link linkend="language.references.pass">引用</link> 方式传递,如下所见:
+    </para>
+    <para>
+     <screen>
+<![CDATA[
        preg_match ( string $pattern , string $subject [, array &$matches
       [, int $flags = 0 [, int $offset = 0 ]]] ) : int
 ]]>
@@ -239,28 +220,28 @@ strlen ( string $string ) : int
     <para>
      在这个例子中,我们可以看到,第三个可选参数 <parameter>&amp;$matches</parameter> 会意引用方式传递。
     </para>
-  <para>
-   有的函数包含更复杂的 PHP 版本信息。我们拿
-   <function>html_entity_decode</function> 举例:
-  </para>
-  <para>
-   <screen>
+    <para>
+     有的函数包含更复杂的 PHP 版本信息。我们拿
+     <function>html_entity_decode</function> 举例:
+    </para>
+    <para>
+     <screen>
 <![CDATA[
-(PHP 4 >= 4.3.0, PHP 5)
+(PHP 4 >= 4.3.0, PHP 5, PHP 7)
 ]]>
-   </screen>
-  </para>
-  <para>
-   它意味着该函数只可在 PHP 4.3.0 及以后发布的版本中使用。
-  </para>
- </sect1>
+     </screen>
+    </para>
+    <para>
+     它意味着该函数只可在 PHP 4.3.0 及以后发布的版本中使用。
+    </para>
+   </sect1>
 
  <sect1 xml:id="about.phpversions">
   <title>本手册中所涉及的 PHP 版本</title>
   <para>
    本手册包含有 PHP
    过去,现在和未来版本的信息。如果(不同版本)有功能变化则作为注释、更新日志以及插入文本方式在手册页中注明。
-   文档内最早的版本是 PHP 5.0.0。
+   文档内最早的版本是 PHP 7.0.0。
   </para>
   <para>
    当对应于最新(尚未发布)开发版的 PHP 有文档存在时,将会被标记为“可在
@@ -272,17 +253,10 @@ strlen ( string $string ) : int
   </para>
   <para>
    要澄清一点,手册会指明 PHP 的主版本号,次版本号和发布编号。以
-   PHP <literal>5.3.1</literal> 为例,<emphasis>5</emphasis>
+   PHP <literal>7.3.1</literal> 为例,<emphasis>5</emphasis>
    是主版本号,<emphasis>3</emphasis> 是次版本号,<emphasis>1</emphasis>
    是发布编号。通常 PHP 只会在主、次版本更新时增加新特性,在发布编号更新时修正错误。不过也不完全是这样。
   </para>
-  
-  
-  
-  
-  
-  
-  
   <para>
    还要注意 PHP 手册是以现在时态书写的,而不是将来时态,即使某特性当前还尚未可用。原因是这样一来手册就可以经受住时间的考验,而不用在每次
    PHP 更新时都去修改无聊的语法。
@@ -325,15 +299,6 @@ strlen ( string $string ) : int
     xlink:href="&url.php.support;">支持页面</link>。
    </para>
   </note>
-  
-  
-  
-  
-  
-  
-  
-  
-  
   <para>
    通过提交注释,用户可以向其它读者提供更多的范例、解释和阐述。但请勿在注释系统提交错误报告。更多细节见<link
    linkend="about.notes">关于用户注释</link>一节。
@@ -347,7 +312,6 @@ strlen ( string $string ) : int
    <literal>irc.efnet.org</literal> 服务器上的
    <literal>#php.doc</literal> 与他们讨论改善 PHP 文档的方法。
   </para>
-
  </sect1>
 
  <sect1 xml:id="about.generate">
@@ -382,12 +346,12 @@ strlen ( string $string ) : int
   </para>
   <para>
    翻译工作者首先从本手册的 <acronym>XML</acronym>
-   源代码(可于 <link xlink:href="&url.php.svn;">&url.php.svn;</link>
+   源代码(可于 <link xlink:href="&url.php.git.mirror;doc-en">&url.php.git.mirror;doc-en"</link>
    获取)入手,将这些源代码翻译成他们的母语。<emphasis>不要</emphasis>从生成后的版本开始翻译(比如
    <acronym>HTML</acronym> 或纯文本版)。因为编译系统会负责将
    <acronym>XML</acronym> 源代码转换成可阅读版本。
   </para>
-  <note> 
+  <note>
    <para>
     要帮忙翻译手册,请发一封空的电子邮件到
     <link xlink:href="mailto:&email.php.doc.subscribe;">&email.php.doc.subscribe;</link>