archived-doc-zh/appendices/about.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: e8ac70bf549a723cb36465667a6109d9933b8619 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>

 <sect1 xml:id="about.formats">
  <title>手册的格式</title>
  <para>
   《PHP 参考手册》提供了多种不同格式的版本，它们可以分为两组：在线阅读版本和可下载打包版本。
  </para>
  <note>
   <para>
    有些出版商可能已经出版了本手册的一些印刷版本。不推荐印刷版，因为
    PHP 参考手册更新得非常快，这些印刷版本的内容很快将过时。
   </para>
  </note>
  <para>
   可以访问 <link xlink:href="&url.php;">PHP.net 网站</link>及其众多的镜像站点来在线阅读《PHP
   参考手册》。为了保证最佳的访问速度，应该选择地理位置最接近的镜像站点。PHP
   手册的在线版本目前有两种 <acronym>CSS</acronym> 样式表：便于浏览和便于打印。
  </para>
  <para>
   和绝大多数离线格式的手册相比，在线阅读版本有两个显著的优点，即它集成了<link
   linkend="about.notes">用户注释</link>，并且可以使用其中的
   <link xlink:href="&url.php.urlhowto;">URL
   快捷方式</link>快速进入手册中想阅读的部分；但是，它的明显的缺点是必须要联网才能阅读。
  </para>
  <para>
   目前，《PHP
   参考手册》提供多种离线阅读格式，最适合于自己的格式取决于所使用的操作系统和个人的阅读习惯。关于《PHP
   参考手册》如何被制作成如此多的版本，请查阅本附录中<link
   linkend="about.generate">如何生成手册的各种格式</link>一节。
  </para>
  <para>
   跨平台性最好的是 HTML 格式。HTML 格式提供了两种方式：一种只有一个很大的
   HTML 文件；另一种方式是每一节分成一个独立文件（它们形成一个包含有几千个文件的文件包）。我们提供的是这两种版本的压缩包，需要使用解压缩工具解压出压缩包中的文件。
  </para>
  <!--
   PDF 版的 PHP 手册“目前”不可用，也许以后有一天会有的。
  <para>
   另一种流行的跨平台格式，也是最适合打印的格式，是 PDF（也就是 Adobe
   Acrobat）格式。不过，需要提醒您本手册超过 2000 页，并且还在不断地被修订。
  </para>
  <note>
   <para>
    有很多软件可以阅读 <acronym>PDF</acronym> 文件，例如
    <link xlink:href="&url.adobe.acrobat;">Adobe Acrobat Reader</link>。
   </para>
  </note>
  -->
  <para>
   对于 Windows 平台，我们利用了 <productname>Windows
   HTML 帮助</productname>应用程序结合本手册的 HTML
   格式，形成了本手册的 <productname>Windows
   HTML 帮助</productname>版本。该版本提供手册的全文搜索、完整的索引以及书签功能。很多
   Windows 平台下流行的 PHP
   集成开发环境也集成了该版本的手册，以给开发者提供最方便快捷的参考。CHM
   阅读器也有 Linux 版本，可以到 <link xlink:href="&url.xchm;">xCHM</link>
   或 <link xlink:href="&url.gnochm;">GnoCHM</link> 网站了解更多信息。
  </para>

  <para>
   同时，PHP 手册也有<link xlink:href="&url.php.echm;">扩展 CHM
   版本</link>提供下载。它更新的速度比较慢，但是提供了附加的功能。由于制作帮助页面时采用的技术的特殊性，它只可在
   <productname>Microsoft Windows</productname> 下工作。
  </para>
 </sect1>

 <sect1 xml:id="about.notes">
  <title>关于用户注释</title>
  <para>
   用户注释在本手册的开发过程中扮演了相当重要的角色。通过允许手册的读者利用它们的浏览器提供范例、解释和进一步的阐述，我们便能够把这些反馈信息包含到手册的正文中。而且，当这些注释被包含后，读者就可以在线通过它们被提交的格式来阅读它们，也可以通过某些离线格式来阅读。
  </para>
  <note>
   <para>
    用户注释在网上出现之前并不成熟，因此这些文字和代码的质量，甚至它们的真实性无从得到保证（这并不是说本手册本身的质量和准确性没有任何的保证）。
   </para>
  </note>
  <note>
   <para>
    由于用户注释被认为是 PHP 手册的一部分，因此它使用本文档的许可协议（目前为创作共用许可协议）。请查阅手册<link
    linkend="copyright">版权页</link>以了解更多详细信息。
   </para>
  </note>
 </sect1>

 <sect1 xml:id="about.prototypes">
   <title>如何阅读函数的定义（函数原型）</title>
   <para>
    文档中的每个函数都只是快速参考，学会如何阅读和理解文档将使得
    PHP 的使用更加简单。和依赖赖于复制／粘贴范例比起来，用户一定更希望知道如何阅读函数的定义（函数原型）：
   </para>
   <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, 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, 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>
   很多函数都有多个变量，例如 <function>in_array</function>。其函数原型如下：
    </para>
    <para>
     <screen>
