编译PHP手册的新办法

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

如果要编译CHM格式的手册，请使用以下参数：

--enable-chm

编译后会生成一个chm目录，其中包含了生成chm需要的文件。

编译手册：

$ phd -d .manual.xml

注意：

如果编译平台为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格式的手册

将Linux下编译得到的html目录打包后传到Windows下。

解压缩到D:\cygwin\home\hao\phpdoc-zh\chm\html

注意在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_COMPILE_DIR=html (注意此处html不可写成./html)
set PHP_HELP_COMPILE_FANCYDIR=abcd (指定编译生成的较为美观的html文件放置的目录)
此行可不写，会导致出错



编译

make_chm.bat zh normal

编译有两种方式：normal和fancy fancy方式生成的文件较为美观

默认为fancy方式。

1. hhc, hhk, hhp三个文件都是由make_chm.php生成。
2. make_chm_fancy.php主要负责将源目录中的普通html文件转换为美观的fancy html文件。
如加入css调用等。并将存入以上设置的abcd目录。
然后复制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
3. 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目录下所有文件删除（不删除也会被覆盖）。