doc:articles:nomenclature

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
doc:articles:nomenclature [2012/01/10 01:17]
vrana Formatting
doc:articles:nomenclature [2017/09/22 13:28] (current)
Line 1: Line 1:
-====phpdoc Nomenclature and Style Guide==== +This page has been removed, in favor of [[http://doc.php.net/tutorial/style.php|new 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/​International English) should be used. Various resources are available at http://​dict.org/​.  +
-Various grammar rules, like for affect vs. effect, there vs their, can be found here: http://​owl.english.purdue.edu/​handouts/​grammar/​ +
- +
-  * 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 betterbecause it is the language learned ​in many countries as foreign. +
-  * note: I (Tularis) agree that International would be better fitting. There'​s a reason why it's often called International after all. As Techtonik noted above, the International version is what is taught in schools here aswell (Netherlands),​ though people often use a combination ​of both American English and International English. +
- +
-==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,​ 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. +
- +
-===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 "​less"​ vs. "​fewer"​ can be confusing. As a general rule, "​less"​ is used when the subject  +
-cannot be precisely quantified. +
- +
-==Examples== +
-  * "The new version is less buggy" is correct. +
-  * "There are less bugs in the new version"​ should be "There are fewer bugs in the new version."​ +
- +
-===Chronology=== +
-When referring to a specific version of PHP, "​since"​ should not be used. "As of" should be used in this case.   +
-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,​ 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| +
-|command line|commandline,​ CLI| +
-|email|e-mail| +
-|[[http://pear.php.net/manual/en/​standards.exampleurls.php|example.com]]|php.net,​google.com| +
-|Linux|linux,​ *n*x, *nix, *nux, etc| +
-|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://​www.w3.org/​QA/​Tips/​noClickHere|*]]|click here,go here| +
- +
-!!TODO: Alphabetize this, add more!!+
doc/articles/nomenclature.txt · Last modified: 2017/09/22 13:28 (external edit)