Merge pull request #464 from StyleGuides/daobrien/457-vale-check

daobrien/457 vale check

Author: daobrien

en-US/M.xml

@@ -41,12 +41,13 @@
 			</listitem>
 
 		</varlistentry>
-<!-- Added for inclusive language -->
 		 <varlistentry id="master">
 			<term>master</term>
 			 <listitem>
 				<para>
-					Do not use "master" when it is paired with "slave". Such use diminishes the horror of the dehumanizing practice of slavery. Use another term such as "main", "primary", "controller", or "leader".
+					Do not use "master" when it is paired with "slave".
+          Such use diminishes the horror of the dehumanizing practice of slavery.
+          Use another term such as "main", "primary", "controller", or "leader".
 				</para>
 				<para>
 					Use of "master" is acceptable in other contexts, such as to refer to mastery of a skill.
@@ -58,7 +59,9 @@
 			<term>matrixes</term>
 			 <listitem>
 				<para>
-					Correct. This is the correct plural form for US English spelling. Do not use "matrices".
+					Correct.
+          This is the correct plural form for US English spelling.
+          Do not use "matrices".
 				</para>
 <!-- "US" without periods? -->
 
@@ -125,18 +128,20 @@
 						<para>
 							Objects on which data can be stored. These include hard disks, CDs, and tapes.
 						</para>
-<!-- Deleted "diskettes". -->
 
 					</listitem>
 					 <listitem>
 						<para>
-							In computer networks, "media" refers to the cables that link workstations together. Out of many types of transmission media, the most popular are twisted-pair wire (normal electrical wire), coaxial cable (the type of cable used for cable television), and fiber optic cable (cables made out of glass).
+							In computer networks, "media" refers to the cables that link workstations together.
+              Out of many types of transmission media, the most popular are twisted-pair wire (normal electrical wire), coaxial cable (the type of cable used for cable television), and fiber optic cable (cables made out of glass).
+              <!-- This is way out of date and needs revision -->
 						</para>
 
 					</listitem>
 					 <listitem>
 						<para>
-							The form and technology to communicate information. Multimedia presentations, for example, combine sound, pictures, and videos, all of which are different types of media.
+							The form and technology to communicate information.
+              Multimedia presentations, for example, combine sound, pictures, and videos, which are all different types of media.
 						</para>
 
 					</listitem>
@@ -254,7 +259,10 @@
 			<term>mouse button</term>
 			 <listitem>
 				<para>
-					<emphasis>n.</emphasis> Two words. Do not use "mouse-button" or "mousebutton". If you need to indicate which mouse button, use "right", "left", or "center", such as "right mouse button". Do not hyphenate.
+					<emphasis>n.</emphasis> Two words.
+          Do not use "mouse-button" or "mousebutton".
+          If you need to indicate which mouse button, use "right", "left", or "center", such as "right mouse button".
+          Do not hyphenate.
 				</para>
 
 			</listitem>
@@ -264,7 +272,9 @@
 			<term>Mozilla Firefox</term>
 			 <listitem>
 				<para>
-					Correct. First reference must be "Mozilla Firefox". Subsequent references can be "Firefox".
+					Correct.
+          The first reference must be "Mozilla Firefox".
+          Any following references can be "Firefox".
 				</para>
 
 			</listitem>
@@ -274,7 +284,9 @@
 			<term>Mozilla Thunderbird</term>
 			 <listitem>
 				<para>
-					Correct. First reference must be "Mozilla Thunderbird". Subsequent references can be "Thunderbird".
+					Correct.
+          The first reference must be "Mozilla Thunderbird".
+          Any following references can be "Thunderbird".
 				</para>
 
 			</listitem>

en-US/N.xml

@@ -10,7 +10,8 @@
  			<term>navigate to</term>
  			 <listitem>
  				<para>
-					Use "Navigate to" when moving through multiple UI options, because it covers all cases where you might have to click, point to, select, or otherwise make a series of selections to initiate an action. For example, "From the OpenShift web console, navigate to Monitoring → Alerting."
+					Use "Navigate to" when moving through multiple UI options, because it covers all cases where you might have to click, point to, select, or otherwise make a series of selections to initiate an action.
+          For example, "From the OpenShift web console, navigate to Monitoring → Alerting."
  				</para>
 				<para>
 					Do not use "Go to", or "point to", or other variations.
@@ -22,7 +23,8 @@
 			<term>needs, needs to be, need to</term>
 			 <listitem>
 				<para>
