Merge branch 'dev'

daobrien · daobrien · commit deb0734cc2d9 · 2020-07-10T14:37:22.000+10:00
Merge all the dev changes ready for release.
diff --git a/en-US/Conventions_for_Writers_and_Editors.ent b/en-US/Conventions_for_Writers_and_Editors.ent
@@ -1,4 +1,4 @@
 <!ENTITY PRODUCT "Red Hat Style Guide">
 <!ENTITY BOOKID "Writing_Style_Guide">
-<!ENTITY YEAR "2019">
+<!ENTITY YEAR "2020">
 <!ENTITY HOLDER "Red Hat, Inc">
diff --git a/en-US/Design.xml b/en-US/Design.xml
@@ -256,10 +256,10 @@ $ vi myFile.txt
 					<title>Documenting Long Commands</title>
 
 <screen># tar --selinux -czvf config_files.tar.gz  /etc/katello \
-  > /etc/elasticsearch /etc/candlepin /etc/pulp /etc/gofer \
-  > /etc/grinder /etc/pki/katello /etc/pki/pulp /etc/qpidd.conf \
-  > /etc/sysconfig/katello /etc/sysconfig/elasticsearch \
-  > /root/ssl–build /var/www/html/pub/* /var/lib/katello
+> /etc/elasticsearch /etc/candlepin /etc/pulp /etc/gofer \
+> /etc/grinder /etc/pki/katello /etc/pki/pulp /etc/qpidd.conf \
+> /etc/sysconfig/katello /etc/sysconfig/elasticsearch \
+> /root/ssl–build /var/www/html/pub/* /var/lib/katello
 
 # cd /var/lib/katello
 
@@ -721,6 +721,38 @@ $ vi myFile.txt
 		</para>
 
 	</section>
+
+	<section id="making-recommendations">
+	 <title>Making Recommendations</title>
+		<para>
+		When making a recommendation, the preferred verbiage is "Red&nbsp;Hat recommends..." instead of the common but indirect "It is recommended...".
+		Recommendations can include best practices, recommended practices, and product-specific suggestions.
+		Refer to <xref linkend="avoiding-confusing-language"/> for information on using the terms "best practices" and "recommended practices" in Red&nbsp;Hat documentation.
+	  </para>
+		<example>
+			<title>
+				(incorrect)
+			</title>
+		<para>
+	    "Although the attack surface is reduced to the same-project traffic, it is recommended to create multiple service accounts within a project."
+	  </para>
+	  <para>
+		  "It is recommended to generate a service account for each microservice in your project."
+	  </para>
+	</example>
+	<example>
+		<title>
+			(correct)
+		</title>
+	  <para>
+		"Although the attack surface is reduced to the same-project traffic, Red&nbsp;Hat recommends creating multiple service accounts within a project."
+	  </para>
+	<para>
+  	"Red&nbsp;Hat recommends that you generate a service account for each microservice in your project."
+	</para>
+</example>
+ </section>
+
 	 <section id="citing-other-works">
 		<title>Citing Other Works</title>
 		 <formalpara id="other-books">
@@ -779,6 +811,7 @@ $ vi myFile.txt
 		</itemizedlist>
 
 	</section>
+
 	 <section id="other-authors">
 		<title>Citing Other Authors</title>
 		 <para>
@@ -794,4 +827,3 @@ $ vi myFile.txt
 	</section>
 
 </chapter>
-
diff --git a/en-US/F.xml b/en-US/F.xml
@@ -94,7 +94,7 @@
 			<term>file extensions (general usage)</term>
 			 <listitem>
 				<para>
-					Write file extensions in all caps and without periods (for example, "a PDF file"), unless the file name is also referenced (for example, "Save as example.pdf").
+					See <citetitle>File names, file types, and directory names</citetitle> in <citetitle>The IBM Style Guide</citetitle>.
 				</para>
 
 			</listitem>
diff --git a/en-US/Grammar.xml b/en-US/Grammar.xml
@@ -752,4 +752,3 @@
 	</section>
 
 </chapter>
-
diff --git a/en-US/K.xml b/en-US/K.xml
@@ -33,7 +33,7 @@
 			<term>kerberize</term>
 			 <listitem>
 				<para>
-					Incorrect. Do not use "kerberize," "kerberized," or other variants to refer to applications or services that use Kerberos authentication. Refer to such applications as "kerberos-aware" or "Kerberos-enabled," or rewrite the sentence.
+					Incorrect. Do not use "kerberize," "kerberized," or other variants to refer to applications or services that use Kerberos authentication. Refer to such applications as "Kerberos-aware" or "Kerberos-enabled," or rewrite the sentence.
 				</para>
 
 			</listitem>
diff --git a/en-US/N.xml b/en-US/N.xml
@@ -26,16 +26,7 @@
 			</listitem>
 
 		</varlistentry>
-		 <varlistentry id="neighbor">
-			<term>neighbor</term>
-			 <listitem>
-				<para>
-					Correct. Do not use "neighbour."
-				</para>
-
-			</listitem>
-
-		</varlistentry>
+		 
 		 <varlistentry id="net">
 			<term>.NET</term>
 			 <listitem>
diff --git a/en-US/O.xml b/en-US/O.xml
@@ -83,6 +83,16 @@
 				</para>
 			</listitem>
 
+		</varlistentry>
+		<varlistentry id="once">
+		 <term>once</term>
+			<listitem>
+			 <para>
+				 Use only to mean "one time." Do not use as a conjunction to mean "after" or "when."
+			 </para>
+
+		 </listitem>
+
 		</varlistentry>
 		 <varlistentry id="online">
 			<term>online</term>
@@ -180,7 +190,8 @@
 			<term>open source</term>
 			 <listitem>
 				<para>
-					Correct. Do not use "OpenSource," "opensource," or "open-source" (obviously, capitalize the "o" in "open source" at the beginning of a sentence).
+					Correct. Do not use "OpenSource," "opensource," or "open-source."
+          Only capitalize the "o" in "open source" at the beginning of a sentence.
 				</para>
 
 			</listitem>
@@ -252,4 +263,3 @@
 
 	</variablelist>
 </chapter>
-
diff --git a/en-US/R.xml b/en-US/R.xml
@@ -142,7 +142,7 @@
 			<term>remote access server</term>
 			 <listitem>
 				<para>
-					A server that is dedicated to handling users that are not on a LAN but need remote access to it. The remote access server allows users to gain access to files and print services on the LAN from a remote location. For example, a user who dials into a network from home using an analog modem or an ISDN connection will dial into a remote access server. Once the user is authenticated they can access shared drives and printers as if they were physically connected to the office LAN.
+					A server that is dedicated to handling users that are not on a LAN but need remote access to it. The remote access server allows users to gain access to files and print services on the LAN from a remote location. For example, a user who dials into a network from home using an analog modem or an ISDN connection will dial into a remote access server. After the user is authenticated they can access shared drives and printers as if they were physically connected to the office LAN.
 				</para>
 
 			</listitem>
@@ -237,4 +237,3 @@
 
 	</variablelist>
 </chapter>
-
diff --git a/en-US/S.xml b/en-US/S.xml
@@ -138,7 +138,9 @@
 			<term>SELinux</term>
 			 <listitem>
 				<para>
-					Short for Security-Enhanced Linux, SELinux uses Linux Security Modules (LSM) in the Linux kernel to provide a range of minimum-privilege-required security policies. Do not use alternatives such as "SLinux," "E Linux," or "SE Linux."
+					Abbreviation of Security-Enhanced Linux.
+          SELinux uses Linux Security Modules (LSM) in the Linux kernel to provide a range of minimum-privilege-required security policies.
+          Do not use any other alternatives.
 				</para>
 
 			</listitem>
@@ -374,7 +376,7 @@
         </para>
       </listitem>
     </varlistentry>
-    
+
 		 <varlistentry id="smart-card">
 			<term>smart card</term>
 			 <listitem>
@@ -385,7 +387,7 @@
 			</listitem>
 
 		</varlistentry>
-		 
+
 		 <varlistentry id="socks">
 			<term>SOCKS</term>
 			 <listitem>
@@ -523,10 +525,20 @@ a programming and technical sense this also means "Run the <command>source</comm
 				<para>
 					Initialism for Secure Shell, a network protocol that allows data exchange using a secure channel. When referring to the protocol, do not use "ssh," "Ssh," or other variants. When referring to the command, use <command>ssh</command>.
 				</para>
-				 <para>
-					Do not use as a verb. For example, instead of "ssh to the remote server," write "Use SSH to connect to the remote server," "Open an SSH connection," or something similar.
+				<para>
+				Do not use as a verb.
+			  </para>
+				<example>
+					<title>
+						Example Use of "SSH"
+				</title>
+				<para>
+				  Incorrect: To begin, "ssh to the remote server."
 				</para>
-
+				<para>
+					Correct: "Use SSH to connect to the remote server," "Open an SSH connection," or something similar.
+				</para>
+			</example>
 			</listitem>
 
 		</varlistentry>
@@ -719,4 +731,3 @@ a programming and technical sense this also means "Run the <command>source</comm
 
 	</variablelist>
 </chapter>
-
diff --git a/en-US/Slang.xml b/en-US/Slang.xml
@@ -23,8 +23,10 @@
 					<para>
 						This is a commonly understood phrase, and despite some concerns about using superlatives without statistics to back them up, Red&nbsp;Hat does not actively discourage its use. It is also a more common search term than most alternatives. If you are in any doubt, the preferred alternative is "recommended practices."
 					</para>
-
-				</listitem>
+					<para>
+						See the section <xref linkend="making-recommendations" /> for additional information about recommendations in Red&nbsp;Hat documentation.
+					</para>
+		 		 </listitem>
 
 			</varlistentry>
 			 <varlistentry id="first-come-first-served">
@@ -872,4 +874,3 @@
 	</section>
 
 </chapter>
-
diff --git a/en-US/T.xml b/en-US/T.xml
@@ -32,10 +32,24 @@
 				<para>
 					Preferred abbreviation for "telecommunications company." Do not use "telecom." See also <xref linkend="csp" />.
 				</para>
+				<para>
+					Use "telecommunications service provider" on first use. Subsequent uses can be "telco" or "telco service provider"; only use "telco" when the context makes it clear that the industry is engaged in providing telecommunications services. Use in URLs.
+					See <xref linkend="telecom-service-provider" />.
+				</para>
 
 			</listitem>
 
 		</varlistentry>
+		<varlistentry id="telecom-service-provider">
+		 <term>telecommunications service provider</term>
+			<listitem>
+			 <para>
+				 Expand fully on first use, after which "telco" is the preferred abbreviation. "Service provider" is also acceptable as an abbreviation, but be careful in content that mentions different industries or types of services. Do not use in URLs. See <xref linkend="telco" />.
+			 </para>
+
+		 </listitem>
+
+	 </varlistentry>
 		 <varlistentry id="telecommunications">
 			<term>telecommunications</term>
 			 <listitem>
@@ -238,4 +252,3 @@
 
 	</variablelist>
 </chapter>
-
diff --git a/en-US/U.xml b/en-US/U.xml
@@ -164,16 +164,7 @@
 			</listitem>
 
 		</varlistentry>
-		 <varlistentry id="usable">
-			<term>usable</term>
-			 <listitem>
-				<para>
-					<emphasis>adj.</emphasis> Correct. Do not use "useable."
-				</para>
-
-			</listitem>
-
-		</varlistentry>
+		 
 		 <varlistentry id="user">
 			<term>user</term>
 			 <listitem>
diff --git a/en-US/V.xml b/en-US/V.xml
@@ -30,7 +30,7 @@
 			<term>vi</term>
 			 <listitem>
 				<para>
-					Correct. use all lowercase letters. Do not use "VI" (all caps).
+					Correct. Use all lowercase letters. Do not use "VI" (all caps).
 				</para>
 
 			</listitem>

Original file line number	Diff line number	Diff line change
`@@ -752,4 +752,3 @@`
`752`	`752`	`</section>`
`753`	`753`
`754`	`754`	`</chapter>`
`755`		`-`