Establish clearer guidelines for command highlighting in code blocks

[jherrman]

The mark-up of commands in code blocks is currently inconsistent across Red Hat documentation:

• Some RH docs use bolded commands, with non-bolded output: Example

• Some RH docs use non-bolded commands and output: Example

• OpenShift documentation uses bold commands in code blocks, with examples in separate code block, also in bold: Example

• ^However, this seems to be a result of different stylesheets on the OpenShift docs site. The same content on the RH Customer Portal is not in bold.

There likely are other variations within our docs set as well. As a result, this creates a rather disjointed reader experience, especially given that code blocks with commands are often the most important parts of our procedures.

This may be partly because our style guides do not really give clear directions about this:

• IBM Style states that command names should be in bold monospace: https://www.ibm.com/docs/en/ibm-style?topic=format-highlighting

• IBM Style states that commands entered on the CLI should be in (just) monospace: “When you tell users to run, type, enter, or issue a command on a command line or at a command prompt, use a monospaced font for the command name.” - https://www.ibm.com/docs/en/ibm-style?topic=elements-commands

• The RH SSG does not determine either way, but uses examples with non-bolded code-blocks: https://redhat-documentation.github.io/supplementary-style-guide/#user-replaced-values

Therefore, I would like to propose recommending (but not necessarily mandating) a specific unified style for code block mark-up. My preference would be the first one I listed - bolded commands, with non-bolded output in the same code block.

• Visual differentiation of commands is very useful for readability and scannability of our procedures. Given that our current stylesheets render code blocks as light-grey, a more prominent styling for the command characters would distinguish them nicely from both the lead-in text and the output.

• The copy-paste button feature on the Customer Portal seems to be able to filter away the output, so keeping it in the same code block as command examples does not have a functional downside and saves on “screen real estate”.

• Making this approach non-mandatory provides leeway for situations when it would not be optimal - for instance when only a specific segment of a command or a part of the output should be emphasised. Optionally, callouts can be used for highlighting in code blocks instead.

[bergerhoffer]

The SSG did purposefully try to avoid taking a stance on this in a recent update, because we know of the wide variance of how people do this.

However, that is news to me that the copy/paste button on the portal can ignore output. That is awesome to hear.

On OpenShift, we do separate commands from output. I believe that the main driver behind this though was because of our copy/paste button code on docs.openshift.com. Our copy button on docs.openshift.com was implemented before the portal implemented theirs, and it does not recognize a command and only copy that. It copies both the command and output. That's why we made a push to separate.

That being said, if the copy button on the portal can ignore example output when being copied, then I think a case can be made for not needing to separate them. Though I don't know if there is any other reason why separating them would be beneficial.

If command and output are combined, then I do prefer the option where the command is bold. To me, this makes it very easy to tell what is the command to be entered vs what is just output after running the command. I am not a fan of command and output combined, but nothing is bold.

My followup question though is what is your recommended stance on having multiple commands in the same code block? Allowed or should multiple commands be separated into their own code blocks?

[jherrman]

My followup question though is what is your recommended stance on having multiple commands in the same code block? Allowed or should multiple commands be separated into their own code blocks?

Well, I would recommend that the style guide strongly encourages one command per code block and one code block per step. My reasoning is:

• https://www.ibm.com/docs/en/ibm-style?topic=format-procedures#writing-steps recommends one step per "significant user action", which in terms of CLI, in majority of cases equates to a single command.
• If you use the copy/paste button function on a codeblock with more commands and paste it into a CLI terminal, it auto-executes all but the last of the commands, which leads to users running commands they did not intend.

[bergerhoffer]

Well, I would recommend that the style guide strongly encourages one command per code block and one code block per step.

Great, that makes sense to me too.

@redhat-documentation/ccs-style-council other thoughts on this issue?

[dfitzmau]

I agree, too. This was a rule often followed in the Runtimes space. There is one exception: using the backslash (escape character) to stop the shell from interpreting line spaces so that one can input a large set of commands as one input.

Screenshot taken from https://docs.openshift.com/container-platform/4.10/post_installation_configuration/node-tasks.html

[jherrman]

@dfitzmau , multi-line commands like this require adding asterisks in the markup on each of the lines, but functionally, they seem to work well in our docs. On the Customer Portal at least, the copy/paste button can "consume" such a multi-line command as a whole, and pasting the command into the terminal does not trigger any of the lines separately.

For testing, see for instance https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/configuring_and_managing_virtualization/assembly_creating-virtual-machines_configuring-and-managing-virtualization#creating-virtual-machines-using-the-command-line-interface_assembly_creating-virtual-machines

[jherrman]

Based on the discussion in today's Style Council meeting, I will be creating a PR for this change to be implemented in the Supplementary Style Guide.

[jherrman]

Created a PR with the updates at #413

@bergerhoffer @dfitzmau or anyone else, feel free to review and let me know if it looks ship-shape.

Cheers,
J.

[rolfedh]

I wonder if using subs quotes might occasionally mangle some legit command input or output that happens to contain words that are incidentally enclosed by AsciiDoc formatting syntax.

I created a python script to find some instances like this but don't quite have the regex chops to pull it off and get too many invalid results.

[jherrman]

I wonder if using subs quotes might occasionally mangle some legit command input or output that happens to contain words that are incidentally enclosed by AsciiDoc formatting syntax.

Yes, that can definitely happen, but usually can be fixed by \escaping one of the (not)asciidoc characters.

[rolfedh]

can be fixed by \escaping one of the (not)asciidoc characters.

I wish we had tooling to ensure that writers would see when they need to do that.

[bergerhoffer]

Closing because PR #413 has been merged!