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 2 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
40 changes: 38 additions & 2 deletions supplementary_style_guide/style_guidelines/formatting.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]]
Copy link
Collaborator

Choose a reason for hiding this comment

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

I know we also briefly talked about stating to show a single command in a code block. And that if you have multiple commands, they should be broken into separate code blocks.

Should we consider adding an entry for this as well? Not sure if it would make sense to add into this one, or to separate them into different entries?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

You're right, that's a topic that falls quite squarely under "Commands in code blocks]", so I'll add a mention of that, too.

== Commands in code blocks
Copy link
Collaborator

Choose a reason for hiding this comment

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

Can you move this up so that it is alphabetical? (Should be first in the file, before "Date formats")

I've also gone back and forth on whether this makes the most sense under formatting, or whether it would be better suited under "Technical examples". It is formatting, but I'm leaning toward the technical examples sense, just so that all of the code block misc is together. wdyt?

Copy link
Contributor

Choose a reason for hiding this comment

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

+1 For Technical examples

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Hm, I'd say it fits rather well under the "Formatting" section, since "Technical examples" primarily seems to deal with guidelines for the content itself rather than its markup.

Also, the "User-replaced values" parts, which deal with a very much related topic, including code block content (which is why I initially bunched up the new section with them), are under Formatting as well.


As a default, use bold formatting for commands in code blocks, to visually distinguish them from their lead-in sentences and example outputs.
Copy link
Collaborator

Choose a reason for hiding this comment

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

I know this sentence implies it, but I would add another sentence that states that output should not use bold formatting.


Copy link
Collaborator

Choose a reason for hiding this comment

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

Do you think we need to clarify that you should still use bold even if there is no example output?

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 think so, good point.

.Example AsciiDoc: 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.

Maybe show this as a step, since that's how it would normally appear in a procedure? (If you do, update in the below rendered output as well

Suggested change
Verify that the `libvirt` default network is active and configured to start automatically:
. Verify that the `libvirt` default network is active and configured to start automatically:

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Actually, I just tested this and it seems to break the formatting of the example in the render for some reason. So, given that it's not really important for the example lead-in sentence to be a step, I'd leave it out.

+
[subs="+quotes"]
----
# *virsh net-list --all*
Name State Autostart Persistent
--------------------------------------------
default active yes yes
----


This renders as:
Copy link
Contributor

Choose a reason for hiding this comment

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

Incomplete sentence. How about: The previous AsciiDoc example outputs as follows?

I'm suggesting this in the event that a new writer scans the RH SSG (to validate term usability) to check for instances of "This renders as" and they then apply it to customer docs.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

This exact wording was actually used in multiple other examples in the section, and I just copied it as a "template". Doesn't change the fact that it's an incomplete sentence, so I'll update the other occurrences, too.


====
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.
Copy link
Collaborator

Choose a reason for hiding this comment

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

I get what we're trying to say with this line, but I think this leaves a lot of room for people to ignore this guideline. Maybe we could leave it out?

Or maybe word it differently to state that if you are using bold to emphasize a different item in the code block, you are not required to bold the command?

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, I do want to leave people some room to manoeuvre around this if they feel so inclined. Your suggestion for the wording does make sense, though.


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

Choose a reason for hiding this comment

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

The three "in" instances makes me stop and reread the sentence. How about:

For a command and its output in a code block, 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

Expand Down Expand Up @@ -143,15 +179,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:

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

Expand Down