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>
- 函数参数前的 & 符号使参数以 <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>
+ 函数参数前的 & 符号使参数以 <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>&$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>