Language Guidelines: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
No edit summary
 
No edit summary
 
(16 intermediate revisions by 8 users not shown)
Line 1: Line 1:
=Language Guidelines=
[[Category:Writing Guidelines]]


This page is part of the [[QtWritingGuidelines|Qt Writing Guidelines]].


==Idioms and usage==
This page is now integrated as part of the [[Qt Writing Guidelines]].
 
===Since/as/because and ambiguity===
 
According to <span class="caps">MSTP</span> both “since” and “as” need to be avoided because they can lead to ambiguous interpretations (causal meaning or temporal meaning). <span class="caps">MSTP</span> 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:<br />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)<br /> e.g. (for example)<br /> cf. (compare)<br /> etc. (and so forth)<br /> vs.(versus)<br /> 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 <span class="caps">URL</span> or a <span class="caps">URL</span> ?===
 
A <span class="caps">URL</span>.
 
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:<br /> You can override this function for your delegate if you need extra logic to decide which transition to return.<br /> ==&gt; 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.<br /> “English Language &amp; Usage”: http://english.stackexchange.com/about.

Latest revision as of 14:24, 15 December 2024


This page is now integrated as part of the Qt Writing Guidelines.

Retrieved from "https://wiki.qt.io/index.php?title=Language_Guidelines&oldid=43580"