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

剑心通明

PHP Documentation HOWTO

几个关键的文件：
manual.xml
            PHP手册的核心文件，用于“链接”各部份，包含了每个章节的标题和引用。该文件由配置过的manual.xml.in生成。
entities/file-entities.ent
            包含所有文件中的实体定义。XML文件的实体由configure生成，所以不要编辑该文件。
entities/global.ent
            所有XML文件的全局内部文本实体。所有外部链接、EMAIL地址和“宏”储存的地方。
dsssl/*
            我们使用的DSSSL样式表，用于生成手册的各种版本。
xsl/*
            XSL样式表，用于生成HTML、phpweb、HTML帮助（chm）和输出。
your_language/language-defs.ent
             包含该语言特定的实体。常见的有标题等，你也要把该语言特定的实体放在此处。
your_language/language-snippets.ent
            已经翻译的经常使用的XML小片断，如警告、注意等。
your_language/translation.xml
           本文件用于存储所有翻译信息，如翻译者的介绍，当前在译的文件等等，在英文版本的手册中本文件不出现。
your_language/some_directory
             PHP手册按分类分成若干个目录。其中内容最多的目录是PHP扩展参考，即reference目录。
When you work on phpdoc XML files, you should stick to these conventions, to ease the team work in the module.

Insert ID attributes in all major section tags such as part, chapter, sect1 etc. The HTML stylesheet will name the HTML files after these IDs.

Function reference IDs look like this (case should be consistent with the rest of the function naming standards, i.e. lowercase): function.mysql-connect. Please note that since underscores cannot be used in IDs, they should be replaced by minus signs (-).

Unlike function reference IDs method reference IDs are case-sensitive. Special operators ::, -> and underscores are replaced by the same minus signs (-). For example function.DOMCharacterData-deleteData is an ID for DOMCharacterData->deleteData and function.ArrayObject-constructor is for ArrayObject::__constructor method accordingly. Note an exception when operators :: and -> followed by two underscores are replaced with one minus sign (-).

Function reference section IDs () look like this: 'ref.category', for example: 'ref.ftp'.

Add PHP example code programlistings always with a role attribute set to "php". Never add any other programlisting or PHP output with such a role. It is reserved for PHP source code only. This role is used to detect PHP code and highlight it.

The contents of examples with programlistings start on column 0 in the XML code. Indenting, bracketing and naming conventions in examples should adhere to the PEAR coding standards.

All examples use the  form instead of . Use  for examples, since it eliminates the need to change  to , etc. Examples look much better, and easily manageable.

Deprecated aliases and syntax should not be used in examples.

Use the  when a function is not available in some special cases, or when the parameter list of a function has changed, but not for every little thing like mentioning that the function also can accept 'foo' instead of 'bar' as value to a parameter. Use notes with care.
Make sure note elements are always children of the main element in a file, unless the note belongs to a specific item in the text, such as an example:
   
   
   
   
     The output is:
   
   
   
     
      This example only works on Unices.
     
   
   
  
If there is something dangerous to document such as the chroot(), or when something can be seen as a weirdness in the language such as weird autoconversion of types, use the  element.
The  can be used in cases where you might want to document a performance issue.

For comments in example, use // for single line comments (preferable above the lines of code the comment comments on), and use /* .. */ for multiline comments:
// This line execute foo
foo();
/* The next few lines also execute foo, but in a
* weird way */
$var = 'foo';
$var();

If an example uses arguments specific to a newer version of PHP, it is helpful to note this in the example:
foo("bar", "baz"); // second argument was added in PHP 4.0.3New arguments are denoted in the main text of the entry using the form:

  The second parameter was added in PHP 4.0.3.

The language constants true, false and null should be written as &true;, &false; and &null;. There are other shortcuts, such as &php.ini;. These are stored in global.ent.

All English XML files should have a  comment as the second line after the  tag. This comment is not necessary for non-English files.

Whitespace changes in the English tree should be prevented as much as possible: it is more important to keep a good change-history of real changes, because of the translations. If a whitespace change is really needed, do it at least in a separate commit, with a clear comment such as 'WS fix' or 'Whitespace fix'.

Never use tabs, not even in example program listings. XML should be indented with one space character for each level of indentation; example code uses four spaces.

Always use LF (Line Feed) for the only newline character in files, this is the Unix standard. Never use CR LF (Windows) or CR (Mac) even, when editing Windows specific files (such as *.bat). It eases the editing works.

In the docs, the types are denoted as: boolean (bool in prototypes), integer (int in prototypes), float (not double!), array, object (not class!), resource and null (all lowercase). For objects different from stdClass, use the class name instead of object.
In prototypes, you can also use mixed (various types), or number (either integer or float). A callback is denoted as callback.
Do not use mixed, if the return value is of a certain (not boolean) type, and FALSE only on error. Provide the primary return type as the return type of the function, and write down in the explanation, that it returns FALSE on error. Use &return.success; if the function returns TRUE on success, and FALSE on failure.
If a function requires no arguments, use  instead of void, since the former is the correct DocBook XML tag.
If a function has an undefined return-value, use the word void.

In a prototype, if there are multiple - really distinct - possibilities, simply make it two! See en/reference/math/functions/min.xml for an example.

Aliases: in refpurpose, put: Alias of realfunc. Do not specify a function prototype synopsis, and nothing but simply the text: This function is an alias of realfunc. This way, people can go to realfunc straight from the ref.foo page.

Document examples always with the following structure:

  
  
]]>
  
  
   The output is:
  
  
  

Chapter 7. What to Document?

Only major functions should be documented; functions which are deprecated variants may be mentioned, but should not be documented as separate functions. They instead should be referenced in the parent function as an alias. Functions which have completely different names, however, should be documented as separate entries, for ease of reference. The aliases.xml appendix is the place to store aliases not documented elsewhere.
For example mysql_db_name and mysql_dbname will be documented as the same function, with the latter being listed as an alias of the former, while show_source and highlight_file will be documented as two different functions (one as an alias), as the names are completely different, and one name is not likely to be found if looking for the name of the other.

Function names should be created, and documented, in lowercase format with an underscore separating the name components. Names without underscores are often only kept for backward compatibility. Document the function named with underscores separating components, and mention the old one as an alias.
Note: It is up to the PHP developers to give names to functions. A PHP documentation writer only uses the name provided to document the function. If you think that a function name is not appropriate, open a discussion on the
internals@lists.php.net
list, by sending a mail to that address.
Good: mcrypt_enc_self_test, mysql_list_fields
OK: mcrypt_module_get_algo_supported_key_sizes (could be mcrypt_mod_get_algo_sup_key_sizes?), get_html_translation_table (could be html_get_trans_table?)
Bad: hw_GetObjectByQueryCollObj, pg_setclientencoding

Functions which are kept only for backwards compatibility should be listed under their current parent names, and not documented as separate functions. Backwards compatible functions and documentation for them should be maintained as long as the code can be reasonably kept as part of the PHP codebase. Also see the appendix aliases.xml.

Short but complete code examples are much more desirable than long ones. If a function is extremely complex, a suitable place to put a longer example is in the chapter introduction. This example can hold code for other functions in the same chapter.

Brevity is appreciated. Long-winded descriptions of each and every function are not appropriate for the reference sections. Using the errata comments as guidelines, it's easier to tell when more documentation is needed, as well as the inverse, when too much documentation in one section has increased confusion.
[1]



本文来自ChinaUnix博客，如果查看原文请点：http://blog.chinaunix.net/u/4206/showart_710255.html