Merge pull request #467 from StyleGuides/daobrien/458-vale-check

daobrien · web-flow · commit a199ab222bd1 · 2023-02-13T15:00:28.000+10:00
Closes #458 Run Vale over style guide part 4.
diff --git a/en-US/T.xml b/en-US/T.xml
@@ -149,32 +149,31 @@
 			</listitem>
 
 		</varlistentry>
-<!-- IBM has now changed to use of one-word forms for many "time-" prefixed words: timebox, timeframe, timeline, timeout, timeslice, timestamp, but still "time zone". -->
 		 <varlistentry id="time-frame">
-			<term>time frame (n.)</term>
+			<term>time frame</term>
 			 <listitem>
 				<para>
-					Correct. Do not use "timeframe" or "time-frame".
+					<emphasis>n.</emphasis> Correct. Do not use "timeframe" or "time-frame".
 				</para>
 
 			</listitem>
 
 		</varlistentry>
 		 <varlistentry id="time-zone">
-			<term>time zone (n.)</term>
+			<term>time zone</term>
 			 <listitem>
 				<para>
-					Correct. Do not use "timezone" or "time-zone".
+					<emphasis>n.</emphasis> Correct. Do not use "timezone" or "time-zone".
 				</para>
 
 			</listitem>
 
 		</varlistentry>
 		 <varlistentry id="token-ring">
-			<term>token-ring (n.)</term>
+			<term>token-ring</term>
 			 <listitem>
 				<para>
-					When capitalized, Token-Ring refers to the PC network architecture that IBM developed. The IBM Token-Ring specification is standardized by the IEEE as the IEEE 802.5 standard. 
+					<emphasis>n.</emphasis> When capitalized, Token-Ring refers to the PC network architecture that IBM developed. The IBM Token-Ring specification is standardized by the IEEE as the IEEE 802.5 standard. 
 					<!-- See the <citetitle>IBM Style Guide</citetitle> for further uses of this term. -->
 				</para>
 
diff --git a/en-US/Translation.xml b/en-US/Translation.xml
@@ -18,18 +18,20 @@
 		 <section id="Sentence_Structure-Using_Lists_Correctly">
 			<title>Using and Formatting Lists</title>
 			 <para>
-				Lists appear in a range of formats, such as series, ordered, unordered (itemized), and so on. Avoid using itemized lists to format a single sentence. Some translation tools display list items and the introductory sentence (or <firstterm>sentence stem</firstterm>) as individual sentences for translation. If they are not complete sentences, they can be difficult to translate.
+				Lists appear in a range of formats, such as series, ordered, unordered (bulleted), and so on.
+        Avoid using bulleted lists to format a single sentence.
+        Some translation tools display list items and the introductory sentence (or <firstterm>sentence stem</firstterm>) as individual sentences for translation.
+        If they are not complete sentences, they can be difficult to translate.
 			</para>
       <para>
         The following general guidelines apply to lists:
       </para>
       <variablelist>
         <varlistentry>
-            <term>Itemized lists</term>
+            <term>Bulleted lists</term>
             <listitem>
                 <para>
-                  They appear as a bulleted list.
-                  Use this list type for three or more entries where order is not important, or in a demonstration section when students are encouraged not to perform steps but to watch the instructor instead.
+                  Use this list type for three or more entries where order is not important.
                   Titles are optional.
                 </para>
             </listitem>
@@ -38,7 +40,7 @@
             <term>Ordered lists</term>
             <listitem>
                 <para>
-                    They appear as a numbered list.
+                    These appear as numbered lists.
                     Use this list type for multiple entries if you need to refer to one of the entries from elsewhere in your document, or where order is important.
                     For example, if you need to list the order of operations that are required to prepare for an installation, or list a sequence of events that occurs.
                     Titles are optional.
@@ -49,7 +51,7 @@
             <term>Variable lists</term>
             <listitem>
                 <para>
-                  They appear as a list of terms followed by definitions.
+                  These appear as a list of terms followed by definitions.
                   Use this list type to list and describe a series of terms, such as variables, command options or arguments, and similar items.
                   Titles are optional.
                   (This list is written as a variable list.)
@@ -62,19 +64,18 @@
             <term>Procedures</term>
             <listitem>
                 <para>
-                    They appear as a list of numbered steps.
+                    These appear as a list of numbered steps.
                     Procedures always include a title, and are used to list the required steps to achieve a task.
                 </para>
             </listitem>
         </varlistentry>
     </variablelist>
     <para>
         You can nest lists, but try to keep the number of levels to two or fewer.
-        To nest procedures in DocBook, use &lt;substep&gt; elements.
     </para>
     <section><title>Formatting Lists for Readability</title>
       <para>
