Merge branch 'dev' to release v4.2

StyleGuides · Dec 3, 2020 · 2f4874f · 2f4874f
2 parents 7a12995 + 8d2cb84
commit 2f4874f
Show file tree

Hide file tree

Showing 6 changed files with 117 additions and 23 deletions.
diff --git a/en-US/B.xml b/en-US/B.xml
@@ -67,13 +67,22 @@
 				</para>
 
 			</listitem>
+		</varlistentry>
+		 <varlistentry id="backwards">
+			<term>backwards</term>
+			 <listitem>
+				<para>
+					Avoid using "backwards" unless you are stating that something has "backwards compatibility."
+				</para>
+
+			</listitem>
 
 		</varlistentry>
 		 <varlistentry id="backwards-compatible">
 			<term>backwards compatible</term>
 			 <listitem>
 				<para>
-					Do not use. Instead, use "compatible with earlier versions." See also <xref linkend="forwards-compatible" />.
+					Correct. Use to refer to something that is compatible with older equipment or previous versions of software. See also <xref linkend="forwards-compatible" />.
 				</para>
 
 			</listitem>
@@ -419,4 +428,3 @@
 
 	</variablelist>
 </chapter>
-
diff --git a/en-US/Book_Info.xml b/en-US/Book_Info.xml
@@ -7,7 +7,7 @@
 	<title>Conventions for Writers and Editors</title>
 	 <productname>The Red Hat Style Guide</productname>
 	 <productnumber></productnumber>
-	 <edition>4</edition>
+	 <edition>4.2</edition>
 	 <pubsnumber>1</pubsnumber>
 	 <abstract>
 		<para>

diff --git a/en-US/Design.xml b/en-US/Design.xml
@@ -120,9 +120,30 @@
 
 		</section>
 		 <section id="documenting-command-syntax">
-			<title>Documenting Command Syntax</title>
+			<title>Documenting Command Terminology and Syntax</title>
+      <para>
+        Sufficient variation exists in the terminology used to describe commands, options, arguments, and so on that only general advice is provided here.
+      </para>
+      <para>
+        When referring to the command line as specified by Bash and POSIX, follow the terminology that the software uses.
+        Never use "flag" when referring to command-line options in POSIX, even though Microsoft often uses the term "flag" when referring to single-character options in Microsoft Windows.
+      </para>
+      <para>
+        The following extract from <command>info libc</command> is of particular interest here:
+      </para>
+      <blockquote>
+        <para>
+          "POSIX recommends these conventions for command line arguments. [...] Arguments are options if they begin with a hyphen delimiter (‘-’). Multiple options may follow a hyphen delimiter in a single token if the options do not take arguments. Thus, ‘-abc’ is equivalent to ‘-a -b -c’. [...] Certain options require an argument. For example, the ‘-o’ option of the ‘ld’ command requires an argument—an output file name." and so on.
+        </para>
+        <para>
+          See <command>info libc argument syntax</command> for the full discussion.
+        </para>
+        </blockquote>
+      <para>
+        See <command>info bash</command> and the <citetitle>Computer Interfaces</citetitle> chapter of <citetitle>The IBM Style Guide</citetitle> for further guidance.
+      </para>
 			 <para>
-				See the <citetitle>Computer Interfaces</citetitle> chapter of <citetitle>The IBM Style Guide</citetitle> for initial guidance. The following examples are intended to highlight correct usage.
+        The following examples are intended to highlight correct usage.
 			</para>
 			 <example id="exam-documenting-command-syntax">
 				<title>Cloning a Git Repository</title>
@@ -151,7 +172,8 @@
 					<term>The command (<command>git clone</command>)</term>
 					 <listitem>
 						<para>
-							The actual command to run, without any optional or replaceable values. This must be typed as is.
+							The actual command to run, without any optional or replaceable values.
+              This must be typed as is.
 						</para>
 
 					</listitem>
@@ -161,7 +183,8 @@
 					<term>Source options <replaceable>[username@]hostname:/repository_filename</replaceable>)</term>
 					 <listitem>
 						<para>
-							The optional user name, indicated by brackets ([]), followed by the host name and path to the repository. All aspects of this component must be replaced with valid values.
+							The optional user name, indicated by brackets ([]), followed by the host name and path to the repository.
+              All aspects of this component must be replaced with valid values.
 						</para>
 
 					</listitem>
@@ -171,7 +194,8 @@
 					<term>Target options <replaceable>[directory]</replaceable></term>
 					 <listitem>
 						<para>
-							The optional directory into which the repository will be cloned. This must be replaced with a valid value, or omitted.
+							The optional directory into which the repository will be cloned.
+              This must be replaced with a valid value, or omitted.
 						</para>
 
 					</listitem>
@@ -236,9 +260,12 @@
 					Avoid using the <option>--force (-f)</option> and <option>--assumeyes (-y)</option> options on most commands, especially when logged in as the <systemitem>root</systemitem> user. This can lead to unintended consequences, such as removing files or directories by mistake or installing packages or other software that may not suit your system. Refer to the following examples:
 				</para>
 
-<screen>[root@serverc pam.d]# rm -f system-auth password-auth (omit the -f)
-[root@serverc ~]# yum install -y new-package (omit the -y)
+<screen>[root@serverc pam.d]# rm -f system-auth password-auth
+[root@serverc ~]# yum install -y new-package
 </screen>