-					Avoid when possible. Suggested alternatives include "must" or "required".
+					Avoid when possible.
+          Use "must" or "required" or similar.
 				</para>
 
 			</listitem>
@@ -56,10 +58,13 @@
 			<term>NFS</term>
 			 <listitem>
 				<para>
-					Abbreviation of Network File System, a client/server application designed by Sun Microsystems that provides access for all network users to shared files stored on computers of different types. NFS provides access to shared files through the Virtual File System (VFS) interface that runs in a layer above TCP/IP. Users can manipulate shared files as if they were stored locally on the user's own hard disk.
+					Abbreviation of Network File System, a client/server application designed by Sun Microsystems that provides access for all network users to shared files stored on computers of different types.
+          NFS provides access to shared files through the Virtual File System (VFS) interface that runs in a layer above TCP/IP.
+          Users can manipulate shared files as if they were stored locally on the user's own hard disk.
 				</para>
 				 <para>
-					With NFS, computers that are connected to a network operate as clients while accessing remote files, and as servers while providing remote users access to local shared files. The NFS standards are publicly available and widely used.
+					With NFS, computers that are connected to a network operate as clients while accessing remote files, and as servers while providing remote users access to local shared files.
+          The NFS standards are publicly available and widely used.
 				</para>
 
 			</listitem>
@@ -111,17 +116,14 @@
 			<term>number sign</term>
 			 <listitem>
 				<para>
-					Generally, use "number sign" to refer to the # character. Alternatively, use "hash" to refer to a hashtag in social media, or to refer to Secure Hash Algorithm (see <xref linkend="sha" />), or when writing exclusively for a European audience. You can instead use "pound sign" when writing exclusively for a North American audience, if "number sign" is not appropriate for the context.  
+					Generally, use "number sign" to refer to the # character.
+          Or, use "hash" to refer to a hashtag in social media, or to refer to Secure Hash Algorithm (see <xref linkend="sha" />), or when writing exclusively for a European audience.
+          You can instead use "pound sign" when writing exclusively for a North American audience, if "number sign" is not appropriate for the context.  
 				</para>
 
 			</listitem>
 
 		</varlistentry>
 
-<!-- Moved "Numbers" entry to Chapter 4. -->
-		 <!-- <varlistentry id="numbers">
-			<term>numbers</term>
-		</varlistentry> -->
-
 	</variablelist>
 </chapter>

en-US/O.xml

@@ -51,15 +51,13 @@
 			<term>offline backup</term>
 			 <listitem>
 				<para>
-					Correct. Use this term to refer to backing up a database while the database is not being accessed by applications. Do not use "cold backup" or any other variations.
+					Correct.
+          Use this term to refer to backing up a database while the database is not being accessed by applications.
+          Do not use "cold backup" or any other variations.
 				</para>
 				 <para>
-					The counterpart to this term is "online backup", to refer to the process of backing up a database while it is being accessed by other applications. Do not use "hot backup" or any other variations.
-<!-- Deleted footnote: URL is no longer valid. -->
-					<!-- <footnote> <para>
-						<ulink url="http://www-01.ibm.com/software/globalization/terminology/o.html" />
-					</para>
-					 </footnote> -->
+					The counterpart to this term is "online backup", to refer to the process of backing up a database while it is being accessed by other applications.
+          Do not use "hot backup" or any other variations.
 				</para>
 
 			</listitem>
@@ -69,12 +67,13 @@
 			<term>OK</term>
 			 <listitem>
 				<para>
-					When referring to the <guibutton>OK</guibutton> button, it is not necessary to use "button" in the sentence. For example, "Click <guibutton>OK</guibutton> to close the dialog box."
+					When referring to the <guibutton>OK</guibutton> button, it is not necessary to use "button" in the sentence.
+          For example, "Click <guibutton>OK</guibutton> to close the dialog box."
 				</para>
 				<para>
-					Use "OK" only to refer to an interface element, not in general text. For example, instead of using "It is OK to run the command", use alternative wording, such as "You can run the command".
+					Use "OK" only to refer to an interface element, not in general text.
+          For example, instead of using "It is OK to run the command", use alternative wording, such as "You can run the command".
 				</para>
-<!-- Added paragraph to avoid "OK" when not referring to a button. -->
 
 			</listitem>
 
@@ -92,7 +91,8 @@
 		 <term>once</term>
 			<listitem>
 			 <para>
-				 Use only to mean "one time". Do not use as a conjunction to mean "after" or "when".
+				 Use only to mean "one time".
+         Do not use as a conjunction to mean "after" or "when".
 			 </para>
 			 <para>
 				 Example 1: Instead of "Once the name is set for a network interface on the system, the name of the interface does not change", use "When the name is set for a network interface on the system, the name of the interface does not change".
