|
|
| (12 intermediate revisions by 7 users not shown) |
| Line 1: |
Line 1: |
| {{Cleanup | reason=Auto-imported from ExpressionEngine.}}
| | [[Category:Writing Guidelines]] |
|
| |
|
| h1. Language Guidelines
| |
|
| |
|
| This page is part of the [[QtWritingGuidelines | Qt Writing Guidelines]]. | | This page is now integrated as part of the [[Qt Writing Guidelines]]. |
| | |
| == Idioms and usage ==
| |
| | |
| === Since/as/because and ambiguity ===
| |
| | |
| According to MSTP both "since" and "as" need to be avoided because they can lead to ambiguous interpretations (causal meaning or temporal meaning). MSTP recommends using "because".
| |
| | |
| The Canadian Writer's Handbook also recommends not using "since" and "as".
| |
| | |
| The Chicago Manual of Style doesn't mention this issue.
| |
| | |
| A very good article in this respect is Grammar Girl's discussion of this topic:
| |
| http://grammar.quickanddirtytips.com/although-versus-while.aspx .
| |
| | |
| == Spelling ==
| |
| | |
| Qt documentation follows the American spelling.
| |
| | |
| === Latin expressions commonly used in English ===
| |
| | |
| i.e. (that is)
| |
| e.g. (for example)
| |
| cf. (compare)
| |
| etc. (and so forth)
| |
| vs.(versus)
| |
| et al. (and others)
| |
| | |
| It is advisable to use the English equivalent for better readibility.
| |
| | |
| == Punctuation ==
| |
| | |
| === Oxford comma ===
| |
| | |
| In punctuation, a serial comma (also called Oxford comma) needs to be placed immediately before the conjunction (often "and" or "or") in a series of three or more terms.
| |
| | |
| Example:
| |
| | |
| I would like crackers, cheese, and garlic.
| |
| | |
| === The comma as a separator between compound sentences. ===
| |
| | |
| Use commas to separate independent clauses when they are joined by any of these seven coordinating conjunctions: and, but, for, or, nor, so, yet.
| |
| | |
| However, the comma can be dropped in the following cases:
| |
| | |
| * if both independent clauses are quite short, especially if the two clauses are very closely related, and even more so if the subject of both clauses is the same, or
| |
| | |
| * if only the first clause is quite short, especially if the two clauses are very closely related, and even more so if the subject of both clauses is the same.
| |
| | |
| === Periods and spaces ===
| |
| | |
| The period ending a sentence should be followed by 1 space.
| |
| | |
| An exception to this rule is the legal text in the beginning of Qt code, which can have 2 spaces after a period.
| |
| | |
| == Grammar issues ==
| |
| | |
| === Genitive ===
| |
| | |
| Can we use the possessive 's if the owner is not a person ?
| |
| | |
| Example:
| |
| * the item's width
| |
| * the width of the item
| |
| | |
| Both are correct. There is presently no rule stating that the owner cannot be an inanimate object.
| |
| | |
| === An URL or a URL ? ===
| |
| | |
| A URL.
| |
| | |
| If the "u" is long, the article is "a". For example, a uniform, a university, a Ugandan man.
| |
| | |
| If it is short, the article is "an". For example, an understatement, an undermining comment, an underdog team.
| |
| | |
| == Usage and idioms ==
| |
| | |
| === Using the second personal pronoun in manuals ===
| |
| | |
| Avoid using "you" in technical documents.
| |
| | |
| When correcting this, use the passive voice, an imperative, and/or rephrase the sentence.
| |
| | |
| For example:
| |
| You can override this function for your delegate if you need extra logic to decide which transition to return.
| |
| ==> This function can be overridden for the delegate if extra logic is required to decide which transition to return.
| |
| | |
| == Sources ==
| |
| | |
| The Chicago Manual of Style, 14th edition. The University of Chicago Press.
| |
| "English Language & Usage": http://english.stackexchange.com/about.
| |
This page is now integrated as part of the Qt Writing Guidelines.