+<para>
+  In the examples shown above, omit the <option>-f</option> and <option>-y</option> options, respectively.
+</para>
 				 <para>
 					In some cases, such as in Ansible Playbooks or other automation scripts, it may be necessary to use these options.
 				</para>
@@ -258,23 +285,55 @@ $ vi myFile.txt
 
 				</example>
 				 <para>
-					If the commands are long, complex, or wrap over multiple lines, use the following design to help optimize clarity.
-          If you are documenting commands on a different operating system, update the prompts and line continuation characters to suit.
-				</para>
+					If the commands are long, complex, or wrap over multiple lines, two design options are available.
+          </para>
+          <itemizedlist>
+            <listitem>
+              <para>
+                Use line continuation characters and the associated PS2 prompts.
+                If you are documenting commands on a different operating system, update the prompts and line continuation characters to suit.
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                Use neither line continuation characters nor the associated PS2 prompts.
+              </para>
+            </listitem>
+          </itemizedlist>
+          <important>
+            <para>
+              Do not mix these two styles.
+              Maintain the same style throughout your document or book.
+            </para>
+          </important>
+          <para>
+            You can also indent the second and subsequent lines of such commands to assist in clarity and readability if required.
+            You can use this option for either of the two designs mentioned above.
+          </para>
+
 				 <example>
-					<title>Documenting Long Commands</title>
+					<title>Wrapping Long Commands with Continuation Characters</title>
+          <para>
+            This example uses both continuation characters and PS2 prompts.
+            These indicators are always used together.
+          </para>
 
 <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
+> /root/ssl–build /var/www/html/pub/* /var/lib/katello</screen>
+          </example>
 
-# cd /var/lib/katello
+<example><title>Wrapping Long Commands Without Continuation Characters</title>
+  <para>
+    This example uses neither continuation characters nor PS2 prompts, but it does demonstrate how to use line indentation to help clarify long commands.
+  </para>
+<screen># cd /var/lib/katello
 
-# myCommand --option funky --color=true \
-> --config_file=&lt;replaceable&gt;/home/user/config.conf&lt;/replaceable&gt; \
-> --output_file=&lt;replaceable&gt;/home/user/output.txt&lt;/replaceable&gt;</screen>
+# myCommand --option funky --color=true
+  --config_file=&lt;replaceable&gt;/home/user/config.conf&lt;/replaceable&gt;
+  --output_file=&lt;replaceable&gt;/home/user/output.txt&lt;/replaceable&gt;</screen>
 
 				</example>
 

diff --git a/en-US/E.xml b/en-US/E.xml
@@ -89,6 +89,22 @@
 			</listitem>
 
 		</varlistentry>
+		<varlistentry id="eol">
+		 <term>EOL</term>
+			<listitem>
+			 <para>
+				 <emphasis>adj.</emphasis> Initialism for "end-of-line"
+			 </para>
+			 <para>
+				 <emphasis>n.</emphasis> Initialism for "end of line"
+			 </para>
+				<para>
+					Always use uppercase for the initialism. Do not capitalize the expansion except at the beginning of a sentence. When documenting GUI objects, use the same capitalization as that shown in the GUI.
+			 </para>
+
+		 </listitem>
+
+		 </varlistentry>
 		 <varlistentry id="essentially">
 			<term>essentially</term>
 			 <listitem>
@@ -175,4 +191,3 @@
 
 	</variablelist>
 </chapter>
-
diff --git a/en-US/F.xml b/en-US/F.xml
@@ -240,10 +240,13 @@
 			<term>FQDN</term>
 			 <listitem>
 				<para>
-					A fully qualified domain name consists of a host and domain name, including top-level domain. For example, www.redhat.com is a fully qualified domain name. www is the host, redhat is the second-level domain, and .com is the top level domain.
+          A fully qualified domain name consists of a list of domain labels representing the hierarchy from the lowest relevant level in the DNS to the top-level domain (TLD). The domain labels are concatenated using the full stop (.) character (dot or period) as a separator between labels.<footnote><para>https://en.wikipedia.org/wiki/Fully_qualified_domain_name</para></footnote>
+        </para>
+        <para>
+          For example, <uri>www.redhat.com</uri> is a fully qualified domain name, where <quote>www</quote> is the host, <quote>redhat</quote> is the second-level domain, and <quote>com</quote> is the top-level domain.
 				</para>
 				 <para>
-					A FQDN always starts with a host name and continues all the way up to the top-level domain name, so www.parc.xerox.com is also a FQDN.
+					A FQDN always starts with a host name and continues all the way up to the top-level domain name; consequently <quote>www.parc.xerox.com</quote> is also a FQDN.
 				</para>
 
 			</listitem>

diff --git a/en-US/M.xml b/en-US/M.xml
@@ -6,6 +6,16 @@
 <chapter id="m">
 	<title>M</title>
 	 <variablelist>
+		 <varlistentry id="macOS">
+		 <term>macOS</term>
+			<listitem>
+			 <para>
+				 In 2016, Apple rebranded OS X to macOS, adopting the nomenclature that it uses for their other operating systems: iOS, watchOS, and tvOS. The latest version of macOS is macOS 10.12 Sierra, which was publicly released in September 2016.	 
+			 </para>
+
+		 </listitem>
+
+	 </varlistentry>
 		<varlistentry id="make-sure">
 			<term>make sure</term>
 			 <listitem>
@@ -296,4 +306,3 @@
 
 	</variablelist>
 </chapter>
-