doc:articles:nomenclature
Differences
This shows you the differences between two versions of the page.
doc:articles:nomenclature [2012/01/10 01:17] vrana Formatting |
doc:articles:nomenclature [2017/09/22 13:28] |
||
---|---|---|---|
Line 1: | Line 1: | ||
- | ====phpdoc Nomenclature and Style Guide==== | ||
- | ==Purpose== | ||
- | This document exists to clarify the nomenclature and grammatical style of the PHP Manual. | ||
- | |||
- | ==Reference== | ||
- | As a general rule, American English (and not British/ | ||
- | Various grammar rules, like for affect vs. effect, there vs their, can be found here: http:// | ||
- | |||
- | * note: I (Sean) don't care if we choose International English over American (I _am_ Canadian, after all). I just think we should choose one or the other, and stick to it | ||
- | * note: I (Aidan) think American english sucks, I'd prefer International. | ||
- | * note: I (Techtonik) also think International is better, because it is the language learned in many countries as foreign. | ||
- | * note: I (Tularis) agree that International would be better fitting. There' | ||
- | |||
- | ==Examples== | ||
- | * color, not colour | ||
- | * favorite, not favourite | ||
- | |||
- | ===Punctuation=== | ||
- | Punctuation in the PHP Manual follows regular grammatical rules. When writing flowing sentences, such as in function descriptions, | ||
- | |||
- | ===Personalization=== | ||
- | The PHP Manual is a technical document, and should be written so. The use of " | ||
- | |||
- | ===Exceptions=== | ||
- | The only exceptions to the personalization rule are: | ||
- | * The PHP Tutorial | ||
- | * FAQs | ||
- | |||
- | ==Examples== | ||
- | (from **strip_tags** | ||
- | |||
- | "You can use the optional second parameter to specify tags which should not be stripped." | ||
- | |||
- | should be: | ||
- | |||
- | "The optional second parameter may be used to specify tags which should not be stripped." | ||
- | |||
- | ===Quantifiers=== | ||
- | The use of " | ||
- | cannot be precisely quantified. | ||
- | |||
- | ==Examples== | ||
- | * "The new version is less buggy" is correct. | ||
- | * "There are less bugs in the new version" | ||
- | |||
- | ===Chronology=== | ||
- | When referring to a specific version of PHP, " | ||
- | Although the new style will not have this structure (a CHANGELOG instead), it's still good to know :) | ||
- | |||
- | ==Example== | ||
- | As of PHP 5, the return value is an array, not bool. | ||
- | |||
- | ===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 | ||
- | (ie, sentences should not end in prepositions). | ||
- | |||
- | ===PHP Manual Terms=== | ||
- | Various non-english, | ||
- | 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| | ||
- | |command line|commandline, | ||
- | |email|e-mail| | ||
- | |[[http:// | ||
- | |Linux|linux, | ||
- | |PHP 4| PHP4, PHP-4| | ||
- | |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| | ||
- | |extension|module| | ||
- | |Windows|windows (when referring to Microsoft Windows)| | ||
- | |Unix|UNIX, UNIX is a registered trademark| | ||
- | |the foo page [[http:// | ||
- | |||
- | !!TODO: Alphabetize this, add more!! |
doc/articles/nomenclature.txt · Last modified: 2017/09/22 13:28 (external edit)