# Grammar and Usage Guidelines

This chapter contains an alphabetical list of grammar and usage guidelines for use in GNOME documentation. Many of these guidelines are only applicable to English-language usage, see the American Heritage Dictionary and the Chicago Manual of Style.

Abbreviations

- Rules: | A shortened form of a word or phrase that takes the place of the full word or phrase, for example Dr., a.m., p.m., and so on. Apply the following rules when you use abbreviations: Avoid creating new abbreviations. Unfamiliar abbreviations can confuse rather than clarify a concept. Do not explain or expand familiar abbreviations. Do not include familiar abbreviations in the glossary of your manual.

Adjectives

- Rules: | Use adjectives with caution. If an adjective is necessary to differentiate between items, then use adjectives. In all cases, test whether the phrase can stand alone without the adjective.

Acronyms

- Rules: | A term that represents a multi-word term. Typically, acronyms are formed in the following ways: From the first letters of each word in a compound term, for example Table of Contents (TOC). From recognizable parts of a compound term, such as GNU Object Model Environment (GNOME). Apply the following rules when you use acronyms: On the first occurrence of an acronym, spell out the full term, with the acronym in parentheses. Do not spell out the full compound for well-known acronyms, unless you think the information is useful for readers. Avoid creating new acronyms. Unfamiliar acronyms can confuse rather than clarify a concept. Write the acronym in uppercase letters, unless there is a compelling case for lowercase. Include the acronym and the full term in the glossary of your manual.

Adverbs

- Rules: | Use adverbs with caution. If an adverb is necessary to qualify the function of a component, then use an adverb. In all cases, test whether the phrase can stand alone without the adverb. Classic superfluous adverbs are: simply, easily, quickly.

Anthropomorphism

- Rules: | Do not apply emotions, desires, or opinions to software applications. Do not apply a sense of location or dimension to a software application. You can not be in a text editor.

Apostrophe

- Rules: | Do not use apostrophes to denote possession. Do not use apostrophes to denote contractions. Do not use apostrophes to denote plurals.

Articles

- Rules: | Do not use the definite article the to begin any of the following items: Manual titles Chapter titles Headings Figure captions Table captions Callouts

Brackets

- Rules: | Do not use brackets [such as these] as a substitute for parentheses (such as these). Use brackets for optional command line entries. Do not use angle brackets to indicate variables in text, instead use the replaceable tag.

Capitalization

- Rules: | Capitalize in the following situations: All letters in acronyms, unless the acronym is a well-known exception Initial letter of the first word in a list Initial letter of the first word in a callout Initial letter of a key name, such as the Shift key Initial letter of a sentence. Avoid starting a sentence with a command name or application name that has a lowercase initial letter Initial letter of a complete sentence after a colon Do not capitalize in the following situations: A compound term that is followed by an abbreviation or an acronym When you want to emphasize something Variable names The initial letter of the first word following a colon, if the word is part of an incomplete sentence

Captions

- Rules: | Use the same rules as for headings, for all captions accompanying figures and tables. Do not put a period at the end of a caption.

Colon

- Rules: | Use a colon in the following situations: To introduce a list Before an explanation After an introduction Do not use a colon in the following situations: To introduce a figure or a table To introduce headings At the end of an introduction to a procedure

Column headings

- Rules: | Use the same rules as for headings.

Comma

- Rules: | Use commas in the following situations: To separate items in a series To separate the parts of a sentence To separate nonrestrictive phrases Instead of dashes to set off appositives With for example and similar expressions Do not use commas in the following situations: In a series of adjectives used as one modifier Between two short independent clauses

Commands

- Rules: | Do not use commands as verbs.

Contractions

- Rules: | Do not use contractions such as can't, don't, or isn't.

Dash

- Rules: | Do not use the em dash or the en dash. Use a paragraph break or a colon instead, where you want to create an introductory piece of text. If you have several items that you want to introduce, then you can use a variable list.

Ellipsis

- Rules: | Use an ellipsis in the following situations: To show that you have omitted something from a sentence To indicate a pause when you quote displayed text

Fractions

- Rules: | Use numerals for fractions in tables and in units of measurement, but spell out fractions in prose. Use a space between a numeral and a related fraction, if there is a possible ambiguity. For example: 1 1/2 instead of 11/2. If a fraction is used in a compound modifier, insert a hyphen between the fraction and the unit of measurement.

Gender

- Rules: | See fundamentals-9.

Grammar

- Rules: | Use standard American English grammar rules, see the Chicago Manual of Style.

Headings

- Rules: | Use the following capitalization rules in headings: Initial uppercase letter for the first word and the last word, regardless of part of speech Initial uppercase letter for all nouns, adjectives, and verbs Initial uppercase letter for conjunctions of four letters or longer Initial uppercase letter for prepositions of four letters or longer Initial uppercase letter for prepositions that are part of a phrasal verb All lowercase letters for conjunctions, articles, and prepositions of less than four letters See infodesign-2 for more information about headings.

Hyphen

- Rules: | Use hyphens in the following situations: With a numeral in a compound modifier To prevent ambiguity With some standard prefixes and suffixes. Use the American Heritage Dictionary for guidance In spelled-out fractions In variable names of two or more words, such as `directory-name`. Note: `filename` is an exception. Do not use hyphens in the following situations: For industry-accepted terms To construct verbs With an adverb ending in ly With numerals as single modifiers With a word that is listed as unhyphenated in the American Heritage Dictionary, and that uses a common prefix With trademarked terms

Latin terms

- Rules: | Do not use Latin terms. Use an equivalent English term instead.

Like

- Rules: | Do not use the term like to denote equivalence or similarity.

Lists

- Rules: | Introduce a list with a complete sentence that ends with a colon.

Numbers

- Rules: | Spell out numbers in the following situations: Numbers from zero through nine unless the number is part of a measurement. Approximations. Extreme values such as million, but precede the value with a numeral Any number that begins a sentence A number that is immediately followed by a numeral, for example: two 10 MB files

Numerals

- Rules: | Use numerals in the following situations: The number 10 or greater Negative numbers Most fractions Percentages Decimals Measurements Units of time smaller than one second References to bits and bytes

Parentheses

- Rules: | Use parentheses in the following situations: To contain the abbreviation of a term on the first occurrence of the full term In man page references, specifically the section number

Period

- Rules: | Use a period in the following situations: To end a sentence In file and directory names In abbreviations that can be mistaken for words, such as a.m. and U.S.

Punctuation

- Rules: | Use standard American English punctuation rules. In addition to the specific points of punctuation in this section, see also the Chicago Manual of Style.

Punctuation in numbers

- Rules: | Do not use a comma in numerals of four digits. Use a comma in numerals of more than four digits.

Quotation marks

- Rules: | Use quotation marks to indicate material that is taken verbatim from another source. Do not use quotation marks to excuse terms from legitimacy. If the term is not legitimate, then use another term. If you must use that term, declare the term in the glossary and make the term legitimate.

Semicolon

- Rules: | Do not use semicolons.

Spelling

- Rules: | Use standard American English spelling rules, see the American Heritage Dictionary for guidelines.

Titles

- Rules: | For manual titles use the same rules as for headings.

Units

- Rules: | Use standard abbreviations for units of measurements, do not invent your own abbreviations. See units for a list of units relevant to the GNOME Desktop. For further guidelines, see the IEEE Standard Dictionary of Electrical and Electronics Terms. Use periods for abbreviated units that might be mistaken for a word. Most standard abbreviations of units account for both singular and plural usage. Insert a space between the numeral and the unit of measurement.