PHP手册翻译/编译指南[6]--手册编译与验证
时间：2008-05-27 来源：剑心通明
The Makefile注意：需要先安装PHP，在Cygwin下，安装PHP5要先安装bison和flex(不是Adobe那个flex哦)，这两个包只要运行cygwin的setup.exe，然后选择安装即可，非常方便。 然后进入PHP源代码目录，输入
./configure
make
PHP安装完成。
在翻译时你会经常需要把手册编译成HTML或其它格式（PDF,RTF等）来检查翻译是否正确，因为XML格式不易阅读。
要生成Makefile（然后能使用make命令进行编译生成手册），请使用cd命令进入phpdoc目录，然后输入以下命令：
$ autoconf
$ ./configure
就会生成Makefile。
注意：如果你的平台为WINDOWS，一定要在Cygwin的bash shell下才能运行以上命令。
另外，在Cygwin下，需要先安装OpenSP，再安装Open Jade(SGML/XML解析器)两个软件，同样这两个软件都可以通过Cygwin的setup.exe来安装。
configure命令有两个重要的参数，一个是--with-dsssl，用于指定DSSSL样式表的路径。有超过15个DSSSL样式表目录，所以不用管这个参数。 另一个参数为--with-lang=，用于指定编译的手册语言，默认为“en”（英文版手册），例如：
$ ./configure --with-lang=nl
还有更多参数，最重要的是--with-xsl，用于指定XSL样式表；还有--with-zendapi，用于指定Zend API文档的路径。
Validating Changes
如果你已经生成了Makefile，你可以编译手册了：
$ cd phpdoc
$ make test
输出的信息可能是这样的：
touch .manual.xml
CONFIG_FILES=manual.xml CONFIG_HEADERS= ./config.status
creating manual.xml
nsgmls -i lang-en -s ./phpdocxml.dcl manual.xml
如果在翻译时有出错，例如没有关闭某个标签（没有配对）或使用了错误的标签，则make test会报告错误并告知哪一行出错：
touch .manual.xml
CONFIG_FILES=manual.xml CONFIG_HEADERS= ./config.status
creating manual.xml
nsgmls -i lang-en -s ./phpdocxml.dcl manual.xml
nsgmls:en/chpaters/intro.xml:54:13:E: end tag for "para" omitted, but OMITTAG NO was specified
make: *** [test] Error 1
在上面的例子中，解析器希望找到标签的结束标签，在文件en/chapters/intro.xml的第54行。通过这个信息，你就可以找到该文件并改正这个错误，在你提交文件到CVS服务器之前。
为了检查XML是否有效和正确，你可以使用make test_xml命令，它会对整个phpdoc树执行一个xmllint检查。这样可以找到make test忽略的错误，如某个实体中漏掉;或者&。xmllint比SGML检查慢得多，需要4倍的时间来检查，而且比较费内存。
$ cd phpdoc
$ make test_xml
如果只检查某个XML文件的正确性，可以使用xml-check.php脚本（位于phpdoc scripts/ 目录下），它比make test或者make test_xml要快得多，如果你只修改了一个文件。使用如下：
$ scripts/xml-check.php en/reference/mysql/functions/mysql-connect.xml
在提交文件到服务器之前进行检查是非常重要的，因为如果你提交了错误的文件，这一个文件就将使整个编译过程停止，则php手册文件和php.net上提供的下载就不会更新，这一定会让phpdoc的负责的人很生气呵呵。
当新增一个文件时，请再次运行./configure，然后才运行make test，这样新文件也可以被检查。
Viewing Your Changes
There are several stylesheets available for generating viewable documentation, the most useful will probably be:
There are also XSL stylesheets available, that are equivalents to the above DSSSL sheets. The list includes: html_xsl, bightml_xsl, phpweb_xsl, howto_xsl, chm_xsl and fo (produces a FO file, that can be later transformed to PDF using a FO processor, like Apache FOP)
To generate a viewable copy of the documentation, cd to the phpdoc directory and issue one of the following commands:
$ make html
$ make bightml
$ make phpwebTo make an actual copy of this HOWTO:
$ make howto
-or-
$ make howto_xslThe plain text version of the PHP documentation is made by filtering the bightml output through lynx.
Note: Generating viewable documentation is CPU intensive and can take a little while to complete. E.g. generating the simple HTML manual takes about 1 hour on a normal computer.
Where the output files are placed depends on the format you built. HTML manuals generate in the html subdirectory of phpdoc, similarly the make phpweb command will place the files in the php directory. The place for the HOWTO HTML files is howto/html.
If all goes well, you should have your own copy of the documentation, including any changes you've made.
Tip: Instead of generating the whole manual (which takes too much time), you can generate just a single section, by issuing the following command: xsltproc --stringparam rootid "" xsl/html.xsl manual.xml (replacing by the ID of the file/section you want to build.
The Online Generation System
The online generation system is working at rsync.php.net.
This system generates manuals for all languages with a language-defs.ent file in the translation directory. However the listing of languages at
http://www.php.net/docs
and
http://www.php.net/get/docs
are static, so only manually added languages show up in those listings.
This generator system only builds a new online manual, and new downloadable files from one language, if it is modified in a one day period. The build process takes hours for only one language, so not all languages can be built in one day. During the generation, a build.log.gz is saved with build information. See the
section for translators
about the build.log.gz file. If there were some errors in the build process, you can find the errors loged in this file.
The automatic build process updates the online manual, and all downloadable ones, excluding the CHM versions. The CHM versions are also built daily, but on a separate Windows machine, as the compiler is only available for Microsoft Windows.
./configure
make
PHP安装完成。
在翻译时你会经常需要把手册编译成HTML或其它格式（PDF,RTF等）来检查翻译是否正确，因为XML格式不易阅读。
要生成Makefile（然后能使用make命令进行编译生成手册），请使用cd命令进入phpdoc目录，然后输入以下命令：
$ autoconf
$ ./configure
就会生成Makefile。
注意：如果你的平台为WINDOWS，一定要在Cygwin的bash shell下才能运行以上命令。
另外，在Cygwin下，需要先安装OpenSP，再安装Open Jade(SGML/XML解析器)两个软件，同样这两个软件都可以通过Cygwin的setup.exe来安装。
configure命令有两个重要的参数，一个是--with-dsssl，用于指定DSSSL样式表的路径。有超过15个DSSSL样式表目录，所以不用管这个参数。 另一个参数为--with-lang=，用于指定编译的手册语言，默认为“en”（英文版手册），例如：
$ ./configure --with-lang=nl
还有更多参数，最重要的是--with-xsl，用于指定XSL样式表；还有--with-zendapi，用于指定Zend API文档的路径。
Validating Changes
如果你已经生成了Makefile，你可以编译手册了：
$ cd phpdoc
$ make test
输出的信息可能是这样的：
touch .manual.xml
CONFIG_FILES=manual.xml CONFIG_HEADERS= ./config.status
creating manual.xml
nsgmls -i lang-en -s ./phpdocxml.dcl manual.xml
如果在翻译时有出错，例如没有关闭某个标签（没有配对）或使用了错误的标签，则make test会报告错误并告知哪一行出错：
touch .manual.xml
CONFIG_FILES=manual.xml CONFIG_HEADERS= ./config.status
creating manual.xml
nsgmls -i lang-en -s ./phpdocxml.dcl manual.xml
nsgmls:en/chpaters/intro.xml:54:13:E: end tag for "para" omitted, but OMITTAG NO was specified
make: *** [test] Error 1
在上面的例子中，解析器希望找到标签的结束标签，在文件en/chapters/intro.xml的第54行。通过这个信息，你就可以找到该文件并改正这个错误，在你提交文件到CVS服务器之前。
为了检查XML是否有效和正确，你可以使用make test_xml命令，它会对整个phpdoc树执行一个xmllint检查。这样可以找到make test忽略的错误，如某个实体中漏掉;或者&。xmllint比SGML检查慢得多，需要4倍的时间来检查，而且比较费内存。
$ cd phpdoc
$ make test_xml
如果只检查某个XML文件的正确性，可以使用xml-check.php脚本（位于phpdoc scripts/ 目录下），它比make test或者make test_xml要快得多，如果你只修改了一个文件。使用如下：
$ scripts/xml-check.php en/reference/mysql/functions/mysql-connect.xml
在提交文件到服务器之前进行检查是非常重要的，因为如果你提交了错误的文件，这一个文件就将使整个编译过程停止，则php手册文件和php.net上提供的下载就不会更新，这一定会让phpdoc的负责的人很生气呵呵。
当新增一个文件时，请再次运行./configure，然后才运行make test，这样新文件也可以被检查。
Viewing Your Changes
There are several stylesheets available for generating viewable documentation, the most useful will probably be:
-
html, the plain html manual found at
http://www.php.net/manual/html/
-
bightml, one big HTML file, only available for download at
http://www.php.net/get/docs
-
phpweb, the main PHP online manual found at
http://www.php.net/manual/
-
install-win.txt, the text version of the Windows install instructions that goes into the PHP source (as php-src/win32/install.txt). It's based off HTML (via lynx) using install-win.xml. Before commit, be sure Unix style (\n) line endings are used as the Windows packaging script later converts them to Windows format (\r\n). Both install-win.txt and install-win.html are generated.
Be sure the &install.windows.building; entity is removed from en/install/windows/index.xml before building this file.
-
install-unix.txt, the text version of the Unix install instructions that goes into the PHP source (as php-src/INSTALL). It's based off HTML (via lynx) using install-unix.xml. Before commit, be sure Unix style (\n) line endings are used. Both install-unix.txt and install-unix.html are generated.
-
pdf, a PDF version of the manual, currently not available online
-
rtf, a RTF (Rich Text Format) version of the manual, currently not available online
-
howto, this HOWTO document in a simple HTML format:
http://php.net/get/dochowto
There are also XSL stylesheets available, that are equivalents to the above DSSSL sheets. The list includes: html_xsl, bightml_xsl, phpweb_xsl, howto_xsl, chm_xsl and fo (produces a FO file, that can be later transformed to PDF using a FO processor, like Apache FOP)
To generate a viewable copy of the documentation, cd to the phpdoc directory and issue one of the following commands:
$ make html
$ make bightml
$ make phpwebTo make an actual copy of this HOWTO:
$ make howto
-or-
$ make howto_xslThe plain text version of the PHP documentation is made by filtering the bightml output through lynx.
Note: Generating viewable documentation is CPU intensive and can take a little while to complete. E.g. generating the simple HTML manual takes about 1 hour on a normal computer.
Where the output files are placed depends on the format you built. HTML manuals generate in the html subdirectory of phpdoc, similarly the make phpweb command will place the files in the php directory. The place for the HOWTO HTML files is howto/html.
If all goes well, you should have your own copy of the documentation, including any changes you've made.
Tip: Instead of generating the whole manual (which takes too much time), you can generate just a single section, by issuing the following command: xsltproc --stringparam rootid "" xsl/html.xsl manual.xml (replacing by the ID of the file/section you want to build.
The Online Generation System
The online generation system is working at rsync.php.net.
This system generates manuals for all languages with a language-defs.ent file in the translation directory. However the listing of languages at
http://www.php.net/docs
and
http://www.php.net/get/docs
are static, so only manually added languages show up in those listings.
This generator system only builds a new online manual, and new downloadable files from one language, if it is modified in a one day period. The build process takes hours for only one language, so not all languages can be built in one day. During the generation, a build.log.gz is saved with build information. See the
section for translators
about the build.log.gz file. If there were some errors in the build process, you can find the errors loged in this file.
The automatic build process updates the online manual, and all downloadable ones, excluding the CHM versions. The CHM versions are also built daily, but on a separate Windows machine, as the compiler is only available for Microsoft Windows.
相关阅读 更多 +