-        It is important to provide sufficient spacing between elements in your documents to facilitate reading and comprehension.
+        It is important to provide enough spacing between elements in your documents to facilitate reading and comprehension.
         You can include a lot of information in a few short paragraphs but readers need to be able to process that information in chunks.
         The same consideration applies to lists.
       </para>
diff --git a/en-US/U.xml b/en-US/U.xml
@@ -20,10 +20,12 @@
 			<term>UltraSPARC</term>
 			 <listitem>
 				<para>
-					Correct. Do not use "ULTRASPARC", "UltraSparc", or other variations.
+					Correct.
+          Do not use "ULTRASPARC", "UltraSparc", or other variations.
 				</para>
 				 <para>
-					UltraSPARC is a trademark of SPARC International, Inc., and is used under license by Sun Microsystems, Inc. Products that bear the SPARC trademarks are based on an architecture developed by Sun Microsystems, Inc.
+					UltraSPARC is a trademark of SPARC International, Inc., and is used under license by Sun Microsystems, Inc.
+          Products that bear the SPARC trademarks are based on an architecture developed by Sun Microsystems, Inc.
 				</para>
 
 			</listitem>
@@ -33,7 +35,10 @@
 			<term>undercloud</term>
 			 <listitem>
 				<para>
-					<emphasis>n.</emphasis> Always lowercase. It is a concept, not a technology or product name. Being a common noun, it requires an article in most cases. See also <xref linkend="overcloud" />.
+					<emphasis>n.</emphasis> Always lowercase.
+          It is a concept, not a technology or product name.
+          Being a common noun, it normally requires an article.
+          See also <xref linkend="overcloud" />.
 				</para>
 
 			</listitem>
@@ -185,10 +190,14 @@
 			<term>user interface</term>
 			 <listitem>
 				<para>
-					<emphasis>n.</emphasis> Correct. Do not use "user-interface" or "userinterface".
+					<emphasis>n.</emphasis> Correct.
+          Do not use "user-interface" or "userinterface".
 				</para>
 				 <para>
-					The junction between a user and a computer program. An interface is a set of commands or menus through which a user communicates with a program. In a command-driven interface, you enter commands. In a menu-driven interface, you select command choices from various menus that are displayed on the screen.
+					The junction between a user and a computer program.
+          An interface is a set of commands or menus through which a user communicates with a program.
+          In a command-driven interface, you enter commands.
+          In a menu-driven interface, you select command choices from various menus that are displayed on the screen.
 				</para>
 
 			</listitem>
@@ -198,7 +207,7 @@
 			<term>username</term>
 			 <listitem>
 				<para>
-					<emphasis>n.</emphasis> One word in most cases.
+					<emphasis>n.</emphasis> Usually one word.
           Capitalize the "U" at the beginning of a sentence.
           See the <citetitle>IBM Style Guide</citetitle> for more information.
 				</para>
@@ -210,7 +219,9 @@
 			<term>user space</term>
 			 <listitem>
 				<para>
-					<emphasis>n.</emphasis> Correct when used as a noun. When used as a modifier, use the hyphenated form, "user-space". Do not use "userspace".
+					<emphasis>n.</emphasis> Correct when used as a noun.
+          When used as a modifier, use the hyphenated form, "user-space".
+          Do not use "userspace".
 				</para>
 
 			</listitem>
diff --git a/en-US/V.xml b/en-US/V.xml
@@ -58,7 +58,10 @@
           Only use "vim" (all lowercase) when referring to the command to start the application.
 				</para>
 				 <para>
-					Vim is an acronym, derived from Vi IMproved. (In the original 1991 release for the Amiga platform, the acronym was derived from Vi IMitation. It became Vi IMproved when ported to various UNIX-based operating systems in 1992.) Despite being an acronym, and despite the first word of the "About" text that appears when you start the editor, the standard, proper noun-derived, mixed-case spelling has been in use since its release on the Amiga.
+					Vim is an acronym, derived from Vi IMproved.
+          (In the original 1991 release for the Amiga platform, the acronym was derived from Vi IMitation.
+          It became Vi IMproved when ported to various UNIX-based operating systems in 1992.)
+          Despite being an acronym, and despite the first word of the "About" text that appears when you start the editor, the standard, proper noun-derived, mixed-case spelling has been in use since its release on the Amiga.
 				</para>
 
 			</listitem>
diff --git a/en-US/W.xml b/en-US/W.xml
@@ -63,7 +63,9 @@
 			<term>web page</term>
 			 <listitem>
 				<para>
-					<emphasis>n.</emphasis> Two words. Capitalize the "W" at the beginning of a sentence. If part of a proper noun, capitalize accordingly.
+					<emphasis>n.</emphasis> Two words.
+          Capitalize the "W" at the beginning of a sentence.
+          If part of a proper noun, capitalize accordingly.
 				</para>
 
 			</listitem>
