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 3 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
58 changes: 51 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,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.
jherrman marked this conversation as resolved.
Show resolved Hide resolved

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.
jherrman marked this conversation as resolved.
Show resolved Hide resolved

[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
----
====

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.
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
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 in the command output. If you need to highlight a specific part of the output, use a different highlighting method.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I don't think this is good guidance. Writers should still be able to use bolded strings in outputs if necessary, especially if in the given code block, the output is more important than the command itself. Also, it would be rather strange to express the same kind of emphasis differently in the very same code block.

Your other suggestions are decidedly improvements, though, thank you :-)

Copy link
Contributor

Choose a reason for hiding this comment

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

@jherrman Apologies for the delay in replying to your comment. It seems odd to me to say bold the command in one place and not in another, but perhaps I misunderstood the intent of this update.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Well, the idea is basically "bold the important part, so that it's visually distinct" - and since the command itself is usually the important part of a CLI example (and the given step in general), it would be the default part do bold. However, when a part of the output is as important as the command in the given context, or more, we should not bar the writer from bolding something else than the command, and potentially even leaving the command un-bolded.

It's entirely possible I did not formulate that clearly enough in the actual source update, though...

Copy link
Collaborator

Choose a reason for hiding this comment

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

@jafiala Can you give us an example of what you're thinking of with bolding pieces of the output?

Copy link
Contributor

Choose a reason for hiding this comment

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

Thanks for the examples, @jherrman.

I think it's better to highlight such lines in the command output by using a callout instead of bold text? The following example shows callouts (in a code example, but the same method could be used for command output):
https://docs.openshift.com/pipelines/1.13/about/understanding-openshift-pipelines.html

WDYT?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Honestly, callouts do not seem like an optimal solution to me.

  • They are pretty wonky to work with in adoc (for instance can only be at the end of a line, cannot be used out of sequence, one callout cannot be used repeatedly, and they must always have an explanation under the codeblock, AFAIK). Also, Customer Portal stylesheets do not render them very well, currently.

  • When they work as expected, callouts are visually very distinct, which may not always be what you want when highlighting a small part of a command output.

If the general intention behind this update is "bold out the operative/important parts of the code block for greater visual clarity", I would say the output should follow that consistently with the commands. Also, it's easier for writers to internalize and follow.

Copy link
Contributor

Choose a reason for hiding this comment

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

@jherrman and @dfitzmau Thank you both! I understand that callouts might not be optimal, but I wonder if we could highlight the command output in some other way rather than by reusing the bold format.

Do you know whether the highlight syntax described here would render correctly in Customer Portal and OpenShift docs?

Copy link
Contributor

Choose a reason for hiding this comment

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

I tried that syntax a few years ago on the CP and it did render, but I was informed to drop it as the yellow highlighting was really distracting. It definetly grabs attention, but it distracts from the surrounding content. I can understand why yellow is a well-adopted colour for safety 💛

Copy link
Contributor Author

@jherrman jherrman Feb 1, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

I tested out the #highlight# markup earlier today. Renders reasonably well in asciidoctor (though, as Darragh points out, the colour is a bit much), but both bccutil and the Customer Portal stylesheets completely ignore it, unfortunately:

https://dxp-docp-prod.apps.ext-waf.spoke.prod.us-west-2.aws.paas.redhat.com/documentation/en-us/zen_and_zany_asciidoc_training_titles/42/html-single/davozenis_advanced_asciidoc_training/index?lb_target=stage#proc_test-two_assembly_nested-test

Source: https://privatebin.corp.redhat.com/?d7d35e248ea634d9#6icGw5GgEyf71smCmNSsPem7bvZ6CFMBjiLVkA7zi8Uj


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[].
jherrman marked this conversation as resolved.
Show resolved Hide resolved

[[date-formats]]
== Date formats

Expand Down Expand Up @@ -104,6 +147,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 +175,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 +187,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 +209,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 +241,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 +257,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