From 8ce04c095d39ffab31a3fb53efa9b71e2f6c1963 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ji=C5=99=C3=AD=20Herrmann?= Date: Mon, 2 Oct 2023 18:19:15 +0200 Subject: [PATCH 01/11] Added a section on bolded commands in codeblocks --- .../style_guidelines/formatting.adoc | 36 +++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/supplementary_style_guide/style_guidelines/formatting.adoc b/supplementary_style_guide/style_guidelines/formatting.adoc index e1ad31ab..3fc5cfc8 100644 --- a/supplementary_style_guide/style_guidelines/formatting.adoc +++ b/supplementary_style_guide/style_guidelines/formatting.adoc @@ -104,6 +104,42 @@ 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_ +[[commands-in-code-blocks]] +== Commands in code blocks + +As a default, use bold formatting for commands in code blocks, to visually distinguish them from their lead-in sentences and example outputs. + +.Example AsciiDoc: 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 renders as: + +==== +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 +---- +==== + +Disregard this guideline for example when the command is not an important part of what you want to show in the given code block. + +In addition, both in commands and outputs in code blocks, observe the correct mark-up for user-replaced values, as described in xref:user-replaced-values[] and xref:user-replaced-values-xml[]. + [[user-replaced-values]] == User-replaced values From 5e81685abdad443082fb64df003aaadb5ad2eddd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ji=C5=99=C3=AD=20Herrmann?= Date: Mon, 2 Oct 2023 18:59:58 +0200 Subject: [PATCH 02/11] Bolded out other commands in codeblocks, for consistency --- supplementary_style_guide/style_guidelines/formatting.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/supplementary_style_guide/style_guidelines/formatting.adoc b/supplementary_style_guide/style_guidelines/formatting.adoc index 3fc5cfc8..f28025a0 100644 --- a/supplementary_style_guide/style_guidelines/formatting.adoc +++ b/supplementary_style_guide/style_guidelines/formatting.adoc @@ -179,7 +179,7 @@ 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: @@ -187,7 +187,7 @@ This renders as: ==== [subs="+quotes"] ---- -$ oc describe node ____ +$ *oc describe node ____* ---- ==== From f0ddde1830a873d1838fdec3e5b68be106c266df Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ji=C5=99=C3=AD=20Herrmann?= Date: Tue, 3 Oct 2023 20:42:37 +0200 Subject: [PATCH 03/11] Applied changes based on review Kudos to Andrea Hoffer and Darragh Fitzmaurice for the feedback --- .../style_guidelines/formatting.adoc | 88 ++++++++++--------- 1 file changed, 48 insertions(+), 40 deletions(-) diff --git a/supplementary_style_guide/style_guidelines/formatting.adoc b/supplementary_style_guide/style_guidelines/formatting.adoc index f28025a0..3329448c 100644 --- a/supplementary_style_guide/style_guidelines/formatting.adoc +++ b/supplementary_style_guide/style_guidelines/formatting.adoc @@ -1,6 +1,49 @@ [[formatting]] = Formatting +[[commands-in-code-blocks]] +== Commands in code blocks + +Use a single command per code block per procedure step. This helps with readability and makes it possible for the copy button in code blocks to work correctly. + +As a default, use bold formatting for commands in code blocks, to visually distinguish them from their lead-in sentences and example outputs. For consistency, do this even when no 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 +---- +==== + +Do not use bold formatting for the output, unless you need to highlight a specific part of it. When you do emphasize a non-command item in a code block, you are not required to bold the command. + +For both commands and outputs in code blocks, observe the correct mark-up for user-replaced values, as described in xref:user-replaced-values[] and xref:user-replaced-values-xml[]. + [[date-formats]] == Date formats @@ -104,41 +147,6 @@ 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_ -[[commands-in-code-blocks]] -== Commands in code blocks - -As a default, use bold formatting for commands in code blocks, to visually distinguish them from their lead-in sentences and example outputs. - -.Example AsciiDoc: 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 renders as: - -==== -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 ----- -==== - -Disregard this guideline for example when the command is not an important part of what you want to show in the given code block. - -In addition, both in commands and outputs in code blocks, observe the correct mark-up for user-replaced values, as described in xref:user-replaced-values[] and xref:user-replaced-values-xml[]. [[user-replaced-values]] == User-replaced values @@ -167,7 +175,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`. @@ -182,7 +190,7 @@ To italicize a user-replaced value in a code block, you must add an attribute to $ *oc describe node ____* ---- -This renders as: +This example renders as follows in HTML: ==== [subs="+quotes"] @@ -201,7 +209,7 @@ $ *oc describe node ____* connection.interface-name: enp7s0 ---- -This renders as: +This example renders as follows in HTML: ==== [subs="+quotes"] @@ -233,7 +241,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"] @@ -249,7 +257,7 @@ This renders as: ---- -This renders as: +This example renders as follows in HTML: ==== [source,xml,subs="+quotes"] From f7d7cbd6f4957add9129baacf7991adea03c0ef6 Mon Sep 17 00:00:00 2001 From: jherrman Date: Fri, 13 Oct 2023 15:02:37 +0200 Subject: [PATCH 04/11] Updating supplementary_style_guide/style_guidelines/formatting.adoc Kudos to Miriam Portman for the suggestion Co-authored-by: Miriam Portman <74915975+mportman12@users.noreply.github.com> --- supplementary_style_guide/style_guidelines/formatting.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/supplementary_style_guide/style_guidelines/formatting.adoc b/supplementary_style_guide/style_guidelines/formatting.adoc index 3329448c..3ab6e0cf 100644 --- a/supplementary_style_guide/style_guidelines/formatting.adoc +++ b/supplementary_style_guide/style_guidelines/formatting.adoc @@ -4,7 +4,7 @@ [[commands-in-code-blocks]] == Commands in code blocks -Use a single command per code block per procedure step. This helps with readability and makes it possible for the copy button in code blocks to work correctly. +Use a single command per code block for each procedure step. This helps with readability and makes it possible for the copy button in code blocks to work correctly. As a default, use bold formatting for commands in code blocks, to visually distinguish them from their lead-in sentences and example outputs. For consistency, do this even when no output is shown in the code block. From 358e3d7d22b25a4b79f008a0e474c1fb8317255b Mon Sep 17 00:00:00 2001 From: jherrman Date: Fri, 13 Oct 2023 15:03:10 +0200 Subject: [PATCH 05/11] Update supplementary_style_guide/style_guidelines/formatting.adoc Kudos to Miriam Portman for the suggestion Co-authored-by: Miriam Portman <74915975+mportman12@users.noreply.github.com> --- supplementary_style_guide/style_guidelines/formatting.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/supplementary_style_guide/style_guidelines/formatting.adoc b/supplementary_style_guide/style_guidelines/formatting.adoc index 3ab6e0cf..d33d3cc8 100644 --- a/supplementary_style_guide/style_guidelines/formatting.adoc +++ b/supplementary_style_guide/style_guidelines/formatting.adoc @@ -6,7 +6,7 @@ Use a single command per code block for each procedure step. This helps with readability and makes it possible for the copy button in code blocks to work correctly. -As a default, use bold formatting for commands in code blocks, to visually distinguish them from their lead-in sentences and example outputs. For consistency, do this even when no output is shown in the code block. +As a default, use bold formatting for commands in code blocks to visually distinguish them from their lead-in sentences and example outputs. For consistency, do this even when no output is shown in the code block. [NOTE] ==== From 8095c71971706f8a4df4cd15539c1254a3452a9c Mon Sep 17 00:00:00 2001 From: jherrman Date: Fri, 13 Oct 2023 15:03:36 +0200 Subject: [PATCH 06/11] Update supplementary_style_guide/style_guidelines/formatting.adoc Kudos to Miriam Portman for the suggestion Co-authored-by: Miriam Portman <74915975+mportman12@users.noreply.github.com> --- supplementary_style_guide/style_guidelines/formatting.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/supplementary_style_guide/style_guidelines/formatting.adoc b/supplementary_style_guide/style_guidelines/formatting.adoc index d33d3cc8..a4935713 100644 --- a/supplementary_style_guide/style_guidelines/formatting.adoc +++ b/supplementary_style_guide/style_guidelines/formatting.adoc @@ -42,7 +42,7 @@ default active yes yes Do not use bold formatting for the output, unless you need to highlight a specific part of it. When you do emphasize a non-command item in a code block, you are not required to bold the command. -For both commands and outputs in code blocks, observe the correct mark-up for user-replaced values, as described in xref:user-replaced-values[] and xref:user-replaced-values-xml[]. +For both commands and 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 From 9c97313528c38583467c852d3d3dcb3076b9c03d Mon Sep 17 00:00:00 2001 From: jherrman Date: Mon, 6 Nov 2023 14:13:58 +0100 Subject: [PATCH 07/11] Update supplementary_style_guide/style_guidelines/formatting.adoc Co-authored-by: Breda McColgan <93921684+bredamc@users.noreply.github.com> --- supplementary_style_guide/style_guidelines/formatting.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/supplementary_style_guide/style_guidelines/formatting.adoc b/supplementary_style_guide/style_guidelines/formatting.adoc index a4935713..32972b8b 100644 --- a/supplementary_style_guide/style_guidelines/formatting.adoc +++ b/supplementary_style_guide/style_guidelines/formatting.adoc @@ -4,7 +4,7 @@ [[commands-in-code-blocks]] == Commands in code blocks -Use a single command per code block for each procedure step. This helps with readability and makes it possible for the copy button in code blocks to work correctly. +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. As a default, use bold formatting for commands in code blocks to visually distinguish them from their lead-in sentences and example outputs. For consistency, do this even when no output is shown in the code block. From 31ead15cc4bb3b614dbb80f0ae3097c104722ee6 Mon Sep 17 00:00:00 2001 From: jherrman Date: Mon, 6 Nov 2023 14:14:25 +0100 Subject: [PATCH 08/11] Update supplementary_style_guide/style_guidelines/formatting.adoc Co-authored-by: Breda McColgan <93921684+bredamc@users.noreply.github.com> --- supplementary_style_guide/style_guidelines/formatting.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/supplementary_style_guide/style_guidelines/formatting.adoc b/supplementary_style_guide/style_guidelines/formatting.adoc index 32972b8b..8304e568 100644 --- a/supplementary_style_guide/style_guidelines/formatting.adoc +++ b/supplementary_style_guide/style_guidelines/formatting.adoc @@ -6,7 +6,7 @@ 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. -As a default, use bold formatting for commands in code blocks to visually distinguish them from their lead-in sentences and example outputs. For consistency, do this even when no output is shown in the code block. +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] ==== From ef1efcd93c409ebb548ae03d37395e2e3e50d064 Mon Sep 17 00:00:00 2001 From: jherrman Date: Mon, 6 Nov 2023 14:14:43 +0100 Subject: [PATCH 09/11] Update supplementary_style_guide/style_guidelines/formatting.adoc Co-authored-by: Breda McColgan <93921684+bredamc@users.noreply.github.com> --- supplementary_style_guide/style_guidelines/formatting.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/supplementary_style_guide/style_guidelines/formatting.adoc b/supplementary_style_guide/style_guidelines/formatting.adoc index 8304e568..4cf17db9 100644 --- a/supplementary_style_guide/style_guidelines/formatting.adoc +++ b/supplementary_style_guide/style_guidelines/formatting.adoc @@ -42,7 +42,7 @@ default active yes yes Do not use bold formatting for the output, unless you need to highlight a specific part of it. When you do emphasize a non-command item in a code block, you are not required to bold the command. -For both commands and 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[]. +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 From 9346e5498ea0df88ebfa580ae9f2d031f7e071fd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ji=C5=99=C3=AD=20Herrmann?= Date: Tue, 13 Feb 2024 17:52:30 +0100 Subject: [PATCH 10/11] Changed phrasing on bolding in output --- supplementary_style_guide/style_guidelines/formatting.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/supplementary_style_guide/style_guidelines/formatting.adoc b/supplementary_style_guide/style_guidelines/formatting.adoc index 4cf17db9..07bcbf6f 100644 --- a/supplementary_style_guide/style_guidelines/formatting.adoc +++ b/supplementary_style_guide/style_guidelines/formatting.adoc @@ -40,7 +40,7 @@ default active yes yes ---- ==== -Do not use bold formatting for the output, unless you need to highlight a specific part of it. When you do emphasize a non-command item in a code block, you are not required to bold the command. +Do not use bold formatting as a default for the output. Nevertheless, if you require highlighting a specific part of the output, bold formatting can be used. However, to avoid clashing with the command visually, consider other methods of highlighting, such as italics or callouts. 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[]. From a05bcc08f17830cc628bcf597c679e45d8d913ff Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ji=C5=99=C3=AD=20Herrmann?= Date: Tue, 13 Feb 2024 23:37:34 +0100 Subject: [PATCH 11/11] Removed guidelines for output --- supplementary_style_guide/style_guidelines/formatting.adoc | 2 -- 1 file changed, 2 deletions(-) diff --git a/supplementary_style_guide/style_guidelines/formatting.adoc b/supplementary_style_guide/style_guidelines/formatting.adoc index 07bcbf6f..eb8de4af 100644 --- a/supplementary_style_guide/style_guidelines/formatting.adoc +++ b/supplementary_style_guide/style_guidelines/formatting.adoc @@ -40,8 +40,6 @@ default active yes yes ---- ==== -Do not use bold formatting as a default for the output. Nevertheless, if you require highlighting a specific part of the output, bold formatting can be used. However, to avoid clashing with the command visually, consider other methods of highlighting, such as italics or callouts. - 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]]