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

Commit: 9279b397d4a2548c5e9f9dc50c174845bed8d7d2 Author: Bole Chen <avenger@php.net> 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 --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>