michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: directive indentation fixes on language.rst

Browse source 
Editing language.rst file to clarify a few items
Also correcting a few things I missed earlier
Also fix title case without hyphen to be consistent

Change-Id: I463d1cdb436957a14af6ea40933f892a51b161aa
Signed-off-by: L.S. Cook <leonax.cook@intel.com>
This commit is contained in:
L.S. Cook 2015-09-28 13:28:47 -07:00 • committed by Anas Nashif
commit cb9749f443
1 changed files with 47 additions and 55 deletions
Download patch file Download diff file Expand all files Collapse all files

102
doc/collaboration/documentation/language.rst
View file

@ -3,9 +3,10 @@
Laguage Usage Guidelines
########################
This chapter provides usage guidelines with regard to words,
This section provides usage guidelines with regard to words,
punctuation, and grammar. The guidelines are not meant to replace a
review by a professional writer but rather help collaborators to submit consistent contributions.
review by a professional writer, but rather to help collaborators
submit consistent contributions.
Capitalization
**************
@ -16,12 +17,12 @@ Words should only be capitalized when:
* They are proper nouns or adjectives.
* They refer to trademarked product names.
* When they are part of a heading using title case.
* They are part of a heading using title case.
.. important::
Do not capitalize a word to indicate it has a greater status than
other words. Never change the case of variable, function or file
names; always keep the original case.
Do not capitalize a word to indicate it has a greater status than
other words. Never change the case of variable, function or file
names; always keep the original case.
Capitalization styles
=====================
@ -86,17 +87,16 @@ A few other menu capitalization rules to keep in mind:
* Put the option to be selected last. "Select
:menuselection:`View --> Side Bar --> Hide Side Bar`"
* Do not include more than 3 navigation steps in a menu selection. If
more than three steps are needed devide the steps using
* Keep menu selection navigation to three steps or fewer. When
more than three steps are needed, divide the steps using
``:guilabel:`` or ``:menuselection:``. For example: "Go to
:guilabel:`File` and select
:menuselection:`Print --> Print Preview --> Set Up`."
Software Version Capitalization
===============================
Do not capitalize the word version or letter v when listing software
or hardware version numbers. The v is lowercase and closed with the
number (no period). For example:
When referring to software or hardware versions, the letter v
should remain lower-case, and end with the version number. For example:
* Widget Pro v5.0
* Widget Master v2.1.12
@ -113,7 +113,7 @@ Plurals and Possessives
***********************
Because English plurals and possessives use the same /s/ and /z/
phonemes, they can create problems for even experienced writers. This
section deals with these issues.
section discusses some of the common use cases.
Singular vs. Plural Possessives
===============================
@ -128,9 +128,8 @@ Here are some guidelines for singular and plural possessives:
* Use apostrophe + s to show possession for a singular that ends in a
silent sibilant: Illinois's capital.
* Use apostrophe + s to show
possession for a singular that ends in a sibilant; s, x, c, z, or
others.
* Use apostrophe + s to show possession for a singular that ends in a sibilant:
s, x, c, z, or others.
The following table provides some examples with the correct and
incorrect cases and the notes that accompanies them.
@ -171,8 +170,7 @@ Apostrophe-s Anomalies
======================
If a company name ends in s, x, c, or a sibilant sound, use the
apostrophe-s ending for
possessives:
apostrophe-s ending for possessives:
Traktronix's oscilloscopes
@ -181,9 +179,9 @@ apostrophe-only ending:
Tejada Instruments' calculators
In many cases, it is actually best to avoid the possessive form
altogether for s-ending singular possessives, such as for company
names and use the company name as a nonpossessive modifier instead:
In many cases, it is best to avoid the possessive form altogether for
singular possessives that already end in s, such as for company
names. Use the company name as a nonpossessive modifier instead:
Traktronix oscilloscopes
Tejada Instruments calculators
@ -196,20 +194,17 @@ use.
Plural modifiers
================
Avoid plural modifiers. For example, it should be a system
administrator, not a systems administrator. It doesn't matter how many
systems this person manage, we don't typically use the plural of a word
to modify a noun. Here a list of exceptions:
Avoid plural modifiers. For example: system administrator, not a systems
administrator. It doesn't matter how many systems this person manages;
it's better to avoid using a plural of a word to modify a noun.
However, some exceptions do occur when the plural form is generally considered
singular: sales, physics, operations. Ask if you are unsure.
* operations manager
* sales department
* graphics team
There are always exceptions, especially when the plural form is
generally considered to be singular: sales, physics, operations. It is
best to adhere to this rule and ask if you are unsure.
Parenthetical plurals
=====================
@ -222,9 +217,8 @@ using parenthetical plurals often creates more confusion.
Correct
Men, women, children, college alumni, moose,
and even desert plants such as cacti should not
use parentheses around plurals.
Men, women, children, college alumni, moose, and even desert plants
such as cacti should not use parentheses around plurals.
Incorrect
@ -258,7 +252,7 @@ Use TRAXes, iBOXes not TRAXs, TRAX's, iBOX's, iBOXs.
Use FAACes not FAAC's, assuming it is pronounced "face".
Use FAACs not FAAC's Assuming it is pronounced "fake".
Whenever you hear the extra syllable in the plural, add the -es suffix
When you hear the extra syllable in the plural, add the -es suffix
for the plural; if you do not hear the extra syllable, add the -s
suffix for the plural.
@ -275,8 +269,8 @@ Pluralize Latin terms in body text as shown:
* Use vertexes not vertices.
.. note::
Some Latin plurals, such as parentheses, phenomena, alumni, and
crises, are widely used and accepted in English.
Some Latin plurals, such as parentheses, phenomena, alumni, and
crises, are widely used and accepted in English.
Contractions
************
@ -289,13 +283,13 @@ because these contractions stand for more than one construction. For
example, there's can be a contraction of there is or there has. The
same applies to where's, it's, that's, and others.
Also, avoid contractions of the word is, especially when combined with
company or product names: Say, WidgetPro is an awesome product; not
WidgetPro's an awesome product.
Also avoid contractions of the word is, especially when combined with
company or product names. Say: "WidgetPro is an awesome product"; not
"WidgetPro's an awesome product".
Hyphenation
***********
The hyphen is often used to join words together to form a compound noun.
A hyphen is often used to join words together to form a compound noun.
Compound nouns often go through this progressions:
* open compound: health care
@ -319,16 +313,15 @@ pre, sub, un.
Here are some words that are often inappropriately hyphenated; do not
hyphenate these words either:
antitheft device, multicamera, multiscreen, prepackaged, reuse,
submenu, autofocus, multifamily, multiuser, pseudoscience, semiannual,
subtotal, autoiris, multimedia, nonprofit, reengineered, semicircle,
superuser, microarchitecture, multiposition, predefined, reevaluate,
subfolder, superscript, microorganism, multiprotocol, predrilled,
reinvent, submarine.
antitheft, multicamera, multiscreen, prepackaged, reuse, submenu,
autofocus, multifamily, multiuser, pseudoscience, semiannual, subtotal,
autoiris, multimedia, nonprofit, reengineered, semicircle, superuser,
microarchitecture, multiposition, predefined, reevaluate, subfolder,
superscript, microorganism, multiprotocol, predrilled, reinvent, submarine.
.. note::
Question whether the pre- prefix is needed at all and consider
leaving it off the word entirely if the meaning is the same.
Question whether the pre- prefix is needed at all and consider
leaving it off the word entirely if the meaning is the same.
Exceptions
----------
@ -352,6 +345,7 @@ Suffix Hyphenation
==================
In general, do not hyphenate suffixes. Here are some examples.
The suffix -wide is usually not hyphenated:
* Nationwide, worldwide, systemwide, campuswide, statewide,
@ -364,15 +358,14 @@ The suffix -wise is usually not hyphenated:
Commas, Semicolons, and Colons
******************************
Here are the most common problems encountered with commas, semicolons,
and colons. Please refer to Merriam-Webster's Collegiate Dictionary
and colons. Please refer to **Merriam-Webster's Collegiate Dictionary**
when in doubt.
Serial Commas
=============
When writing a series or items, use the serial comma before the
coordinating conjunctions and and or to avoid confusion and ambiguity.
For example:
When writing a series or items, use the serial comma before coordinating
conjunctions to avoid confusion and ambiguity. For example:
* Mom, Dad, and I are going to the game.
* Mom, Dad and I are going to the game.
@ -447,7 +440,6 @@ Follow these guidelines for quotation marks:
* Restrict use of quotation marks to terms as terms.
* Do not use quotation marks for emphasis; use *italics* for emphasis.
* Avoid using single-quote marks.
* In terms of punctuation: commas and periods typically go inside the
end-quote; semicolons, colons, question marks, and exclamation points
typically go outside quotation marks. Unless they are part of the
actual quotation.
* Commas and periods typically go inside the end-quote; semicolons, colons,
question marks, and exclamation points typically go outside quotation marks
unless they are part of the actual quotation.