diff --git a/supplementary_style_guide/style_guidelines/formatting.adoc b/supplementary_style_guide/style_guidelines/formatting.adoc index e1ad31ab..eb8de4af 100644 --- a/supplementary_style_guide/style_guidelines/formatting.adoc +++ b/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 @@ -104,6 +145,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 @@ -131,7 +173,7 @@ Ensure that user-replaced values have the following characteristics: Create an Ansible inventory file that is named `/__/inventory/hosts`. ---- -This renders as: +This example renders as follows in HTML: ==== Create an Ansible inventory file that is named `/__/inventory/hosts`. @@ -143,15 +185,15 @@ To italicize a user-replaced value in a code block, you must add an attribute to [subs="+quotes"] ---- - $ oc describe node ____ + $ *oc describe node ____* ---- -This renders as: +This example renders as follows in HTML: ==== [subs="+quotes"] ---- -$ oc describe node ____ +$ *oc describe node ____* ---- ==== @@ -165,7 +207,7 @@ $ oc describe node ____ connection.interface-name: enp7s0 ---- -This renders as: +This example renders as follows in HTML: ==== [subs="+quotes"] @@ -197,7 +239,7 @@ Ensure that user-replaced values in XML have the following characteristics: __${ip_address}__ ---- -This renders as: +This example renders as follows in HTML: ==== [source,xml,subs="+quotes"] @@ -213,7 +255,7 @@ This renders as: ---- -This renders as: +This example renders as follows in HTML: ==== [source,xml,subs="+quotes"]