Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Issue#390 - bold commands in codeblocks #413

Merged
merged 11 commits into from
Feb 20, 2024
Merged

Issue#390 - bold commands in codeblocks #413

Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
8ce04c0
Added a section on bolded commands in codeblocks
jherrman Oct 2, 2023
5e81685
Bolded out other commands in codeblocks, for consistency
jherrman Oct 2, 2023
f0ddde1
Applied changes based on review
jherrman Oct 3, 2023
f7d7cbd
Updating supplementary_style_guide/style_guidelines/formatting.adoc
jherrman Oct 13, 2023
358e3d7
Update supplementary_style_guide/style_guidelines/formatting.adoc
jherrman Oct 13, 2023
8095c71
Update supplementary_style_guide/style_guidelines/formatting.adoc
jherrman Oct 13, 2023
9c97313
Update supplementary_style_guide/style_guidelines/formatting.adoc
jherrman Nov 6, 2023
31ead15
Update supplementary_style_guide/style_guidelines/formatting.adoc
jherrman Nov 6, 2023
ef1efcd
Update supplementary_style_guide/style_guidelines/formatting.adoc
jherrman Nov 6, 2023
9346e54
Changed phrasing on bolding in output
jherrman Feb 13, 2024
a05bcc0
Removed guidelines for output
jherrman Feb 13, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 49 additions & 7 deletions supplementary_style_guide/style_guidelines/formatting.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My only feedback is whether this example should actually be shown as a bullet or numbered step. But I don't think that's important enough to hold up the PR over since it has 2 other approvals. Just something to consider if we should adjust in a separate PR or not!


[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

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -131,7 +173,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`.
Expand All @@ -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 __<node_name>__
$ *oc describe node __<node_name>__*
dfitzmau marked this conversation as resolved.
Show resolved Hide resolved
----

This renders as:
This example renders as follows in HTML:

====
[subs="+quotes"]
----
$ oc describe node __<node_name>__
$ *oc describe node __<node_name>__*
----
====

Expand All @@ -165,7 +207,7 @@ $ oc describe node __<node_name>__
connection.interface-name: enp7s0
----

This renders as:
This example renders as follows in HTML:

====
[subs="+quotes"]
Expand Down Expand Up @@ -197,7 +239,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"]
Expand All @@ -213,7 +255,7 @@ This renders as:
<oauth2-introspection client-id="__${client_id}__"/>
----

This renders as:
This example renders as follows in HTML:

====
[source,xml,subs="+quotes"]
Expand Down
Loading