<![CDATA[
      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> 方式传递，如下所见：
    </para>
    <para>
     <screen>
<![CDATA[
       preg_match ( string $pattern , string $subject [, array &$matches
      [, int $flags = 0 [, int $offset = 0 ]]] ) : int
]]>
     </screen>
    </para>
    <para>
     在这个例子中，我们可以看到，第三个可选参数 <parameter>&amp;$matches</parameter> 会意引用方式传递。
    </para>
    <para>
     有的函数包含更复杂的 PHP 版本信息。我们拿
     <function>html_entity_decode</function> 举例：
    </para>
    <para>
     <screen>
<![CDATA[
(PHP 4 >= 4.3.0, PHP 5, PHP 7)
]]>
     </screen>
    </para>
    <para>
     它意味着该函数只可在 PHP 4.3.0 及以后发布的版本中使用。
    </para>
   </sect1>

 <sect1 xml:id="about.phpversions">
  <title>本手册中所涉及的 PHP 版本</title>
  <para>
   本手册包含有 PHP
   过去，现在和未来版本的信息。如果（不同版本）有功能变化则作为注释、更新日志以及插入文本方式在手册页中注明。
   文档内最早的版本是 PHP 7.0.0。
  </para>
  <para>
   当对应于最新（尚未发布）开发版的 PHP 有文档存在时，将会被标记为“可在
   Git 获取”或者“开发版本”。应该计划好相关变更，虽不多见但确有可能会有变动。
  </para>
  <para>
   所有开发都放置于 Git 中，应按照<link xlink:href="&url.php.anongit;">匿名 Git
   访问</link>页面中的方法来取出。
  </para>
  <para>
   要澄清一点，手册会指明 PHP 的主版本号，次版本号和发布编号。以
   PHP <literal>7.3.1</literal> 为例，<emphasis>5</emphasis>
   是主版本号，<emphasis>3</emphasis> 是次版本号，<emphasis>1</emphasis>
   是发布编号。通常 PHP 只会在主、次版本更新时增加新特性，在发布编号更新时修正错误。不过也不完全是这样。
  </para>
  <para>
   还要注意 PHP 手册是以现在时态书写的，而不是将来时态，即使某特性当前还尚未可用。原因是这样一来手册就可以经受住时间的考验，而不用在每次
   PHP 更新时都去修改无聊的语法。
  </para>
  <para>
   PHP 手册会多次列出 PHP 配置选项的“默认值”。默认值是没有 &php.ini;
   配置文件时的值，所以与 <filename>php.ini-development</filename> 和 <filename>php.ini-production</filename>
   存在很大差异。同时这些值也是基于最新版本的
   PHP。请参考 <link linkend="ini.list">PHP 配置选项列表</link>以了解更多信息。
  </para>
 </sect1>

 <sect1 xml:id="about.more">
  <title>如何得到关于 PHP 更多的信息</title>
  <para>
   本手册并不打算提供基本的编程开发指导。刚学编程的或者新手程序员会发现仅仅用本手册来学习如何用
   PHP 编程是一件很困难的事情。应该寻找一本更适合初学者的书。
  </para>
  <para>
   目前，PHP 官方提供了许多邮件列表来讨论 PHP
   编程相关的各个方面的问题。如果卡在了某个问题上，可以到该邮件列表寻求帮助。有关支持以及邮件列表请访问
   <link xlink:href="&url.php.support;">PHP.net 支持页面</link>。
  </para>
 </sect1>

 <sect1 xml:id="about.howtohelp">
  <title>如何帮助改进本文档</title>
  <para>
   可以通过以下三种途径来帮助改善本文档。
  </para>
  <para>
   如果发现本手册任何一种翻译语言中存在错误，请通过 <link xlink:href="&url.php.git;">&url.php.git;</link> 中对应
   语种的仓库 issue 追踪器报告错误，
   例如，中文手册的错误应该在 <link xlink:href="&url.php.git;doc-zh/issues">&url.php.git;doc-zh/issues</link>
   报告。所有文档相关的问题，包括手册格式，都应作为错误提交。
  </para>
  <note>
   <para>
    请勿滥用问题追踪器（issue trackers）来寻求帮助。如需帮助请访问<link
    xlink:href="&url.php.support;">支持页面</link>。
   </para>
  </note>
  <para>
   通过提交注释，用户可以向其它读者提供更多的范例、解释和阐述。但请勿在注释系统提交错误报告。更多细节见<link
   linkend="about.notes">关于用户注释</link>一节。
  </para>
  <para>
   PHP 手册被翻译成很多种语言。如果懂英语和另一种语言，可以加入翻译团队来帮助改善文档。关于开始一个新语种的翻译，或者加入某一个语言版本的翻译工作，请下载并阅读
   <link xlink:href="&url.php.dochowto;">&url.php.dochowto;</link>。
  </para>
  <para>
   PHP 文档项目也有一个 IRC 频道，许多手册作者都常去。可以访问
   <literal>irc.efnet.org</literal> 服务器上的
   <literal>#php.doc</literal> 与他们讨论改善 PHP 文档的方法。
  </para>
 </sect1>

 <sect1 xml:id="about.generate">
  <title>如何生成手册的各种格式</title>
  <para>
   本手册使用 <acronym>XML</acronym> 语言编写，同时运用了
   <link xlink:href="&url.docbook.xml;">DocBook XML DTD</link>。还用了
   <link
   xlink:href="&url.phd;"><acronym>PhD</acronym></link>（基于 [PH]P 的
   [D]ocBook 渲染器）来维护和格式化。
  </para>
  <para>
   将 <acronym>XML</acronym>
   语言作为源文件格式，使得我们只需维护该源文件文档，就可以可以利用它生成许多其它的输出格式。生成在线手册格式的工具是
   <link xlink:href="&url.phd;">PhD</link>。我们使用
   <link xlink:href="&url.winhelp;">Microsoft HTML Help Workshop</link>
   来生成本手册的 <productname>Windows HTML 帮助</productname> 格式。当然，PHP 本身也完成了其它一些转换和格式化工作。
  </para>
  <para>
   PHP 手册被生成多种不同语言和格式，详情见
   <link xlink:href="&url.php.docs;">&url.php.docs;</link>。<acronym>XML</acronym>
   格式的源代码可以通过 SVN 下载，并通过
   <link xlink:href="&url.php.svn;">&url.php.svn;</link>
   在线浏览。文档存放于 <literal>phpdoc</literal> 模块中。
  </para>
 </sect1>

 <sect1 xml:id="about.translations">
  <title>手册译文</title>
  <para>
   《PHP 参考手册》不但有各种不同的格式，而且还有各种语言的版本。手册的正文最初是用英语撰写的，后来有来自全世界各地的工作组致力于本手册各种语言版本的翻译工作。如果某个函数或者章节的内容尚未被翻译，则该语言版本手册的发布将落后于英语版本。
  </para>
  <para>
   翻译工作者首先从本手册的 <acronym>XML</acronym>
   源代码（可于 <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>
   <para>
    要帮忙翻译手册，请发一封空的电子邮件到
    <link xlink:href="mailto:&email.php.doc.subscribe;">&email.php.doc.subscribe;</link>
    加入 phpdoc 邮件列表以便与文档翻译小组取得联系。邮件列表的地址为
    <literal>&email.php.doc;</literal>。请在电子邮件中声明对文档翻译工作感兴趣，有人会回复并帮助加入到已经存在的翻译小组，或者开始新语种的翻译工作。
   </para>
  </note>
  <para>
   目前，本手册已经（或部分）有超过 10 种语言可用。
  </para>
  <para>
   可以访问 <link xlink:href="&url.php.docs;">&url.php.docs;</link> 来下载各种版本。
  </para>
 </sect1>

</appendix>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->