9c2a3e006c
This patch adds some missing newlines and trims multiple newlines into one. According to POSIX, a line is a sequence of zero or more non-' <newline>' characters plus a terminating '<newline>' character. [1] Files should normally have at least one final newline character. C89 [2] and later standards [3] mention a final newline: "A source file that is not empty shall end in a new-line character, which shall not be immediately preceded by a backslash character." Although it is not mandatory for all files to have a final newline fixed, a more consistent and homogeneous approach brings less of commit differences issues and a better development experience in certain text editors and IDEs. [1] http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_206 [2] https://port70.net/~nsz/c/c89/c89-draft.html#2.1.1.2 [3] https://port70.net/~nsz/c/c99/n1256.html#5.1.1.2
3.1 KiB
Style guidelines
Technical requirements
- All files must be encoded using UTF-8 (without BOM)
- Use only Unix line endings (
\n)
Line lengths
Please aim to keep lines in an XML file around 80 characters long or less. This is a loose requirement and 100 is probably acceptable as a maximum length. This aids in keeping diffs simple, which is particularly useful for translators, so follow this rule carefully.
Whitespaces
For XML, indent using one space. Do not use tabs. PHP code, in examples, uses four spaces for indentation, since the code should adhere to the PEAR Coding Standards.
Punctuation
Punctuation in the PHP Manual follows regular grammatical rules. When writing flowing sentences, such as in function descriptions, normal punctuation should be used. Lists, titles, and sentence fragments should not be punctuated with a period. Sentences need not have two spaces between them. Commas and apostrophes should be used appropriately.
Personalization
The PHP Manual is a technical document, and should be written so. The use of "you" is rampant in the manual, and presents an unprofessional image. The only exceptions to the personalization rule are: the PHP Tutorial and FAQs.
Example:
INCORRECT: You can use the optional second parameter to specify tags that should not be stripped.
CORRECT: The optional second parameter may be used to specify tags that should not be stripped.
Chronology
- When referring to a specific version of PHP, "since" should not be used. "As of" should be used in this case.
- In changelogs, newer PHP versions go above older ones.
- If a changelog entry applies to multiple PHP versions, separate them by a comma with the lower version first.
Example:
<entry>5.2.11, 5.3.1</entry>
General Grammar
The PHP Manual should be written with particular attention to general English grammar. Contractions should be used appropriately. Special attention should be applied to sentence construction when using prepositions (i.e., sentences should not end in prepositions).
PHP Manual Terms
Various non-english, technical terms are used throughout the PHP Manual, without clear indication of their appropriate spelling. The following list clears up this issue:
| Appropriate Use | Inappropriate Use(s) |
|---|---|
| any way | anyway, anyways |
| appendices | appendixes |
| built-in | built in, builtin |
| example.com | php.net, google.com |
| extension | module |
| Linux | linux, nx, *nix, *nux, etc |
| PHP 5 | PHP5, PHP-5 |
| PHP 4.3.0 | PHP 4.3, PHP 4.3.0RC2, PHP 5.0.0BETA, PHP 4.3.0PL1 |
| superglobals | super globals, autoglobals |
| web server | webserver |
| the Foo Page | click here, go here |
| Unix | UNIX (it's a registered trademark) |
| Windows | windows (when referring to Microsoft Windows) |