Merge pull request #413 from jherrman/Issue#390_bold-commands-in-codeblocks

Issue#390 - bold commands in codeblocks

Author: bergerhoffer

supplementary_style_guide/style_guidelines/formatting.adoc

@@ -1,6 +1,47 @@
 [[formatting]]
 = Formatting
 
+[[commands-in-code-blocks]]
+== Commands in code blocks
+
+Use a single command per code block for each procedure step. This approach helps with readability and makes it possible for the copy button in code blocks to work correctly.
+
+By default, use bold formatting for commands in code blocks to visually distinguish the commands from their lead-in sentences and from the command prompts and example outputs. For consistency, use bold formatting for commands even when no command output is shown in the code block.
+
+[NOTE]
+====
+To apply formatting in a code block, you must use the `quotes` link:https://docs.asciidoctor.org/asciidoc/latest/subs/apply-subs-to-blocks/[AsciiDoc substitution].
+====
+
+.Example AsciiDoc: A command and its output in a code block
+
+  Verify that the `libvirt` default network is active and configured to start automatically:
+  
+  [subs="+quotes"]
+  ----
+  # *virsh net-list --all*
+  Name      State    Autostart   Persistent
+  --------------------------------------------
+  default   active   yes         yes
+  ----
+
+
+This example renders as follows in HTML:
+
+====
+Verify that the `libvirt` default network is active and configured to start automatically:
+
+[subs="+quotes"]
+----
+# *virsh net-list --all*
+Name      State    Autostart   Persistent
+--------------------------------------------
+default   active   yes         yes
+----
+====
+
+For commands and command outputs in code blocks, observe the correct markup for user-replaced values, as described in xref:user-replaced-values[] and xref:user-replaced-values-xml[].
+
 [[date-formats]]
 == Date formats
 
@@ -121,6 +162,7 @@ Write all titles and headings, including the titles of product documentation gui
 * _Configuring the node port service range_
 * _How to perform an unsupported conversion from a RHEL-derived Linux distribution to RHEL_
 
+
 [[user-replaced-values]]
 == User-replaced values
 
@@ -148,7 +190,7 @@ Ensure that user-replaced values have the following characteristics:
 Create an Ansible inventory file that is named `/_<path>_/inventory/hosts`.
 ----
 
-This renders as:
+This example renders as follows in HTML:
 
 ====
 Create an Ansible inventory file that is named `/_<path>_/inventory/hosts`.
@@ -160,15 +202,15 @@ To italicize a user-replaced value in a code block, you must add an attribute to
 
   [subs="+quotes"]
   ----
-  $ oc describe node __<node_name>__
+  $ *oc describe node __<node_name>__*
   ----
 
-This renders as:
+This example renders as follows in HTML:
 
 ====
 [subs="+quotes"]
 ----
-$ oc describe node __<node_name>__
+$ *oc describe node __<node_name>__*
 ----
 ====
 
@@ -182,7 +224,7 @@ $ oc describe node __<node_name>__
   connection.interface-name:  enp7s0
   ----
 
-This renders as:
+This example renders as follows in HTML:
 
 ====
 [subs="+quotes"]
@@ -214,7 +256,7 @@ Ensure that user-replaced values in XML have the following characteristics:
   <ipAddress>__${ip_address}__</ipAddress>
   ----
 
-This renders as:
+This example renders as follows in HTML:
 
 ====
 [source,xml,subs="+quotes"]
@@ -230,7 +272,7 @@ This renders as:
   <oauth2-introspection client-id="__${client_id}__"/>
   ----
 
-This renders as:
+This example renders as follows in HTML:
 
 ====
 [source,xml,subs="+quotes"]