PHP手册翻译/编译指南[5]

中文手册翻译小组的邮件列表：
[email protected]
Automatization with scripts
Table of Contents
12.1.
aspell.php

12.2.
check-references.php

12.3.
diff_en_rev.php

12.4.
extensions.xml.php

12.5.
html_syntax.php

12.6.
iniupdate/*.php

12.7.
xml-check.php
The PHP manual is very big and the PHP sources change every day. To help the documentation writers's work, we have developed a couple of scripts during the last years. Below you will find a list of the scripts, as well a short explanation and usage tips for each one.
12.1. aspell.php
This script can be used to escape or unescape manual files for use with aspell. Escaping moves the contents of tags with non-English texts (like ,  or ) to the attribute aspell so the Aspell will ignore them. Unescaping is the opposite process.
File en.pws contains words not included in the Aspell dictionary but valid in the PHP manual and can be used as the personal dictionary.
check-references.php
This script tries to parse the PHP sources and compares the facts about function parameters (their count, types, optionality and the need of passing them as reference) with the documentation. Only easy parsable functions from Zend, extensions, PECL and SAPI sources are checked.
Used rules are not absolutely precise, they are rather heuristics. Thus not everything printed automatically denotes errors and sources should be always read by a human before modifying the documentation. If the sources correspond to the documentation and this script still produces error, function should be added to one of $difficult_* arrays defined in the beginning of this script.
diff_en_rev.php
One of the scripts helping translators.
It prints a diff between the current English version and the translated version of a file. It uses the  tag to determine the translated version. If the local English file has different revision, cvs diff is executed to obtain the list of changes.
It is possible to pass a directory name instead of file name. In this case, list of modified files in the directory is printed.
extensions.xml.php
The extensions.xml.php script creates the
extension categorization appendix
. It collects the data from the reference.xml files and updates the en/appendices/extensions.xml file.
The tags supported for the reference/*/reference.xml files include:
Table 12-1.
Tag
Explanation
The purpose of the extension, specified by an ID. There are several IDs available, which can be consulted in the en/extensions.ent file. They look like database.vendors or xml.
If none of the available categories fits your extension, you can create a new one. To do so, you must add a new entity in the en/extensions.ent file, like: XML Manipulation'>. After this, you still need to edit en/appendices/extensions.xml and create a new section for your ID, by copying an already existent section. This isn't done automatically to allow you to choose the order of the sections.
This tag can have multiple values, that should be separated by commas. Valid values include: core (for PHP core extensions, like the strings or date extension), pecl (if the extension lives in PECL), bundled (if the extension is bundled with the main PHP distribution), and external (if the extension relies on external - and not bundled - libraries).
This tag is optional and can only have two values, either deprecated or experimental.
Note: If you mark an extension as deprecated and if it is very old and unusable, you shouldn't add the purpose and membership tags, so that the extension doesn't appear in the appendix (to avoid confusing users).
The script should warn you for missing tags or even bogus values, although it won't report any XML errors. So, you have the responsability to run make test before running this script. Failing to do so, may lead to unexpected results.
Note: This script requires PHP >= 5 with SimpleXML.
html_syntax.php
This script is used in the build process to syntax highlight PHP examples both for the online and downloadable manuals.
iniupdate/*.php
The iniupdate directory contains a set of scripts that are used to generate the en/appendices/ini.xml table. They also update the information that is dispersed in the en/reference/*/ini.xml files.
To use this script, you must download all the PHP 4, 5 and 6 sources (which will take a long time), so that the script can create a DB with the history of the changes between the versions. To do that, you can just run the ./update-all script. If you are using the 'functable' script as well, you may just create a symlink to its sources, as the sources are the same :) The rest of the process is explained in the README file.
The core of the scripts is in ini_search_lib.php, and it is very regex based. The main regexes work correctly, although some heuristics are used to catch the cfg_get_*() uses. The generate_changelog.php is used to generate the changelog (based on the data previously collected in the DB).
xml-check.php
Build process of the whole manual can be very slow. This script takes one XML file, creates xml-check.xml in the documentation root with the beginning and ending DocBook tags and parses this file with xmllint. Beginning tags are taken from manual.xml.in.
Detected errors are printed thus empty output means correct file.