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 http://www.bartleby.com/61/ and the http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html.
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.
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.
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.
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.
- 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.
- Do not use apostrophes to denote possession.
- Do not use apostrophes to denote contractions.
- Do not use apostrophes to denote plurals.
Do not use the definite article the to begin any of the following items:
- Manual titles
- Chapter titles
- Figure captions
- Table captions
- 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.
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
- 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.
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
- Use the same rules as for headings.
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
Rules: Do not use commands as verbs.
Rules: Do not use contractions such as can't, don't, or isn't.
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.
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
- 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.
Rules: See Section 1.4.4 ― Do Not Offend Your Audience.
Rules: Use standard American English grammar rules, see the http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html.
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 Section 2.1 ― Section Headings for more information about headings.
Use hyphens in the following situations:
- With a numeral in a compound modifier
- To prevent ambiguity
- With some standard prefixes and suffixes. Use the http://www.bartleby.com/61/ 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 http://www.bartleby.com/61/, and that uses a common prefix
- With trademarked terms
- Latin terms
Rules: Do not use Latin terms. Use an equivalent English term instead.
Rules: Do not use the term like to denote equivalence or similarity.
Rules: Introduce a list with a complete sentence that ends with a colon.
Spell out numbers in the following situations:
- Numbers from zero through nine unless the number is part of a measurement.
- 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
Use numerals in the following situations:
- The number 10 or greater
- Negative numbers
- Most fractions
- Units of time smaller than one second
- References to bits and bytes
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
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.
Rules: Use standard American English punctuation rules. In addition to the specific points of punctuation in this section, see also the http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html.
- Punctuation in numbers
- Do not use a comma in numerals of four digits.
- Use a comma in numerals of more than four digits.
- Quotation marks
- 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.
Rules: Do not use semicolons.
Rules: Use standard American English spelling rules, see the http://www.bartleby.com/61/ for guidelines.
Rules: For manual titles use the same rules as for headings.
- Use standard abbreviations for units of measurements, do not invent your own abbreviations.
- See Appendix B ― 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.