@@ -73,7 +75,8 @@
 			<term>web UI</term>
 			 <listitem>
 				<para>
-					Correct. Use this term to refer to a browser-based interface to a software application, even if that application has no connection to the web.
+					Correct.
+          Use this term to refer to a browser-based interface to a software application, even if that application has no connection to the web.
           Do not hyphenate the abbreviation or use the one-word form.
 				</para>
 
@@ -97,7 +100,7 @@
 			<term>whether</term>
 			 <listitem>
 				<para>
-		  Use “whether” instead of “if” to refer to a choice or to alternatives.
+    		  Use "whether" instead of "if" to refer to a choice or to alternatives.
           For example, instead of "Test if authenticated FTP access is restored", write "Test whether authenticated FTP access is restored".
 				</para>
 
@@ -109,23 +112,23 @@
 			<term>while</term>
 			 <listitem>
 				<para>
-		  In technical content, use “while” only to indicate that many tasks or processes occur at the same time.
-          For example, instead of "While most targets use one target portal group (TPG), advanced configurations might define multiple TPGs", write "Although most targets use one target portal group (TPG), advanced configurations might define multiple TPGs".
+		      In technical content, use "while" only to indicate that many tasks or processes occur at the same time.
+          For example, instead of "While most targets use one target portal group (TPG), advanced configurations might define multiple TPGs", write "Although most targets use one target portal group (TPG), advanced configurations might define multiple TPGs."
 				</para>
 
 			</listitem>
 
 		</varlistentry>
 
-<!-- Added for inclusive language -->
 		 <varlistentry id="whitelist">
 			<term>whitelist</term>
 			 <listitem>
 				<para>
 					Do not use. Use "allowlist".
 				</para>
 				<para>
-					Do not use the terms "white" or "black" in a context where white is represented as good or black is represented as bad. Such usage reinforces a model that promotes racial bias.
+					Do not use the terms "white" or "black" in a context where white is represented as good or black is represented as bad.
+          Such usage reinforces a model that promotes racial bias.
 				</para>
 			</listitem>
 
@@ -138,7 +141,8 @@
           Use the pronoun "whom" as a direct object, an indirect object, or the object of a preposition.
 				</para>
 				 <para>
-					For example: Who owns this phone? To whom does this phone belong?
+					For example: Who owns this phone?
+          To whom does this phone belong?
 				</para>
 
 			</listitem>
diff --git a/en-US/WUG_Intro.xml b/en-US/WUG_Intro.xml
@@ -6,14 +6,18 @@
 <chapter id="usage-dictionary">
 	<title>Usage Dictionary</title>
 	 <para>
-		This page provides guidelines for the correct use of common terms in Red Hat documentation, which terms to avoid, and the preferred spelling where variations exist. This page is constantly evolving, and open to discussion and improvement.
+		This page provides guidelines for the correct use of common terms in Red&nbsp;Hat documentation, which terms to avoid, and the preferred spelling where variations exist.
+    This page is constantly evolving, and open to discussion and improvement.
 	</para>
 	 <variablelist>
 		<varlistentry id="Usage_Dictionary-A_note_about_trademarks">
 			<term>A note about trademarks</term>
 			 <listitem>
 				<para>
-					The status of a trademark can vary from country to country. Therefore, do not attach the symbols for trademark or registered trademark (™ and ®) to any third-party trademarks that you mention in your document unless Red Hat legal asks you to do so. In XML terms, this means that you should not generally tag trademarks with the &lt;trademark&gt; tag. We do mark Red Hat's own trademarks. See <ulink url="https://home.corp.redhat.com/node/34059">Copyright Notices and Trademark Legends</ulink> for more information.
+					The status of a trademark can vary from country to country.
+          Therefore, do not attach the symbols for trademark or registered trademark (™ and ®) to any third-party trademarks that you mention in your document unless Red&nbsp;Hat legal asks you to do so.
+          We do mark Red&nbsp;Hat trademarks.
+          See <ulink url="https://home.corp.redhat.com/node/34059">Copyright Notices and Trademark Legends</ulink> for more information.
 				</para>
 
 			</listitem>
diff --git a/en-US/XYZ.xml b/en-US/XYZ.xml
@@ -70,7 +70,8 @@
 			<term>YAML</term>
 			 <listitem>
 				<para>
-					Recursive acronym for "YAML Ain't Markup Language." Expand on first use only.
+					Recursive acronym for "YAML Ain't Markup Language."
+          Expand on first use only.
 				</para>
 
 			</listitem>
@@ -80,7 +81,8 @@
 			<term>you</term>
 			 <listitem>
 				<para>
-					Use second person wherever possible. Do not use "I", "we", "he", or "she."
+					Use second person wherever possible.
+          Do not use "I", "we", "he", or "she."
 				</para>
 
 			</listitem>
