Merge pull request #217 from StyleGuides/daobrien/216-continuation-pr…

…ompts #216 continuation prompts
StyleGuides · Dec 3, 2020 · 8d2cb84 · 8d2cb84
2 parents 93563e7 + 5f706a6
commit 8d2cb84
Show file tree

Hide file tree

Showing 2 changed files with 47 additions and 12 deletions.
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
@@ -260,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>
@@ -282,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>