Qt wiki will be updated on October 12th 2023 starting at 11:30 AM (EEST) and the maintenance will last around 2-3 hours. During the maintenance the site will be unavailable.

Language Guidelines: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
No edit summary
 
No edit summary
Line 1: Line 1:
=Language Guidelines=
h1. Language Guidelines


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


==Idioms and usage==
== Idioms and usage ==


===Since/as/because and ambiguity===
=== 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”.
According to MSTP both &quot;since&amp;quot; and &quot;as&amp;quot; need to be avoided because they can lead to ambiguous interpretations (causal meaning or temporal meaning). MSTP recommends using &quot;because&amp;quot;.


The Canadian Writer’s Handbook also recommends not using “since” and “as”.
The Canadian Writer's Handbook also recommends not using &quot;since&amp;quot; and &quot;as&amp;quot;.


The Chicago Manual of Style doesn’t mention this issue.
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 .
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==
== Spelling ==


Qt documentation follows the American spelling.
Qt documentation follows the American spelling.


===Latin expressions commonly used in English===
=== 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)
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.
It is advisable to use the English equivalent for better readibility.


==Punctuation==
== Punctuation ==


===Oxford comma===
=== 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.
In punctuation, a serial comma (also called Oxford comma) needs to be placed immediately before the conjunction (often &quot;and&amp;quot; or &quot;or&amp;quot;) in a series of three or more terms.


Example:
Example:
Line 35: Line 35:
I would like crackers, cheese, and garlic.
I would like crackers, cheese, and garlic.


===The comma as a separator between compound sentences.===
=== 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.
Use commas to separate independent clauses when they are joined by any of these seven coordinating conjunctions: and, but, for, or, nor, so, yet.
Line 45: Line 45:
* 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.
* 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===
=== Periods and spaces ===


The period ending a sentence should be followed by 1 space.
The period ending a sentence should be followed by 1 space.
Line 51: Line 51:
An exception to this rule is the legal text in the beginning of Qt code, which can have 2 spaces after a period.
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==
== Grammar issues ==


===Genitive===
=== Genitive ===


Can we use the possessive ‘s if the owner is not a person ?
Can we use the possessive 's if the owner is not a person ?


Example:
Example:<br />* the item's width<br />* the width of the item
 
* 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.
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> ?===
=== An URL or a URL ? ===


A <span class="caps">URL</span>.
A URL.


If the “u” is long, the article is “a”. For example, a uniform, a university, a Ugandan man.
If the &quot;u&amp;quot; is long, the article is &quot;a&amp;quot;. 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.
If it is short, the article is &quot;an&amp;quot;. For example, an understatement, an undermining comment, an underdog team.


==Usage and idioms==
== Usage and idioms ==


===Using the second personal pronoun in manuals===
=== Using the second personal pronoun in manuals ===


Avoid using “you” in technical documents.
Avoid using &quot;you&amp;quot; in technical documents.


When correcting this, use the passive voice, an imperative, and/or rephrase the sentence.
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.
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==
== Sources ==


The Chicago Manual of Style, 14th edition. The University of Chicago Press.<br /> “English Language &amp; Usage”: http://english.stackexchange.com/about.
The Chicago Manual of Style, 14th edition. The University of Chicago Press.<br />&quot;English Language &amp; Usage&amp;quot;: http://english.stackexchange.com/about.

Revision as of 11:06, 24 February 2015

h1. Language Guidelines

This page is part of the Qt Writing Guidelines.

Idioms and usage

Since/as/because and ambiguity

According to MSTP both "since&quot; and "as&quot; need to be avoided because they can lead to ambiguous interpretations (causal meaning or temporal meaning). MSTP recommends using "because&quot;.

The Canadian Writer's Handbook also recommends not using "since&quot; and "as&quot;.

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&quot; or "or&quot;) 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&quot; is long, the article is "a&quot;. For example, a uniform, a university, a Ugandan man.

If it is short, the article is "an&quot;. For example, an understatement, an undermining comment, an underdog team.

Usage and idioms

Using the second personal pronoun in manuals

Avoid using "you&quot; 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&quot;: http://english.stackexchange.com/about.