@@ -162,7 +162,9 @@
 			<term>on-the-fly</term>
 			 <listitem>
 				<para>
-					Do not use. Avoid idioms, which might not be globally known. In this case, for example, "real time" is both non-idiomatic and more technically accurate.
+					Do not use.
+          Avoid idioms, which might not be globally known.
+          In this case, for example, "real time" is both non-idiomatic and more technically accurate.
 				</para>
 
 			</listitem>
@@ -172,7 +174,10 @@
 			<term>oops</term>
 			 <listitem>
 				<para>
-					A kernel oops is an error message that is generated as a result of a bug in the kernel. Do not use "oops" on its own. Also, avoid using "kernel oops" at the beginning of a sentence. See also "kernel panic".
+					A kernel oops is an error message that is generated because of a bug in the kernel.
+          Do not use "oops" on its own.
+          Also, avoid using "kernel oops" at the beginning of a sentence.
+          See also "kernel panic".
 				</para>
 
 			</listitem>
@@ -244,10 +249,11 @@
 			<term>open source way</term>
 			 <listitem>
 				<para>
-					A phrase that was coined by the Red&nbsp;Hat community and adopted by opensource.com in 2009. It is a reference to an "open source method", as in "Let's develop this project the open source way."
+					A phrase that was coined by the Red&nbsp;Hat community and adopted by opensource.com in 2009.
+          It is a reference to an "open source method", as in "Let's develop this project the open source way."
 				</para>
 				 <para>
-					Do not use to suggest that something is being done only in the "spirit" of open source without actually having an open source policy as defined by <ulink url="http://opensource.org/osd">Open Source Initiative</ulink>, to avoid diluting the legal meaning of the term "open source".
+					Do not use to suggest that something is being done only in the "spirit" of open source without having an open source policy as defined by <ulink url="http://opensource.org/osd">Open Source Initiative</ulink>, to avoid diluting the legal meaning of the term "open source".
 				</para>
 
 			</listitem>
@@ -287,7 +293,10 @@
 			<term>overcloud</term>
 			 <listitem>
 				<para>
-					<emphasis>n.</emphasis> Always lowercase. This is a concept, not a technology or product name. Being a common noun, it requires an article in most cases. See also <xref linkend="undercloud" />.
+					<emphasis>n.</emphasis> Always lowercase.
+          This is a concept, not a technology or product name.
+          Being a common noun, it normally requires an article.
+          See also <xref linkend="undercloud" />.
 				</para>
 
 			</listitem>
@@ -297,7 +306,8 @@
 			<term>override</term>
 			 <listitem>
 				<para>
-					Correct. Do not use "over-ride" or "over ride".
+					Correct.
+          Do not use "over-ride" or "over ride".
 				</para>
 
 			</listitem>

en-US/Objectives.xml

@@ -6,7 +6,10 @@
 <chapter id="objectives">
 	<title>Objectives of this Guide</title>
 	 <para>
-		The objective of the Red&nbsp;Hat Style Guide is to help authors communicate information in a clear, transparent fashion, and to facilitate consistency in tone and delivery. We write documentation for a variety of audiences, across multiple geographies and with very different skill sets. We write for end users as well as expert users. Red&nbsp;Hat documentation is:
+		The objective of the Red&nbsp;Hat Style Guide is to help authors communicate information in a clear, transparent fashion, and to facilitate consistency in tone and delivery.
+    We write documentation for various audiences, across multiple geographies and with different skill sets.
+    We write for end users as well as expert users.
+    Red&nbsp;Hat documentation is:
 		<itemizedlist>
 			<!--                                       <listitem>
 				<para>
@@ -15,13 +18,13 @@
 
 			</listitem>                                       --> <listitem>
 				<para>
-					Accurate and consistent
+					Accurate and consistent.
 				</para>
 
 			</listitem>
 			 <listitem>
 				<para>
-					Readable, with a score of 60-70 on the Flesch–Kincaid reading ease scale.
+					Readable, with a score of 60-70 on the Flesch-Kincaid reading ease scale.
 				</para>
 
 			</listitem>
@@ -44,7 +47,10 @@
 	  <formalpara id="readability">
 		<title>Readability</title>
 		 <para>
