编译PHP手册的新办法
作者：Haohappy
来源：PHPEye开源社区 2008-10-15 最后更新：2009-02-13 09:01:54
收藏:
参考：http://wiki.php.net/doc/phd
PHP手册有了新的编译方式，和原来的编译方式相比，简单多了！
首先安装PhD (the [PH]P based [D]ocbook renderer):
$ pear channel-discover doc.php.net
$ pear install doc.php.net/phd-beta
通过CVS更新PHP中文手册源文件到本地：
$ cvs -d:pserver:cvsread@cvs.php.net/repository co phpdoc-zh
然后进行php中文手册目录
$ cd phpdoc-zh
$ php configure.php --with-lang=zh
有时候可能因为手册章节中某些xml文件内容格式不对，无法生成.manual.xml，可以使用下面的参数强制生成。
--enable-force-dom-save
如果想查看详细的出错原因，可以加上以下参数：
--enable-xml-details
故完整命令为：
php configure.php --with-lang=zh --enable-force-dom-save --enable-xml-details
如果要编译CHM格式的手册，请使用以下参数：
--enable-chm
编译后会生成一个chm目录，其中包含了生成chm需要的文件。
编译手册：
$ phd -d .manual.xml
注意，如果要编译chm，需要使用-L/--lang 参数来指定chm的头部信息，否则生成的chm相关文件可能不正确。例如：
$ phd -d .manual.xml -L zh
如果编译正常会在chm目录下生成以下三个文件及一个res目录（其中是生成的html文件）：
- php_manual_zh.hhc
- php_manual_zh.hhk
- php_manual_zh.hhp
注意：
如果编译平台为Windows，要使用PHP5.3.0以上版本，因为需要getopt()函数，而该函数在php5.3之前在win平台无效。
编译后生成的手册文件位于html目录中。首页为index.html。
注：
1. 可能需要安装nsgmls，该命令在jade软件中。
yum install jade
2. 编译过程中如果出现以下错误：
Strict Standards: date(): It is not safe to rely on the system's timezone settings. Please use the date.timezone setting, the TZ environment variable or the date_default_timezone_set() function. In case you used any of those methods and you are still getting this warning, you most likely misspelled the timezone identifier. We selected 'America/Denver' for 'MST/-7.0/no DST' instead in /home/www/php/lib/php/phd/config.php on line 76 [12:53:45 - VERBOSE_TOC_WRITING] Wrote TOC (/home/php_manual/phpdoc-zh/php/toc/imagick.setup.inc)
请编辑php.ini设置时区
[Date] date.timezone = America/Los_Angeles （按实际情况，如中国可写为PRC）
编译CHM格式的手册
编译chm时，会生成一个chm目录，其中有一个res目录，包含chm文件要使用的html文件。
用PHD编译的html文件（即res目录中的文件）默认就是带有CSS样式的。
将Linux下编译得到的chm目录打包后传到Windows下。
解压缩到D:\cygwin\home\hao\phpdoc-zh\chm
注意在chm目录中应该包含
make_chm.bat
make_chm.php
make_chm_fancy.php
等多个文件。
编辑make_chm.bat
set PHP_PATH=c:\php5\php.exe
set PHP_HELP_COMPILE_LANG=zh
set PHP_HELP_COMPILER="C:\Program Files\HTML Help Workshop\hhc.exe"
set PHP_HELP_COMPILE_DIR=chm\res (注意此处html不可写成./res)
set PHP_HELP_COMPILE_FANCYDIR=chm\fancy (指定编译生成的较为美观的html文件放置的目录)
此行可不写，会导致出错
编译
C:> cd E:\projects\php_manual\zh\phpdoc-zh
E:\projects\php_manual\zh\phpdoc-zh> chm\make_chm.bat zh normal
由于现在生成的html文件已经带有CSS样式，所以我们可以直接使用：
chm\make_chm.bat zh -D . normal
注意要在chm目录上级目录下执行编译命令！
编译有两种方式：normal和fancy fancy方式生成的文件较为美观
默认为fancy方式。
- hhc, hhk, hhp三个文件都是由make_chm.php生成。
- make_chm_fancy.php主要负责将源目录中的普通html文件转换为美观的fancy html文件。
如加入css调用等。并将结果文件存入以上设置的fancy目录。
然后复制fancy-index.html, style.css 和spacer.gif三个文件到abcd目录中。
- style.css 源自make_chm_style.css ，可以从docs.php.net 网站上下载site.css放入其中，效果较为美观。
- spacer.gif 源自make_chm_spc.gif
- bat调用ms的HTML Help Workshop将abcd目录中的文件编译成chm。
注意编译时需要phpdoc-zh\zh中的文件，如make_chm_index.html
注意：
官方的make_chm_fancy.php 有bug
其中函数function fancy_design($fname){}
里面的正则表达式只能替换大写的HTML，而实际上使用本文介绍的新编译方法生成的normal html中的html标签是小写的。
要将正则的patterns全部改为大小写不敏感 /pattern/i 否则普通的html不会被转换成较为美观的html。
重新编译时，可以把chm\chm目录下所有文件删除（不删除也会被覆盖）。
收藏:
|