-			Technical documents should be readable by the targeted audience. In this instance, we expect our audiences to have the minimum reading and comprehension level of an eighth-grade student, of an age between 14 and 15 years. The Flesch-Kincaid and Gunning Fog index provide measurable grades. A Red&nbsp;Hat guide should have a Gunning Fog index of 9-12.
+			Technical documents should be readable by the targeted audience.
+      In this instance, we expect our audiences to have the minimum reading and comprehension level of an eighth-grade student, of an age between 14 and 15 years.
+      The Flesch-Kincaid and Gunning Fog index provide measurable grades.
+      A Red&nbsp;Hat guide should have a Gunning Fog index of 9-12.
 		</para>
 
 	</formalpara>

en-US/P.xml

@@ -72,10 +72,13 @@
 			<term>plain text</term>
 			 <listitem>
 				<para>
-					<emphasis>n.</emphasis> Two words. In most cases, do not use "plaintext", "cleartext", or other variants.
+					<emphasis>n.</emphasis> Two words.
+          In most cases, do not use "plaintext", "cleartext", or other variants.
 				</para>
 				 <para>
-					Cryptographers distinguish between "cleartext" (unencrypted data) and "plaintext" (unencrypted data as input to an encryption algorithm). Red&nbsp;Hat uses "plain text" as a plain English denotation of all unencrypted information, whether it is stored or being fed to an encryption algorithm. Unless it is necessary to make the cryptographer's distinction, do not use "plaintext" or "cleartext".
+					Cryptographers distinguish between "cleartext" (unencrypted data) and "plaintext" (unencrypted data as input to an encryption algorithm).
+          Red&nbsp;Hat uses "plain text" as a plain English denotation of all unencrypted information, whether it is stored or being fed to an encryption algorithm.
+          Unless it is necessary to make the cryptographer's distinction, do not use "plaintext" or "cleartext".
 				</para>
 
 			</listitem>
@@ -85,9 +88,9 @@
 			<term>please</term>
 			 <listitem>
 				<para>
-					Do not use. Instead of saying "Please see the <citetitle>Getting Started Guide</citetitle>", use "See the <citetitle>Getting Started Guide."</citetitle>
+					Do not use.
+          Instead of saying "Please see the <citetitle>Getting Started Guide</citetitle>", use "See the <citetitle>Getting Started Guide."</citetitle>
 				</para>
-<!-- Added justification -->
 				<para>
 				Technical information requires an authoritative tone; terms of politeness convey the wrong tone for technical information and are not regarded the same way in all cultures.
 				</para>
@@ -109,12 +112,11 @@
 			<term>plug-in</term>
 			 <listitem>
 				<para>
-					<emphasis>n.</emphasis> Write hyphenated. Do not use "plugin".
+					<emphasis>n.</emphasis> Write hyphenated.
+          Do not use "plugin".
 				</para>
 				 <para>
 					A hardware or software module that adds a specific feature or service to a larger system.
-<!-- Removed dated example. -->
-					<!-- For example, a number of plug-ins are available for the Netscape Navigator browser that enable it to display different types of audio or video messages. Navigator plug-ins are based on MIME file types. -->
 				</para>
 
 			</listitem>
@@ -173,10 +175,12 @@
 					<emphasis>n.</emphasis> The name of the Power architecture is "Power", but the designation of individual chips tends to be either "PowerPC" or "POWER". Refer to IBM marketing or the <ulink url="http://openpowerfoundation.org">Open Power Foundation</ulink> if unsure.
 				</para>
 				 <para>
-					Do not use the "PPC64" or "ppc64le" shorthand. Depending on context, either "64-bit PowerPC" (which covers most 64-bit PowerPC implementations) or "64-bit IBM Power Series" (which covers the IBM POWER2 and IBM POWER8 and POWER9 series) is correct. Additional application binary interface (ABI) features are important, but are not officially part of the Power architecture name, so use them as descriptors, such as "64-bit IBM Power Series in little-endian mode".
+					Do not use the "PPC64" or "ppc64le" shorthand.
+          Depending on context, either "64-bit PowerPC" (which covers most 64-bit PowerPC implementations) or "64-bit IBM Power Series" (which covers the IBM POWER2 and IBM POWER8 and POWER9 series) is correct.
+          Additional application binary interface (ABI) features are important, but are not officially part of the Power architecture name, so use them as descriptors, such as "64-bit IBM Power Series in little-endian mode".
 				</para>
 				 <para>
-					Note: The PowerPC version of Red Hat Enterprise Linux runs on 64-bit IBM Power Series hardware in almost all cases.
+					Note: The PowerPC version of Red&nbsp;Hat Enterprise Linux runs on 64-bit IBM Power Series hardware in most cases.
 				</para>
 
 			</listitem>